# tree-sitter-openqasm

OpenQASM 3, and the OpenQASM 2 forms in common use, as a tree-sitter grammar:
for highlighting, folding and structural selection in any editor that reads
tree-sitter grammars. The language service (`wai-quantum lsp`) gives the
engine's diagnostics, completion, hover and renames; this grammar gives the
editor the program's structure as it is typed.

| Path | What it is |
|---|---|
| `grammar.js` | The grammar: every statement of OpenQASM 3.1 (declarations of every type, gates, subroutines, modifiers, control flow, timing, calibrations kept as text, pragmas, annotations) and OpenQASM 2's `qreg`, `creg`, `opaque`, `measure q -> c` and `if(c==1)` |
| `src/` | The parser generated from it (ABI 14), committed so that an editor builds it with a C compiler alone |
| `queries/highlights.scm` | Highlighting, in the common capture names (`@keyword`, `@type`, `@function`, `@number`, …) |
| `queries/locals.scm` | Scopes, definitions and references |
| `queries/folds.scm` | Foldable blocks |
| `test/corpus/` | The parse of every construct, checked tree for tree |
| `test/highlight/` | Highlighting checked capture by capture |
| `script/check-programs.mjs` | Parses every program in the repository's conformance material and examples, and fails on any error |

The grammar reads what is written. It does not say what a program means: the
engine's reader decides that, and the language server reports it.

## Building and testing

With Node.js 22 and a C compiler:

```sh
npm ci                                   # the pinned tree-sitter command line
npx tree-sitter generate --abi 14        # src/ from grammar.js
npx tree-sitter test                     # the corpus and the highlighting
node script/check-programs.mjs           # every program in the repository
```

`src/` must be regenerated and committed with any change to `grammar.js`; CI
regenerates it and fails if the committed parser differs.

## Versions

The names of the grammar's nodes and fields are what queries name, so they are its public surface: one is renamed or removed only in a major release, as [WAI Quantum's policy](https://git.transaction.science/Transaction-Science/open-standards/src/branch/main/wai/wai-quantum/VERSIONING.md) says, and listed in [the deprecations](https://git.transaction.science/Transaction-Science/open-standards/src/branch/main/wai/wai-quantum/DEPRECATIONS.md) at least one minor release before.

## Using it in an editor

The editor configurations in [`../wai-quantum-editor/editors/`](../wai-quantum-editor/editors/)
point at this directory, and the [editors guide](../wai-quantum-editor/README.md#other-editors)
says how to install each.