NumParse

A TypeScript parser combinator library. Build parsers by composing small, reusable pieces.

Installation

npm install numparse-ts

Usage

import { streamFromString, string, append, oneOrMore, digit } from "numparse";

// Create a stream from a string
const stream = streamFromString("hello123");

// Build a parser
const parser = append(string("hello"), oneOrMore(digit));

const result = parser(stream);

if (result.tag === "parse_success") {
  console.log(result.matched); // "hello123"
  console.log(result.value);   // [ParseSuccess<"hello">, ParseSuccess<string>[]]
}

Core concepts

Stream

A Stream is the input to a parser — a character array with a current index.

const stream = streamFromString("input string");

Parser<A>

A Parser<A> is a function (stream: Stream) => ParseResult<A>. It either succeeds with a value of type A or fails with a ParseError.

ParseResult<A>

Either a ParseSuccess<A> (with tag: "parse_success") or a ParseError (with tag: "parse_error").

Combinators

Primitives

| Function | Description | |---|---| | string(s) | Matches a literal string | | digit | Matches a single digit character | | letter | Matches a single letter | | space | Matches a single whitespace character | | alphanumeric | Matches a letter or digit | | whitespace | Matches a whitespace character | | empty | Always succeeds, consuming nothing | | succeed(value) | Always succeeds with value, consuming nothing |

Combining

| Function | Description | |---|---| | append(p1, p2, ...) | Runs parsers in sequence, returning a tuple of results | | appendStr(p1, p2, ...) | Runs string parsers in sequence, concatenating results | | keepLast(p1, p2) | Runs two parsers in sequence, returning only the second result | | oneOf(p1, p2, ...) | Tries each parser in order, returning the first success | | seq(p1, p2) | Runs two parsers in sequence, returning a tuple | | either(p1, p2) | Tries p1, falls back to p2 on failure | | chain(p, f) | Runs p, then passes the result to f to get the next parser |

Repetition

| Function | Description | |---|---| | oneOrMore(p) | One or more matches | | noneOrMore(p) | Zero or more matches | | oneOrMoreStr(p) | One or more matches, concatenated into a string | | strNoneOrMore(p) | Zero or more matches, concatenated into a string | | optional(p) | Zero or one match |

Transformation

| Function | Description | |---|---| | map(f)(p) | Maps a function over a parser's result | | mapResult(f) | Maps over ParseResult, propagating errors | | flatten(p) | Flattens a Parser<ParseResult<A>> into Parser<A> | | trimStart(p) | Skips leading whitespace before running p |

Other

| Function | Description | |---|---| | not(p) | Succeeds (consuming nothing) if p fails | | lazy(fn) | Delays parser construction — use for recursive parsers | | oneOfManyStrings(strings) | Efficiently matches any string in an array (trie-backed) | | slice(start, end) | Extracts the matched string between two stream positions | | is.success(result) | Type guard for ParseSuccess |

License

MIT