rcl/docs/grammars.md

Grammars

The grammar directory contains various versions of the RCL grammar, as well as plugins and extensions for editors and other tools to add support for RCL. If you are interested in using those, see the syntax highlighting chapter.

The source of truth for RCL's grammars are the lexer and parser in src/lexer.rs and src/parser.rs. These contain a hand-written lexer and recursive descent parser. The parser produces a concrete syntax tree (CST) and the same parser is shared by the evaluator and autoformatter.

Bison

In bison there is a Bison grammar. It can be compiled to check for errors, but the goal is not to be used directly; the goal is to provide a readable yet precise specification of the grammar, and to act as an aid in designing the grammar, to avoid making ad-hoc decisions in the hand-written parser that are difficult to parse with more general tools. To check the grammar for ambiguities:

bison -Werror=all grammar/bison/grammar.y

Tree-sitter

The tree-sitter-rcl directory contains a Tree-sitter grammar that forms the basis of various editor integrations. It has its own chapter.

Vim

The directory rcl.vim contains the Vim plugin. The final rcl.vim is generated from a template by tools/generate_keywords.py, so the source of truth for builtins to highlight can be kept in a single place.

The Vim documentation contains a section with standard group names to use for highlighting, similar to scopes for Tree Sitter.

Zed

The zed directory contains the Zed plugin. This directory is the source of truth for the plugin. We subsequently export the directory, including generated Tree-sitter files, into an external repository. The script tools/update_repos.py syncs changes from this repository into an external checkout.