0
# Parsimmon
1

2
Parsimmon is a monadic LL(infinity) parser combinator library that enables developers to build complex parsers from simple, composable parsing primitives. It provides a declarative approach to parsing where small parsers are combined to create larger, more sophisticated parsers for text processing, language interpretation, and data format parsing.
3

4
## Package Information
5

6
- **Package Name**: parsimmon
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install parsimmon`
10

11
## Core Imports
12

13
```javascript
14
const Parsimmon = require("parsimmon");
15
```
16

17
For ES6 modules:
18

19
```javascript
20
import Parsimmon from "parsimmon";
21
```
22

23
## Basic Usage
24

25
```javascript
26
const Parsimmon = require("parsimmon");
27

28
// Create a simple parser for integers
29
const integer = Parsimmon.regexp(/[0-9]+/).map(Number);
30

31
// Parse a string
32
const result = integer.parse("42");
33
console.log(result); // { status: true, value: 42 }
34

35
// Build a more complex parser using combinators
36
const pair = Parsimmon.seq(
37
  integer.skip(Parsimmon.string(",")),
38
  integer
39
).map(([x, y]) => ({ x, y }));
40

41
const pairResult = pair.parse("10,20");
42
console.log(pairResult); // { status: true, value: { x: 10, y: 20 } }
43
```
44

45
## Architecture
46

47
Parsimmon is built around several core concepts:
48

49
- **Parser Constructor**: The main `Parsimmon(action)` function creates parser instances
50
- **Static Generators**: Factory methods like `string()`, `regexp()`, `seq()` create parsers from primitives
51
- **Instance Methods**: Chainable methods on parser instances for transformation and combination
52
- **Combinators**: Functions that combine multiple parsers into more complex parsers
53
- **Monadic Interface**: Support for `map`, `chain`, and other functional programming patterns
54
- **Binary Support**: Specialized parsers for binary data formats and buffer operations
55
- **Error Handling**: Detailed error reporting with position information
56

57
## Capabilities
58

59
### Core Parser Construction
60

61
Fundamental parser creation and execution functionality. Essential for all parsing operations.
62

63
```javascript { .api }
64
function Parsimmon(action);
65

66
// Static parser generators
67
Parsimmon.string(str);
68
Parsimmon.regexp(re, group?);
69
Parsimmon.succeed(value);
70
Parsimmon.of(value);
71
Parsimmon.fail(message);
72

73
// Lookahead and assertions
74
Parsimmon.lookahead(parser);
75
Parsimmon.notFollowedBy(parser);
76

77
// Utility functions
78
Parsimmon.isParser(obj);
79
Parsimmon.makeSuccess(index, value);
80
Parsimmon.makeFailure(index, expected);
81
Parsimmon.formatError(input, error);
82
```
83

84
[Core Parser Construction](./core-parsers.md)
85

86
### String and Character Parsing
87

88
Built-in parsers for common string and character matching patterns.
89

90
```javascript { .api }
91
// Pre-built parsers
92
Parsimmon.any;
93
Parsimmon.digit;
94
Parsimmon.digits;
95
Parsimmon.letter;
96
Parsimmon.letters;
97
Parsimmon.whitespace;
98
Parsimmon.optWhitespace;
99
Parsimmon.cr;
100
Parsimmon.lf;
101
Parsimmon.crlf;
102
Parsimmon.newline;
103
Parsimmon.end;
104
Parsimmon.eof;
105
Parsimmon.all;
106

107
// Character set parsers
108
Parsimmon.oneOf(str);
109
Parsimmon.noneOf(str);
110
Parsimmon.range(begin, end);
111

112
// Predicate-based parsers
113
Parsimmon.test(predicate);
114
Parsimmon.takeWhile(predicate);
115
```
116

117
[String and Character Parsing](./string-parsers.md)
118

119
### Parser Combinators
120

121
Functions that combine multiple parsers into more complex parsing patterns. Core to building sophisticated parsers.
122

123
```javascript { .api }
124
Parsimmon.seq(p1, p2, ...pn);
125
Parsimmon.seqMap(p1, p2, ...pn, mapperFn);
126
Parsimmon.alt(p1, p2, ...pn);
127
Parsimmon.sepBy(content, separator);
128
Parsimmon.sepBy1(content, separator);
129
```
130

131
[Parser Combinators](./combinators.md)
132

133
### Parser Transformation Methods
134

135
Instance methods for transforming and chaining parsers. Essential for building parsing pipelines.
136

137
```javascript { .api }
138
// Execution methods
139
parser.parse(input);
140
parser.tryParse(input);
141

142
// Transformation methods
143
parser.map(fn);
144
parser.contramap(fn);
145
parser.promap(inputFn, outputFn);
146
parser.result(value);
147
parser.chain(fn);
148
parser.then(next);
149
parser.skip(next);
150

151
// String manipulation
152
parser.tie();
153
parser.tieWith(separator);
154

155
// Control flow
156
parser.fallback(value);
157
parser.assert(condition, message);
158

159
// Repetition methods
160
parser.many();
161
parser.times(min, max);
162
parser.atLeast(n);
163
parser.atMost(n);
164

165
// Utility methods
166
parser.desc(description);
167
parser.thru(wrapper);
168
```
169

170
[Parser Transformation](./transformation.md)
171

172
### Binary Data Parsing
173

174
Specialized parsers for binary data formats, buffers, and bit-level operations.
175

176
```javascript { .api }
177
// Basic binary parsers
178
Parsimmon.Binary.byte(b);
179
Parsimmon.Binary.buffer(length);
180
Parsimmon.Binary.encodedString(encoding, length);
181

182
// Integer parsers (Big Endian)
183
Parsimmon.Binary.uintBE(length);
184
Parsimmon.Binary.intBE(length);
185
Parsimmon.Binary.uint8BE;
186
Parsimmon.Binary.uint16BE;
187
Parsimmon.Binary.uint32BE;
188
Parsimmon.Binary.int8BE;
189
Parsimmon.Binary.int16BE;
190
Parsimmon.Binary.int32BE;
191

192
// Integer parsers (Little Endian)
193
Parsimmon.Binary.uintLE(length);
194
Parsimmon.Binary.intLE(length);
195
Parsimmon.Binary.uint8LE;
196
Parsimmon.Binary.uint16LE;
197
Parsimmon.Binary.uint32LE;
198
Parsimmon.Binary.int8LE;
199
Parsimmon.Binary.int16LE;
200
Parsimmon.Binary.int32LE;
201

202
// Floating point parsers
203
Parsimmon.Binary.floatBE;
204
Parsimmon.Binary.floatLE;
205
Parsimmon.Binary.doubleBE;
206
Parsimmon.Binary.doubleLE;
207

208
// Bit-level parsers
209
Parsimmon.Binary.bitSeq(alignments);
210
Parsimmon.Binary.bitSeqObj(namedAlignments);
211
```
212

213
[Binary Data Parsing](./binary-parsing.md)
214

215
### Language Creation
216

217
Framework for creating complete parsing languages with interdependent rules.
218

219
```javascript { .api }
220
Parsimmon.createLanguage(parsers);
221
Parsimmon.lazy(fn);
222
```
223

224
[Language Creation](./language-creation.md)
225

226
## Types
227

228
```javascript { .api }
229
// Parse result structure
230
interface ParseResult {
231
  status: boolean;
232
  value?: any;
233
  index?: {
234
    offset: number;
235
    line: number;
236
    column: number;
237
  };
238
  expected?: string[];
239
}
240

241
// Parser instance interface (conceptual - JavaScript doesn't have interfaces)
242
interface Parser {
243
  // Execution
244
  parse(input): ParseResult;
245
  tryParse(input): any; // throws on failure
246
  
247
  // Transformation
248
  map(fn): Parser;
249
  chain(fn): Parser;
250
  then(next): Parser;
251
  skip(next): Parser;
252
  
253
  // Repetition
254
  many(): Parser;
255
  times(min, max?): Parser;
256
  atLeast(n): Parser;
257
  atMost(n): Parser;
258
  
259
  // Combination
260
  or(alternative): Parser;
261
  sepBy(separator): Parser;
262
  sepBy1(separator): Parser;
263
  
264
  // Utilities
265
  desc(description): Parser;
266
  mark(): Parser;
267
  node(name): Parser;
268
  trim(parser): Parser;
269
  wrap(left, right): Parser;
270
  
271
  // Fantasy Land methods
272
  empty(): Parser;
273
  concat(other): Parser;
274
  ap(other): Parser;
275
  "fantasy-land/ap"(other): Parser;
276
  "fantasy-land/chain"(fn): Parser;
277
  "fantasy-land/concat"(other): Parser;
278
  "fantasy-land/empty"(): Parser;
279
  "fantasy-land/of"(value): Parser;
280
  "fantasy-land/map"(fn): Parser;
281
}
282
```