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 - JSON command blocks
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

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. Pest-compatible grammar syntax - Familiar PEG rules for parsing
2. JSON semantic actions - Declarative AST construction
3. TypedAST target - A universal, typed intermediate representation

Instead of writing imperative code to build AST nodes, you declare what to build using JSON command blocks attached to grammar rules.

Example

// Grammar rule for integer literals
integer_literal = @{ "-"? ~ ASCII_DIGIT+ }
  -> TypedExpression {
      "get_text": true,
      "parse_int": true,
      "define": "int_literal",
      "args": { "value": "$result" }
  }

This single rule:

• Parses signed integers
• Extracts the matched text
• Converts it to an integer
• Creates a TypedAST literal node