Debugging feature: textual descriptions for parsers

[barona-mika-vilpas]

I think it should be possible to generate a textual description of each parser. This will help when debugging, since you can print the description together with an error, and it can also be used to pretty print the parsers and generally understanding what’s happening in a complex program.

I was planning on doing this using emojis like in the README. I think they do a good job of separating different parts of the description visually.

The 🍕 emoji would indicate a building block parser (I think it’s a cute joke, and I couldn’t find anything better), and ⚙️ might indicate combinators. Then an arrow ➜ could be used to further separate combinator inputs.

The idea is not to have a parseable format, just a way of pretty printing. So humans should be able to figure it out, but it can be a little ambiguous.

I wasn’t able to develop the format fully and I don’t know how it will look for complex parsers.

In fact, ideally, there should be several formats.

A full format which prints the whole structure of the parser.
A concise single-like format.

This came up in the discussion in #64 (comment)

[barona-mika-vilpas]

This might be (partially) implemented with .debug() which I implemented when I was working on the new math example.

// Built-in parser for floating point numbers.
const tupleElement = float();

// Allow whitespace around elements:
const paddedElement = tupleElement.pipe(between(whitespace()));
// Multiple instances of {paddedElement}, separated by a comma:
const separated = paddedElement.pipe(manySepBy(","));

// Surround everything with parentheses:
export const surrounded = separated.pipe(between("(", ")"), between(whitespace())).debug();
// ⬆️ notice the .debug()

It prints something like this when you run the parser (for example in your tests):

      consumed '(1,  2 , 3 )' (length 12)
      at position 0->12
      👍🏻 (Ok)
      {
        "input": "(1,  2 , 3 )",
        "userState": {},
        "position": 12,
        "stack": [],
        "value": [
          1,
          2,
          3
        ],
        "kind": "OK",
        "reason": "expecting a character"
      }
      {
        "type": "map",
        "expecting": "expecting a character matching a predicate"
      }

It's not exactly what the idea was but it should be good for a low level, quick and dirty understanding. It was very useful for me.

I haven't documented this yet, so I'll still keep this open for now.

[barona-mika-vilpas]

Forgot to mention that the best place to read about the .debug() feature is currently in the PR description here #80