0
# CLI Tools
1

2
Command-line tools for grammar compilation, testing, railroad diagram generation, and text generation.
3

4
## Capabilities
5

6
### nearleyc - Grammar Compiler
7

8
Compile `.ne` grammar files into JavaScript modules ready for use with nearley parsers.
9

10
```bash { .api }
11
nearleyc [options] <file.ne>
12

13
Options:
14
  -o, --out [filename.js]     File to output to (defaults to stdout)
15
  -e, --export [name]         Variable to set parser to (default: "grammar")
16
  -q, --quiet                 Suppress linter warnings
17
  --nojs                      Do not compile postprocessors
18
  -v, --version               Display version number
19
  -h, --help                  Display help information
20
```
21

22
**Usage Examples:**
23

24
```bash
25
# Compile grammar to stdout
26
nearleyc grammar.ne
27

28
# Compile grammar to file
29
nearleyc -o grammar.js grammar.ne
30

31
# Compile with custom export name
32
nearleyc -e myGrammar -o parser.js grammar.ne
33

34
# Compile without JavaScript postprocessors
35
nearleyc --nojs -o parser.js grammar.ne
36

37
# Suppress linter warnings
38
nearleyc -q -o parser.js grammar.ne
39
```
40

41
**Programmatic Usage:**
42

43
```javascript
44
// The nearleyc tool uses these internal modules:
45
const nearley = require("nearley");
46
const Compile = require("nearley/lib/compile");
47
const generate = require("nearley/lib/generate");
48
const lint = require("nearley/lib/lint");
49

50
// Parse .ne file and compile
51
const fs = require("fs");
52
const grammarSource = fs.readFileSync("grammar.ne", "utf8");
53

54
// Parse grammar with nearley's bootstrapped parser
55
const parserGrammar = nearley.Grammar.fromCompiled(
56
  require("nearley/lib/nearley-language-bootstrapped")
57
);
58
const parser = new nearley.Parser(parserGrammar);
59
parser.feed(grammarSource);
60

61
// Compile the parsed grammar
62
const compiled = Compile(parser.results[0], {
63
  version: "2.20.1"
64
});
65

66
// Generate JavaScript code
67
const jsCode = generate(compiled, "grammar");
68
console.log(jsCode);
69
```
70

71
### nearley-test - Grammar Tester
72

73
Test compiled grammars with input strings and inspect parse results.
74

75
```bash { .api }
76
nearley-test [options] <file.js>
77

78
Options:
79
  -i, --input [string]        Input string to parse (stdin if not provided)
80
  -s, --start [symbol]        Start symbol (uses parser default if not provided)
81
  -o, --out [filename]        Output file (defaults to stdout)
82
  -q, --quiet                 Output parse results only (hide Earley table)
83
  -v, --version               Display version number
84
  -h, --help                  Display help information
85
```
86

87
**Usage Examples:**
88

89
```bash
90
# Test with input string
91
nearley-test -i "2 + 3 * 4" arithmetic.js
92

93
# Test with stdin input
94
echo "hello world" | nearley-test language.js
95

96
# Test with custom start symbol
97
nearley-test -s expression -i "x + y" math.js
98

99
# Quiet mode (results only)
100
nearley-test -q -i "test input" grammar.js
101

102
# Save output to file
103
nearley-test -i "data" -o results.txt parser.js
104
```
105

106
**Example Output:**
107

108
```
109
Table length: 15
110
Number of parses: 1
111
Parse Charts
112
Chart: 0
113
0: {expression → ● term}, from: 0
114
1: {term → ● factor}, from: 0
115
...
116

117
Parse results: 
118
[
119
  {
120
    type: 'expression',
121
    left: { type: 'number', value: 2 },
122
    operator: '+',
123
    right: {
124
      type: 'expression', 
125
      left: { type: 'number', value: 3 },
126
      operator: '*',
127
      right: { type: 'number', value: 4 }
128
    }
129
  }
130
]
131
```
132

133
### nearley-railroad - Diagram Generator
134

135
Generate railroad diagrams (syntax diagrams) from `.ne` grammar files.
136

137
```bash { .api }
138
nearley-railroad [options] <file.ne>
139

140
Options:
141
  -o, --out [filename.svg]    Output file (defaults to stdout)  
142
  -v, --version               Display version number
143
  -h, --help                  Display help information
144
```
145

146
**Usage Examples:**
147

148
```bash
149
# Generate diagram to stdout (HTML format)
150
nearley-railroad grammar.ne
151

152
# Generate diagram to HTML file
153
nearley-railroad -o diagram.html grammar.ne
154

155
# View diagram directly in browser
156
nearley-railroad grammar.ne > diagram.html && open diagram.html
157
```
158

159
**Example Grammar for Railroad Diagrams:**
160

161
```nearley
162
# arithmetic.ne
163
expr -> expr "+" term | term
164
term -> term "*" factor | factor  
165
factor -> "(" expr ")" | number
166
number -> [0-9]:+
167
```
168

169
**Generated Diagram Structure:**
170

171
The output is a complete HTML document with embedded CSS and SVG railroad diagrams showing the visual structure of each grammar rule.
172

173
### nearley-unparse - Text Generator
174

175
Generate random text from compiled grammars for testing and example generation.
176

177
```bash { .api }
178
nearley-unparse [options] <file.js>
179

180
Options:
181
  -s, --start [name]          Start symbol (uses parser default if not provided)
182
  -n, --count [n]             Number of samples to generate (default: 1)
183
  -d, --depth [n]             Depth bound for generation (default: -1 for unbounded)
184
  -o, --out [filename]        Output file (defaults to stdout)
185
  -v, --version               Display version number
186
  -h, --help                  Display help information
187
```
188

189
**Usage Examples:**
190

191
```bash
192
# Generate one random sample
193
nearley-unparse grammar.js
194

195
# Generate 10 random samples
196
nearley-unparse -n 10 grammar.js
197

198
# Generate with depth limit
199
nearley-unparse -d 5 -n 5 grammar.js
200

201
# Generate with custom start symbol
202
nearley-unparse -s expression -n 3 math-grammar.js
203

204
# Save output to file
205
nearley-unparse -n 100 -o samples.txt grammar.js
206
```
207

208
**Example Output:**
209

210
```bash
211
$ nearley-unparse -n 5 arithmetic.js
212
42
213
17 + 23
214
(8 * 3) + 15
215
91 + (7 * 2)
216
((4 + 6) * 5) + 12
217
```
218

219
### Integration with npm Scripts
220

221
Common patterns for integrating nearley CLI tools into build workflows.
222

223
**Usage Examples:**
224

225
```json
226
{
227
  "scripts": {
228
    "build:grammar": "nearleyc -o lib/parser.js grammar/language.ne",
229
    "test:parser": "nearley-test -i 'test input' lib/parser.js",
230
    "diagram": "nearley-railroad -o docs/syntax.html grammar/language.ne",
231
    "examples": "nearley-unparse -n 20 -o examples/samples.txt lib/parser.js",
232
    "validate": "nearleyc -q grammar/language.ne > /dev/null",
233
    "watch:grammar": "chokidar 'grammar/*.ne' -c 'npm run build:grammar'"
234
  },
235
  "devDependencies": {
236
    "nearley": "^2.20.1",
237
    "chokidar-cli": "^3.0.0"
238
  }
239
}
240
```
241

242
**Makefile Integration:**
243

244
```makefile
245
# Build grammar
246
lib/parser.js: grammar/language.ne
247
	nearleyc -o $@ $<
248

249
# Generate examples
250
examples/samples.txt: lib/parser.js
251
	nearley-unparse -n 50 -o $@ $<
252

253
# Generate documentation
254
docs/syntax.html: grammar/language.ne
255
	nearley-railroad -o $@ $<
256

257
# Test grammar
258
test: lib/parser.js
259
	nearley-test -i "example input" $<
260

261
# Validate grammar syntax
262
validate: grammar/language.ne
263
	nearleyc -q $< > /dev/null
264

265
.PHONY: test validate
266
```
267

268
### Error Handling and Debugging
269

270
Common error scenarios and debugging techniques with CLI tools.
271

272
**Usage Examples:**
273

274
```bash
275
# Check grammar syntax
276
nearleyc -q grammar.ne
277
# Exit code 0 = success, non-zero = syntax error
278

279
# Debug parser issues with verbose output
280
nearley-test -i "problematic input" parser.js
281
# Shows full parse table and state transitions
282

283
# Generate simple examples for debugging
284
nearley-unparse -d 2 -n 10 parser.js
285
# Shallow examples are easier to debug
286

287
# Validate compiled output
288
node -e "console.log(require('./parser.js'))"
289
# Check if compiled grammar loads correctly
290
```
291

292
**Common Error Messages:**
293

294
```bash
295
# Grammar compilation errors
296
nearleyc: SyntaxError: Unexpected token at line 5 col 10
297
nearleyc: Error: Cannot find built-in "nonexistent.ne"
298

299
# Parser test errors  
300
nearley-test: Error: No valid parse found
301
nearley-test: SyntaxError: Unexpected character 'x' at line 1 col 5
302

303
# Unparse errors
304
nearley-unparse: Error: Cannot match rule: undefined_symbol
305
```
306

307
### Advanced CLI Usage
308

309
Complex workflows combining multiple CLI tools.
310

311
**Usage Examples:**
312

313
```bash
314
#!/bin/bash
315
# Complete grammar development workflow
316

317
echo "Building grammar..."
318
nearleyc -o parser.js grammar.ne || exit 1
319

320
echo "Validating with test cases..."
321
while IFS= read -r test_case; do
322
  echo "Testing: $test_case"
323
  nearley-test -q -i "$test_case" parser.js || echo "FAILED: $test_case"
324
done < test_cases.txt
325

326
echo "Generating examples..."
327
nearley-unparse -n 20 -o examples.txt parser.js
328

329
echo "Creating documentation..."
330
nearley-railroad -o syntax-diagram.html grammar.ne
331

332
echo "Grammar development complete!"
333
```
334

335
### Tool Configuration
336

337
Environment variables and configuration options for CLI tools.
338

339
**Usage Examples:**
340

341
```bash
342
# Set custom nearley installation path
343
export NEARLEY_PATH=/usr/local/lib/node_modules/nearley
344

345
# Configure output formatting
346
export NEARLEY_QUIET=1  # Suppress warnings by default
347

348
# Batch processing with configuration
349
find grammars/ -name "*.ne" -exec nearleyc -o compiled/{}.js {} \;
350

351
# Test multiple grammars
352
for grammar in compiled/*.js; do
353
  echo "Testing $grammar..."
354
  nearley-test -q -i "test" "$grammar" || echo "Failed: $grammar"
355
done
356
```