ts-orbit

A tree-sitter grammar for the Orbit programming language.

---

⚠️ Alpha. Orbit's syntax is still evolving; this grammar tracks it and changes alongside it. Node names and fields may shift between commits.

What is this?

This repository defines the tree-sitter grammar for Orbit — the concrete parser that turns .orb source into a syntax tree. It is the parsing engine behind the official Orbit extension for Zed, and can be reused by any tree-sitter host (Neovim, Emacs, Helix, a future language server, CLI tooling, etc.).

It is a component, not an end-user product: on its own it does nothing visible. Editors and tools consume it to get accurate syntax trees, on top of which they build highlighting, indentation, folding, structural navigation, and more.

What it parses

The grammar covers the full current surface of Orbit, including:

• The complete literal set — integers (dec/hex/oct/bin, signed & unsigned), floats, chars, normal / raw (r"…") / bytes (b"…") strings, atoms (@name), booleans, nil
• Classes, traits, impl, init/cleanup, visibility (pub/prot/weak), const/async modifiers, decorators (@[ … ])
• Functions with default / keyword / variadic parameters, anonymous functions
• Control flow — if/elif/else, loop, for … in, switch with fallthrough, labeled loops, defer, try/catch/finally, sync
• Concurrency — spawn, await, channel send/receive (<-), pipelines (|>)
• Null-safety operators (?., ??, ?:) and a precedence-correct expression grammar (Pratt-style, mirroring the language's operator precedences)
• FFI — both single native func … from "lib" declarations and the grouped native from "lib" { … } block form
• Modules — import with aliasing and selective imports

Layout

ts-orbit/
├── grammar.js        # the grammar definition (edit this)
├── package.json      # tree-sitter package metadata
└── src/              # GENERATED — do not edit by hand
    ├── parser.c      #   the generated parser
    ├── grammar.json  #   grammar in JSON form
    ├── node-types.json
    └── tree_sitter/  #   runtime headers

grammar.js is the single source of truth. Everything under src/ is produced by the tree-sitter CLI and committed so that consumers (like Zed) can compile the parser without a JS toolchain.

Usage

In Zed

You don't use this repo directly — the Orbit Zed extension references a specific commit of it in its extension.toml and compiles it to WebAssembly automatically.

In other tree-sitter hosts

Point your host at this grammar the way it expects (a git dependency, a submodule, or a local path). The generated src/parser.c and the query files provided by each editor integration are all that's needed.

Regenerating the parser

After editing grammar.js:

npx tree-sitter-cli generate

This rewrites everything under src/. Commit grammar.js and the regenerated src/ together — consumers pin an exact commit, so the two must always match.

For the Zed extension: after regenerating and committing here, bump the commit hash in the extension's extension.toml to this repo's new HEAD, then reinstall the dev extension so Zed recompiles the grammar.

Status

Actively developed alpha, kept in lockstep with the Orbit language. Parser generation is warning-free and validated against representative .orb sources covering every construct above.

Maintenance

This grammar is fully AI-managed: grammar.js, the regenerated parser, and this documentation are authored and kept in sync with the Orbit language by an AI workflow, tracking every feature the language currently supports.

License

Licensed under the Apache License 2.0. See LICENSE.