Create parser combinator library

[pskfyi]

Finally done 👏 It's ginormous but a lot of work has been done that should make it easier to review:

• More than half of the changes are tests and JSDocs comments.

• The PR is divided into 4 commits.

• The monolithic combinator.ts file has been decomposed as much as possible without impairing maintainability.

  • parser/core.ts exports foundational types and an abstract class CoreParser which underpins all others.

  • parser/ignored.ts and parser/Parser.ts build on top of CoreParser.

  • parser/RegExpParser.ts builds on top of Parser.

  • parser/string.ts, parser/regexp.ts, and parser/sequence.ts build on top of the above.

  • parser/named.ts houses the short, reusable parsers that don't take inputs such as whitespace and end.

[github-actions]

Release Notes Preview

These notes are auto-generated from the conventional commit messages of this PR, and will be re-generated if the commits are updated.

Features

• (md/codeBlock): findAll functions return details objects (67c35c3)

• (parser): init (e7e95d9)

  Parser combinator libraries provide composable parsers used together to construct more complex parsers. This first draft is robust enough for simple DSLs. Notably it does not implement backtracking or a chain combinator, which would allow for more advanced branching. However the TS implementation is very powerful, capable of inferring the return types from complex parsers without explicit compiler hints in userland.

  The following is a brief overview of the features added. Additionally, the four existing parsers in the repository were re-written using the library - they can serve as examples and documentation, in addition to robust JSDoc comments and test suites.

  • The base Parser class implements core helper methods like .fallback(), into(), .not(), .and(), .or(), .optional, .ignore, and .zeroOrMore.

  • Shorthand factory string() makes it easy to construct a Parser from one or more strings.

  • ArrayParser with shorthand factory sequence() provides a specialized Parser with array-specific .flat, .item(), .items(), .join(), and .toObject(), and specialized handling for parser-like inputs and ignored parsers.

  • RegExpParser with shorthand factory regexp() provides a specialized Parser around one or more RegExp patterns, with RegExp-specific .match, .group(), and .groups() methods.

  • Common helpers like whitespace, blankLine, and end are provided. Some are re-exported under line (ex. line.blank) and whitespace (ex. whitespace.inline) for convenience.

Refactors

• (git/commit/conventional): use parser module (9d84a19)

• (md/codeBlock): use parser module; export parsers (7cc4e78)

[AustinArey]

Amazing work, thanks for the great documentation. I'll take some notes as I go through this beast.

[AustinArey]

Looks great I just saw a couple typos in the commit messages

• Commit message of feat(parser): init -> End of line 8 typo of "stings." should be "strings."
• Commit message of feat(parser): init -> Line 11 typo of "RagExp"

[pskfyi]

Thanks! Great catches.

[AustinArey]

Most Excellent work.