0
# Development Tools
1

2
Development and debugging tools for Tree-sitter parser development including web-based playground, language information display, and shell completion generation. These tools enhance the parser development workflow and provide utilities for exploration and automation.
3

4
## Capabilities
5

6
### Web Playground
7

8
Start a local web server providing an interactive playground for exploring Tree-sitter parsers in the browser with real-time parsing and visualization.
9

10
```bash { .api }
11
tree-sitter playground [options]  # Aliases: play, pg, web-ui
12
```
13

14
**Options:**
15
- `--quiet, -q`: Don't automatically open in default browser
16
- `--grammar-path <path>`: Path to directory containing grammar and WASM files
17

18
**Playground Features:**
19
- **Real-time parsing**: Edit source code and see parse tree updates instantly
20
- **Grammar visualization**: Explore grammar rules and their relationships
21
- **Query testing**: Write and test Tree-sitter queries interactively
22
- **Syntax highlighting**: Preview highlight query results
23
- **Error visualization**: See parsing errors and recovery attempts
24
- **Export capabilities**: Download parse trees and query results
25

26
**Usage:**
27
The playground serves a web interface typically at `http://localhost:8080` and automatically opens in the default browser unless `--quiet` is specified.
28

29
**Example:**
30
```bash
31
# Start playground with auto-open
32
tree-sitter playground
33

34
# Start without opening browser
35
tree-sitter playground --quiet
36

37
# Use custom grammar location
38
tree-sitter playground --grammar-path ./my-grammar
39

40
# Access playground at http://localhost:8080
41
```
42

43
**Requirements:**
44
- WASM compilation of parser (use `tree-sitter build --wasm`)
45
- Modern web browser with WebAssembly support
46
- Network access to localhost
47

48
### Language Information Display
49

50
Display comprehensive information about all known Tree-sitter language parsers configured in the system.
51

52
```bash { .api }
53
tree-sitter dump-languages [options]  # Alias: langs
54
```
55

56
**Options:**
57
- `--config-path <path>`: Use alternative config.json file
58

59
**Displayed Information:**
60
For each configured language:
61
- **Scope**: TextMate scope identifier
62
- **Parser**: Path to parser library/WASM file  
63
- **Highlights**: Paths to highlight query files
64
- **File types**: Associated file extensions
65
- **Content regex**: Patterns for content-based language detection
66
- **Injection regex**: Patterns for embedded language detection
67

68
**Example:**
69
```bash
70
# Show all configured languages
71
tree-sitter dump-languages
72

73
# Use custom configuration
74
tree-sitter dump-languages --config-path ./custom-config.json
75
```
76

77
**Sample Output:**
78
```
79
scope: source.javascript
80
parser: "/usr/local/lib/tree-sitter-javascript.so"
81
highlights: ["queries/highlights.scm"]
82
file_types: ["js", "jsx", "mjs"]
83
content_regex: None
84
injection_regex: Some("^(js|javascript)$")
85

86
scope: source.python
87
parser: "/usr/local/lib/tree-sitter-python.so"  
88
highlights: ["queries/highlights.scm", "queries/injections.scm"]
89
file_types: ["py", "pyi", "py3", "pyw"]
90
content_regex: Some("^#!/.*python[0-9.]*")
91
injection_regex: Some("python")
92
```
93

94
### Shell Completion Generation
95

96
Generate shell completion scripts for the Tree-sitter CLI to enable tab completion of commands and options.
97

98
```bash { .api }
99
tree-sitter complete --shell <shell>  # Alias: comp
100
```
101

102
**Arguments:**
103
- `--shell <shell>, -s`: Target shell for completion generation
104

105
**Supported Shells:**
106
- `bash`: Bash completion script
107
- `elvish`: Elvish completion script
108
- `fish`: Fish shell completion script
109
- `powershell`: PowerShell completion script
110
- `zsh`: Zsh completion script
111
- `nushell`: Nushell completion script
112

113
**Installation:**
114
Completion scripts should be installed to appropriate shell-specific directories:
115

116
**Bash:**
117
```bash
118
tree-sitter complete --shell bash > /etc/bash_completion.d/tree-sitter
119
# or
120
tree-sitter complete --shell bash > ~/.local/share/bash-completion/completions/tree-sitter
121
```
122

123
**Zsh:**
124
```bash
125
tree-sitter complete --shell zsh > ~/.zsh/completions/_tree-sitter
126
# Add to .zshrc: fpath=(~/.zsh/completions $fpath)
127
```
128

129
**Fish:**
130
```bash
131
tree-sitter complete --shell fish > ~/.config/fish/completions/tree-sitter.fish
132
```
133

134
**PowerShell:**
135
```powershell
136
tree-sitter complete --shell powershell | Out-String | Invoke-Expression
137
# Add to PowerShell profile for persistence
138
```
139

140
**Example:**
141
```bash
142
# Generate Bash completions
143
tree-sitter complete --shell bash
144

145
# Generate Zsh completions
146
tree-sitter complete --shell zsh
147

148
# Install Bash completions (Linux)
149
sudo tree-sitter complete --shell bash > /etc/bash_completion.d/tree-sitter
150

151
# Install Fish completions
152
tree-sitter complete --shell fish > ~/.config/fish/completions/tree-sitter.fish
153
```
154

155
## Development Workflow Integration
156

157
### Editor Integration
158

159
Tree-sitter CLI tools integrate with various editors and development environments:
160

161
**Visual Studio Code:**
162
- Tree-sitter parsers provide syntax highlighting
163
- Playground helps debug highlighting queries
164
- Query testing validates editor features
165

166
**Vim/Neovim:**
167
- Native Tree-sitter support in Neovim
168
- CLI tools aid in parser development
169
- Completion generation supports command-line workflow
170

171
**Emacs:**
172
- tree-sitter-mode uses Tree-sitter parsers
173
- CLI tools support parser configuration
174
- Query development with playground
175

176
### Continuous Integration
177

178
Integrate development tools into CI pipelines:
179

180
```bash
181
# Validate language configurations
182
tree-sitter dump-languages --config-path ci-config.json
183

184
# Build playground assets for deployment  
185
tree-sitter build --wasm
186
tree-sitter playground --quiet &
187
# Run automated tests against playground API
188
```
189

190
### Documentation Generation
191

192
Use tools to generate parser documentation:
193

194
```bash
195
# Extract language information for docs
196
tree-sitter dump-languages | grep -A 10 "scope: source.mylang"
197

198
# Generate query documentation from playground
199
# (Access playground programmatically for automation)
200
```
201

202
## Advanced Usage
203

204
### Custom Playground Deployment
205

206
Deploy playground for team collaboration:
207

208
```bash
209
# Build WASM parser
210
tree-sitter build --wasm
211

212
# Start playground on custom port
213
PORT=3000 tree-sitter playground --quiet
214

215
# Serve behind reverse proxy for external access
216
# nginx/apache configuration for production deployment
217
```
218

219
### Language Configuration Management
220

221
Manage multiple language configurations:
222

223
```bash
224
# Development configuration
225
tree-sitter dump-languages --config-path dev-config.json
226

227
# Production configuration  
228
tree-sitter dump-languages --config-path prod-config.json
229

230
# Compare configurations
231
diff <(tree-sitter dump-languages --config-path dev-config.json) \
232
     <(tree-sitter dump-languages --config-path prod-config.json)
233
```
234

235
### Automated Setup Scripts
236

237
Create setup scripts using CLI tools:
238

239
```bash
240
#!/bin/bash
241
# Grammar development setup script
242

243
# Generate completions for current shell
244
if [ "$SHELL" = "/bin/bash" ]; then
245
    tree-sitter complete --shell bash > ~/.local/share/bash-completion/completions/tree-sitter
246
elif [ "$SHELL" = "/bin/zsh" ]; then
247
    tree-sitter complete --shell zsh > ~/.zsh/completions/_tree-sitter
248
fi
249

250
# Initialize default configuration
251
tree-sitter init-config 2>/dev/null || echo "Config already exists"
252

253
# Start development playground
254
tree-sitter build --wasm && tree-sitter playground --quiet &
255
echo "Playground started at http://localhost:8080"
256
```
257

258
## Troubleshooting
259

260
### Playwright Issues
261

262
Common playground problems and solutions:
263

264
**WASM Build Missing:**
265
```bash
266
# Ensure WASM build exists
267
tree-sitter build --wasm
268
ls -la *.wasm
269
```
270

271
**Port Conflicts:**
272
```bash
273
# Check for port usage
274
lsof -i :8080
275
# Kill conflicting processes or use different port
276
```
277

278
**Browser Compatibility:**
279
- Ensure WebAssembly support is enabled
280
- Try different browsers (Chrome, Firefox, Safari)
281
- Check browser console for JavaScript errors
282

283
### Language Configuration Issues
284

285
Debug language configuration problems:
286

287
```bash
288
# Verify language configurations
289
tree-sitter dump-languages | grep -A 5 -B 5 "error\|invalid"
290

291
# Test language loading
292
tree-sitter parse --scope source.mylang test-file.txt
293

294
# Check file associations
295
tree-sitter parse test-file.mylang  # Should auto-detect language
296
```
297

298
### Completion Installation Problems
299

300
Fix shell completion issues:
301

302
**Bash:**
303
- Ensure bash-completion package is installed
304
- Verify completion directory exists and is in PATH
305
- Check .bashrc sources completion files
306

307
**Zsh:**
308
- Verify fpath includes completion directory
309
- Run `compinit` to rebuild completion index
310
- Check .zshrc configuration
311

312
**Fish:**
313
- Ensure Fish version supports completions
314
- Verify completion file location and permissions
315
- Restart Fish shell after installation