The SyntaxIR Specifications

SyntaxIR is a parser framework built around a grammar language that extends PEG (Parsing Expression Grammar). Its behavior is defined by several specifications, each with its own contents and chapter numbering. Together they describe the syntax and meaning of .sxir grammar files, the results of parsing input with them, the contracts of the runtimes that execute them, and the internal representations that the engine builds from a grammar. A specification may link to another where it relies on it; apart from those links and the publications of the standards that they cite (RFC 2119, for the key words of the conventions), they link to nothing else.

Specifications

Specification Defines
Grammar Language The syntax and meaning of .sxir grammar files: lexical structure, types, rule expressions, Operators Rules, predicates, actions, attributes, pragmas and the checks the compiler applies
Parser and Runtime Parsing input with a grammar: positions, results, errors, the node model, Documents, streaming, tracing and profiling, compiled grammars, generated parsers, output schemas, the linter, input generation, edit fuzzing and the Go packages
Core IR The intermediate representation of a checked grammar: its modules, nodes, action expressions, effects, invariants and text form
Code IR The base of the form that a grammar is compiled to: modules, functions of structured code, dialects and stages, invariants and text form
Flow Dialect The operations that say how a parser runs a rule, at the Flow stage of Code IR: functions, operations, invariants and passes
Exec Dialect The abstract machine and its programs, at the Exec stage of Code IR: the state of a parse, the operations on it with their contracts, the compositions every runtime shares, and their conversion, passes and printing
Bytecode The portable bytecode that a grammar compiles to, the virtual machine that runs it and the .sxirc file format
Proofs That the results the runtimes reuse are those that evaluating again would give, and the cost bounds of the mechanisms of reuse

The Glossary lists the terms of all the specifications, with the place where each is defined.

Conventions

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted as described in RFC 2119. They are used only where a requirement is normative; most of the specifications state the behavior of the language in plain declarative sentences.

Grammar examples are written in ```sxir code blocks. Output of the sxir command that an example shows is the output of running that command. Syntax summaries use angle brackets for placeholders (<name>), square brackets for optional parts ([<type>]) and | for alternatives.