sovrin / unitas

100%

push

github

feat!: parse by offset and report where a failure happened (#2)

Parsers took a sliced suffix of the input, so nothing in the system knew
where it was in the original source. Position was not being withheld, it
did not exist: `position` returned the remaining length, and 50 of the
52 failure sites passed no message because there was nothing useful to
say.

    before : Error: Not all input consumed: ",b=x,c=3"
    after  : ParseError: 1:7 expected digit, found 'x'
               1 | a=1,b=x,c=3
                 |       ^

A `Parser<T>` now reads from an offset and never slices:

    type Parser<T> = (input: string, index?: number, ctx?: Context) => Result<T>;
    type Success<T> = { ok: true; value: T; index: number };
    type Failure = { ok: false; index: number; expected: readonly string[] };

Both new arguments are optional, so composing the built-in parsers is
unchanged and `myParser('input')` still works.

`ctx` is a per-parse context holding the furthest offset any branch
reached and what was wanted there. It only moves forward, so
backtracking cannot lose it, and it is written only on the failure path.
That is what makes the message point at the mistake: `separatedBy`
succeeds at 1:4 with one pair, so without it the error would read
"1:4 expected end of input" — true, and pointing at the wrong character.

Falling out of the offsets:

- `parse` reports line, column and expectations without throwing;
  `run` throws a `ParseError` carrying the same.
- `grammar` names left-recursive rules instead of overflowing the stack.
- `memoize` keys on an offset, so entries are cheap and are dropped when
  a different input is parsed.
- `regex` matches with a sticky pattern, anchored by construction.
- `position` reports the offset from the start, so it pairs with
  `locate` to give a parsed node a source span.

Nothing allocates a slice per step any more, and the library is faster
or tied against master on every benchmark:

    many(char) 200k          4.63... (continued)

332 of 332 branches covered (100.0%)

Branch coverage included in aggregate %.

460 of 460 new or added lines in 88 files covered. (100.0%)

749 of 749 relevant lines covered (100.0%)

35.78 hits per line