SyntaxIR Parser and Runtime Specification

This specification defines what happens when a compiled grammar meets input: the start rule, positions, results, syntax errors, the node and value model, incremental documents and streaming, and the tools around a running parser: tracing, compiled grammars, generated parsers, output schemas, the linter, input generation and edit fuzzing, and the Go packages that provide them. The grammars themselves are defined by the Grammar Language Specification; the portable instruction set that a grammar compiles to is defined by the Bytecode Specification.

Behavior described as supported in this specification is implemented. Features proposed but not yet implemented are marked "(not implemented)".

Contents

The chapters are in two groups, in reading order: each builds on the ones before it.

Parsing and Results

Running a grammar on input and the results it produces, for whole texts, edited documents and streams.

Chapter Defines
1 Parsing A parse as a whole: the start rule, input and positions, results, syntax errors, memoization, prefix parsing, time and memory, limits and modes
2 Nodes and Values The value and node model, source information, the Go Node type, traversal, and the text and JSON renderings
3 Incremental Documents Editing and reparsing text: versions, snapshots, interruption and change notifications
4 Streaming Parsing a reader and delivering the elements of a #stream repetition as they match

Tools and Formats

Observing a parse, saving and generating parsers, describing their output, checking grammars, testing them with generated inputs and edits, and the Go packages of all of these.

Chapter Defines
5 Tracing and Profiling Rule tracing and profiling of the engine and of generated parsers
6 Compiled Grammars Saving and loading .sxirc files, their modes and the operations each serves, versions and loading checks
7 Generated Parsers sxir gen: the Go and TypeScript parsers, their APIs and what each supports
8 Output Schemas and Structural Queries Describing the output of a grammar and searching result nodes (experimental)
9 Grammar Lint The checks of the linter, severities and suppression directives
10 Fixture Suites and Edit Sequences The JSON formats of sxir test suites and sxir edit-fuzz saved sequences
11 Input Generation Generating inputs that a grammar accepts, near-miss inputs that it rejects and coverage: the options and the sample package
12 Edit Fuzzing Checking incremental parsing against fresh parses with generated edit sequences: the checks, failures and the editfuzz package
13 Go Packages The public Go packages, what each is responsible for and where it is defined, the runtime and compiler sides, and the compiler package

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

Conventions

The conventions of the specifications apply.