Parsuna

Parsuna is a parser generator. You write a grammar in a small, regular-like DSL and it emits a pull-based, recoverable parser in the target language of your choice. The generator supports Rust, Python, TypeScript, Go, Java, C#, and C; every target shares the same event model, so a program that consumes a parse in one language is structurally the same in every other.

This manual is split into three parts:

• A language-agnostic user guide covering the grammar DSL, the CLI, and the event stream consumers iterate over.

• A pipeline reference that follows one grammar from source through parsing, analysis, lowering, and code generation, documenting the data each pass produces.

• Backend-shaped appendices for mapping the shared event stream to idioms in each target language.

User guide

• Introduction
  • What parsuna gives you
  • Design principles
  • Where to go next
• The grammar language
  • Declarations
  • Token patterns
  • Rule expressions
  • What the grammar cannot express
  • Fragment rules and tokens
  • Naming conventions and reserved names
• Using parsuna
  • The CLI
  • The shape of a generated parser
  • A minimal driver
  • Starting from a rule other than the default
  • Typical integration workflow
  • Tokens, skips, and whitespace
  • Interpreting token text
• The event model
  • The four events
  • Ordering guarantees
  • Building a tree from events
  • Skip tokens
  • The Pos and Span types
  • Reserved token kinds
  • Error recovery, observably

Pipeline

• Pipeline
  • Pass 1 — Grammar parsing
  • Pass 2 — Analysis
  • Pass 3 — Lowering
  • Pass 4 — Code generation
• Pass 1 — Grammar parsing
  • Input
  • Bootstrap
  • The Grammar IR
  • Where the distinction matters
  • Error collection
  • Post-conditions
• Pass 2 — Analysis
  • Diagnostics
  • Sub-pass 2a — Structural validation
  • Sub-pass 2b — Post-validation lints
  • Sub-pass 2c — Iterative FIRST/FOLLOW at the smallest viable k
  • Conflict detection
  • The AnalyzedGrammar
  • Why both follow and follow_k
  • Output
• Pass 3 — Lowering
  • The StateTable
  • The lexer DFA
  • The state-machine op set
  • Sub-pass 3a — Build
  • Sub-pass 3b — Layout
  • Sub-pass 3c — Fuse
  • Interactions between build, layout, and fuse
  • What comes out
• Pass 4 — Code generation
  • Inputs
  • The shape each backend produces
  • The state-dispatch function: how ops become code
  • The compiled lexer DFA
  • Shared helpers
  • Differences between backends
  • The tree-sitter backend
  • Putting it all together

Indices

• Index

• Search Page