Chapter 3

Incremental Documents

A Document holds a text that changes over time, applies edits to it and parses the current text. Reparsing after an edit reuses results of the previous parse that the edit did not affect. Reuse never changes the outcome: a parse of a document is the same as a parse of the current text from scratch. This chapter defines the document API, its versions and snapshots, change notifications and reuse-history controls.

Scope and Terminology

A document is a Document, created by Parser.NewDocument. The text is the current content of the document. A version is the opaque token returned by Document.Version. A snapshot is an immutable capture of one revision's text, parse outcome and value graph. A batch is a set of replacements that apply simultaneously to one base revision.

Positions and edit ranges use the document's position unit, which is fixed when the document is created; see Positions.

Contract

Construction and Ownership

Operation Behavior
p.NewDocument(text, opts...) Returns a document holding text. WithUnit fixes the position unit (also the unit of edits) and WithExpectations fixes whether syntax errors record expectations (a later Parse or Snapshot that asks for the other mode is an error); WithContext and WithLimits set defaults for initialization and later parses. It fails for an unknown start rule and when initialization is interrupted. Nothing is parsed
doc.Text() The current text. In Bytes it holds the exact bytes of the initial text and the replacements; in CodePoints each invalid UTF-8 byte of them is replaced with U+FFFD
doc.Unit() The fixed position unit
doc.Version() A comparable opaque token identifying the current text revision. A new document starts at sequence 1. Parsing does not advance the version. The token does not retain the document, the text or parse caches

A Document has one owner and is not safe for concurrent use; a Parser is safe for concurrent use. A document is always parsed as a whole: #stream has no effect on it and it is not a stream parse. Grammars that use #missing are rejected.

For Bytes, construction can charge no budget, because a large immutable input need not be scanned or copied. For CodePoints, initialization decodes and normalizes the input, and the inspected input is charged.

Edits

doc.Edit(start, end, text) replaces [start, end) with text, in the document's unit. start == end inserts and an empty text deletes. It returns an error if the range is outside the text and, in Bytes, if start or end lies inside a character. In CodePoints, invalid UTF-8 in text is normalized, one replacement character per invalid byte. It does not parse. A successful Edit advances the version once, including an edit that changes nothing. A failed edit changes nothing.

doc.EditBatch(base, edits...) applies replacements simultaneously to the text identified by the token base, a DocumentVersion that doc.Version() returned. Each edit is an input.TextEdit, which replaces [Start, End) with Text.

  • Every range uses coordinates in the original base text and the document's unit.
  • Starts MUST be strictly increasing and ranges MUST NOT overlap. A repeated start, including several insertions at one position, is rejected.
  • A token from another document or from an older revision is rejected, even for an empty batch.
  • An empty valid batch changes neither text nor version. A successful nonempty batch advances the version once and does not parse. Version sequence overflow is rejected before any change.
  • The complete batch is validated and prepared before it is published. A rejected batch leaves the text, version, statistics, reusable state and previously returned nodes unchanged.
  • In Bytes, endpoints are checked against character boundaries of the base text. Replacements can create or remove UTF-8 sequences at their seams; the next parse decodes them. In CodePoints, invalid UTF-8 in replacement text is normalized, one replacement character per invalid byte.
  • After a successful batch the next parse equals a fresh parse of the resulting text. Committing a batch clears reusable parse caches; it does not promise the reuse that the same replacements applied as separate Edit calls could give.

In Bytes, only the interior of a valid UTF-8 character is excluded as an edit boundary. Each invalid byte is a separate replacement character, so text can be replaced at it, or inserted before or after it. An edit can join an incomplete prefix and continuation bytes into a valid character; the next parse invalidates results that depended on the earlier decoding, including a prefix completed by an insertion at the end of the text. In CodePoints, invalid bytes have already been replaced with U+FFFD, and editing the normalized text does not reassemble the original bytes: an invalid byte is one replacement character whether it stands alone or belongs to an incomplete or ill-formed sequence, so a replacement never joins with the text around it.

Edit and EditBatch are outside parse compute limits.

Parsing

doc.Parse(opts...) parses the current text using the construction defaults overridden by the options of the call; WithLimits overrides only the nonzero fields it sets (Default Limits). Context, limits and tracing MAY vary per call; the unit, backend, start rule and non-recognition mode MUST NOT, and an option that tries to change them is an error. Counters reset on each call. Results and errors are those of Parser.Parse, including recovered SyntaxErrors.

Parse publishes recovered parser-produced syntax diagnostics as caller-owned values: it copies each SyntaxError and its Expected and Messages slices, so a caller's mutation cannot change memoized errors or a later parse. Ordinary parse failures are newly constructed; caller-supplied errors such as Context.Err keep their identity. This does not detach the mutable Node graph, which MAY share nodes with the document, and nodes that an earlier parse returned MAY be moved in place by a later one. A later parse moves only the nodes it reuses, so even when it completes a tree from an earlier parse can be left partly moved, and when it is interrupted while it moves them no later parse moves them again. The positions in a tree from an earlier parse are unspecified once a parse after an edit has started; to keep a tree as it was, take a Clone before that parse. Typed values returned by a generated parser's Document.ParseValue are read-only and shared with the document and earlier results; its generated CloneValue returns an independent copy (see Generated Parsers). Parsing and diagnostic publication use the same invocation controls. If publication is interrupted, no result is returned and reusable execution state is cleared for retry.

Under a finite memory limit, the count of a Parse starts at the bytes the document retains from earlier parses: its memo table, its repetition records and edits, and the stacks it keeps. If they alone exceed Memory, the document drops them before parsing, as ResetHistory does, and the parse runs from scratch. Retained bytes within Memory are kept, so a parse that reuses them can exceed the limit where a parse from scratch would not; that interruption clears them, and the next parse starts without them. The retained bytes are counted as the memory limit counts storage, not as EstimatedBytes estimates it. A generated document counts its memo table, and a typed generated document an estimate of its retained memo slots and entries.

Statistics

Operation Behavior
doc.Stats() ParseStats of the last parse. Evaluated counts rule bodies run, MemoHits and ResumedElements count the two kinds of reuse, and Reused is their sum
doc.CacheStats() Point-in-time counts of the retained reuse cache, read by the owner of the document
doc.ResetHistory() Drops memo, repetition and reusable parser history and keeps the text, the version, the construction options and the last statistics. The next parse starts fresh. No threshold applies; the caller chooses when to reset. Nodes returned earlier stop moving through reuse; movement from parses before the reset is not undone

CacheStats has the fields LiveMemoEntries (memo entries linked for reuse), RetiredMemoEntries (retired entries retained for reuse), RepetitionElements (elements in resumable repetition runs) and EstimatedBytes (approximate cache-owned backing storage). All four are zero immediately after ResetHistory. EstimatedBytes excludes the text, caller-held result trees, shared strings, shared expectation, error and environment payloads, map buckets and allocator overhead; it is neither process heap use nor a limit.

Snapshots

doc.Snapshot(opts...) captures the current text revision, parse outcome and value graph in one immutable Snapshot. It resolves invocation overrides once over the construction defaults, with the same variable and fixed options as Parse. Parsing and freezing use the same cancellation context and the same cumulative spend counter. Copying the text, freezing nodes and fields and copying diagnostics are part of that invocation. A snapshot MAY share immutable records with the previous one of the same document; whether it does is not observable except in memory, and the Compute it charges is the same whether or not the previous snapshot is still alive: it is a function of the document and of the new graph alone.

A normally returned parse outcome produces a snapshot, including an ordinary syntax error and a recovered error. For an ordinary syntax failure the snapshot keeps the text and version, has a zero root as Document.Parse does, and exposes a defensive copy of the SyntaxError. A recovered outcome keeps its root and SyntaxErrors. A parse that nests deeper than the depth limit is a normally returned outcome too: the snapshot keeps a copy of its LimitError of kind LimitDepth. Cancellation or an exhausted compute or memory limit during parsing or freezing returns a nil snapshot and a fatal interruption error, which grammar choice, predicates and recovery cannot absorb. No partial graph, text or diagnostics are published. If execution began, reusable execution state is cleared before retry; completed input tables MAY remain and partial tables are discarded. An error before execution keeps existing caches and statistics. Cleanup is not charged. A trace callback panic propagates unchanged after cleanup. Snapshot accessors and Materialize run after capture and do not inherit its context or compute limits.

Accessor Meaning
snapshot.Root() The captured root, a SnapshotNode
snapshot.Text() The exact text of the revision
snapshot.Version() The revision token
snapshot.Error() The diagnostic of that revision
snapshot.Materialize() A new independent mutable *Node graph. Each call creates a separate graph

SnapshotNode is a read-only handle. Its zero value represents a nil node. Kind, Len and Value answer as Node.Kind, Node.Len and Node.Value do for the node that was frozen (Node Model), and each takes constant time: Kind is what the node stands for, Len is ChildCount for a tuple or list and 0 for any other node, and Value is the value of a KindValue node or the string of a KindString node and nil for any other. On the zero value Len is 0 and Value is nil, and Kind panics, as Node.Kind does not accept a nil node. ChildCount and Child address the elements of a tuple or list node, and ChildCount includes nil slots. Field(name) returns a value and a presence flag that distinguishes an absent field from a present nil value; a typed nil *Node field becomes a zero handle and an untyped nil stays nil. Fields() returns an owned slice of SnapshotField values, each a Name and a Value, in original order. Handles and snapshots are immutable and safe for concurrent reads while the document has one editing and parsing owner.

Freezing preserves shared node identities, cycles, nil child slots and nil versus allocated-empty collections. It accepts field values of dynamic type nil, int, string, bool and *Node, including a typed nil *Node; a boxed value may have type nil, int, string or bool. Any other dynamic type returns no snapshot and a *SnapshotCaptureError that contains the deterministic path and the reflect.Type, without retaining the unsupported value; the error also carries a defensive copy of the ordinary parse error, if one existed, and preserves errors.Is and errors.As behavior for it. Materialize preserves identities, cycles, nil slots and nil versus allocated-empty collections.

Interruption

A cancellation or option error detected before execution touches reusable state preserves valid caches and the last statistics. Once execution starts, an interruption clears memo and repetition state before the next attempt, because entries can depend on unfinished left-recursion work and a result that was being moved in place can be left partly moved. Fully completed input tables MAY be retained; incomplete tables are never published. The text and options stay available for retry or editing. A retry with fresh controls MUST produce the result of parsing the current text from scratch. Syntax errors and recovered errors are completed outcomes and keep their reusable caches.

Reuse

Reuse is a performance property, not a result property. An implementation MAY retain, shift, drop or recompute any intermediate result, provided that every parse returns what a parse of the current text from scratch returns. Reuse is observable only through the statistics. A lookup that finds a memo entry applies the edits since the entry was stored or last found, and counts one unit of Compute for each edit it applies, against an explicit Compute limit only (Default Limits). An entry that lags behind by more than 128 edits is treated as absent and the call evaluates again, so a lookup applies at most 128 edits and the linear cost proof bounds their work by that constant. An edit applies itself at once only to the entries at the positions it replaced (Reuse Model), so it costs time in proportion to them and to its distance from the previous edit, not to the memo. The number 128 is where reuse stops paying when the edits are spread over the whole text; it is one constant shared by every backend, and every backend counts the lag of each entry from the parse that stored it or last found it.

A result that read the growing result of a left recursion in progress when it started depends on that growth, not only on the text. A parse keeps it only while the growth at its position lasts (see Evaluations of Rules), so a later parse evaluates it again, even when the text is unchanged. A result that a later parse reuses read no such growing result.

Reuse Model

The engine and the generated runtimes reuse the results of a Document parse in the following way. Wherever a rule below keeps a result, evaluating again would give the same result; wherever it does not, the parse evaluates again. Reuse states the guarantee that results do not change.

Slots. Slot i of a text of length n is the character at position i when i < n, and the end of the text when i = n. A terminal, a character class, ., an anchor or the decoding of a character examines a slot when its result depends on what the slot holds:

  • matching a character examines its slot, and rejecting one examines it too;
  • testing for the end of the input or of a line at i examines slot i;
  • testing for the beginning of a line (^) or of the input (^^) at i examines slot i − 1, or at i = 0 the absence of one, written slot -1;
  • decoding the character at position i in bytes examines the bytes from i up to the first that completes it or makes it invalid, or slot n when the text ends inside a valid prefix of a character, and no byte before i.

In bytes, a slot is a byte, and only what decodes a character examines more than one slot at a time: a character class, ., and the U+FFFD of a literal, which matches one invalid byte. Any other character of a literal is compared byte by byte with its UTF-8 encoding, so a literal that differs at a byte examines no byte after it, and testing for the end of a line examines the one byte at i. Skipping an alternative or a call by the character at i is a shortcut of evaluating it and examines what the evaluation would.

Examined range. The examined range of an evaluation is the interval [l, h) from the least to one past the greatest slot that it, or a call within it, examined; an evaluation at p that examined no slot has the empty range [p, p). For an evaluation at p, l ≤ p ≤ h. Every failure that an evaluation records is at a slot that it examined. The range is sound: every slot whose content can change the outcome of the evaluation lies in it, so an edit that changes only slots outside it leaves that outcome as it was. A Document may record a smaller l; that only drops more entries and resumes fewer iterations. Every Document records h exactly, one past the greatest examined slot.

Position-free evaluations. An evaluation is position-free when no action or predicate in it, or in a call within it, reads a position (the .Start and .End members), and its outcome has no recovered errors, whose lines and columns depend on positions. Shifting the outcome of a position-free evaluation by δ adds δ to its end, to the ranges of its nodes and to its farthest failure.

Entries under edits. At each edit that replaces [a, b) and changes the length of the text by δ, a memo entry with recorded range [l, h) is:

  • kept unchanged if h ≤ a;
  • shifted by δ, together with its position and its range, if l ≥ b and its evaluation was position-free;
  • dropped otherwise.

A backend may drop an entry that these rules would shift: the typed memo of a generated Go parser (ParseValue) drops one whose value holds a value other than a basic value, which it cannot move. The values of Parse are nodes and basic values, which every backend moves.

Edits are applied to an entry in order, either all at once or when the entry is next looked up. Every backend applies them to an entry when a lookup finds it, and at once to the entries at the positions a to b, both included. An entry found to be dropped may stay where it is, where no lookup returns it, until a store under its key replaces it, a later edit whose positions include its position drops it, a walk of its chain finds that it lags behind by more than 128 edits (Work of a Document Parse), or the whole memo is dropped. A batch is one edit for the text and drops every entry and run (Edits).

Results that are stored. A parse stores entries under the rules of Evaluations of Rules, except that it also memoizes the rules that the first exception there leaves unmemoized in an ordinary parse (the transient rules); since a leader is memoized in every case, no leader is memoized only by a Document. A result that read the growing result of a left recursion is dropped within the parse and never reaches a later one. A parse that does not complete, because it is interrupted or aborted by a run-time error of an action, the nesting limit or another fatal error, drops the memo entries and the runs, and publishes no partial table.

Runs. A run record of a repetition at p holds, for each iteration that matched, its start, its end, its examined range, its value, and its farthest failure with its expected items. A Document may record only runs of at least a minimum number of iterations.

  • Recording. A run is recorded for a repetition that matched outside a lookahead and a skip, whose element has no predicate, calls no rule that reads variables, and writes no capture to an enclosing scope. No recovered error remains at the end of the run. During the run no call read the current result of a growth, directly or through an entry stored by a call that did, even of a growth that started and ended within the run, nor reused a result that read one; a run during which such a read or reuse happened is not recorded.
  • Resuming. A repetition resumes a record only outside a lookahead and a skip, in one of two ways. Whole: the record of the same repetition at the same position, stored earlier in the same parse, or by an earlier parse of the same text with no edit since; it reuses every recorded iteration. Across one edit: the record of the previous parse when exactly one edit of [a, b) by δ came since, stored at p when p ≤ a, or at p − δ when p ≥ b + δ; at a position between them no record is resumed. It reuses the recorded iterations from the first on while their examined range ends at or before a, whatever δ is. It then evaluates iterations, possibly none. When the current position is s + δ for the start s of a recorded iteration j such that every recorded iteration from j on examined only slots at or after b, it reuses those iterations shifted by δ, which requires δ = 0 or position-free iterations. After the reused iterations it goes on as a repetition does.

Work of a Document Parse

A Document parse, on every backend, does work that a parse of the same text from scratch does not: it applies pending edits, walks and indexes the chains of memo entries that earlier parses left, moves or copies the values it reuses, works through the records of runs, grows the memo table, copies diagnostics and decodes the characters of its text. None of this work is an event of the parse (Cost): no Compute limit, the default or an explicit one, counts it, and it does not change the units that a parse reports, so a parse reaches the same decision on the same limit whichever way a backend does it: moving a value, copying it, applying an edit at once or when a lookup finds the entry. What a parse counts is its calls, their keys and the other events of the table in Cost; a result that it reuses counts one call and its key, whatever the work to bring it up to date.

This section bounds that work instead, in units of work: the steps that an implementation makes and that the polls for cancellation and the memory limit count, as they count the steps of any parse. Each bound is an upper bound: an operation may do less. The bounds are what keeps the time of a Document parse proportional to what the parse counts, plus the bound of each operation, even though no limit counts the work. The generated runtimes keep no runs (Reuse); a run's work is not covered for them until they resume runs. The generated TypeScript runtime still counts its Document work against an explicit Compute limit until it leaves that work out as the engine and the generated Go runtime do.

The work is a function of the logical state, as for every parse: the same Document after the same operations does the same work for its next parse.

A chain is the sequence of memo entries at one position, live or dropped (Reuse Model), in the order a lookup passes them. An entry lags when it lags behind by more than 128 edits, the entry that a lookup treats as absent (Reuse).

Edits. An edit does no work that a parse counts. A Document keeps a log of the edits since its memo was last dropped. The edit that finds 65,536 edits in the log drops the memo entries and the run records and empties the log instead of adding to it, so a parse finds at most 65,536 pending edits.

Lookups. A lookup counts nothing for finding an entry: the call of the rule paid for the lookup of its key (Cost), whatever the lookup compares. The work of a lookup stays bounded by that payment:

  • it passes the entries of the chain, compares the keys of the entries of the same rule (a lookup of a rule that only a Document memoizes compares strings by identity), and removes each lagging entry that it meets from the chain without comparing it; each entry is removed once, after the counted call that stored it;
  • it compares at most 32 entries that do not lag; on a chain that holds more, a lookup of a rule that a parse from scratch memoizes too then removes every lagging entry of the chain, builds the index of the position if it has none, hashes its own key and probes the index, comparing its key with at most as many entries as the chain holds. A lookup of a rule that only a Document memoizes stops after the 32 entries and misses;
  • building an index hashes the key of each entry of the chain. Only an edit and the removal of a lagging entry drop the index of a position, so a parse builds the index of a position at most once;
  • when the entry it finds does not account for every edit of the log, it applies the pending edits to the entry, one unit of work for each, at most 128 (Reuse), since an entry that lags is never found. This is the only work of a lookup beyond the bound above, and no limit counts it.

Stores. A store does only bounded work: it walks and indexes the chain as a lookup does to find the entry it replaces, and links the new entry. When the entry it replaces lies beyond the first 32, it walks the chain up to it; when it lies among them and the position has an index, it hashes the key it replaces. A store of a rule that only a Document memoizes walks at most 32 entries, as its lookup does, and when none of them is the entry it replaces, it links the new entry in front of the chain and replaces none. A store never narrows the calls that the entry it finds answers (Evaluations of Rules): when that entry was computed outside a lookahead and the new one inside one, it keeps that entry and links nothing. In the reference implementation it first applies to that entry the edits that it does not account for, as a lookup does; an entry that cannot take them is replaced, and so is an entry whose value an edit shifted and the generated typed Go code cannot move. A store at a position beyond the slots of the memo table grows them, which counts nothing, as in any parse (Cost).

Moves. A backend either moves the value of an entry that an edit shifted or copies it; the bound below is the engine's, and a copy of the same value is bounded by the same number of units, one for each node and one for each child and field it copies. A lookup that finds an entry whose value an edit shifted (Reuse Model) moves the value, once: the entry then accounts for every pending edit. A move makes one pass over the value. It does one unit of work for each node it visits and one for each child and field of it. It does not visit a node that starts where it ends (an empty node) in place: it copies it for the move, with the empty nodes below it, and does the copy as a visit and at most one more unit of work to forget it at the end; a reference to a node that the move has already copied costs one unit and copies nothing. A node that does not start where it ends is moved in place, and a move does not visit a node that this parse built or has already moved, so such a node moves at most once in a parse. Each node of the value accounts for the edits up to the parse that last moved or built it. For the nodes that account for the same number of edits, the move replays the edits that they do not account for once, at one unit for each, and does at most one unit to forget them at the end. A move therefore does at most two units for each node it visits, counting an empty node once for each reference by which it reaches it, and for each child and field of those nodes, plus one unit for each edit it replays.

Runs. The operations of a repetition that may resume a record (Reuse Model) merge the expected items of an iteration into those of the farthest failure. The operations of runs reserve no unit on any backend, and a resumed element is no event: its work is bounded in steps, as follows, but no limit counts it. A merge takes one step for each item, and, when the Document records expected items (WithExpectations), at most one more step for each item that the record of the farthest failure holds when it adds the item: it may look for the item among them. That record holds each item at most once, so a merge does at most one plus the number of distinct expected items of the grammar for each item it merges. The operations take:

  • starting the run, and starting the evaluation of an iteration: nothing;
  • each attempt to reuse the next recorded iteration: one step, and when it reuses one, the merge of its expected items, and, for an iteration after the edit, the move of its value;
  • ending an evaluated iteration: the merge of its expected items, and, when it matched, at most two steps for each expected item that it records (it compares them with the last set of expected items that the parse kept and copies them unless the two are the same) and, when the number of new iterations that it then holds is a power of two, the number that it held before;
  • looking for a recorded iteration after the edit, before an iteration after the edit is evaluated: one step for each recorded iteration that it passes. Scanning recorded iterations charges nothing; each recorded iteration is scanned at most once per parse, by the search for the iteration that starts where the next one would, and at most once more by the check that it and the iterations after it examined only input after the edit, since the search resumes where it last stopped and an iteration that fails the check bars every later look up to it; when it passes them all the run reuses them;
  • keeping the values of the iterations that it reuses: one step for each, and growing the stack of values as any parse does;
  • recording the run when it ends: one step for each iteration, and nothing for a run too short to record.

A reuse, and each recorded iteration that the look for an iteration after the edit passes, counts toward the interval at which the parse observes its context and its memory limit (Reservations and Interruptions), as a unit does, without charging it.

A parse resumes a record of the previous parse at most once: resuming it removes it from the records that the parse can resume.

This work of growing storage is a function of lengths and of the operations of the parse: the capacity that earlier parses left in storage that the Document keeps for its next parse changes no work.

Decoding. A parse in Bytes positions that decodes a character of the text of a Document does, besides the unit of a parse from scratch, one unit of work for each further byte that it reads for the decoding: at most three more units for each examination of the input.

Change Notifications

Notifications are off by default. doc.EnableChanges(limit) turns them on for one document before the edits and parses to be observed. The positive limit bounds the number of queued events; it does not bound the bytes of replacement text or the size of the comparison snapshot. Enabling twice is rejected. doc.DrainChanges() transfers owned records out and clears the queue. Tracking retains one comparison snapshot. A record is a DocumentChange: its Kind (an input.DocumentChangeKind), the versions From and To, the position Unit, the Edits of an edit event as input.TextEdit values, FullRefresh, the conservative Invalidated and Reevaluation of an edit, and the Output comparison of an outcome (an input.OutputChange).

There are three kinds of event.

Kind Meaning
ChangeEdit An accepted edit or atomic batch. From is the coordinate base and To the resulting source revision. Batch edits remain simultaneous replacements in the base coordinates and original order. Failed operations and empty batches emit nothing. Identity edits still advance the version and emit an event
ChangeOutcome A Parse or Snapshot outcome. From identifies the preceding comparable capture and To the current revision. It MAY cover several previously delivered edits and does not advance an edit-replay cursor, so source revisions and displayed-output revisions are tracked separately
ChangeFullRefresh Replaces history that overflowed the limit. Consumers rebuild from the latest state; the marker cannot reconstruct dropped edits or intermediate comparisons. A gap in edit revisions also requires a rebuild

Edit events mark the whole output conservatively invalidated, and their re-evaluation is reported as unknown, because invalidation and memo statistics cannot establish execution ranges. Notifications never promise minimal tree differences.

The first capture reports OutputMayHaveChanged. Later complete captures report OutputUnchanged or a conservative OutputChanged, comparing immutable node metadata, positions, string text, elements, scalar fields, syntax diagnostics and graph sharing. Alias topology and nil versus empty collection differences count as changes; this is a refresh policy and not language value equality. Unknown non-syntax diagnostic types count as changed. Source text and parse statistics are not part of output equality.

With tracking enabled, both Parse and Snapshot capture and compare, using the invocation's cumulative context and compute limits. A cancellation or compute limit interruption returns nil and emits OutputUnavailable, which clears comparison continuity: the next successful capture reports OutputMayHaveChanged. Completed syntax failures stay comparable. Unsupported captures also report unavailable.

Snapshots that consumers retain stay immutable. Parse still returns its mutable Node, which later parses of the document can change; a Snapshot never changes. The To of a ChangeEdit is the document version after the edit, and the To of a ChangeOutcome is the document version when the Parse or Snapshot ran. The version of the latest outcome can therefore be older than the version of the latest edit: edits that follow an outcome are not part of it.

Validation and Errors

Condition Result
NewDocument with Recognize, an unavailable backend or an unknown start rule Error; no document
A grammar that uses #missing, or a WithMissingTokens limit other than zero, in NewDocument or Parse Error; no document or result
Edit range outside the text, or inside a character in Bytes Error; text and version unchanged
EditBatch with a foreign or stale version, unordered or overlapping edits, repeated starts or invalid ranges The whole batch is rejected
Parse option that changes unit, backend, start rule or mode Error before execution; caches and statistics kept
Cancellation, or a compute or memory limit, during Parse Error and no result; execution state cleared
Cancellation, or a compute or memory limit, during Snapshot Nil snapshot and a fatal error
Unsupported field value type while freezing Nil snapshot and *SnapshotCaptureError
EnableChanges twice Error
Stream diagnostic options (WithDiagnosticCallback, WithDiagnosticLimit) Rejected

Compatibility and Support

All three engine backends and both position units support documents. Generated Go parsers provide an opt-in Document with NewDocument, Text, Edit, Parse, Stats and Node.Clone, and, with typed values, Document.ParseValue; they have neither EditBatch, Version, Unit, Snapshot, CacheStats, ResetHistory nor change notifications. Parse reuses memoized results and resumes runs as the engine does, and their Stats counts both; ParseValue keeps a typed memo of its own, which resumes no runs. Generated TypeScript parsers provide an opt-in Document with createDocument, text, bytes, edit, parse, stats and, with typed values, parseValue. text and bytes return the current text as doc.Text() defines it, in CodePoints with each invalid UTF-8 byte replaced with U+FFFD. It reuses the memoized results of earlier parses as the generated Go Document does but resumes no runs, and its stats has only evaluated and reused. See Generated Parsers.

Conformance

The behavior is established by the document tests of the repository, which compare random edits with fresh parses, and by the edit fuzzer of sxir edit-fuzz, which compares every reparse with a fresh parse.