or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

binary-parsing.mdcombinators.mdcore-parsers.mdindex.mdlanguage-creation.mdstring-parsers.mdtransformation.md
tile.json

tessl/npm-parsimmon

A monadic LL(infinity) parser combinator library

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/parsimmon@1.18.x

To install, run

npx @tessl/cli install tessl/npm-parsimmon@1.18.0

index.mddocs/

Parsimmon

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.

Package Information

  • Package Name: parsimmon
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install parsimmon

Core Imports

const Parsimmon = require("parsimmon");

For ES6 modules:

import Parsimmon from "parsimmon";

Basic Usage

const Parsimmon = require("parsimmon");

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

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

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

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

Architecture

Parsimmon is built around several core concepts:

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

Capabilities

Core Parser Construction

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

function Parsimmon(action);

// Static parser generators
Parsimmon.string(str);
Parsimmon.regexp(re, group?);
Parsimmon.succeed(value);
Parsimmon.of(value);
Parsimmon.fail(message);

// Lookahead and assertions
Parsimmon.lookahead(parser);
Parsimmon.notFollowedBy(parser);

// Utility functions
Parsimmon.isParser(obj);
Parsimmon.makeSuccess(index, value);
Parsimmon.makeFailure(index, expected);
Parsimmon.formatError(input, error);

Core Parser Construction

String and Character Parsing

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

// Pre-built parsers
Parsimmon.any;
Parsimmon.digit;
Parsimmon.digits;
Parsimmon.letter;
Parsimmon.letters;
Parsimmon.whitespace;
Parsimmon.optWhitespace;
Parsimmon.cr;
Parsimmon.lf;
Parsimmon.crlf;
Parsimmon.newline;
Parsimmon.end;
Parsimmon.eof;
Parsimmon.all;

// Character set parsers
Parsimmon.oneOf(str);
Parsimmon.noneOf(str);
Parsimmon.range(begin, end);

// Predicate-based parsers
Parsimmon.test(predicate);
Parsimmon.takeWhile(predicate);

String and Character Parsing

Parser Combinators

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

Parsimmon.seq(p1, p2, ...pn);
Parsimmon.seqMap(p1, p2, ...pn, mapperFn);
Parsimmon.alt(p1, p2, ...pn);
Parsimmon.sepBy(content, separator);
Parsimmon.sepBy1(content, separator);

Parser Combinators

Parser Transformation Methods

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

// Execution methods
parser.parse(input);
parser.tryParse(input);

// Transformation methods
parser.map(fn);
parser.contramap(fn);
parser.promap(inputFn, outputFn);
parser.result(value);
parser.chain(fn);
parser.then(next);
parser.skip(next);

// String manipulation
parser.tie();
parser.tieWith(separator);

// Control flow
parser.fallback(value);
parser.assert(condition, message);

// Repetition methods
parser.many();
parser.times(min, max);
parser.atLeast(n);
parser.atMost(n);

// Utility methods
parser.desc(description);
parser.thru(wrapper);

Parser Transformation

Binary Data Parsing

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

// Basic binary parsers
Parsimmon.Binary.byte(b);
Parsimmon.Binary.buffer(length);
Parsimmon.Binary.encodedString(encoding, length);

// Integer parsers (Big Endian)
Parsimmon.Binary.uintBE(length);
Parsimmon.Binary.intBE(length);
Parsimmon.Binary.uint8BE;
Parsimmon.Binary.uint16BE;
Parsimmon.Binary.uint32BE;
Parsimmon.Binary.int8BE;
Parsimmon.Binary.int16BE;
Parsimmon.Binary.int32BE;

// Integer parsers (Little Endian)
Parsimmon.Binary.uintLE(length);
Parsimmon.Binary.intLE(length);
Parsimmon.Binary.uint8LE;
Parsimmon.Binary.uint16LE;
Parsimmon.Binary.uint32LE;
Parsimmon.Binary.int8LE;
Parsimmon.Binary.int16LE;
Parsimmon.Binary.int32LE;

// Floating point parsers
Parsimmon.Binary.floatBE;
Parsimmon.Binary.floatLE;
Parsimmon.Binary.doubleBE;
Parsimmon.Binary.doubleLE;

// Bit-level parsers
Parsimmon.Binary.bitSeq(alignments);
Parsimmon.Binary.bitSeqObj(namedAlignments);

Binary Data Parsing

Language Creation

Framework for creating complete parsing languages with interdependent rules.

Parsimmon.createLanguage(parsers);
Parsimmon.lazy(fn);

Language Creation

Types

// Parse result structure
interface ParseResult {
  status: boolean;
  value?: any;
  index?: {
    offset: number;
    line: number;
    column: number;
  };
  expected?: string[];
}

// Parser instance interface (conceptual - JavaScript doesn't have interfaces)
interface Parser {
  // Execution
  parse(input): ParseResult;
  tryParse(input): any; // throws on failure
  
  // Transformation
  map(fn): Parser;
  chain(fn): Parser;
  then(next): Parser;
  skip(next): Parser;
  
  // Repetition
  many(): Parser;
  times(min, max?): Parser;
  atLeast(n): Parser;
  atMost(n): Parser;
  
  // Combination
  or(alternative): Parser;
  sepBy(separator): Parser;
  sepBy1(separator): Parser;
  
  // Utilities
  desc(description): Parser;
  mark(): Parser;
  node(name): Parser;
  trim(parser): Parser;
  wrap(left, right): Parser;
  
  // Fantasy Land methods
  empty(): Parser;
  concat(other): Parser;
  ap(other): Parser;
  "fantasy-land/ap"(other): Parser;
  "fantasy-land/chain"(fn): Parser;
  "fantasy-land/concat"(other): Parser;
  "fantasy-land/empty"(): Parser;
  "fantasy-land/of"(value): Parser;
  "fantasy-land/map"(fn): Parser;
}