0
# Grammar Processing
1

2
Internal system for processing and analyzing grammar definitions including production rules, nonterminals, and operator precedence. These APIs are primarily used internally by Jison but may be useful for advanced grammar analysis.
3

4
## Capabilities
5

6
### Grammar Processing
7

8
Core method for processing raw grammar definitions into internal representation.
9

10
```javascript { .api }
11
/**
12
 * Process a grammar definition into internal representation
13
 * @param grammar - Raw grammar object containing lex, bnf/ebnf, operators, etc.
14
 */
15
processGrammar(grammar);
16
```
17

18
This method:
19
- Converts EBNF to BNF if needed
20
- Processes operator precedence declarations
21
- Builds symbol tables
22
- Creates production rules
23
- Augments grammar with accept production
24

25
**Usage Examples:**
26

27
```javascript
28
const generator = new jison.Generator(grammar);
29
// processGrammar is called internally during construction
30

31
// Access processed components
32
console.log(generator.nonterminals);  // Nonterminal objects
33
console.log(generator.productions);   // Production rule array
34
console.log(generator.symbols);       // All grammar symbols
35
```
36

37
### Production Building
38

39
Builds production rules from BNF grammar definitions with semantic actions.
40

41
```javascript { .api }
42
/**
43
 * Build production rules from BNF grammar
44
 * @param bnf - BNF grammar object with nonterminal -> productions mapping
45
 * @param productions - Production array to populate
46
 * @param nonterminals - Nonterminal symbol objects
47
 * @param symbols - All grammar symbols array
48
 * @param operators - Operator precedence rules
49
 */
50
buildProductions(bnf, productions, nonterminals, symbols, operators);
51
```
52

53
This method processes:
54
- Production rules from BNF definitions
55
- Semantic actions associated with productions
56
- Named semantic values (e.g., `$variable`)
57
- Operator precedence assignments
58
- Error recovery rules
59

60
### Grammar Augmentation
61

62
Adds the accept production and required symbols to complete the grammar.
63

64
```javascript { .api }
65
/**
66
 * Augment grammar with accept production and required symbols
67
 * @param grammar - Original grammar definition
68
 */
69
augmentGrammar(grammar);
70
```
71

72
This method:
73
- Adds `$accept` production as grammar start
74
- Adds `$end` (EOF) terminal symbol
75
- Sets up initial symbol mappings
76
- Validates start symbol exists
77

78
## Grammar Analysis Classes
79

80
### Production Class
81

82
Represents individual production rules in the grammar.
83

84
```javascript { .api }
85
/**
86
 * Production rule constructor
87
 * @param symbol - Left-hand side nonterminal
88
 * @param handle - Right-hand side symbol array
89
 * @param id - Unique production identifier
90
 */
91
function Production(symbol, handle, id);
92

93
/**
94
 * Production instance properties and methods
95
 */
96
class Production {
97
  symbol: string;        // Left-hand side nonterminal
98
  handle: string[];      // Right-hand side symbols
99
  id: number;           // Production identifier
100
  nullable: boolean;    // Whether production can derive epsilon
101
  first: string[];      // First set for this production
102
  precedence: number;   // Operator precedence level
103
  
104
  /**
105
   * Convert production to string representation
106
   * @returns String in "A -> B C D" format
107
   */
108
  toString(): string;
109
}
110
```
111

112
**Usage Examples:**
113

114
```javascript
115
// Productions are created internally during grammar processing
116
const generator = new jison.Generator(grammar);
117

118
generator.productions.forEach(production => {
119
  console.log(`${production.symbol} -> ${production.handle.join(' ')}`);
120
  console.log(`Precedence: ${production.precedence}`);
121
  console.log(`Nullable: ${production.nullable}`);
122
});
123
```
124

125
### Nonterminal Class
126

127
Represents nonterminal symbols with their associated productions and computed sets.
128

129
```javascript { .api }
130
/**
131
 * Nonterminal symbol constructor
132
 * @param symbol - Symbol name
133
 */
134
function Nonterminal(symbol);
135

136
/**
137
 * Nonterminal instance properties and methods
138
 */
139
class Nonterminal {
140
  symbol: string;          // Symbol name
141
  productions: Set;        // Associated production rules
142
  first: string[];         // First set
143
  follows: string[];       // Follow set  
144
  nullable: boolean;       // Whether symbol can derive epsilon
145
  
146
  /**
147
   * Convert nonterminal to string with debug information
148
   * @returns Detailed string representation
149
   */
150
  toString(): string;
151
}
152
```
153

154
**Usage Examples:**
155

156
```javascript
157
const generator = new jison.Generator(grammar);
158

159
// Access nonterminal information
160
for (const symbolName in generator.nonterminals) {
161
  const nt = generator.nonterminals[symbolName];
162
  console.log(`Symbol: ${nt.symbol}`);
163
  console.log(`Nullable: ${nt.nullable}`);
164
  console.log(`First: [${nt.first.join(', ')}]`);
165
  console.log(`Follow: [${nt.follows.join(', ')}]`);
166
  console.log(`Productions: ${nt.productions.size()}`);
167
}
168
```
169

170
## Lookahead Computation
171

172
Methods for computing First, Follow, and Nullable sets used in parsing algorithms.
173

174
### First Sets
175

176
Compute First sets for symbols and symbol sequences.
177

178
```javascript { .api }
179
/**
180
 * Compute First sets for all productions and nonterminals
181
 */
182
firstSets();
183

184
/**
185
 * Get First set for a symbol or sequence of symbols
186
 * @param symbol - Single symbol (string) or array of symbols
187
 * @returns Array of terminal symbols that can begin derivations
188
 */
189
first(symbol);
190
```
191

192
### Follow Sets
193

194
Compute Follow sets for nonterminal symbols.
195

196
```javascript { .api }
197
/**
198
 * Compute Follow sets for all nonterminals
199
 */
200
followSets();
201
```
202

203
### Nullable Analysis
204

205
Determine which symbols and productions can derive the empty string.
206

207
```javascript { .api }
208
/**
209
 * Compute nullable properties for all symbols and productions
210
 */
211
nullableSets();
212

213
/**
214
 * Check if a symbol or sequence can derive epsilon
215
 * @param symbol - Single symbol (string) or array of symbols
216
 * @returns True if symbol/sequence is nullable
217
 */
218
nullable(symbol);
219
```
220

221
**Usage Examples:**
222

223
```javascript
224
const generator = new jison.Generator(grammar);
225
// Lookahead sets are computed automatically for LR/LL generators
226

227
// Manual computation (if extending generators)
228
generator.computeLookaheads();
229

230
// Check specific symbols
231
const firstOfE = generator.first('e');
232
const isENullable = generator.nullable('e');
233
const firstOfSequence = generator.first(['e', '+', 'e']);
234
```
235

236
## Operator Processing
237

238
Process operator precedence and associativity declarations.
239

240
```javascript { .api }
241
/**
242
 * Process operator precedence declarations
243
 * @param ops - Array of operator declarations
244
 * @returns Object mapping operators to precedence/associativity
245
 */
246
function processOperators(ops);
247
```
248

249
Operator declarations format:
250
```javascript
251
const operators = [
252
  ['left', '+', '-'],        // Left associative, precedence 1
253
  ['left', '*', '/'],        // Left associative, precedence 2  
254
  ['right', '^'],            // Right associative, precedence 3
255
  ['nonassoc', '==', '!=']   // Non-associative, precedence 4
256
];
257
```
258

259
## Error Handling and Debugging
260

261
### Debug Output
262

263
Enable detailed processing information during grammar analysis.
264

265
```javascript { .api }
266
/**
267
 * Output trace information (no-op unless debug mode enabled)
268
 * @param ...args - Arguments to trace
269
 */
270
trace(...args);
271

272
/**
273
 * Output warning messages
274
 * @param ...args - Warning message components
275
 */
276
warn(...args);
277

278
/**
279
 * Throw formatted error
280
 * @param msg - Error message
281
 * @throws Error with formatted message
282
 */
283
error(msg);
284
```
285

286
**Usage Examples:**
287

288
```javascript
289
// Enable debug mode during construction
290
const generator = new jison.Generator(grammar, { debug: true });
291

292
// Debug output will show:
293
// - Grammar processing steps
294
// - Symbol table construction
295
// - First/Follow set computation
296
// - Conflict resolution details
297
```
298

299
### Common Processing Errors
300

301
Grammar processing can fail with various error conditions:
302

303
- **"Grammar error: must have at least one rule"** - Empty BNF section
304
- **"Grammar error: startSymbol must be a non-terminal"** - Invalid start symbol
305
- **"Could not parse jison grammar"** - Malformed grammar syntax
306
- **"Could not parse lex grammar"** - Invalid lexical rules
307

308
```javascript
309
try {
310
  const parser = new jison.Parser(grammar);
311
} catch (error) {
312
  if (error.message.includes('Grammar error')) {
313
    // Handle grammar-specific errors
314
    console.error('Grammar processing failed:', error.message);
315
  }
316
}
317
```