zsuite

A toolkit for building programming languages in Python: syntax, checks, execution and editor support.

Programming languages, DSLs and data formats, from a grammar to a fast implementation with an editor. Each stage is its own package, usable alone; together they cover the whole way.

Installation

pip install zsuite-py              # the four packages, at versions that work together
pip install "zsuite-py[exe]"       # and what building executables needs

The import names are zgram, zrules, zrun and zlsp (each can also be installed alone as <name>-py). Wheels cover CPython 3.10+ on x86_64 Linux and Windows.

Quick start

zsuite new calc        # a language project: grammar, rules, semantics, language server, tests
cd calc
python calc.py run fib.calc        # run a program, compiled to native code
python calc.py check fib.calc      # its errors and warnings
python calc.py lsp                 # a language server for your editor
python -m pytest test_calc.py      # its tests

The project is the tutorial's language under your name: change the grammar in syntax.py, the rules in checks.py, what each construct does in semantics.py, and the editor's view in server.py.

How they fit

source ──zgram──▶ parse tree ──zrules──▶ checked tree + symbols + types ──zrun──▶ running program
                                   │
                                   └──zlsp──▶ editor (diagnostics, go to definition, hover, ...)

• zgram turns text into a tree: a grammar in, a parser out (zgram.compile(grammar)), its nodes labelled with what the grammar names them.
• zrules checks the tree: rules written as selectors over node kinds ("break_stmt" inside a loop, each name defined once in its scope, the types of expressions), reported as diagnostics with source positions.
• zrun runs it: a semantic per node kind, plain Python taking the node and the runtime; zrun compiles the semantics for the program's tree to native code, so the language runs at a fraction of a hand-written interpreter's speed.
• zlsp serves it to editors: the grammar and the rules are all it needs.

Versions

Each package is released on its own; these are the current ones, which work together:

Documentation

• Tutorial: building a language through all four stages, from grammar to editor and executable.
• Best practices: grammars that recover well, rules, semantics that compile fast, testing, shipping.
• Design: how the suite fits together, its decisions and its roadmap.
• Each package's README is its reference.

Project Structure

src/zsuite/          # the zsuite package: versions(), `zsuite new`
examples/tiny/       # the tutorial's language: one file per stage, and its tests
                     # (also `zsuite new`'s template)
docs/                # the tutorial, best practices, the design
tests/               # the package's tests

License

MIT