0
# Parser Generation
1

2
Core functionality for generating JavaScript parsers from PEG grammar specifications with comprehensive configuration options and multiple output formats.
3

4
## Capabilities
5

6
### Main Generate Function
7

8
Generates a parser from a specified grammar string with optional configuration.
9

10
```javascript { .api }
11
/**
12
 * Generates a parser from a specified grammar and returns it
13
 * @param grammar - PEG grammar string in parser.pegjs format
14
 * @param options - Optional generation configuration
15
 * @returns Generated parser object or source code string
16
 * @throws {peg.parser.SyntaxError} If grammar contains syntax error
17
 * @throws {peg.GrammarError} If grammar contains semantic error
18
 */
19
function generate(grammar, options);
20
```
21

22
**Usage Examples:**
23

24
```javascript
25
const peg = require("pegjs");
26

27
// Basic parser generation
28
const parser = peg.generate('start = "hello" "world"');
29
const result = parser.parse("helloworld"); // Returns: ["hello", "world"]
30

31
// Generate source code instead of parser object
32
const source = peg.generate('start = "hello"', { output: "source" });
33
console.log(source); // JavaScript parser code as string
34

35
// Advanced configuration
36
const parser = peg.generate(grammar, {
37
  allowedStartRules: ["expression", "statement"],
38
  cache: true,
39
  format: "commonjs",
40
  optimize: "speed",
41
  trace: false
42
});
43
```
44

45
### Browser Usage
46

47
PEG.js can be used in browser environments with automatic module format detection and global variable support.
48

49
**Browser Integration:**
50

51
```html
52
<!-- Include PEG.js library -->
53
<script src="path/to/peg.js"></script>
54

55
<script>
56
// PEG.js automatically detects environment:
57
// - AMD loader available: defines as AMD module
58
// - No AMD loader: available as global 'peg' variable
59

60
// Generate parser in browser
61
const grammar = `
62
start = "hello" "world"
63
`;
64

65
const parser = peg.generate(grammar);
66
const result = parser.parse("hello world");
67
console.log(result); // ["hello", "world"]
68
</script>
69
```
70

71
**AMD Module Usage:**
72

73
```javascript
74
// When AMD loader (like RequireJS) is detected
75
define(['peg'], function(peg) {
76
  const parser = peg.generate(grammar);
77
  return parser;
78
});
79
```
80

81
**Browser-Optimized Parser Generation:**
82

83
```javascript
84
// Generate optimized parser for browser delivery
85
const browserParser = peg.generate(grammar, {
86
  output: "source",
87
  format: "globals",       // Creates global variable
88
  exportVar: "MyParser",   // Name of global variable
89
  optimize: "size"         // Minimize code size
90
});
91

92
// Save browserParser string to .js file for browser inclusion
93
// Usage: <script src="generated-parser.js"></script>
94
//        MyParser.parse("input");
95
```
96

97
### Parser Object Interface
98

99
Generated parsers provide a consistent interface for parsing input strings.
100

101
```javascript { .api }
102
/**
103
 * Generated parser interface
104
 */
105
interface GeneratedParser {
106
  /** 
107
   * Parse input string using the generated grammar
108
   * @param input - String to parse
109
   * @param options - Optional parsing configuration
110
   * @returns Parse result (depends on grammar actions)
111
   * @throws {SyntaxError} If input doesn't match grammar
112
   */
113
  parse(input, options);
114
}
115

116
/**
117
 * Parse options for generated parsers
118
 */
119
interface ParseOptions {
120
  /** Rule name to start parsing from (must be in allowedStartRules) */
121
  startRule?: string;
122
  /** Custom tracer object for debugging */
123
  tracer?: any;
124
}
125
```
126

127
**Usage Examples:**
128

129
```javascript
130
// Basic parsing
131
const result = parser.parse("some input");
132

133
// Parse with specific start rule
134
const result = parser.parse("expression", { startRule: "expr" });
135

136
// Parse with custom tracer for debugging
137
const tracer = {
138
  trace: function(event) {
139
    console.log("Parse event:", event);
140
  }
141
};
142
const result = parser.parse("input", { tracer: tracer });
143
```
144

145
## Generation Options
146

147
### Output Control
148

149
```javascript { .api }
150
interface OutputOptions {
151
  /** 
152
   * Parser output type
153
   * - "parser": Return executable parser object (default)
154
   * - "source": Return parser source code as string  
155
   */
156
  output?: "parser" | "source";
157
  
158
  /** 
159
   * Generated code format (only when output is "source")
160
   * - "amd": AMD module format
161
   * - "bare": Plain JavaScript (compiler default)
162
   * - "commonjs": CommonJS module format (CLI default)
163
   * - "globals": Global variable assignment
164
   * - "umd": Universal Module Definition
165
   */
166
  format?: "amd" | "bare" | "commonjs" | "globals" | "umd";
167
  
168
  /** 
169
   * Global variable name for parser (globals/umd formats only)
170
   */
171
  exportVar?: string;
172
}
173
```
174

175
### Parser Behavior
176

177
```javascript { .api }
178
interface BehaviorOptions {
179
  /** 
180
   * Rules the parser can start parsing from
181
   * Default: [first rule in grammar]
182
   */
183
  allowedStartRules?: string[];
184
  
185
  /** 
186
   * Enable result caching to avoid exponential parsing time
187
   * Trade-off: faster parsing vs higher memory usage
188
   * Default: false
189
   */
190
  cache?: boolean;
191
  
192
  /** 
193
   * Enable parser progress tracing for debugging
194
   * Default: false
195
   */
196
  trace?: boolean;
197
  
198
  /** 
199
   * Optimization target
200
   * - "speed": Optimize for parsing speed (default)
201
   * - "size": Optimize for generated code size
202
   */
203
  optimize?: "speed" | "size";
204
}
205
```
206

207
### Module Dependencies
208

209
```javascript { .api }
210
interface DependencyOptions {
211
  /** 
212
   * Module dependencies map for generated parser
213
   * Maps variable names to module IDs
214
   * Valid for: amd, commonjs, umd formats
215
   * Example: { "lodash": "lodash", "utils": "./utils" }
216
   */
217
  dependencies?: { [variable: string]: string };
218
  
219
  /** 
220
   * Plugin instances to use during generation
221
   * Plugins can modify compilation passes and options
222
   */
223
  plugins?: any[];
224
}
225
```
226

227
**Usage Examples:**
228

229
```javascript
230
// Generate CommonJS module with dependencies
231
const source = peg.generate(grammar, {
232
  output: "source",
233
  format: "commonjs", 
234
  dependencies: {
235
    "lodash": "lodash",
236
    "utils": "./my-utils"
237
  }
238
});
239

240
// Generate optimized parser for production
241
const parser = peg.generate(grammar, {
242
  cache: true,
243
  optimize: "speed",
244
  allowedStartRules: ["program", "expression"]
245
});
246

247
// Generate browser-ready global parser
248
const source = peg.generate(grammar, {
249
  output: "source",
250
  format: "globals",
251
  exportVar: "MyParser"
252
});
253
```
254

255
## Error Handling
256

257
### Grammar Errors
258

259
```javascript { .api }
260
/**
261
 * Thrown when grammar contains semantic errors
262
 */
263
class GrammarError extends Error {
264
  name: "GrammarError";
265
  message: string;
266
  location?: LocationRange;
267
}
268
```
269

270
**Common Grammar Errors:**
271
- Undefined rule references
272
- Duplicate rule definitions  
273
- Duplicate labels within rules
274
- Infinite recursion patterns
275
- Infinite repetition patterns
276

277
**Error Handling Example:**
278

279
```javascript
280
try {
281
  const parser = peg.generate(invalidGrammar);
282
} catch (error) {
283
  if (error.name === "GrammarError") {
284
    console.error("Grammar error:", error.message);
285
    if (error.location) {
286
      console.error(`At line ${error.location.start.line}`);
287
    }
288
  } else if (error.name === "SyntaxError") {
289
    console.error("Grammar syntax error:", error.message);
290
  }
291
}
292
```
293

294
### Parser Errors
295

296
Generated parsers throw `SyntaxError` when input doesn't match the grammar.
297

298
```javascript { .api }
299
/**
300
 * Thrown by generated parsers when input doesn't match grammar
301
 */
302
class SyntaxError extends Error {
303
  name: "SyntaxError";
304
  message: string;
305
  expected: any[];
306
  found: string;
307
  location: LocationRange;
308
}
309
```
310

311
**Parser Error Handling Example:**
312

313
```javascript
314
try {
315
  const result = parser.parse("invalid input");
316
} catch (error) {
317
  if (error.name === "SyntaxError") {
318
    console.error("Parse error:", error.message);
319
    console.error("Expected:", error.expected);
320
    console.error("Found:", error.found);
321
    console.error(`At line ${error.location.start.line}, column ${error.location.start.column}`);
322
  }
323
}
324
```