Skip to main content

Module decorate

panproto_parse

Module decorate 

Source
Expand description

Put-direction of the parse / decorate / emit lens: build a decorated schema from an abstract one by routing through emit_pretty + parse. The put-direction of the parse / decorate / emit lens.

decorate attaches a complete layout enrichment fibre to an AbstractSchema, producing a DecoratedSchema that emit_pretty_with_protocol can render byte-for-byte. It is a section of the schema-level forgetful U DecoratedSchema::forget_layout at the granularity of kind- and edge-multiset equivalence (the ordering invariant — vertex IDs are reborn by the re-parse).

§Implementation strategy

  1. Render the abstract schema to canonical bytes via emit_pretty_with_policy. The de-novo emitter walks grammar.json production rules driven by the caller-supplied LayoutPolicy.

  2. Re-parse those bytes. The parse walker attaches the full layout fibre (start-byte, end-byte, every interstitial-N, chose-alt-fingerprint, chose-alt-child-kinds) and invents fresh vertex IDs.

Step 2’s ID renaming is intrinsic to the parse walker: tree-sitter reparses can consolidate or fragment tokens at boundaries that the emit pipeline doesn’t know how to mirror (e.g. lilypond’s c'4 parses as a single note even when the emitter rendered three tokens c, ', 4). Recovering vertex IDs from the abstract input by parallel walk therefore cannot succeed for all grammars; the documented section law holds at the standard granularity of kind_multiset and edge_multiset.

§Laws

For every a : AbstractSchema and p : LayoutPolicy:

  • Section law (mod kind- and edge-multiset): kind_multiset(forget_layout(decorate(a, p)).as_schema()) == kind_multiset(a.as_schema()) AND edge_multiset(forget_layout(decorate(a, p)).as_schema()) == edge_multiset(a.as_schema()), for every protocol with a vendored grammar. The edge-multiset half is the load-bearing one for sequenced data: order of notes in a Pattern<MidiEvent>, of tokens in a parsed AST, of items in a homogeneous list, would all collapse without it. Verified by the decorate_section_law integration test.
  • Policy fidelity: the bytes produced by pretty_with_protocol honour every field of p (separator, newline, indent_width, line_break_after, indent_open / close).

Functions§

decorate_with_parser
Decorate an abstract schema by routing through emit_pretty_with_policy + parse against parser.