Crate sipha 

sipha

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

Crate layout

• parse — grammar builder, VM engine, IR (Insn), codegen, memoisation.
• tree — green/red syntax trees, trivia, walking, optional emit/transform.
• diagnostics — spans, line index, ParsedDoc, parse and semantic diagnostics.
• types — Span, SyntaxKind, char classes, tree events.
• extras — optional tools (display, fmt, diff, …), feature-gated.

Use prelude for the usual names in one import, or import from the modules above.

Quick start

use sipha::prelude::*;

let mut g = GrammarBuilder::new();
g.rule("start", |g| {
    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 diagnostics::line_index and diagnostics::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 tree::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 the Cookbook in the repository at sipha/docs/COOKBOOK.md (rendered on GitHub).

Modules

diagnostics

Diagnostics, spans, line indexing, and error formatting.

extrasstd

Optional higher-level utilities (feature-gated).

parse

Parsing-related APIs (grammar builder, engine, VM IR, memoisation).

prelude

Commonly used types. For granular imports, use parse, tree, or diagnostics.

treestd

Syntax tree types and utilities (green/red trees, trivia, display).

types

Macros

assert_parse

Assert that parsing input with parse_fn produces a tree matching expected_sexp.

choices

Convenience macro for GrammarBuilder::choices.

sipha_grammar

Expand a PEG grammar DSL into code that builds a sipha BuiltGraph.

Derive Macros

AstNode

Derive sipha::tree::ast::AstNode for a tuple-struct wrapper around SyntaxNode.

SyntaxKinds

Derive IntoSyntaxKind and FromSyntaxKind for an enum of syntax kinds.