Crate oak_zig 

🛠️ Zig Parser Developer Guide

This guide is designed to help you quickly get started with developing and integrating oak-zig.

🚦 Quick Start

Add the dependency to your Cargo.toml:

[dependencies]
oak-zig = { path = "..." }

Basic Parsing Example

The following is a standard workflow for parsing a Zig source file:

use oak_zig::{ZigParser, SourceText, ZigLanguage};

fn main() {
    // 1. Prepare Zig source code
    let code = r#"
        const std = @import("std");

        pub fn main() !void {
            const stdout = std.io.getStdOut().writer();
            try stdout.print("Hello, {s}!\n", .{"Oak"});
        }
    "#;
    let source = SourceText::new(code);

    // 2. Initialize parser
    let config = ZigLanguage::new();
    let parser = ZigParser::new(&config);

    // 3. Execute parsing
    let result = parser.parse(&source);

    // 4. Handle results
    if result.is_success() {
        println!("Parsing successful! AST node count: {}", result.node_count());
    } else {
        eprintln!("Errors found during parsing.");
        for diag in result.diagnostics() {
            println!("[{}:{}] {}", diag.line, diag.column, diag.message);
        }
    }
}

🔍 Core API Usage

1. Syntax Tree Traversal

After a successful parse, you can use the built-in visitor pattern or manually traverse the Green/Red Tree to extract Zig constructs like function definitions, comptime blocks, or struct declarations.

2. Incremental Parsing

Zig projects often involve many small files or frequent edits. oak-zig supports sub-millisecond incremental updates:

// Re-parse only the modified section
let new_result = parser.reparse(&new_source, &old_result);

3. Error Recovery

The parser is designed for industrial-grade fault tolerance, recovering gracefully from missing semicolons or malformed try/catch blocks to provide continuous feedback in IDEs.

🏗️ Architecture Overview

• Lexer: Tokenizes Zig source text, supporting Zig-specific features like multi-line strings, character literals, and preprocessor-like @import.
• Parser: A high-performance recursive descent parser with Pratt parsing for expressions, handling Zig’s operator precedence and complex compile-time logic.
• AST: A strongly-typed, lossless syntax tree that preserves all trivia (comments/whitespace) for refactoring and formatting tools.

🔗 Advanced Resources

• Full Examples: Check the examples/ folder in the project root.
• API Documentation: Run cargo doc --open for detailed type definitions.
• Test Cases: See tests/readme.md for details on our snapshot-based testing.

🚀 Oak Zig Parser

Pragmatic Performance for Systems Programming — A high-performance, incremental Zig parser built on the Oak framework. Specially optimized for Zig’s unique syntax, compile-time features, and modern developer tool integration.

🎯 Project Vision

Zig is designed for robustness, optimality, and maintainability. oak-zig brings these same values to the world of Zig code analysis. By leveraging Oak’s incremental parsing architecture, we provide a modern, Rust-powered infrastructure that can handle Zig’s complex compile-time features (comptime) and unique syntax with sub-millisecond responsiveness. Our goal is to empower developers to build sophisticated IDEs, build systems, and static analyzers that can navigate large Zig projects with ease, ensuring that the simplicity and power of Zig are matched by its tooling.

✨ Core Features

• ⚡ Blazing Fast: Engineered in Rust to deliver sub-millisecond parsing performance, essential for real-time developer feedback and large-scale Zig project analysis.
• 🔄 Incremental by Design: Only re-parse what changed. Ideal for the rapid iteration cycles typical of Zig development.
• 🌳 High-Fidelity AST: Generates a comprehensive Abstract Syntax Tree capturing the full depth of Zig:
  • Comptime Awareness: Precise tracking of compile-time expressions and logic.
  • Error Handling: Detailed mapping of error sets, try, and catch blocks.
  • Structs & Unions: Robust support for Zig’s data layout and memory management constructs.
  • C Integration: Seamlessly handles Zig’s C interoperability syntax.
• 🛡️ Industrial-Grade Fault Tolerance: Engineered to recover from syntax errors gracefully, providing precise diagnostics—crucial for maintaining a smooth developer experience during active coding.
• 🧩 Deep Ecosystem Integration: Seamlessly works with oak-lsp for full LSP support and other Oak-based code analysis tools.

🏗️ Architecture

The parser follows the Green/Red Tree architecture (inspired by Roslyn), which allows for:

1. Efficient Immutability: Share nodes across different versions of the tree without copying.
2. Lossless Syntax Trees: Retains all trivia (whitespace and comments), enabling faithful code formatting and refactoring.
3. Type Safety: Strongly-typed “Red” nodes provide a convenient and safe API for tree traversal and analysis.

🤝 Contributing

We welcome contributions of all kinds! If you find a bug, have a feature request, or want to contribute code, please check our issues or submit a pull request. Zig support for the Oak language framework.

Re-exports

pub use crate::ast::ZigRoot;

pub use crate::builder::ZigBuilder;

pub use crate::language::ZigLanguage;

pub use crate::lexer::ZigLexer;

pub use crate::parser::ZigParser;

pub use crate::lsp::ZigLanguageService;

pub use lexer::token_type::ZigTokenType;

pub use parser::element_type::ZigElementType;

Modules

ast

AST module.

builder

Builder module.

language

Kind definition module. Language configuration module.

lexer

Lexer module.

lsp

LSP module.

parser

Parser module.

Traits

ElementType

A trait for types that represent an element’s kind in a syntax tree.

TokenType

A trait for types that represent a token’s kind in a specific language.