tree-sitter-qsharp 0.1.1

Q# grammar for tree-sitter
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

# tree-sitter-qsharp

A [tree-sitter](https://tree-sitter.github.io/) grammar for [Q#](https://learn.microsoft.com/en-us/azure/quantum/overview-what-is-qsharp-and-qdk), Microsoft's quantum programming language.

This is a new project, not affiliated with Microsoft or the tree-sitter organization. Feedback, bug reports, and contributions are welcome.

## What it does

Parses Q# source files into a concrete syntax tree that editors can use for syntax highlighting, code folding, symbol navigation, and indentation.

Built by reading the [Q# language reference](https://learn.microsoft.com/en-us/azure/quantum/user-guide/) and the [Q# compiler source](https://github.com/microsoft/qsharp). Tested against Q# files in the microsoft/qsharp repository.

### Supported constructs

- Namespaces, imports, exports, open directives
- Operations and functions with type parameters, functor clauses, specializations
- Structs, newtypes, all builtin types
- Full expression grammar with operator precedence per the [official specification](https://learn.microsoft.com/en-us/azure/quantum/user-guide/language/expressions/precedenceandassociativity)
- Quantum-specific syntax: `use`/`borrow`, `within`/`apply`, `repeat`/`until`/`fixup`, `Adjoint`/`Controlled`
- All literals: int, bigint, float, imaginary, string, interpolated string, bool, Result, Pauli
- External scanner for float/range disambiguation (`1.` vs `0..5`)

### Known limitations

- Explicit type arguments on calls (`Foo<Int>(x)`) are not supported due to `<`/`>` ambiguity with comparison operators. Q# type inference handles this in practice.
- Open-ended step ranges (`...2...`) parse but the AST does not perfectly represent all range component positions.
- This is a v0.x project. There may be edge cases that are not yet covered.

## Editor query files

| Feature | File |
|---|---|
| Syntax highlighting | `queries/highlights.scm` |
| Code folding | `queries/folds.scm` |
| Symbol outline | `queries/tags.scm` |
| Auto-indentation | `queries/indents.scm` |
| Scope tracking | `queries/locals.scm` |
| Text objects | `queries/textobjects.scm` |

Capture names follow the [nvim-treesitter](https://github.com/nvim-treesitter/nvim-treesitter/blob/main/CONTRIBUTING.md) conventions.

## Installation

```bash
npm install tree-sitter-qsharp    # Node.js
cargo add tree-sitter-qsharp      # Rust
pip install tree-sitter-qsharp    # Python
```

Or from source:

```bash
git clone https://github.com/bezpechno/tree-sitter-qsharp
cd tree-sitter-qsharp
tree-sitter generate
```

## Development

```bash
tree-sitter generate    # regenerate parser
tree-sitter test        # run corpus tests
tree-sitter fuzz        # fuzz test
tree-sitter parse file.qs          # parse a file
tree-sitter highlight file.qs      # preview highlighting
```

## Contributing

If you find Q# code that doesn't parse correctly, please open an issue with the `.qs` file or a minimal reproducing snippet. Pull requests are welcome.

## References

- [Q# overview](https://learn.microsoft.com/en-us/azure/quantum/overview-what-is-qsharp-and-qdk)
- [microsoft/qsharp](https://github.com/microsoft/qsharp) — Q# compiler and standard library (MIT)
- [tree-sitter](https://tree-sitter.github.io/tree-sitter/) — parser generator

## License

MIT