willbooster-tree-sitter-ruby 17.0.0

Ruby 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
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

# @willbooster/tree-sitter-ruby

[![npm version](https://img.shields.io/npm/v/@willbooster/tree-sitter-ruby.svg)](https://www.npmjs.com/package/@willbooster/tree-sitter-ruby)
[![license](https://img.shields.io/npm/l/@willbooster/tree-sitter-ruby.svg)](https://www.npmjs.com/package/@willbooster/tree-sitter-ruby)
[![Test](https://github.com/WillBooster/tree-sitter-ruby/actions/workflows/test.yml/badge.svg)](https://github.com/WillBooster/tree-sitter-ruby/actions/workflows/test.yml)
[![Test rust](https://github.com/WillBooster/tree-sitter-ruby/actions/workflows/test-rust.yml/badge.svg)](https://github.com/WillBooster/tree-sitter-ruby/actions/workflows/test-rust.yml)
[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
[![wbfy](https://img.shields.io/badge/wbfy-21.3.0-1e90ff.svg)](https://github.com/WillBooster/shared/tree/main/packages/wbfy)
[![crates.io](https://img.shields.io/crates/v/willbooster-tree-sitter-ruby.svg)](https://crates.io/crates/willbooster-tree-sitter-ruby)

Ruby grammar for [tree-sitter](https://github.com/tree-sitter/tree-sitter), forked from
[tree-sitter/tree-sitter-ruby](https://github.com/tree-sitter/tree-sitter-ruby). We are grateful
to its authors and contributors. This is not an official release of that project.

This fork extends the upstream grammar to parse anonymous block forwarding, spaced block arguments, and command calls in endless methods, with a parser generated by
[WillBooster/tree-sitter](https://github.com/WillBooster/tree-sitter), whose compact parse tables make the
parser smaller. The parser carries that fork's own ABI number (`0x5742000c`); upstream's tree-sitter runtime and
incompatible ABI versions of the fork's runtime reject it.
The scanner preserves long heredoc identifiers
when their state fits the runtime's serialization buffer. If the open heredocs cannot fit, their bodies are parsed as
code instead of aborting the process.

## Support Scope

This fork maintains only full parsing: valid input yields a correct tree, and invalid input yields `ERROR` or `MISSING`
nodes without crashing, hanging, or taking more than linear time. Incremental parsing and queries (highlights, locals,
injections, tags) are not supported. Node types, field names, and the trees that error recovery produces may change;
such changes are released as new major versions.

## Usage

The npm package ships `tree-sitter-ruby.wasm` for
[@willbooster/web-tree-sitter](https://www.npmjs.com/package/@willbooster/web-tree-sitter) 20.x, which runs in Node.js,
Bun, browsers, and Cloudflare Workers.

In Node.js and Bun, load the grammar from its path:

```js
import { fileURLToPath } from 'node:url';

import { Language, Parser } from '@willbooster/web-tree-sitter';

await Parser.init();
const parser = new Parser();
const wasmPath = fileURLToPath(import.meta.resolve('@willbooster/tree-sitter-ruby/tree-sitter-ruby.wasm'));
parser.setLanguage(await Language.load(wasmPath));
const tree = parser.parse('puts "Hello"\n');
```

In browsers, load the grammar from its URL. With Vite:

```js
import rubyUrl from '@willbooster/tree-sitter-ruby/tree-sitter-ruby.wasm?url';
import { Language, Parser } from '@willbooster/web-tree-sitter';
import runtimeUrl from '@willbooster/web-tree-sitter/web-tree-sitter.wasm?url';

await Parser.init({ locateFile: () => runtimeUrl });
const parser = new Parser();
parser.setLanguage(await Language.load(rubyUrl));
```

In Cloudflare Workers, which do not allow compiling Wasm at run time, import both `.wasm` files as modules:

```js
import ruby from '@willbooster/tree-sitter-ruby/tree-sitter-ruby.wasm';
import { Language, Parser } from '@willbooster/web-tree-sitter';
import runtime from '@willbooster/web-tree-sitter/web-tree-sitter.wasm';

await Parser.init({ wasmModule: runtime });
const parser = new Parser();
parser.setLanguage(await Language.load(ruby));
```

The package also ships the node types in `src/node-types.json`.

In Rust, depend on the [crate](https://crates.io/crates/willbooster-tree-sitter-ruby) and on
[willbooster-tree-sitter](https://crates.io/crates/willbooster-tree-sitter) 20.x, the runtime this package is tested and
fuzzed with:

```sh
cargo add willbooster-tree-sitter@20.0.0 --rename tree-sitter
cargo add willbooster-tree-sitter-ruby --rename tree-sitter-ruby
```

```rust
let mut parser = tree_sitter::Parser::new();
parser.set_language(&tree_sitter_ruby::LANGUAGE.into())?;
```

## Development

```sh
mise install
bun install --frozen-lockfile
bun run test/ci-setup
bun run build/ci
bun run verify
bun run test
cargo test
```

- `bun run test/ci-setup`: run once to install Chromium before `bun run test`.
- `bun run build/ci`: run before `bun run test`, and commit `src/` after changing `grammar.js`, `tree-sitter.json`, `test/corpus/`, or tracked files in `examples/`. Stage added or removed `examples/` files with `git add -A examples` before generating so the profile sees them.
- `script/parse-examples`: run without arguments to update `script/known-failures.txt` after a grammar or pin change alters which `ruby/spec` files fail to parse.
- `script/tree-sitter`: use for direct CLI commands such as `script/tree-sitter parse file.rb` so they run the `WillBooster/tree-sitter` version locked in `Cargo.lock`.

### References

- [AST Format of the Whitequark parser](https://github.com/whitequark/parser/blob/master/doc/AST_FORMAT.md)