219cc3b5f3
- wai-quantum/VERSIONING.md: the public surface of every WAI Quantum package, what each part of a version number promises, the schemas' rules, what changed in a receipt's canonical content, the support windows the owner decided (2026-10-27), how a deprecated item says so on each surface, the rule before 1.0, and what CI checks. - wai-quantum/DEPRECATIONS.md: each deprecated item, the version that deprecated it, its replacement; none today. - Every WAI Quantum README links both; the changelog entry. Co-Authored-By: Claude Opus 5.5 <[email protected]>
45 lines
2.6 KiB
Markdown
45 lines
2.6 KiB
Markdown
# 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.
|