Parsimmon Parser Combinator Library

1.18.1 · active · verified Tue Apr 21

Parsimmon is a compact, monadic LL(infinity) parser combinator library for JavaScript, enabling the construction of complex parsers from smaller, composable units. It is currently at version 1.18.1 and supports both modern Node.js environments and older browser versions (down to IE7). Its release cadence appears to be infrequent, with the last major feature release (1.7.0) being in 2018, though bug fixes and minor updates have occurred more recently. Key differentiators include its inspiration from Haskell's Parsec and Promises/A+ for its API design, its support for binary parsing using Node.js Buffers, and its compatibility with the Fantasy Land specification, implementing several algebraic structures like Semigroup, Apply, Applicative, Functor, Chain, and Monad. It distinguishes itself by offering a functional and declarative approach to parsing, making grammars easy to read and maintain.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'string')
```
cause Attempting to destructure static methods from the `parsimmon` module in an ESM context (e.g., `import { string } from 'parsimmon';`) when the module is a CJS default export.

fix Import the `Parsimmon` object as a default import and access methods via `Parsimmon.string` (e.g., `import Parsimmon from 'parsimmon'; const myParser = Parsimmon.string('hello');`).
```
ReferenceError: Parsimmon is not defined
```
cause In a browser environment, the `Parsimmon` global is not available because the UMD build was not loaded via a script tag, or in a Node.js environment where `require()` or `import` was not used correctly.

fix For browsers, ensure a `<script>` tag loading the UMD build (e.g., from unpkg) is present before attempting to use `Parsimmon`. For Node.js, use `const Parsimmon = require('parsimmon');` or `import Parsimmon from 'parsimmon';` to import the library.
```
Error: Expected a character in the range 'x' to 'y' but got "..."
```
cause A parser combinator like `Parsimmon.range(begin, end)` or `Parsimmon.letter` encountered an unexpected character in the input string, indicating a mismatch between the parser's expectation and the actual data.

fix Inspect the input string for unexpected characters or malformed data. Adjust the parser definition to correctly handle the expected input format, or add `.or()` combinators to handle alternative valid patterns. The error message from `parser.parse(input)` usually provides line and column details.

Warnings

gotcha Parsimmon is primarily a CommonJS module with UMD builds for browsers. While Node.js can import CommonJS modules using `import`, it only supports default imports for the entire module. Directly named imports for static methods (e.g., `import { string } from 'parsimmon'`) will not work as expected in an ESM context.
Fix: Always import the main `Parsimmon` object as a default import (e.g., `import Parsimmon from 'parsimmon'`) and access static methods or parser methods via `Parsimmon.<methodName>` or `parserInstance.<methodName>`.
breaking In version 1.0.0, `parser.empty` was changed from a property to a function (`parser.empty()`), and `f.ap(x)` was changed to `x.ap(f)` to align with Fantasy Land specifications. Code using the old syntax for these specific combinators will break.
Fix: Update `parser.empty` calls to `parser.empty()` and adjust the order of arguments for `ap` to `x.ap(f)`.
breaking In version 0.9.1, `Parsimmon.seqMap` began throwing an error when called with zero arguments or if the final argument was not a function. This enforces correct usage of the combinator.
Fix: Ensure `Parsimmon.seqMap` is always called with at least one parser argument and that the last argument is a mapping function.
breaking In version 0.9.0, `Parsimmon.regexp` (aliased as `P.regex` previously) was updated to throw an error if the regular expression included flags other than `i` (case-insensitive), `m` (multiline), or `u` (unicode). This might affect parsers relying on unsupported regex flags.
Fix: Review `Parsimmon.regexp` usage and ensure only `i`, `m`, or `u` flags are used. Adjust regular expressions or parsing logic if other flags were previously relied upon.
gotcha The library's development seems less active recently, with the latest significant feature release (v1.7.0) being in 2018, though maintenance updates exist. While stable and well-tested (100% coverage since 1.6.1), rapid introduction of new features or quick resolution of complex issues might not be expected.
Fix: Evaluate active community support and contribution patterns on the GitHub repository for critical, time-sensitive projects. Consider contributing or preparing for self-maintenance if specific niche features or rapid development are required.

Install

npm install parsimmon npm
yarn add parsimmon yarn
pnpm add parsimmon pnpm

Imports

Parsimmon
wrong:
```
const Parsimmon = require('parsimmon').Parsimmon
```
correct:
```
import Parsimmon from 'parsimmon'
```
Parsimmon exports itself as the default, making named imports unnecessary for the top-level object. For CommonJS, `require('parsimmon')` directly returns the Parsimmon object.
Parsimmon.string
wrong:
```
import { string } from 'parsimmon';
```
correct:
```
import Parsimmon from 'parsimmon';
const myParser = Parsimmon.string('hello');
```
Most core parser functions are static methods on the `Parsimmon` object, not named exports. Destructuring directly from the package root is incorrect for these.

parser.map

wrong:

import { map } from 'parsimmon';
map(parser, fn);

correct:

import Parsimmon from 'parsimmon';
const myParser = Parsimmon.string('hello').map(s => s.toUpperCase());

Parser combinators like `map` are methods on a `Parsimmon` parser instance, intended for chaining, following a monadic style.

Parsimmon.createLanguage
wrong:
```
const { createLanguage } = require('parsimmon');
```
correct:
```
import Parsimmon from 'parsimmon';
const language = Parsimmon.createLanguage({});
```
Similar to `Parsimmon.string`, `createLanguage` is a static method of the main `Parsimmon` object, not a direct named export from the module.

Quickstart

Demonstrates defining basic parsers for digits and operators, combining them to parse arithmetic expressions and comma-separated lists, and handling parse results.

import Parsimmon from 'parsimmon';

// Define basic parsers
const digit = Parsimmon.regexp(/[0-9]/);
const plus = Parsimmon.string('+');
const minus = Parsimmon.string('-');

// Combine parsers to recognize an integer (one or more digits)
const integer = digit.atLeast(1).map(digits => parseInt(digits.join(''), 10));

// Combine parsers to recognize an operator
const operator = plus.or(minus);

// Define a parser for a simple arithmetic expression like '123+45'
const expression = Parsimmon.seq(integer, operator, integer).map(
  ([left, op, right]) => {
    if (op === '+') return left + right;
    if (op === '-') return left - right;
    return NaN; // Should not happen with defined operators
  }
);

// Parse some input strings
const result1 = expression.parse('123+45');
const result2 = expression.parse('99-10');
const result3 = expression.parse('5*2'); // Will fail

console.log('Result for "123+45":', result1);
console.log('Result for "99-10":', result2);
console.log('Result for "5*2" (expected failure):', result3);

// Example of parsing a more complex structure (e.g., a comma-separated list of numbers)
const comma = Parsimmon.string(',');
const listOfNumbers = integer.sepBy(comma).map(nums => nums.join(', '));
const listResult = listOfNumbers.parse('1,2,3,4,5');
console.log('List of numbers for "1,2,3,4,5":', listResult);

view raw JSON →