0
# PEG.js
1

2
PEG.js is a simple parser generator for JavaScript that produces fast parsers with excellent error reporting. You can use it to process complex data or computer languages and build transformers, interpreters, compilers and other tools easily. It uses parsing expression grammar (PEG) formalism which is more powerful than traditional LL(k) and LR(k) parsers.
3

4
## Package Information
5

6
- **Package Name**: pegjs
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install pegjs`
10
- **Global Installation**: `npm install -g pegjs`
11

12
## Core Imports
13

14
```javascript
15
const peg = require("pegjs");
16

17
// Access individual modules
18
const { generate, GrammarError, parser, compiler } = require("pegjs");
19
```
20

21
For browser usage:
22

23
```html
24
<script src="path/to/peg.js"></script>
25
<!-- PEG.js will be available as a global variable -->
26
<script>
27
  const parser = peg.generate(grammar);
28
</script>
29
```
30

31
## Basic Usage
32

33
```javascript
34
const peg = require("pegjs");
35

36
// Define a simple grammar
37
const grammar = `
38
start = additive
39

40
additive
41
  = left:multiplicative "+" right:additive { return left + right; }
42
  / multiplicative
43

44
multiplicative
45
  = left:primary "*" right:multiplicative { return left * right; }
46
  / primary
47

48
primary
49
  = integer
50
  / "(" additive:additive ")" { return additive; }
51

52
integer "integer"
53
  = digits:[0-9]+ { return parseInt(digits.join(""), 10); }
54
`;
55

56
// Generate parser from grammar
57
const parser = peg.generate(grammar);
58

59
// Use the generated parser
60
const result = parser.parse("2*(3+4)"); // Returns: 14
61
```
62

63
## Architecture
64

65
PEG.js is organized around several key components:
66

67
- **Parser Generator**: Main `generate()` function that creates parsers from grammars
68
- **Grammar Parser**: Built-in parser for PEG grammar syntax that produces ASTs
69
- **Compiler System**: Multi-pass compiler that transforms ASTs into executable parsers
70
- **Visitor Pattern**: AST traversal system for compiler passes and plugins
71
- **CLI Tool**: Command-line interface for generating parsers from grammar files
72
- **Utility Libraries**: Helper functions for arrays, objects, and class inheritance
73

74
## Capabilities
75

76
### Parser Generation
77

78
Core functionality for generating JavaScript parsers from PEG grammar specifications. Supports various output formats and optimization options.
79

80
```javascript { .api }
81
function generate(grammar, options);
82
```
83

84
[Parser Generation](./parser-generation.md)
85

86
### Grammar Parsing  
87

88
Built-in parser for PEG grammar syntax that converts grammar strings into abstract syntax trees.
89

90
```javascript { .api }
91
const parser = {
92
  parse: function(input, options),
93
  SyntaxError: function(message, expected, found, location)
94
};
95
```
96

97
[Grammar Parsing](./grammar-parsing.md)
98

99
### Compiler System
100

101
Multi-pass compiler architecture for transforming grammar ASTs into executable parser code with validation and optimization.
102

103
```javascript { .api }
104
const compiler = {
105
  compile: function(ast, passes, options),
106
  visitor: { build: function(functions) },
107
  passes: {
108
    check: Object,
109
    transform: Object, 
110
    generate: Object
111
  }
112
};
113
```
114

115
[Compiler System](./compiler-system.md)
116

117
### CLI Tool
118

119
Command-line interface for generating parser files from grammar specifications with extensive configuration options.
120

121
```bash
122
pegjs [options] [input_file]
123
```
124

125
[CLI Tool](./cli-tool.md)
126

127
### Utility Modules
128

129
Internal utility modules for array operations, object manipulation, and class inheritance used throughout PEG.js.
130

131
```javascript { .api }
132
const arrays = {
133
  range: function(start, stop),
134
  find: function(array, valueOrPredicate),
135
  indexOf: function(array, valueOrPredicate),
136
  contains: function(array, valueOrPredicate),
137
  each: function(array, iterator),
138
  map: function(array, iterator),
139
  pluck: function(array, key),
140
  every: function(array, predicate),
141
  some: function(array, predicate)
142
};
143

144
const objects = {
145
  keys: function(object),
146
  values: function(object), 
147
  clone: function(object),
148
  defaults: function(object, defaults)
149
};
150

151
const classes = {
152
  subclass: function(child, parent)
153
};
154
```
155

156
[Utility Modules](./utility-modules.md)
157

158
## Core Types
159

160
```javascript { .api }
161
// Main module interface
162
interface PEG {
163
  VERSION: string;
164
  GrammarError: typeof GrammarError;
165
  parser: typeof parser;
166
  compiler: typeof compiler;
167
  generate: (grammar: string, options?: GenerateOptions) => any;
168
}
169

170
// Generation options
171
interface GenerateOptions {
172
  allowedStartRules?: string[];
173
  cache?: boolean;
174
  dependencies?: { [key: string]: string };
175
  exportVar?: string;
176
  format?: "amd" | "bare" | "commonjs" | "globals" | "umd";
177
  optimize?: "speed" | "size";
178
  output?: "parser" | "source";
179
  plugins?: any[];
180
  trace?: boolean;
181
}
182

183
// Grammar error class
184
class GrammarError extends Error {
185
  name: "GrammarError";
186
  message: string;
187
  location?: LocationRange;
188
}
189

190
// Parse options
191
interface ParseOptions {
192
  startRule?: string;
193
  tracer?: any;
194
}
195

196
// Location information
197
interface LocationRange {
198
  start: { offset: number; line: number; column: number };
199
  end: { offset: number; line: number; column: number };
200
}
201
```