0
# Core Parsing
1

2
Core parsing functionality using the Earley algorithm for parsing any context-free grammar. Supports streaming input, error recovery, and ambiguous grammars.
3

4
## Capabilities
5

6
### Parser Class
7

8
The main parsing engine that implements the Earley parsing algorithm with streaming support.
9

10
```javascript { .api }
11
/**
12
 * Create a new parser instance
13
 * @param rules - Grammar rules object (compiled grammar) or Grammar instance
14
 * @param start - Start symbol name (optional if using Grammar instance)
15
 * @param options - Parser configuration options
16
 */
17
class Parser {
18
  constructor(rules, start, options);
19
  constructor(grammar, options);
20
}
21

22
/**
23
 * Parser configuration options
24
 */
25
interface ParserOptions {
26
  /** Keep history for rewinding (default: false) */
27
  keepHistory?: boolean;
28
  /** Custom lexer instance (default: StreamLexer) */
29
  lexer?: object;
30
}
31
```
32

33
**Usage Examples:**
34

35
```javascript
36
const nearley = require("nearley");
37

38
// Using compiled grammar rules
39
const compiledGrammar = require("./my-grammar.js");
40
const parser1 = new nearley.Parser(compiledGrammar);
41

42
// Using Grammar instance
43
const grammar = nearley.Grammar.fromCompiled(compiledGrammar);
44
const parser2 = new nearley.Parser(grammar);
45

46
// With options
47
const parser3 = new nearley.Parser(grammar, {
48
  keepHistory: true,
49
  lexer: customLexer
50
});
51
```
52

53
### Parser Static Properties
54

55
```javascript { .api }
56
/**
57
 * Reserved token for indicating parse failure in postprocessors
58
 */
59
static Parser.fail: object;
60
```
61

62
### Feed Input
63

64
Process input text through the parser in chunks.
65

66
```javascript { .api }
67
/**
68
 * Feed a chunk of input to the parser
69
 * @param chunk - String to parse
70
 * @returns Parser instance for chaining
71
 * @throws Error if parsing fails
72
 */
73
feed(chunk: string): Parser;
74
```
75

76
**Usage Examples:**
77

78
```javascript
79
const parser = new nearley.Parser(grammar);
80

81
try {
82
  // Parse in chunks
83
  parser.feed("hello");
84
  parser.feed(" world");
85
  
86
  // Or parse all at once
87
  parser.feed("complete input text");
88
  
89
  console.log("Parse results:", parser.results);
90
} catch (error) {
91
  console.error("Parse error:", error.message);
92
  console.error("Error at token index:", error.offset);
93
}
94
```
95

96
### State Management
97

98
Save and restore parser state for advanced parsing scenarios.
99

100
```javascript { .api }
101
/**
102
 * Save current parser state
103
 * @returns Column representing the current parse state
104
 */
105
save(): Column;
106

107
/**
108
 * Restore parser to a previously saved state
109
 * @param column - Previously saved parse state
110
 */
111
restore(column: Column): void;
112

113
/**
114
 * Rewind parser to a specific token index (deprecated - use save/restore instead)
115
 * @param index - Token index to rewind to
116
 * @throws Error if keepHistory is not enabled
117
 * @deprecated Use save() and restore() methods instead
118
 */
119
rewind(index: number): void;
120
```
121

122
**Usage Examples:**
123

124
```javascript
125
const parser = new nearley.Parser(grammar, { keepHistory: true });
126

127
// Parse some input
128
parser.feed("partial input");
129
const checkpoint = parser.save();
130

131
// Continue parsing
132
try {
133
  parser.feed(" more input");
134
} catch (error) {
135
  // Restore to checkpoint and try alternative
136
  parser.restore(checkpoint);
137
  parser.feed(" alternative input");
138
}
139
```
140

141
### Results and Completion
142

143
Get final parse results and handle parsing completion.
144

145
```javascript { .api }
146
/**
147
 * Get all possible parse results
148
 * @returns Array of parse results (empty if no complete parses)
149
 */
150
finish(): any[];
151

152
/**
153
 * Parser instance properties
154
 */
155
interface Parser {
156
  /** Current parsing results */
157
  results: any[];
158
  /** Parse table (array of columns) */
159
  table: Column[];
160
  /** Current token index */
161
  current: number;
162
  /** Grammar being used */
163
  grammar: Grammar;
164
  /** Parser options */
165
  options: ParserOptions;
166
  /** Current lexer instance */
167
  lexer: object;
168
  /** Current lexer state */
169
  lexerState: object;
170
}
171
```
172

173
**Usage Examples:**
174

175
```javascript
176
const parser = new nearley.Parser(grammar);
177

178
parser.feed("input text");
179

180
// Check results
181
if (parser.results.length === 0) {
182
  console.log("No valid parse found");
183
} else if (parser.results.length === 1) {
184
  console.log("Unique parse:", parser.results[0]);
185
} else {
186
  console.log("Ambiguous parse:", parser.results.length, "interpretations");
187
  parser.results.forEach((result, i) => {
188
    console.log(`Parse ${i + 1}:`, result);
189
  });
190
}
191

192
// Get final results explicitly
193
const finalResults = parser.finish();
194
```
195

196
### Error Handling
197

198
Comprehensive error reporting with detailed diagnostics.
199

200
```javascript { .api }
201
/**
202
 * Generate error message for unexpected token
203
 * @param token - The problematic token
204
 * @returns Formatted error message with context
205
 */
206
reportError(token: object): string;
207

208
/**
209
 * Generate error message for lexer errors
210
 * @param lexerError - Error from lexer
211
 * @returns Formatted error message
212
 */
213
reportLexerError(lexerError: Error): string;
214

215
/**
216
 * Get display string for a grammar symbol
217
 * @param symbol - Grammar symbol to display
218
 * @returns Human-readable symbol description
219
 */
220
getSymbolDisplay(symbol: any): string;
221
```
222

223
**Error Handling Examples:**
224

225
```javascript
226
const parser = new nearley.Parser(grammar);
227

228
try {
229
  parser.feed("invalid input");
230
} catch (error) {
231
  console.error("Parse failed:", error.message);
232
  
233
  // Error properties
234
  console.log("Error at offset:", error.offset);
235
  console.log("Problematic token:", error.token);
236
  
237
  // The error message includes:
238
  // - Line and column information
239
  // - Context around the error
240
  // - Expected tokens at that position
241
  // - Parse state stack trace
242
}
243
```
244

245
## Internal Types
246

247
```javascript { .api }
248
/**
249
 * Parse state in the Earley algorithm
250
 */
251
interface State {
252
  rule: Rule;
253
  dot: number;
254
  reference: number;
255
  data: any[];
256
  wantedBy: State[];
257
  isComplete: boolean;
258
}
259

260
/**
261
 * Column in the Earley parse table
262
 */
263
interface Column {
264
  grammar: Grammar;
265
  index: number;
266
  states: State[];
267
  wants: object;
268
  scannable: State[];
269
  completed: object;
270
}
271
```