nonbinary.computer
OR-1 dataflow CPU sketch
1# Node Tree-sitter
2
3[![CI][ci]](https://github.com/tree-sitter/node-tree-sitter/actions/workflows/ci.yml)
4[![npm][npm]](https://npmjs.com/package/tree-sitter)
5[![docs][docs]](https://tree-sitter.github.io/node-tree-sitter)
6
7This module provides Node.js bindings to the [tree-sitter] parsing library.
8
9## Installation
10
11```sh
12npm install tree-sitter
13```
14
15## Basic Usage
16
17### Prerequisites
18
19First, you'll need a Tree-sitter grammar for the language you want to parse. There are many [existing grammars][grammars],
20such as [tree-sitter-javascript][javascript]. These grammars can typically be installed with a package manager like NPM,
21so long as the author has published them.
22
23```sh
24npm install tree-sitter-javascript
25```
26
27You can also develop a new grammar by using the [Tree-sitter CLI][cli] and following the [docs][ts docs].
28
29### Parsing Source Code
30
31Once you've got your grammar, create a parser with that grammar.
32
33```javascript
34const Parser = require('tree-sitter');
35const JavaScript = require('tree-sitter-javascript');
36
37const parser = new Parser();
38parser.setLanguage(JavaScript);
39```
40
41Then you can parse some source code,
42
43```javascript
44const sourceCode = 'let x = 1; console.log(x);';
45const tree = parser.parse(sourceCode);
46```
47
48and inspect the syntax tree.
49
50```javascript
51console.log(tree.rootNode.toString());
52
53// (program
54// (lexical_declaration
55// (variable_declarator (identifier) (number)))
56// (expression_statement
57// (call_expression
58// (member_expression (identifier) (property_identifier))
59// (arguments (identifier)))))
60
61const callExpression = tree.rootNode.child(1).firstChild;
62console.log(callExpression);
63
64// {
65// type: 'call_expression',
66// startPosition: {row: 0, column: 16},
67// endPosition: {row: 0, column: 30},
68// startIndex: 0,
69// endIndex: 30
70// }
71```
72
73If your source code *changes*, you can update the syntax tree. This is much faster than the first parse.
74
75```javascript
76// In the code, we replaced 'let' with 'const'.
77// So, we set our old end index to 3, and our new end index to 5.
78// Note that the end index is exclusive.
79const newSourceCode = 'const x = 1; console.log(x);';
80// ^ ^
81// indices: 3 5
82// points: (0,3) (0,5)
83
84tree.edit({
85 startIndex: 0,
86 oldEndIndex: 3,
87 newEndIndex: 5,
88 startPosition: {row: 0, column: 0},
89 oldEndPosition: {row: 0, column: 3},
90 newEndPosition: {row: 0, column: 5},
91});
92
93const newTree = parser.parse(newSourceCode, tree);
94```
95
96### Parsing Text From a Custom Data Structure
97
98If your text is stored in a data structure other than a single string, such as a rope or array, you can parse it by supplying
99a callback to `parse` instead of a string:
100
101```javascript
102const sourceLines = [
103 'let x = 1;',
104 'console.log(x);'
105];
106
107const tree = parser.parse((index, position) => {
108 let line = sourceLines[position.row];
109 if (line) {
110 return line.slice(position.column);
111 }
112});
113```
114
115### Further Reading
116
117It's recommended that you read the [Tree-sitter documentation][usage docs] on using parsers to get a higher-level overview
118of the API. Once you're comfortable with the basics, you can explore the [full API documentation](https://tree-sitter.github.io/node-tree-sitter),
119which should map closely to the C API, though there are some differences.
120
121[ci]: https://img.shields.io/github/actions/workflow/status/tree-sitter/node-tree-sitter/ci.yml?logo=github&label=CI
122[cli]: https://github.com/tree-sitter/tree-sitter/tree/master/cli
123[docs]: https://img.shields.io/badge/docs-website-blue
124[npm]: https://img.shields.io/npm/v/tree-sitter?logo=npm
125[grammars]: https://github.com/tree-sitter/tree-sitter/wiki/List-of-parsers
126[javascript]: http://github.com/tree-sitter/tree-sitter-javascript
127[ts docs]: https://tree-sitter.github.io/tree-sitter/creating-parsers
128[usage docs]: https://tree-sitter.github.io/tree-sitter/using-parsers