zigsyn

zigsyn is a pure Rust scanner and parser for Zig source code. It parses Zig syntax into a structured AST while preserving token-level information for lossless inspection.

The parser is driven by the bundled spec/grammar.peg snapshot from ziglang/zig-spec.

API documentation is available on docs.rs.

Features

• Pure Rust scanner and parser for Zig syntax.
• Public helpers for parsing source strings, individual files, and directories.
• Structured AST types exposed through zigsyn::ast.
• Structured syntax errors instead of unparsed token buckets.
• Optional serde support for AST and token data.
• Grammar snapshot and deviation notes kept under spec/.

Installation

Add zigsyn to your Cargo.toml:

[dependencies]
zigsyn = "0.1"

To enable serialization support:

[dependencies]
zigsyn = { version = "0.1", features = ["serde"] }

If you are using this repository directly:

[dependencies]
zigsyn = { path = "../zigsyn" }

Usage

Parse a source string:

fn main() {
    let file = zigsyn::parse_source("pub fn main() void {}")
        .expect("valid Zig source");

    assert_eq!(file.members.len(), 1);
}

Parse a file:

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let file = zigsyn::parse_file("src/main.zig")?;
    println!("top-level members: {}", file.members.len());
    Ok(())
}

For lower-level control, construct a parser directly:

let mut parser = zigsyn::Parser::from("1 + 2 * 3");
let expression = parser.expression().expect("valid Zig expression");

API Overview

• zigsyn::parse_source(source) parses a string into ast::File.
• zigsyn::parse_file(path) parses a .zig file into ast::File.
• zigsyn::parse_dir(path) parses direct .zig children of a directory.
• zigsyn::Parser exposes lower-level parsing entry points.
• zigsyn::scanner::Scanner exposes tokenization.

Project Layout

• src/ast.rs: AST definitions.
• src/scanner.rs: Zig tokenizer.
• src/parser.rs: parser implementation.
• src/token.rs: token and operator definitions.
• spec/: grammar snapshot and deviation notes.
• tests/: integration and fixture-based tests.
• benches/: Criterion benchmarks.
• fuzz/: cargo-fuzz target.
• CHANGELOG.md: release notes.

Development

Run the standard checks:

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features

Run benchmarks:

cargo bench

Run the fuzz target with cargo-fuzz:

cargo fuzz run parse_source

Specification

The active grammar snapshot is documented in spec/README.md. Accepted grammar deviations and implementation decisions are tracked in spec/DEVIATIONS.md.

License

Licensed under the MIT License.