0
# CLI Tool
1

2
Command-line interface for generating parser files from PEG grammar specifications with comprehensive configuration options and multiple output formats.
3

4
## Capabilities
5

6
### Command-Line Usage
7

8
The `pegjs` command provides a full-featured CLI for parser generation.
9

10
```bash
11
# Basic usage
12
pegjs [options] [input_file]
13

14
# Examples
15
pegjs grammar.pegjs                    # Generate grammar.js
16
pegjs -o parser.js grammar.pegjs      # Specify output file
17
pegjs --format commonjs grammar.pegjs # Generate CommonJS module
18
```
19

20
**Installation:**
21

22
```bash
23
# Global installation for CLI usage
24
npm install -g pegjs
25

26
# Local installation for programmatic usage
27
npm install pegjs
28
```
29

30
### Basic Options
31

32
Core command-line options for parser generation.
33

34
```bash
35
# Input/Output
36
pegjs grammar.pegjs                   # Input from file, output to grammar.js
37
pegjs -o output.js input.pegjs       # Specify output file
38
pegjs < input.pegjs > output.js      # Use stdin/stdout
39
pegjs --                             # Read from stdin, write to stdout
40

41
# Output format
42
pegjs --format commonjs grammar.pegjs    # CommonJS module (default)
43
pegjs --format amd grammar.pegjs         # AMD module
44
pegjs --format globals grammar.pegjs     # Global variable
45
pegjs --format umd grammar.pegjs         # Universal Module Definition
46

47
# Help and version
48
pegjs --help                             # Show help information
49
pegjs --version                          # Show version number
50
```
51

52
### Parser Configuration
53

54
Options that control parser behavior and capabilities.
55

56
```bash
57
# Start rules
58
pegjs --allowed-start-rules rule1,rule2 grammar.pegjs
59

60
# Caching and optimization  
61
pegjs --cache grammar.pegjs                    # Enable result caching
62
pegjs --optimize speed grammar.pegjs           # Optimize for speed (default)
63
pegjs --optimize size grammar.pegjs            # Optimize for size
64

65
# Debugging
66
pegjs --trace grammar.pegjs                    # Enable parser tracing
67
```
68

69
### Module Configuration
70

71
Options for configuring generated module format and dependencies.
72

73
```bash
74
# Dependencies (for amd, commonjs, umd formats)
75
pegjs --dependency lodash grammar.pegjs              # Add dependency: lodash
76
pegjs --dependency utils:./utils grammar.pegjs      # Map variable to module
77
pegjs -d lodash -d utils:./utils grammar.pegjs     # Multiple dependencies
78

79
# Global variable (for globals, umd formats)
80
pegjs --export-var MyParser grammar.pegjs          # Set global variable name
81
pegjs -e MyParser grammar.pegjs                    # Short form
82
```
83

84
### Advanced Options
85

86
Advanced configuration and plugin support.
87

88
```bash
89
# Extra options (JSON format)
90
pegjs --extra-options '{"customOption": true}' grammar.pegjs
91
pegjs --extra-options-file options.json grammar.pegjs
92

93
# Plugins
94
pegjs --plugin ./my-plugin.js grammar.pegjs
95
pegjs --plugin pegjs-plugin-name grammar.pegjs
96
```
97

98
## Command Reference
99

100
### Complete Option List
101

102
```bash { .api }
103
# Usage: pegjs [options] [--] [<input_file>]
104

105
# Start rule configuration
106
--allowed-start-rules <rules>    # Comma-separated list of allowed start rules
107
                                # Default: first rule in grammar
108

109
# Parser behavior  
110
--cache                         # Enable result caching
111
                               # Trade-off: speed vs memory usage
112

113
# Dependencies
114
-d, --dependency <dependency>   # Add module dependency  
115
                               # Format: variable or variable:module
116
                               # Can be specified multiple times
117

118
# Module format
119
-e, --export-var <variable>     # Global variable name for parser
120
                               # Valid for: globals, umd formats
121

122
--format <format>              # Output module format
123
                               # Options: amd, commonjs, globals, umd  
124
                               # Default: commonjs
125

126
# Optimization
127
-O, --optimize <goal>          # Optimization target
128
                               # Options: speed (default), size
129

130
# Output
131
-o, --output <file>            # Output file path
132
                               # Default: input file with .js extension
133

134
# Advanced configuration  
135
--extra-options <options>      # Additional options in JSON format
136
--extra-options-file <file>    # JSON file with additional options
137

138
# Plugins
139
--plugin <plugin>              # Use specified plugin  
140
                               # Can be specified multiple times
141

142
# Debugging
143
--trace                        # Enable parser tracing
144

145
# Information
146
-h, --help                     # Show help and exit
147
-v, --version                  # Show version and exit
148

149
# End of options
150
--                             # Treat remaining arguments as files
151
```
152

153
### Input/Output Behavior
154

155
```bash
156
# File input/output
157
pegjs grammar.pegjs                    # grammar.pegjs → grammar.js
158
pegjs -o parser.js grammar.pegjs      # grammar.pegjs → parser.js
159

160
# Standard input/output  
161
pegjs < grammar.pegjs > parser.js     # stdin → stdout
162
echo 'start = "hello"' | pegjs        # pipe input
163
pegjs -                               # explicit stdin → stdout
164

165
# No input file specified
166
pegjs                                 # stdin → stdout
167
pegjs -o parser.js                    # stdin → parser.js
168
```
169

170
## Usage Examples
171

172
### Basic Parser Generation
173

174
```bash
175
# Simple grammar file to parser
176
echo 'start = "hello" "world"' > hello.pegjs
177
pegjs hello.pegjs
178
# Generates hello.js with CommonJS parser
179

180
# Test the generated parser
181
node -e "
182
const parser = require('./hello.js');
183
console.log(parser.parse('helloworld'));
184
"
185
```
186

187
### Advanced Configuration
188

189
```bash
190
# Generate optimized browser parser
191
pegjs \
192
  --format globals \
193
  --export-var Calculator \
194
  --optimize size \
195
  --cache \
196
  -o calculator.js \
197
  calculator.pegjs
198

199
# Generate Node.js module with dependencies
200
pegjs \
201
  --format commonjs \
202
  --dependency lodash \
203
  --dependency utils:./my-utils \
204
  --optimize speed \
205
  --allowed-start-rules expression,statement \
206
  -o language-parser.js \
207
  language.pegjs
208
```
209

210
### JSON Configuration
211

212
Create `options.json`:
213

214
```json
215
{
216
  "allowedStartRules": ["program", "expression"],
217
  "cache": true,
218
  "optimize": "speed",
219
  "dependencies": {
220
    "lodash": "lodash",
221
    "utils": "./utilities"
222
  }
223
}
224
```
225

226
Use with CLI:
227

228
```bash
229
pegjs --extra-options-file options.json --format commonjs grammar.pegjs
230
```
231

232
### Plugin Usage
233

234
```bash
235
# Use built-in or installed plugin
236
pegjs --plugin pegjs-otherlib-parser grammar.pegjs
237

238
# Use local plugin file
239
pegjs --plugin ./plugins/my-plugin.js grammar.pegjs
240

241
# Multiple plugins
242
pegjs \
243
  --plugin ./plugin1.js \
244
  --plugin pegjs-plugin-name \
245
  --plugin ./plugin2.js \
246
  grammar.pegjs
247
```
248

249
## Output Formats
250

251
### CommonJS (Default)
252

253
```bash
254
pegjs --format commonjs grammar.pegjs
255
# or just:
256
pegjs grammar.pegjs
257
```
258

259
Generated output:
260

261
```javascript
262
"use strict";
263
// ... parser code ...
264
module.exports = {
265
  SyntaxError: peg$SyntaxError,
266
  parse: peg$parse
267
};
268
```
269

270
### AMD Module
271

272
```bash
273
pegjs --format amd grammar.pegjs
274
```
275

276
Generated output:
277

278
```javascript
279
define(function() {
280
  "use strict";
281
  // ... parser code ...
282
  return {
283
    SyntaxError: peg$SyntaxError,
284
    parse: peg$parse
285
  };
286
});
287
```
288

289
### Global Variable
290

291
```bash
292
pegjs --format globals --export-var MyParser grammar.pegjs
293
```
294

295
Generated output:
296

297
```javascript
298
(function(root) {
299
  "use strict";
300
  // ... parser code ...
301
  root.MyParser = {
302
    SyntaxError: peg$SyntaxError,
303
    parse: peg$parse
304
  };
305
})(this);
306
```
307

308
### Universal Module Definition
309

310
```bash
311
pegjs --format umd --export-var MyParser grammar.pegjs
312
```
313

314
Generated output supports AMD, CommonJS, and global formats.
315

316
### Bare Format
317

318
```bash
319
pegjs --format bare grammar.pegjs
320
```
321

322
Generated output is plain JavaScript without module wrapper.
323

324
## Error Handling
325

326
### CLI Error Messages
327

328
The CLI provides detailed error reporting for various failure scenarios:
329

330
```bash
331
# Grammar syntax errors
332
pegjs invalid.pegjs
333
# Output: Line 2, Column 5: Expected rule name
334

335
# Grammar semantic errors  
336
pegjs grammar-with-undefined-rules.pegjs
337
# Output: Rule "undefined_rule" is not defined
338

339
# File system errors
340
pegjs nonexistent.pegjs
341
# Output: Can't read from file "nonexistent.pegjs"
342

343
pegjs -o /readonly/output.js grammar.pegjs  
344
# Output: Can't write to file "/readonly/output.js"
345

346
# Invalid options
347
pegjs --format invalid grammar.pegjs
348
# Output: Module format must be one of "amd", "commonjs", "globals", and "umd"
349

350
pegjs --optimize invalid grammar.pegjs
351
# Output: Optimization goal must be either "speed" or "size"
352
```
353

354
### Exit Codes
355

356
```bash
357
# Success
358
pegjs grammar.pegjs
359
echo $?  # 0
360

361
# Error (syntax, semantic, file system, etc.)
362
pegjs invalid.pegjs
363
echo $?  # 1
364
```
365

366
### Error Output Format
367

368
Location information for grammar errors:
369

370
```
371
Line:Column: Error message
372
2:15: Expected "}" but found end of input
373
```
374

375
## Integration Examples
376

377
### Build System Integration
378

379
**Makefile:**
380

381
```makefile
382
# Generate all parsers
383
parsers: json.js css.js javascript.js
384

385
%.js: %.pegjs
386
	pegjs --format commonjs -o $@ $<
387

388
clean:
389
	rm -f *.js
390

391
.PHONY: parsers clean
392
```
393

394
**npm scripts:**
395

396
```json
397
{
398
  "scripts": {
399
    "build:parsers": "pegjs --format commonjs -o lib/parser.js src/grammar.pegjs",
400
    "build": "npm run build:parsers && webpack",
401
    "watch:grammar": "nodemon --watch src/grammar.pegjs --exec 'npm run build:parsers'"
402
  }
403
}
404
```
405

406
**Gulp task:**
407

408
```javascript
409
const gulp = require('gulp');
410
const { spawn } = require('child_process');
411

412
gulp.task('grammar', () => {
413
  return spawn('pegjs', [
414
    '--format', 'commonjs',
415
    '--optimize', 'speed', 
416
    '--cache',
417
    '-o', 'lib/parser.js',
418
    'src/grammar.pegjs'
419
  ], { stdio: 'inherit' });
420
});
421
```