Home

The Zyn Book

A comprehensive guide to building language frontends with ZynPEG.

Table of Contents

1. Introduction - What is Zyn and why use it?
2. Getting Started - Your first Zyn grammar
3. Using the CLI - Compilation, execution, and REPL
4. Grammar Syntax - PEG-based grammar rules
5. Semantic Actions - TypedAST action expressions
6. The TypedAST - Understanding the target representation
7. TypedAST Builder - Building AST nodes programmatically
8. Complete Example: Zig - A real-world grammar walkthrough
9. Reference - Command reference and API
10. Packaging & Distribution - ZPack format, AOT linking, and distribution
11. HIR Builder - Building HIR directly for custom backends
12. Embedding SDK - Embedding Zyntax in Rust applications with native calling
13. Async Runtime - Promise-based async native runtime
14. Runtime Plugins - ZRTL standard library plugins (I/O, FS, Net, Thread, etc.)
15. Building DSLs - Creating domain-specific languages with Zyntax
16. Tutorial: Image Pipeline DSL - Step-by-step DSL tutorial with working example

Quick Start

# Build zyntax
cargo build --release

# Compile and run a Zig file using the zig.zyn grammar
./target/release/zyntax compile \
    --grammar crates/zyn_peg/grammars/zig.zyn \
    --source examples/hello.zig \
    --run

# Start an interactive REPL
./target/release/zyntax repl --grammar crates/zyn_peg/grammars/zig.zyn

What is Zyn?

Zyn is a Parser Expression Grammar (PEG) system that combines:

1. Packrat-memoized PEG parsing - O(n) parsing with named bindings
2. TypedAST semantic actions - Direct AST construction at parse time
3. TypedAST target - A universal, typed intermediate representation

Instead of writing imperative code to build AST nodes, you write typed construct expressions that mirror Rust struct/enum syntax:

Example

// Atomic rule (@) captures matched text automatically via the binding name
integer_literal = @{ "-"? ~ ASCII_DIGIT+ }
  -> TypedExpression::IntLiteral { value: integer_literal }

This single rule:

• Parses signed integers
• Captures the matched text automatically (no get_text needed)
• Constructs a TypedExpression::IntLiteral node directly