0
# Parser Generation
1

2
Core functionality for generating parsers from PEG grammars. The `generate` function is the main entry point for all parser generation operations, providing multiple output formats and extensive configuration options.
3

4
## Capabilities
5

6
### Generate Parser Function
7

8
The primary function for creating parsers from PEG grammar definitions. Supports multiple output formats including parser objects, source code, and ASTs.
9

10
```typescript { .api }
11
/**
12
 * Returns a generated parser object (default behavior)
13
 * @param grammar - PEG grammar string or array of source texts
14
 * @param options - Parser build options
15
 * @returns Parser object ready for parsing input
16
 * @throws {SyntaxError} If grammar contains syntax errors
17
 * @throws {GrammarError} If grammar contains semantic errors
18
 */
19
function generate(
20
  grammar: GrammarInput,
21
  options?: ParserBuildOptions
22
): Parser;
23

24
/**
25
 * Returns the generated source code as a string
26
 * @param grammar - PEG grammar string or array of source texts
27
 * @param options - Source build options with output: "source"
28
 * @returns Generated parser source code
29
 */
30
function generate(
31
  grammar: GrammarInput,
32
  options: SourceBuildOptions<"source">
33
): string;
34

35
/**
36
 * Returns source code with embedded source map as data URI
37
 * @param grammar - PEG grammar string or array of source texts
38
 * @param options - Source build options with output: "source-with-inline-map"
39
 * @returns Generated parser source code with inline source map
40
 */
41
function generate(
42
  grammar: GrammarInput,
43
  options: SourceBuildOptions<"source-with-inline-map">
44
): string;
45

46
/**
47
 * Returns SourceNode object with source code and source map
48
 * @param grammar - PEG grammar string or array of source texts
49
 * @param options - Source build options with output: "source-and-map"
50
 * @returns SourceNode object for generating code and source maps
51
 */
52
function generate(
53
  grammar: GrammarInput,
54
  options: SourceBuildOptions<"source-and-map">
55
): SourceNode;
56

57
/**
58
 * Returns the processed grammar AST
59
 * @param grammar - PEG grammar string or array of source texts
60
 * @param options - Source build options with output: "ast"
61
 * @returns Processed grammar AST with all compilation passes applied
62
 */
63
function generate(
64
  grammar: GrammarInput,
65
  options: SourceOptionsBase<"ast">
66
): ast.Grammar;
67
```
68

69
**Usage Examples:**
70

71
```typescript
72
import { generate } from "peggy";
73
import { SourceNode } from "source-map-generator"; // Required for source-and-map output
74

75
// Basic parser generation
76
const grammar = `
77
  start = "hello" " " name:[a-z]+ { return "Hello, " + name.join(""); }
78
`;
79

80
// Generate parser object (default)
81
const parser = generate(grammar);
82
const result = parser.parse("hello world"); // "Hello, world"
83

84
// Generate source code string
85
const sourceCode = generate(grammar, { output: "source" });
86
console.log(sourceCode); // Generated JavaScript code
87

88
// Generate with source maps
89
const sourceWithMap = generate(grammar, {
90
  output: "source-and-map",
91
  grammarSource: "my-grammar.peggy"
92
});
93
const { code, map } = sourceWithMap.toStringWithSourceMap();
94

95
// Generate AST for inspection
96
const ast = generate(grammar, { output: "ast" });
97
console.log(ast.rules); // Grammar rules
98
```
99

100
### Advanced Parser Options
101

102
Configure parser generation with extensive options for caching, start rules, plugins, and output formats.
103

104
```typescript { .api }
105
/**
106
 * Parser build options for generating parser objects
107
 */
108
interface ParserBuildOptions extends BuildOptionsBase {
109
  /** Output format - defaults to "parser" */
110
  output?: "parser";
111
}
112

113
/**
114
 * Source build options for generating source code
115
 */
116
interface SourceBuildOptions<Output extends SourceOutputs = "source"> extends BuildOptionsBase {
117
  /** Output format */
118
  output: Output;
119
  /** Module format for generated code */
120
  format?: "amd" | "bare" | "commonjs" | "es" | "globals" | "umd";
121
  /** Module dependencies mapping */
122
  dependencies?: Dependencies;
123
  /** Global variable name for "globals" and "umd" formats */
124
  exportVar?: string;
125
}
126

127
/**
128
 * Base build options shared by all generation modes
129
 */
130
interface BuildOptionsBase {
131
  /** Rules allowed as start rules (default: first rule) */
132
  allowedStartRules?: string[];
133
  /** Enable result caching to avoid exponential parsing time */
134
  cache?: boolean;
135
  /** Source identifier for error reporting and source maps */
136
  grammarSource?: any;
137
  /** Plugins to extend compilation process */
138
  plugins?: Plugin[];
139
  /** Enable parse tracing for debugging */
140
  trace?: boolean;
141
  /** Error callback for compilation diagnostics */
142
  error?: DiagnosticCallback;
143
  /** Warning callback for compilation diagnostics */
144
  warning?: DiagnosticCallback;
145
  /** Info callback for compilation diagnostics */
146
  info?: DiagnosticCallback;
147
  /** Override default reserved words */
148
  reservedWords?: string[];
149
}
150

151
/**
152
 * Module dependencies for AMD, CommonJS, ES, and UMD formats
153
 */
154
interface Dependencies {
155
  [variable: string]: string;
156
}
157

158
/**
159
 * Grammar input types
160
 */
161
type GrammarInput = SourceText[] | string;
162

163
/**
164
 * Source text entry with source identifier
165
 */
166
interface SourceText {
167
  source: any;
168
  text: string;
169
}
170

171
/**
172
 * Available output formats
173
 */
174
type SourceOutputs = "parser" | "source-and-map" | "source-with-inline-map" | "source" | "ast";
175
```
176

177
**Advanced Usage Examples:**
178

179
```typescript
180
import { generate } from "peggy";
181

182
// Multiple start rules
183
const parser = generate(grammar, {
184
  allowedStartRules: ["expression", "statement", "program"]
185
});
186

187
// Enable caching for complex grammars
188
const cachedParser = generate(complexGrammar, {
189
  cache: true
190
});
191

192
// CommonJS module generation
193
const commonjsCode = generate(grammar, {
194
  output: "source",
195
  format: "commonjs",
196
  dependencies: {
197
    "utils": "./utils",
198
    "lodash": "lodash"
199
  }
200
});
201

202
// ES module generation
203
const esmCode = generate(grammar, {
204
  output: "source",
205
  format: "es",
206
  dependencies: {
207
    "validator": "./validator.js"
208
  }
209
});
210

211
// UMD with global variable
212
const umdCode = generate(grammar, {
213
  output: "source",
214
  format: "umd",
215
  exportVar: "MyParser"
216
});
217

218
// With plugins and diagnostics
219
const parserWithPlugin = generate(grammar, {
220
  plugins: [myPlugin],
221
  trace: true,
222
  error: (stage, message, location) => console.error(`${stage}: ${message}`),
223
  warning: (stage, message, location) => console.warn(`${stage}: ${message}`)
224
});
225
```
226

227
### Plugin System
228

229
Extend Peggy's compilation process with custom plugins that can modify parser behavior, add new passes, or customize code generation.
230

231
```typescript { .api }
232
/**
233
 * Plugin interface for extending Peggy
234
 */
235
interface Plugin {
236
  /**
237
   * Called during parser generation to configure compilation
238
   * @param config - Mutable configuration object
239
   * @param options - Build options passed to generate()
240
   */
241
  use(config: Config, options: ParserBuildOptions): void;
242
}
243

244
/**
245
 * Plugin configuration object
246
 */
247
interface Config {
248
  /** Parser object for grammar parsing */
249
  parser: Parser;
250
  /** Compilation passes by stage */
251
  passes: Stages;
252
  /** Reserved words list */
253
  reservedWords: string[];
254
}
255

256
/**
257
 * Compilation stages with their passes
258
 */
259
interface Stages {
260
  /** Preparation passes (linking, etc.) */
261
  prepare: Pass[];
262
  /** Validation passes */
263
  check: Pass[];
264
  /** AST transformation passes */
265
  transform: Pass[];
266
  /** Semantic analysis passes */
267
  semantic: Pass[];
268
  /** Code generation passes */
269
  generate: Pass[];
270
}
271

272
/**
273
 * Compilation pass function
274
 */
275
type Pass = (
276
  ast: ast.Grammar,
277
  options: ParserBuildOptions,
278
  session: Session
279
) => void;
280

281
/**
282
 * Compilation session for error reporting
283
 */
284
interface Session {
285
  problems: Problem[];
286
  error(message: string, location?: LocationRange, notes?: DiagnosticNote[]): void;
287
  warning(message: string, location?: LocationRange, notes?: DiagnosticNote[]): void;
288
  info(message: string, location?: LocationRange, notes?: DiagnosticNote[]): void;
289
}
290
```
291

292
**Plugin Usage Example:**
293

294
```typescript
295
import { generate } from "peggy";
296

297
// Custom plugin that logs compilation stages
298
const loggingPlugin = {
299
  use(config, options) {
300
    // Add custom pass to transform stage
301
    config.passes.transform.push((ast, options, session) => {
302
      session.info(`Processing ${ast.rules.length} rules`);
303
    });
304
    
305
    // Modify reserved words
306
    config.reservedWords.push("myReservedWord");
307
  }
308
};
309

310
const parser = generate(grammar, {
311
  plugins: [loggingPlugin],
312
  info: (stage, message) => console.log(`[${stage}] ${message}`)
313
});
314
```
315

316
### Error Handling
317

318
Comprehensive error handling with detailed location information and multiple error types.
319

320
```typescript { .api }
321
/**
322
 * Grammar semantic error
323
 */
324
class GrammarError extends SyntaxError {
325
  /** Error location in grammar */
326
  location?: LocationRange;
327
  /** Additional diagnostic notes */
328
  diagnostics: DiagnosticNote[];
329
  /** Compilation stage where error occurred */
330
  stage: Stage | null;
331
  /** All problems from compilation session */
332
  problems: Problem[];
333
  
334
  /**
335
   * Format error with source context
336
   * @param sources - Mapping from source to text for formatting
337
   * @returns Formatted error message with source context
338
   */
339
  format(sources: SourceText[]): string;
340
}
341

342
/**
343
 * Diagnostic callback for compilation messages
344
 */
345
type DiagnosticCallback = (
346
  stage: Stage,
347
  message: string,
348
  location?: LocationRange,
349
  notes?: DiagnosticNote[]
350
) => void;
351

352
/**
353
 * Diagnostic note with location
354
 */
355
interface DiagnosticNote {
356
  message: string;
357
  location: LocationRange;
358
}
359

360
/**
361
 * Problem tuple from compilation
362
 */
363
type Problem = [
364
  severity: "error" | "info" | "warning",
365
  message: string,
366
  location?: LocationRange,
367
  diagnostics?: DiagnosticNote[]
368
];
369

370
/**
371
 * SourceNode from source-map-generator package (separate dependency)
372
 * Used for source-and-map output format
373
 */
374
interface SourceNode {
375
  toStringWithSourceMap(options?: { file?: string }): { code: string; map: any };
376
  toString(): string;
377
}
378
```
379

380
**Error Handling Example:**
381

382
```typescript
383
import { generate, GrammarError } from "peggy";
384

385
try {
386
  const parser = generate("invalid grammar syntax @#$");
387
} catch (error) {
388
  if (error instanceof GrammarError) {
389
    console.log("Grammar error:", error.message);
390
    console.log("Location:", error.location);
391
    console.log("Stage:", error.stage);
392
    
393
    // Format with source context
394
    const formatted = error.format([{
395
      source: "my-grammar.peggy",
396
      text: "invalid grammar syntax @#$"
397
    }]);
398
    console.log(formatted);
399
  }
400
}
401
```