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.