Parsimmon

Parsimmon does not provide a Parsimmon.not combinator because inverting a parser's success/failure makes it difficult to report meaningful error messages and creates ambiguity regarding how much input should be consumed.

If you need to ensure a pattern does not follow a certain sequence without consuming input, use .notFollowedBy() or Parsimmon.notFollowedBy().

Parsimmon parsers and .map() statements must be pure. Do not perform side effects such as:

• Pushing to an external array.
• Modifying objects.
• console.log.
• Reading from external data sources.
• Generating random numbers.

Why: Parsimmon uses backtracking (e.g., via Parsimmon.alt). If a parser performs a side effect and then fails, Parsimmon will backtrack to try an alternative, but the side effect cannot be undone. This leads to incorrect state (e.g., duplicate entries in an array).

Accepts a function that returns a parser, which is evaluated the first time the parser is used. This is essential for implementing recursive parsers or referencing parsers that haven't been defined yet.

Note: If you are using Parsimmon.createLanguage, Parsimmon.lazy is typically not needed.

var Value = Parsimmon.lazy(function() {
  return Parsimmon.alt(
    Parsimmon.string("X"),
    Parsimmon.string("(")
      .then(Value)
      .skip(Parsimmon.string(")"))
  );
});

Value.parse("X"); // => {status: true, value: 'X'}
Value.parse("(X)"); // => {status: true, value: 'X'}
Value.parse("((X))"); // => {status: true, value: 'X'}

To parse languages like Python or Markdown that rely on indentation (nesting structure), use Parsimmon.createLanguage inside a constructor function. This allows you to pass context (like indentSize) and generate new language instances with updated indentation levels as you descend into nested blocks.

const createMyLanguage = ({ indentSize }) =>
  Parsimmon.createLanguage({
    Indent: () => Parsimmon.string(" ").times(indentSize),
    ForLoop: l =>
      l.SomeBlockStart.chain(block => {
        const lang = createMyLanguage({
          indentSize: block.newIndentSize
        });
        return lang.Item.atLeast(1);
      })
  });

const MyLanguage = createMyLanguage({ indentSize: 0 });
const ast = MyLanguage.File.tryParse(/* ... */);

To use Parsimmon effectively, understand these three core concepts:

• Yields: When a function is said to yield a value (e.g., an array of strings), it means the resulting parser, when executed via .parse(), will return an object containing that value.
• Input: The string provided to the .parse() method is referred to as the input.
• Consumes: A parser consumes text when it successfully matches it, moving the internal pointer forward so that subsequent parsers only see the remaining unconsumed text.

Parsimmon parsers represent actions on a text stream. You can execute a parser using two primary methods:

1. .parse(string): Returns a result object.
   • If successful: { status: true, value: <yielded_value> }.
   • If failed: { status: false, index: <error_index>, expected: [<messages>], error: { offset, line, column } }.
2. .tryParse(string): Returns the yielded value directly if successful, or throws an error if the parse fails.

You can use Parsimmon.formatError(source, error) to convert a parse error object into a human-readable string using the original source text.

Parsimmon can be used in Node.js environments or directly in the browser.

Node.js

Install via npm using the package name parsimmon.

Browser

Include Parsimmon via a script tag. It exports a global variable called Parsimmon. You can use unpkg to fetch the latest build.

Note: Parsimmon is currently unmaintained.