Decodal

Components

Decodal is split into a small runtime core and separate syntax tooling components. The public surface is intentionally organized by use case: execute Decodal with Rust or WebAssembly, edit Decodal on the Web with Lezer and CodeMirror, and integrate Decodal into general-purpose editors with Tree-sitter.

Runtime components

Rust crate

The decodal crate is the primary Rust runtime and embedding API. It owns parsing, evaluation, materialization, diagnostics, host-provided values, and schema/decode traits. Rust applications should use this crate when they want to load Decodal source, evaluate it, or embed Decodal into a host program.

Important paths:

crates/decodal-core/
crates/decodal-derive/

decodal-derive provides optional derive macros for Rust struct integration. It is a companion to the runtime crate rather than an editor or syntax-highlighting component.

WebAssembly package

decodal-wasm exposes the runtime to browsers. The documentation site playground uses it to evaluate Decodal entirely in the browser.

Important paths:

crates/decodal-wasm/
site/decodal-site/src/wasm/

The generated files in site/decodal-site/src/wasm/ are committed so the site can build without requiring every consumer to run wasm-pack first. The WebAssembly package is for execution, not syntax highlighting.

Web editor components

The Web playground editor uses CodeMirror 6 with a generated Lezer parser. This is the source of syntax highlighting, folding, indentation, and editor syntax tree behavior in the browser UI.

Important paths:

editors/lezer-decodal/decodal.grammar
site/decodal-site/src/lib/codemirror/decodal-parser.js
site/decodal-site/src/lib/codemirror/decodal-parser.terms.js
site/decodal-site/src/lib/codemirror/decodal.js

The Lezer grammar is derived from the canonical grammar documentation, but it is not a literal copy of the EBNF. Precedence and token conflict handling are represented in the Lezer grammar in the form CodeMirror needs.

General editor components

Tree-sitter is the portable editor-integration grammar. Editors such as Zed, Neovim, Helix, and Emacs should consume this component when they need Decodal parsing or highlighting outside the Web playground.

Important paths:

editors/tree-sitter-decodal/grammar.js
editors/tree-sitter-decodal/queries/highlights.scm
editors/tree-sitter-decodal/queries/locals.scm
editors/tree-sitter-decodal/src/

The generated parser sources under editors/tree-sitter-decodal/src/ are committed so editor integrations can consume the grammar without regenerating it first.

Canonical grammar

The human-readable grammar lives in:

doc/manual/souce/language/grammar.md

This EBNF is the language-level reference. The Rust parser, Lezer grammar, and Tree-sitter grammar should be kept aligned with it, but each implementation may encode precedence and recovery behavior in the form required by its parser generator or runtime.

What is not a public component

The Rust lexer is an implementation detail of the Rust parser. Decodal does not expose a standalone public tokenizer API for editor tooling. Consumers that need syntax information should use the component that matches their environment:

  • Rust execution and embedding: decodal
  • Browser execution: decodal-wasm
  • Web editor syntax: Lezer / CodeMirror
  • General editor syntax: Tree-sitter

This avoids having a separate token stream API whose behavior would have to be kept compatible with both runtime parsing and editor grammars.