CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-parsimmon

A monadic LL(infinity) parser combinator library

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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;
}
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/parsimmon@1.18.x
Publish Source
CLI
Badge
tessl/npm-parsimmon badge