incremental

mattbierner edited this page Dec 9, 2014 · 8 revisions
Clone this wiki locally

Almost any parser can be run incrementally

Starting Parsing

runInc(p, [userData])

Start parsing p incrementally with optional user data. Returns a paused computation. Once the computation is finished, returns success results directly and throws error results.

var c = parse_inc.runInc(
    parse.eager(parse.many(parse_text.character('a')));

var c1 = parse_inc.provideString('a', c);
parse_inc.finish(c1); // 'a'

var c2 = parse_inc.provideString('aa', c1);
parse_inc.finish(c2); // 'aaa';

var c3 = parse_inc.provideString('x', c2);
parse_inc.finish(c3); // 'aaa';

runIncState(p, state)

Start parsing p incrementally with a custom parser. Returns a paused computation. Once the computation completes, returns success results directly and throws error results.

Note that if state has some input already set when it is passed to runInc, this input will automatically be provided before the paused computation is returned.

parserInc(p, ud, ok, err)

Start parsing p incrementally with some user data. Returns a paused computation.

Once the computation is finished, runs ok with success results or err with failure results and throws error results. The computations are only evaluated when finish is called

var c = parse_inc.parseInc(
    parse.eager(parse_lang.times(2, parse_text.character('a'))),
    null,
    \x -> console.log("suc" + x),
    \x -> console.log("error" + x));

var c1 = parse_inc.provideString('a', c);
parse_inc.finish(c1); // logs error

var c2 = parse_inc.provideString('a', c1);
parse_inc.finish(c2); // logs 'aa';

var c3 = parse_inc.provideString('x', c2);
parse_inc.finish(c3); // 'aa';

parserIncState(p, state, ok, err)

Start parsing p incrementally with a parser state and completions.

Feed

provide(stream, r)

Provide a chunk of data stream to paused parser r. stream is a potentially infinite Nu stream. Runs as much as possible before pausing.

var c = parse_inc.runInc(
    parse.eager(parse.many(parse.anyToken)));

var c1 = parse_inc.provide(stream.from('a'), c);
parse_inc.finish(c1); // 'a'

var c2 = parse_inc.provide(stream.from('bc'), c1);
parse_inc.finish(c2); // 'abc';

// Feeding alt input to `c1`.
var c3 = parse_inc.provide(stream.from('yx'), c1);
parse_inc.finish(c3); // 'axy';

provideString(arr, r)

Provide a chunk of data arr to paused parser r. arr is a array of values. Runs as much as possible before pausing.

var c = parse_inc.runInc(
    parse.eager(parse.many(parse.anyToken)));

var c1 = parse_inc.provideString(['a', 'b'], c);
parse_inc.finish(c1); // 'ab'

// This is the same as
var c1 = parse_inc.provideStream('ab', c);
parse_inc.finish(1); // 'ab'

finish(r)

Signal paused parser r that no more input is coming. Returns result of completions. r is not mutated and can be feed more data, so finish can be used to inspect the working state.