0
# Jison
1

2
Jison is a parser generator library for JavaScript that creates bottom-up parsers using an API similar to Bison. It takes JSON-encoded grammars or Bison-style grammar definitions and outputs JavaScript parsers capable of parsing languages described by those grammars. The library supports many of Bison's major features while adding its own enhancements, making it suitable for creating parsers programmatically or via command-line interface.
3

4
## Package Information
5

6
- **Package Name**: jison
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install jison` or `npm install jison -g` for global CLI access
10

11
## Core Imports
12

13
```javascript
14
const jison = require("jison");
15
const Parser = jison.Parser;
16
```
17

18
The main Jison object provides access to all functionality:
19

20
```javascript
21
const jison = require("jison");
22

23
// Access parser constructor
24
const Parser = jison.Parser;
25

26
// Access generator factory
27
const Generator = jison.Generator;
28

29
// Access individual generator classes
30
const {
31
  LR0Generator,
32
  SLRGenerator, 
33
  LALRGenerator,
34
  LR1Generator,
35
  LLGenerator
36
} = jison;
37
```
38

39
For CLI functionality:
40

41
```javascript
42
const cli = require("jison/lib/cli");
43
```
44

45
## Basic Usage
46

47
```javascript
48
const jison = require("jison");
49
const Parser = jison.Parser;
50

51
// Define a simple grammar
52
const grammar = {
53
  "lex": {
54
    "rules": [
55
      ["\\s+", "/* skip whitespace */"],
56
      ["[0-9]+", "return 'NUMBER';"],
57
      ["\\+", "return '+';"],
58
      ["\\*", "return '*';"],
59
      ["\\(", "return '(';"],
60
      ["\\)", "return ')';"],
61
      ["$", "return 'EOF';"]
62
    ]
63
  },
64
  "bnf": {
65
    "expressions": [["e EOF", "return $1;"]],
66
    "e": [
67
      ["e + e", "$$ = $1 + $3;"],
68
      ["e * e", "$$ = $1 * $3;"],
69
      ["( e )", "$$ = $2;"],
70
      ["NUMBER", "$$ = Number(yytext);"]
71
    ]
72
  }
73
};
74

75
// Create parser
76
const parser = new Parser(grammar);
77

78
// Parse input
79
const result = parser.parse("2 + 3 * 4");
80
console.log(result); // 14
81
```
82

83
## Architecture
84

85
Jison is built around several key components:
86

87
- **Parser Constructor**: Main entry point for creating parsers from grammar definitions
88
- **Generator System**: Factory pattern for creating different parser types (LR0, SLR, LALR, LR1, LL)
89
- **Grammar Processing**: Internal classes for handling productions, nonterminals, and grammar analysis
90
- **Code Generation**: System for generating standalone parser modules in various formats
91
- **CLI Interface**: Command-line tool for generating parsers from grammar files
92
- **Utility Classes**: Helper classes for object composition and set operations
93

94
## Capabilities
95

96
### Parser Creation
97

98
Core functionality for creating parsers from grammar definitions. Supports both JSON and Bison-style grammar formats with automatic algorithm selection.
99

100
```javascript { .api }
101
/**
102
 * Create a parser from a grammar definition
103
 * @param grammar - Grammar definition (object or string)  
104
 * @param options - Parser generation options
105
 * @returns Parser instance with parse() method
106
 */
107
new jison.Parser(grammar, options);
108

109
/**
110
 * Factory function for creating parser generators
111
 * @param grammar - Grammar definition
112
 * @param options - Generation options including parser type
113
 * @returns Generator instance based on options.type
114
 */
115
new jison.Generator(grammar, options);
116
```
117

118
[Parser Creation](./parser-creation.md)
119

120
### Grammar Processing
121

122
Internal system for processing and analyzing grammar definitions including production rules, nonterminals, and operator precedence.
123

124
```javascript { .api }
125
/**
126
 * Process a grammar definition into internal representation
127
 * @param grammar - Raw grammar object
128
 */
129
processGrammar(grammar);
130

131
/**
132
 * Build production rules from BNF grammar
133
 * @param bnf - BNF grammar object
134
 * @param productions - Production array to populate
135
 * @param nonterminals - Nonterminal symbols
136
 * @param symbols - All grammar symbols
137
 * @param operators - Operator precedence rules
138
 */
139
buildProductions(bnf, productions, nonterminals, symbols, operators);
140
```
141

142
[Grammar Processing](./grammar-processing.md)
143

144
### Parser Generation
145

146
Code generation system that creates standalone parser modules in various formats (CommonJS, AMD, plain JavaScript) from processed grammars.
147

148
```javascript { .api }
149
/**
150
 * Generate parser source code
151
 * @param options - Generation options
152
 * @returns Generated parser source code
153
 */
154
generate(options);
155

156
/**
157
 * Generate CommonJS module
158
 * @param options - Module generation options
159
 * @returns CommonJS module source
160
 */
161
generateCommonJSModule(options);
162

163
/**
164
 * Generate AMD module
165
 * @param options - AMD module options
166
 * @returns AMD module source
167
 */
168
generateAMDModule(options);
169
```
170

171
[Parser Generation](./parser-generation.md)
172

173
### Algorithm Selection
174

175
Support for multiple parsing algorithms including LR(0), SLR(1), LALR(1), LR(1), and LL(1) with automatic selection based on grammar complexity.
176

177
```javascript { .api }
178
/**
179
 * LR(0) parser generator
180
 */
181
class LR0Generator extends Generator;
182

183
/**
184
 * SLR(1) parser generator  
185
 */
186
class SLRGenerator extends Generator;
187

188
/**
189
 * LALR(1) parser generator (default)
190
 */
191
class LALRGenerator extends Generator;
192

193
/**
194
 * Canonical LR(1) parser generator
195
 */
196
class LR1Generator extends Generator;
197

198
/**
199
 * LL(1) parser generator
200
 */
201
class LLGenerator extends Generator;
202
```
203

204
[Algorithm Selection](./algorithm-selection.md)
205

206
### Command Line Interface
207

208
CLI tool for generating parsers from grammar files with support for various output formats and parser algorithms.
209

210
```javascript { .api }
211
/**
212
 * Main CLI entry point
213
 * @param opts - Command line options
214
 */
215
function main(opts);
216

217
/**
218
 * Generate parser string from grammar
219
 * @param opts - Generation options
220
 * @param grammar - Parsed grammar object
221
 * @returns Generated parser source
222
 */
223
function generateParserString(opts, grammar);
224

225
/**
226
 * Process grammar and lexer files
227
 * @param file - Grammar file content
228
 * @param lexFile - Lexer file content (optional)
229
 * @param jsonMode - Whether to parse as JSON
230
 * @returns Parsed grammar object
231
 */
232
function processGrammars(file, lexFile, jsonMode);
233
```
234

235
[Command Line Interface](./cli.md)
236

237
## Types
238

239
```javascript { .api }
240
/**
241
 * Main Jison module interface
242
 */
243
interface JisonModule {
244
  Parser: typeof Parser;
245
  Generator: typeof Generator;
246
  LR0Generator: typeof LR0Generator;
247
  SLRGenerator: typeof SLRGenerator;
248
  LALRGenerator: typeof LALRGenerator;
249
  LR1Generator: typeof LR1Generator;
250
  LLGenerator: typeof LLGenerator;
251
  version: string;
252
}
253

254
/**
255
 * Grammar definition object
256
 */
257
interface Grammar {
258
  lex?: LexicalGrammar;     // Lexical rules (optional)
259
  bnf?: BNFGrammar;         // BNF production rules
260
  ebnf?: EBNFGrammar;       // EBNF production rules (alternative to bnf)
261
  operators?: OperatorDef[]; // Operator precedence declarations
262
  tokens?: string[] | string; // Terminal symbols
263
  start?: string;           // Start symbol (optional)
264
  options?: ParserOptions;  // Parser generation options
265
}
266

267
/**
268
 * Lexical grammar definition
269
 */
270
interface LexicalGrammar {
271
  rules: LexRule[];         // Array of lexical rules
272
  options?: LexerOptions;   // Lexer options
273
}
274

275
/**
276
 * Lexical rule definition
277
 */
278
type LexRule = [string, string]; // [pattern, action]
279

280
/**
281
 * BNF grammar rules mapping nonterminals to productions
282
 */
283
interface BNFGrammar {
284
  [nonterminal: string]: string[] | string; // Productions as array or |-separated string
285
}
286

287
/**
288
 * EBNF grammar rules (alternative to BNF)
289
 */
290
interface EBNFGrammar {
291
  [nonterminal: string]: string[] | string; // EBNF productions
292
}
293

294
/**
295
 * Operator precedence and associativity declaration
296
 */
297
type OperatorDef = [string, ...string[]]; // [associativity, ...operators]
298

299
/**
300
 * Lexer options
301
 */
302
interface LexerOptions {
303
  ranges?: boolean;           // Include token range information
304
  flex?: boolean;             // Flex-like lexing behavior
305
  backtrack_lexer?: boolean;  // Backtracking lexer mode
306
}
307

308
/**
309
 * Parser generation options
310
 */
311
interface ParserOptions {
312
  type?: 'lr0' | 'slr' | 'lalr' | 'lr' | 'll'; // Parser algorithm
313
  moduleName?: string;      // Generated module name
314
  moduleType?: 'commonjs' | 'amd' | 'js'; // Module format
315
  debug?: boolean;          // Enable debug mode
316
}
317

318
/**
319
 * Generated parser interface
320
 */
321
interface GeneratedParser {
322
  parse(input: string): any; // Parse input string
323
  yy: object;               // Shared state object
324
  lexer?: Lexer;            // Associated lexer (if generated)
325
}
326

327
/**
328
 * Lexer interface for tokenization
329
 */
330
interface Lexer {
331
  setInput(input: string): void;    // Set input string
332
  lex(): string | number;           // Get next token
333
  EOF: number;                      // End-of-file token value
334
  yytext: string;                   // Current token text
335
  yylloc: object;                   // Current token location
336
}
337
```