Crate sipha 

sipha

A PEG (Parsing Expression Grammar) parser with a stack-based VM, green/red syntax trees, and optional packrat memoisation.

Quick start

use sipha::prelude::*;

let mut g = GrammarBuilder::new();
g.begin_rule("start");
g.byte(b'a');
g.end_of_input();
g.accept();
let built = g.finish().unwrap();
let graph = built.as_graph();

let mut engine = Engine::new();
let out = engine.parse(&graph, b"a").unwrap();
assert_eq!(out.consumed, 1);

Compiler / formatter API

For a single handle to source, tree, and line info after a successful parse, use [ParsedDoc]: build it from ParseOutput and then use doc.root(), doc.offset_to_line_col_1based(), and doc.format_diagnostic() for errors. See examples/parsed_doc_errors.rs and the line_index and parsed_doc modules.

Tree walk (visitor, optional)

With the default walk feature, use [SyntaxNode::walk] (or the free function walk) with a [Visitor] and [WalkOptions] to traverse the red tree for formatting, scope analysis, type checking, or linting. See the walk module.

Semantic (analysis) diagnostics

For validation and other post-parse analyses, use [SemanticDiagnostic] and [Severity]. Report span, message, and severity; then format with [SemanticDiagnostic::format_with_source] or convert to miette via [SemanticDiagnostic::into_miette] (with the miette feature). [ParsedDoc] provides [ParsedDoc::format_semantic_diagnostic] so you can plug the same output style as parse errors.

Miette integration (optional)

Enable the miette feature for pretty-printed diagnostics. Then use [ParseError::to_miette_report] or [Diagnostic::into_miette] for parse errors, and [SemanticDiagnostic::into_miette] for analysis diagnostics. See examples/miette_errors.rs.

See the individual modules for details and the examples/ directory for full grammars (e.g. JSON). For common patterns (expression precedence, error recovery, byte_dispatch, trivia), see docs/COOKBOOK.md in the crate.

Modules

builder

Grammar Builder

capture

Capture Tree

codegen

Code Generator

context

Parse Context — multi-word flag bank

engine

Parse Engine

error

Error Diagnostics

expr

Helpers for building expression grammars with precedence (left/right-assoc infix levels).

green

Green Tree

green_builder

Green tree builder

incremental

Incremental reparse: reuse unchanged parts of the green tree after a text edit.

insn

Instruction Set

line_index

Line index

memo

Packrat Memoisation

parsed_doc

Parsed document

prelude

red

Red Tree

sexp

S-expression serialization of syntax trees for grammar tests.

simd

SIMD-Accelerated Literal Comparison

source_map

Span mapping (source map)

tree_display

Format a sipha red syntax tree as a readable ASCII/Unicode tree.

trivia

Trivia helpers

types

walk

Tree walk (visitor)

Macros

choices

N-way choice without Vec<Box<dyn FnOnce>>: choices!(g, |g| g.literal(b"a"), |g| g.literal(b"b")).

Derive Macros

SyntaxKinds

Derive [IntoSyntaxKind] and [FromSyntaxKind] for an enum of syntax kinds.