{"id":16172,"library":"parsimmon","title":"Parsimmon Parser Combinator Library","description":"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.","status":"active","version":"1.18.1","language":"javascript","source_language":"en","source_url":"https://github.com/jneen/parsimmon","tags":["javascript","parsing","parse","parsers","parser combinators"],"install":[{"cmd":"npm install parsimmon","lang":"bash","label":"npm"},{"cmd":"yarn add parsimmon","lang":"bash","label":"yarn"},{"cmd":"pnpm add parsimmon","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Parsimmon exports itself as the default, making named imports unnecessary for the top-level object. For CommonJS, `require('parsimmon')` directly returns the Parsimmon object.","wrong":"const Parsimmon = require('parsimmon').Parsimmon","symbol":"Parsimmon","correct":"import Parsimmon from 'parsimmon'"},{"note":"Most core parser functions are static methods on the `Parsimmon` object, not named exports. Destructuring directly from the package root is incorrect for these.","wrong":"import { string } from 'parsimmon';","symbol":"Parsimmon.string","correct":"import Parsimmon from 'parsimmon';\nconst myParser = Parsimmon.string('hello');"},{"note":"Parser combinators like `map` are methods on a `Parsimmon` parser instance, intended for chaining, following a monadic style.","wrong":"import { map } from 'parsimmon';\nmap(parser, fn);","symbol":"parser.map","correct":"import Parsimmon from 'parsimmon';\nconst myParser = Parsimmon.string('hello').map(s => s.toUpperCase());"},{"note":"Similar to `Parsimmon.string`, `createLanguage` is a static method of the main `Parsimmon` object, not a direct named export from the module.","wrong":"const { createLanguage } = require('parsimmon');","symbol":"Parsimmon.createLanguage","correct":"import Parsimmon from 'parsimmon';\nconst language = Parsimmon.createLanguage({});"}],"quickstart":{"code":"import Parsimmon from 'parsimmon';\n\n// Define basic parsers\nconst digit = Parsimmon.regexp(/[0-9]/);\nconst plus = Parsimmon.string('+');\nconst minus = Parsimmon.string('-');\n\n// Combine parsers to recognize an integer (one or more digits)\nconst integer = digit.atLeast(1).map(digits => parseInt(digits.join(''), 10));\n\n// Combine parsers to recognize an operator\nconst operator = plus.or(minus);\n\n// Define a parser for a simple arithmetic expression like '123+45'\nconst expression = Parsimmon.seq(integer, operator, integer).map(\n  ([left, op, right]) => {\n    if (op === '+') return left + right;\n    if (op === '-') return left - right;\n    return NaN; // Should not happen with defined operators\n  }\n);\n\n// Parse some input strings\nconst result1 = expression.parse('123+45');\nconst result2 = expression.parse('99-10');\nconst result3 = expression.parse('5*2'); // Will fail\n\nconsole.log('Result for \"123+45\":', result1);\nconsole.log('Result for \"99-10\":', result2);\nconsole.log('Result for \"5*2\" (expected failure):', result3);\n\n// Example of parsing a more complex structure (e.g., a comma-separated list of numbers)\nconst comma = Parsimmon.string(',');\nconst listOfNumbers = integer.sepBy(comma).map(nums => nums.join(', '));\nconst listResult = listOfNumbers.parse('1,2,3,4,5');\nconsole.log('List of numbers for \"1,2,3,4,5\":', listResult);\n","lang":"javascript","description":"Demonstrates defining basic parsers for digits and operators, combining them to parse arithmetic expressions and comma-separated lists, and handling parse results."},"warnings":[{"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>`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update `parser.empty` calls to `parser.empty()` and adjust the order of arguments for `ap` to `x.ap(f)`.","message":"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.","severity":"breaking","affected_versions":"1.0.0"},{"fix":"Ensure `Parsimmon.seqMap` is always called with at least one parser argument and that the last argument is a mapping function.","message":"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.","severity":"breaking","affected_versions":"0.9.1"},{"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.","message":"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.","severity":"breaking","affected_versions":"0.9.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.7.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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');`).","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.","error":"TypeError: Cannot read properties of undefined (reading 'string')"},{"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.","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.","error":"ReferenceError: Parsimmon is not defined"},{"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.","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.","error":"Error: Expected a character in the range 'x' to 'y' but got \"...\""}],"ecosystem":"npm"}