0
# Command Line Interface
1

2
CLI tool for generating parsers from grammar files with support for various output formats and parser algorithms. The CLI provides a convenient way to generate parsers without writing JavaScript code.
3

4
## Installation and Usage
5

6
Install Jison globally to access the CLI:
7

8
```bash
9
npm install -g jison
10
```
11

12
Basic usage:
13
```bash
14
jison grammar.jison
15
jison grammar.jison lexer.jisonlex
16
jison --help
17
```
18

19
## Capabilities
20

21
### Main CLI Function
22

23
Entry point for the command-line interface that processes arguments and orchestrates parser generation.
24

25
```javascript { .api }
26
/**
27
 * Main CLI entry point
28
 * @param opts - Command line options object
29
 */
30
function main(opts);
31
```
32

33
The main function handles:
34
- Input file processing (grammar and lexer files)
35
- Output file generation
36
- Error handling and reporting
37
- Stdin input processing when no files specified
38

39
**Command Line Options:**
40

41
| Option | Short | Description | Default |
42
|--------|-------|-------------|---------|
43
| `file` | - | Grammar file path | - |
44
| `lexfile` | - | Lexer file path (optional) | - |
45
| `--json` | `-j` | Force JSON grammar format | Auto-detect |
46
| `--outfile` | `-o` | Output filename | `<input>.js` |
47
| `--debug` | `-t` | Enable debug mode | `false` |
48
| `--module-type` | `-m` | Module format (commonjs, amd, js) | `commonjs` |
49
| `--parser-type` | `-p` | Algorithm (lr0, slr, lalr, lr) | `lalr` |
50
| `--version` | `-V` | Show version and exit | - |
51
52
**Usage Examples:**
53

54
```bash
55
# Generate parser from grammar file
56
jison calculator.jison
57

58
# Specify separate lexer file
59
jison grammar.jison lexer.jisonlex
60

61
# Custom output filename and module type
62
jison -o my-parser.js -m amd calculator.jison
63

64
# Use specific parser algorithm with debug output
65
jison -p lr -t calculator.jison
66

67
# Generate JSON grammar
68
jison -j calculator.json
69

70
# Process from stdin
71
echo "expr: NUM;" | jison
72
```
73

74
### Parser String Generation
75

76
Generate parser source code from processed grammar objects.
77

78
```javascript { .api }
79
/**
80
 * Generate parser source code from grammar object
81
 * @param opts - Generation options from command line
82
 * @param grammar - Parsed grammar object
83
 * @returns Generated parser source code as string
84
 */
85
function generateParserString(opts, grammar);
86
```
87

88
This function:
89
- Creates appropriate generator based on parser-type option
90
- Applies command-line options to generator settings
91
- Returns complete parser source code ready for file output
92

93
**Usage Examples:**
94

95
```javascript
96
const cli = require("jison/lib/cli");
97

98
const grammar = {
99
  "bnf": {
100
    "expr": [["NUM", "return Number($1);"]]
101
  }
102
};
103

104
const opts = {
105
  "parser-type": "lalr",
106
  "module-type": "commonjs",
107
  "debug": false,
108
  "moduleName": "Calculator"
109
};
110

111
const parserCode = cli.generateParserString(opts, grammar);
112
console.log(parserCode); // Complete parser source
113
```
114

115
### Grammar Processing
116

117
Parse and process grammar and lexer files into internal grammar objects.
118

119
```javascript { .api }
120
/**
121
 * Process grammar and lexer files into grammar object
122
 * @param file - Grammar file content as string
123
 * @param lexFile - Lexer file content as string (optional)
124
 * @param jsonMode - Whether to parse grammar as JSON
125
 * @returns Processed grammar object ready for parser generation
126
 */
127
function processGrammars(file, lexFile, jsonMode);
128
```
129

130
This function handles:
131
- JSON vs Bison-style grammar parsing
132
- Lexer file integration
133
- Grammar validation and error reporting
134
- Format detection and conversion
135

136
**Usage Examples:**
137

138
```javascript
139
const cli = require("jison/lib/cli");
140
const fs = require("fs");
141

142
// Process Bison-style grammar
143
const grammarContent = fs.readFileSync("calculator.jison", "utf8");
144
const grammar = cli.processGrammars(grammarContent, null, false);
145

146
// Process JSON grammar with separate lexer
147
const jsonGrammar = fs.readFileSync("grammar.json", "utf8");
148
const lexerContent = fs.readFileSync("lexer.jisonlex", "utf8");
149
const combinedGrammar = cli.processGrammars(jsonGrammar, lexerContent, true);
150
```
151

152
## File Formats
153

154
### Jison Grammar Files (.jison)
155

156
Bison-compatible grammar files with embedded lexer rules:
157

158
```jison
159
/* calculator.jison */
160

161
/* Lexical rules */
162
%lex
163
%%
164
\s+                   /* skip whitespace */
165
[0-9]+("."[0-9]+)?\b  return 'NUMBER'
166
"*"                   return '*'
167
"+"                   return '+'
168
"("                   return '('
169
")"                   return ')'
170
<<EOF>>               return 'EOF'
171
/lex
172

173
/* Grammar rules */
174
%left '+' '-'
175
%left '*' '/'
176

177
%%
178

179
expressions
180
    : e EOF
181
        { return $1; }
182
    ;
183

184
e
185
    : e '+' e
186
        { $$ = $1 + $3; }
187
    | e '*' e
188
        { $$ = $1 * $3; }
189
    | '(' e ')'
190
        { $$ = $2; }
191
    | NUMBER
192
        { $$ = Number(yytext); }
193
    ;
194
```
195

196
Generate parser:
197
```bash
198
jison calculator.jison
199
node calculator.js  # Use the generated parser
200
```
201

202
### JSON Grammar Files (.json)
203

204
Structured JSON format for grammar definitions:
205

206
```json
207
{
208
  "lex": {
209
    "rules": [
210
      ["\\s+", "/* skip whitespace */"],
211
      ["[0-9]+", "return 'NUMBER';"],
212
      ["\\+", "return '+';"],
213
      ["\\*", "return '*';"],
214
      ["\\(", "return '(';"],
215
      ["\\)", "return ')';"],
216
      ["$", "return 'EOF';"]
217
    ]
218
  },
219
  "bnf": {
220
    "expressions": [["e EOF", "return $1;"]],
221
    "e": [
222
      ["e + e", "$$ = $1 + $3;"],
223
      ["e * e", "$$ = $1 * $3;"],
224
      ["( e )", "$$ = $2;"],
225
      ["NUMBER", "$$ = Number(yytext);"]
226
    ]
227
  },
228
  "operators": [
229
    ["left", "+", "-"],
230
    ["left", "*", "/"]
231
  ]
232
}
233
```
234

235
Generate parser:
236
```bash
237
jison --json calculator.json
238
```
239

240
### Separate Lexer Files (.jisonlex)
241

242
Dedicated lexer files for complex tokenization:
243

244
```jisonlex
245
/* lexer.jisonlex */
246
%%
247
\s+                   /* skip whitespace */
248
"//".*                /* skip comments */
249
[a-zA-Z_][a-zA-Z0-9_]* return 'IDENTIFIER'
250
[0-9]+                return 'NUMBER'
251
"+"                   return 'PLUS'
252
"*"                   return 'MULTIPLY'
253
"("                   return 'LPAREN'
254
")"                   return 'RPAREN'
255
";"                   return 'SEMICOLON'
256
<<EOF>>               return 'EOF'
257
%%
258
```
259

260
Use with grammar:
261
```bash
262
jison grammar.jison lexer.jisonlex
263
```
264

265
## CLI Workflow Examples
266

267
### Simple Calculator
268

269
```bash
270
# Create calculator.jison
271
cat > calculator.jison << 'EOF'
272
%lex
273
%%
274
\s+                   /* skip whitespace */
275
[0-9]+                return 'NUMBER'
276
"+"                   return '+'
277
"*"                   return '*'
278
"("                   return '('
279
")"                   return ')'
280
<<EOF>>               return 'EOF'
281
/lex
282

283
%%
284
expressions: e EOF { return $1; };
285
e: e '+' e { $$ = $1 + $3; }
286
 | e '*' e { $$ = $1 * $3; }
287
 | '(' e ')' { $$ = $2; }
288
 | NUMBER { $$ = Number(yytext); }
289
 ;
290
EOF
291

292
# Generate parser
293
jison calculator.jison
294

295
# Test the parser
296
echo "console.log(require('./calculator').parse('2 + 3 * 4'))" | node
297
# Output: 14
298
```
299

300
### Advanced JSON Parser
301

302
```bash
303
# Generate JSON parser with debug output
304
jison --debug --outfile json-parser.js --module-type commonjs json.jison
305

306
# Use in Node.js
307
cat > test.js << 'EOF'
308
const parser = require('./json-parser');
309
const result = parser.parse('{"name": "test", "value": 123}');
310
console.log(JSON.stringify(result, null, 2));
311
EOF
312

313
node test.js
314
```
315

316
### Browser-Compatible Parser
317

318
```bash
319
# Generate AMD module for browser use
320
jison --module-type amd --outfile browser-parser.js grammar.jison
321

322
# Use with RequireJS
323
cat > index.html << 'EOF'
324
<!DOCTYPE html>
325
<html>
326
<head>
327
    <script src="require.js"></script>
328
</head>
329
<body>
330
    <script>
331
        require(['./browser-parser'], function(parser) {
332
            const result = parser.parse(inputString);
333
            console.log(result);
334
        });
335
    </script>
336
</body>
337
</html>
338
EOF
339
```
340

341
## Error Handling
342

343
### Grammar File Errors
344

345
Common error conditions and their resolutions:
346

347
```bash
348
# Invalid grammar syntax
349
jison invalid.jison
350
# Error: Could not parse jison grammar
351

352
# Missing lexer rules
353
jison grammar-without-lexer.jison  
354
# Error: Lexical rules required
355

356
# Grammar conflicts
357
jison --debug conflicted.jison
358
# Shows detailed conflict information
359
```
360

361
### CLI Option Errors
362

363
```bash
364
# Invalid parser type
365
jison --parser-type invalid grammar.jison
366
# Uses default LALR(1) algorithm
367

368
# Missing input file
369
jison
370
# Reads from stdin instead
371

372
# Invalid output directory
373
jison --outfile /invalid/path/parser.js grammar.jison
374
# Error: Cannot write to output file
375
```
376

377
### File Processing Errors
378

379
```bash
380
# File not found
381
jison nonexistent.jison
382
# Error: ENOENT: no such file or directory
383

384
# Permission denied
385
jison --outfile /root/parser.js grammar.jison
386
# Error: EACCES: permission denied
387

388
# Invalid JSON format
389
jison --json invalid.json
390
# Error: Could not parse jison grammar
391
```
392

393
## Integration Examples
394

395
### Build Tool Integration
396

397
**Makefile:**
398
```makefile
399
parser.js: grammar.jison
400
	jison --outfile $@ $<
401

402
clean:
403
	rm -f parser.js
404

405
.PHONY: clean
406
```
407

408
**npm scripts:**
409
```json
410
{
411
  "scripts": {
412
    "build-parser": "jison --outfile lib/parser.js grammar/parser.jison",
413
    "clean": "rm -f lib/parser.js"
414
  }
415
}
416
```
417

418
**Webpack integration:**
419
```javascript
420
// webpack.config.js
421
const { execSync } = require('child_process');
422

423
module.exports = {
424
  plugins: [
425
    {
426
      apply: (compiler) => {
427
        compiler.hooks.beforeCompile.tap('JisonPlugin', () => {
428
          execSync('jison --outfile src/parser.js grammar.jison');
429
        });
430
      }
431
    }
432
  ]
433
};
434
```
435

436
### Programmatic CLI Usage
437

438
```javascript
439
const cli = require("jison/lib/cli");
440

441
// Simulate command line arguments
442
const opts = {
443
  file: "grammar.jison",
444
  outfile: "generated-parser.js",
445
  "module-type": "commonjs",
446
  "parser-type": "lalr",
447
  debug: false
448
};
449

450
try {
451
  cli.main(opts);
452
  console.log("Parser generated successfully");
453
} catch (error) {
454
  console.error("Generation failed:", error.message);
455
}
456
```