Galley

Appearance

Getting Started ​

Table of Contents ​

What You Need ​

  • Zig 0.16+ — the supported build toolchain
  • A terminal or shell

Your First Parser ​

The fastest path is to start with an example grammar that already ships with the repo. Run all commands from the repository root directory.

Parse existing JSON ​

sh
# 1. Generate the LL parser
zig build
./zig-out/bin/galley --parser-type ll languages/json

# 2. Run the repository API benchmark harness
zig build -Doptimize=ReleaseFast run-ll-json -- \
  languages/json/samples/code-01.json --iterations 100

That's it — languages/json/samples/code-01.json parses at hundreds of megabytes per second.

The separate json-recovery implementation demonstrates explicit recovery and custom messages while keeping the benchmark grammar minimal. Its demonstration input is intentionally malformed and exits with SyntaxError after reporting three recoverable value errors:

sh
./zig-out/bin/galley --parser-type ll --with-error-recovery languages/json-recovery
zig build run-ll-json-recovery -- languages/json-recovery/recovery-demo.json

Bootstrap a new language project ​

To turn a directory that only contains a grammar into a runnable Zig project, pass --bootstrap-zig-project. Galley writes build.zig, build.zig.zon, and src/main.zig next to the generated parser, and refuses to overwrite existing project files:

sh
./zig-out/bin/galley --bootstrap-zig-project my-language

If GALLEY_CHECKOUT is set to a Galley working tree, build.zig.zon depends on it with .path and does not run zig fetch.

Bootstrapping is off by default; pass --bootstrap-zig-project to create the minimal project. That scaffold is a stub runner for your grammar, using the same addParserModule helper as the rest of the Zig API. The native runtime showcase (the same demo as the language bindings) is examples/zig; the API manual is Using Galley from Another Zig Project.

Try the LR parser too ​

sh
# 1. Generate the LR parser
zig build
./zig-out/bin/galley --parser-type lr languages/json

# 2. Run its API benchmark harness
zig build -Doptimize=ReleaseFast run-lr-json -- \
  languages/json/samples/code-01.json --iterations 100

Next Steps ​

Now that you have verified the bundled JSON parsers work, you can run the native runtime showcase in examples/zig, learn how to use Galley from another Zig project, explore the other included languages, review the generator and runtime options, or start writing your own custom language.