tarsec 0.0.12 → 0.0.14

package/README.md

@@ -41,7 +41,11 @@ parser("hello there"); // failure
 ## Features
 - tarsec is entirely TypeScript. There's nothing to compile.
 - [Debug mode](/tutorials/debugging.md) that prints what's happening step-by-step
+- Tools to debug your parser's [performance](/tutorials/performance.md)
 - Derived types: tarsec will generate TypeScript types for your parser
 - Partial [backtracking](/tutorials/backtracking.md) support
 
-Read more about [use cases for tarsec](/tutorials/use-case.md).
+Read more about [use cases for tarsec](/tutorials/use-case.md).
+
+## Contributing
+PRs for documentation, tests, and bug fixes are welcome.

package/dist/combinators.d.ts

@@ -1,6 +1,30 @@
-import { CaptureParser, GeneralParser, MergedCaptures, MergedResults, Parser, PickParserType, Prettify } from "./types";
-export declare function many<T>(parser: Parser<T>): Parser<T[]>;
-export declare function many1<T>(parser: Parser<T>): Parser<T[]>;
+import { CaptureParser, GeneralParser, InferManyReturnType, MergedCaptures, MergedResults, Parser, PickParserType, PlainObject } from "./types";
+/**
+ * Takes a parser and runs it zero or more times, returning the results as an array.
+ * If the parser is a capture parser, it returns the captures as an array in this form:
+ *
+ * ```ts
+ * { captures: <array of captures> }
+ * ```
+ *
+ * @param parser - parser to run
+ * @returns - parser that runs the given parser zero to many times,
+ * and returns the result as an array
+ */
+export declare function many<const T extends GeneralParser<any, any>>(parser: T): InferManyReturnType<T>;
+/**
+ * Same as `many`, but fails if the parser doesn't match at least once.
+ *
+ * @param parser - parser to run
+ * @returns a parser that runs the given parser one to many times,
+ */
+export declare function many1<const T extends GeneralParser<any, any>>(parser: T): InferManyReturnType<T>;
+/**
+ * Takes a parser, runs it, and returns the number of times it succeeded.
+ * @param parser - parser to run
+ * @returns - the number of times the parser succeeded.
+ */
+export declare function count<T>(parser: Parser<T>): Parser<T[]>;
 /**
  * Takes a parser, runs it n times, and returns the results as an array.
  * If it cannot run the parser n times, it fails without consuming input.
@@ -8,8 +32,22 @@ export declare function many1<T>(parser: Parser<T>): Parser<T[]>;
  * @param parser - parser to run
  * @returns - parser that runs the given parser `num` times and returns an array of the results
  */
-export declare function count<T>(num: number, parser: Parser<T>): Parser<T[]>;
-export declare function manyWithJoin(parser: Parser<string>): Parser<string>;
+export declare function exactly<T>(num: number, parser: Parser<T>): Parser<T[]>;
+/**
+ * Same as `many`, but joins the results into a single string.
+ *
+ * @param parser - parser to run. The parser must return a string as its result.
+ * @returns - parser that runs the given parser zero to many times,
+ * and returns the result as a single string
+ */
+export declare function manyWithJoin<const T extends GeneralParser<string, any>>(parser: T): GeneralParser<string, any>;
+/**
+ * Same as `many1`, but joins the results into a single string.
+ *
+ * @param parser - parser to run. The parser must return a string as its result.
+ * @returns - parser that runs the given parser one to many times,
+ * and returns the result as a single string
+ */
 export declare function many1WithJoin(parser: Parser<string>): Parser<string>;
 /**
  * `or` takes an array of parsers and runs them sequentially.
@@ -38,16 +76,127 @@ export declare function many1WithJoin(parser: Parser<string>): Parser<string>;
  * @returns - a parser that tries each parser in order. Returns the result of the first parser that succeeds.
  */
 export declare function or<const T extends readonly GeneralParser<any, any>[]>(...parsers: T): PickParserType<T>;
+/**
+ * Takes a parser and runs it. If the parser fails,
+ * optional returns a success with a null result.
+ *
+ * @param parser - parser to run
+ * @returns - a parser that runs the given parser.
+ * If it fails, returns a success with a null result.
+ */
 export declare function optional<T>(parser: Parser<T>): Parser<T | null>;
+/**
+ * Takes a parser and runs it. If the parser fails,
+ * `not` returns a success with a `null` result.
+ * If the parser succeeds, `not` returns a failure.
+ *
+ * @param parser - parser to run
+ * @returns - a parser that runs the given parser.
+ * If it fails, returns a success with a `null` result.
+ * If it succeeds, returns a failure.
+ */
 export declare function not(parser: Parser<any>): Parser<null>;
+/**
+ * Takes three parsers, `open`, `close`, and `parser`.
+ * `between` matches something that matches `parser`,
+ * surrounded by `open` and `close`. It returns the result of `parser`.
+ * If any of the parsers fail, `between` fails.
+ *
+ * @param open - parser for the opening delimiter
+ * @param close - parser for the closing delimiter
+ * @param parser - parser for the content
+ * @returns a parser that returns the result of `parser`.
+ */
 export declare function between<O, C, P>(open: Parser<O>, close: Parser<C>, parser: Parser<P>): Parser<P>;
+/**
+ * Parses many instances of the parser separated by separator.
+ * @param separator
+ * @param parser
+ * @returns a parser that runs the given parser zero to many times, separated by the separator parser.
+ */
 export declare function sepBy<S, P>(separator: Parser<S>, parser: Parser<P>): Parser<P[]>;
+/**
+ * Convenience function to use as the second argument to `seq` to get all the results from `seq`
+ * @param results
+ * @param captures
+ * @returns `results`
+ */
 export declare function getResults<R, C>(results: R, captures: C): R;
+/**
+ * Convenience function to use as the second argument to seq to get all the captures.
+ * @param results
+ * @param captures
+ * @returns `captures`
+ */
 export declare function getCaptures<R, C>(results: R, captures: C): C;
+/**
+ * `capture` is the only way to create a capture. Given a parser and a name,
+ * `capture` runs the parser and saves its result in a captures object
+ * with the given name as the key. It returns the result from the parser,
+ * and attaches the captures object along with it.
+ *
+ * @param parser - parser to run
+ * @param name - name of the capture
+ * @returns - the results of the parser, with the captures object attached.
+ */
 export declare function capture<T, const S extends string>(parser: Parser<T>, name: S): CaptureParser<T, Record<S, T>>;
-export declare function wrap<T, const S extends string>(parser: Parser<T>, name: S): Parser<Prettify<Record<S, T>>>;
+/**
+ * Returns a parser that consumes input till the given parser succeeds.
+ * @param parser - the stop parser
+ * @returns a parser that consumes the input string until the stop parser succeeds.
+ * Then it returns the consumed input as a string.
+ * The stop parser's match is not included in the result.
+ */
 export declare function manyTill<T>(parser: Parser<T>): Parser<string>;
-export declare function transform<T, X>(parser: Parser<T>, transformerFunc: (x: T) => X): Parser<X>;
+/**
+ * Just like `manyTill`, but fails unless at least one character of input is consumed.
+ * @param parser - the stop parser
+ * @returns a parser that consumes the input string until the stop parser succeeds.
+ */
+export declare function many1Till<T>(parser: Parser<T>): Parser<string>;
+/**
+ * `manyTillStr` is an optimized version of `manyTill`.
+ * The `manyTill` combinator is slow because it runs the given parser
+ * on every character of the string until it succeeds. However, if you
+ * just want to consume input until you get to a substring,
+ * use `manyTillStr`. It uses `indexOf`, which is significantly faster
+ * than running a parser over every character.
+ *
+ * @param str - the string to stop at
+ * @param options - object of optional parameters. { caseInsensitive: boolean }
+ * @returns a parser that consumes the input string until the given string is found.
+ */
+export declare function manyTillStr(str: string, { caseInsensitive }?: {
+    caseInsensitive?: boolean;
+}): Parser<string>;
+/**
+ * Like `manyTillStr`, but case insensitive.
+ * @param str - the string to stop at
+ * @returns a parser that consumes the input string until the given string is found.
+ */
+export declare function iManyTillStr(str: string): Parser<string>;
+/**
+ * `map` is a parser combinator that takes a parser and a mapper function.
+ * If the parser succeeds, it maps its result using the mapper function.
+ * You can think of map as a general `map`, like for functors, applied to a parser.
+ * Since `map` itself is a parser, you can use it in `seq` or other combinators.
+ *
+ * @param parser - parser to run
+ * @param mapperFunc - function to map the result of the parser
+ * @returns
+ */
+export declare function map<R, C extends PlainObject, X>(parser: GeneralParser<R, C>, mapperFunc: (x: R) => X): GeneralParser<X, C>;
+/**
+ * Given a parser that returns a string, `search` looks for all substrings in a string that match that parser.
+ * For example, given a parser that matches quoted strings, `search` will return an array of all the quoted strings
+ * it finds in the input, as an array.
+ *
+ * The rest of the input that isn't part of the result is simply joined together and returned as a string.
+ * If you need a more structured result + rest, you can use `within` instead.
+ *
+ * @param parser - a parser that returns a string
+ * @returns - a parser that returns an array of strings
+ */
 export declare function search(parser: Parser<string>): Parser<string[]>;
 /**
  * seq takes an array of parsers and runs them sequentially.
@@ -68,11 +217,28 @@ export declare function search(parser: Parser<string>): Parser<string[]>;
  * and pass the remaining input to the next parser yourself.
  * seq also does some backtracking for you that you will need to do yourself.
  *
+ * Also see `seqR` and `seqC` for convenience functions that return the results or captures respectively.
+ *
  * @param parsers - parsers to run sequentially
  * @param transform - function to transform the results and captures. The params are the results and captures
  * @param debugName - optional name for trace debugging
  * @returns
  */
 export declare function seq<const T extends readonly GeneralParser<any, any>[], U>(parsers: T, transform: (results: MergedResults<T>[], captures: MergedCaptures<T>) => U, debugName?: string): Parser<U>;
+/** Just like seq except it returns the results.
+ * It's like using `seq([parsers], getResults)`.
+ */
 export declare function seqR<const T extends readonly GeneralParser<any, any>[]>(...parsers: T): Parser<MergedResults<T>[]>;
+/** Just like seq except it returns the captures.
+ * It's like using `seq([parsers], getCaptures)`.
+ */
 export declare function seqC<const T extends readonly GeneralParser<any, any>[]>(...parsers: T): Parser<MergedCaptures<T>>;
+/**
+ * Match takes an input string and a parser. If the parser matches the input string
+ * and consumes the entire input string, `match` returns `true`. Otherwise it returns `false`.
+ *
+ * @param input - input string
+ * @param parser - parser to match input against
+ * @returns - true if the parser matches the input and consumes all input, false otherwise
+ */
+export declare function match(input: string, parser: GeneralParser<any, any>): boolean;

package/dist/combinators.js

@@ -9,26 +9,62 @@
 })(function (require, exports) {
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
-    exports.seqC = exports.seqR = exports.seq = exports.search = exports.transform = exports.manyTill = exports.wrap = exports.capture = exports.getCaptures = exports.getResults = exports.sepBy = exports.between = exports.not = exports.optional = exports.or = exports.many1WithJoin = exports.manyWithJoin = exports.count = exports.many1 = exports.many = void 0;
+    exports.match = exports.seqC = exports.seqR = exports.seq = exports.search = exports.map = exports.iManyTillStr = exports.manyTillStr = exports.many1Till = exports.manyTill = exports.capture = exports.getCaptures = exports.getResults = exports.sepBy = exports.between = exports.not = exports.optional = exports.or = exports.many1WithJoin = exports.manyWithJoin = exports.exactly = exports.count = exports.many1 = exports.many = void 0;
     const within_1 = require("./parsers/within");
     const trace_1 = require("./trace");
     const types_1 = require("./types");
     const utils_1 = require("./utils");
+    /**
+     * Takes a parser and runs it zero or more times, returning the results as an array.
+     * If the parser is a capture parser, it returns the captures as an array in this form:
+     *
+     * ```ts
+     * { captures: <array of captures> }
+     * ```
+     *
+     * @param parser - parser to run
+     * @returns - parser that runs the given parser zero to many times,
+     * and returns the result as an array
+     */
     function many(parser) {
         return (0, trace_1.trace)("many", (input) => {
             let results = [];
+            let captures = [];
             let rest = input;
             while (true) {
                 let parsed = parser(rest);
                 if (!parsed.success) {
-                    return (0, types_1.success)(results, rest);
+                    if (Object.keys(captures).length) {
+                        return (0, types_1.captureSuccess)(results, rest, { captures });
+                    }
+                    else {
+                        return (0, types_1.success)(results, rest);
+                    }
                 }
                 results.push(parsed.result);
+                if ((0, types_1.isCaptureResult)(parsed)) {
+                    captures.push(parsed.captures);
+                }
                 rest = parsed.rest;
+                // don't loop infinitely on empty strings
+                if (rest === "") {
+                    if (Object.keys(captures).length) {
+                        return (0, types_1.captureSuccess)(results, rest, { captures });
+                    }
+                    else {
+                        return (0, types_1.success)(results, rest);
+                    }
+                }
             }
         });
     }
     exports.many = many;
+    /**
+     * Same as `many`, but fails if the parser doesn't match at least once.
+     *
+     * @param parser - parser to run
+     * @returns a parser that runs the given parser one to many times,
+     */
     function many1(parser) {
         return (0, trace_1.trace)(`many1`, (input) => {
             let result = many(parser)(input);
@@ -44,6 +80,21 @@
         });
     }
     exports.many1 = many1;
+    /**
+     * Takes a parser, runs it, and returns the number of times it succeeded.
+     * @param parser - parser to run
+     * @returns - the number of times the parser succeeded.
+     */
+    function count(parser) {
+        return (0, trace_1.trace)("count", (input) => {
+            const result = many(parser)(input);
+            if (result.success) {
+                return (0, types_1.success)(result.result.length, result.rest);
+            }
+            return result;
+        });
+    }
+    exports.count = count;
     /**
      * Takes a parser, runs it n times, and returns the results as an array.
      * If it cannot run the parser n times, it fails without consuming input.
@@ -51,8 +102,8 @@
      * @param parser - parser to run
      * @returns - parser that runs the given parser `num` times and returns an array of the results
      */
-    function count(num, parser) {
-        return (0, trace_1.trace)("count", (input) => {
+    function exactly(num, parser) {
+        return (0, trace_1.trace)("exactly", (input) => {
             let results = [];
             let rest = input;
             for (let i = 0; i < num; i++) {
@@ -66,13 +117,39 @@
             return (0, types_1.success)(results, rest);
         });
     }
-    exports.count = count;
+    exports.exactly = exactly;
+    /**
+     * Same as `many`, but joins the results into a single string.
+     *
+     * @param parser - parser to run. The parser must return a string as its result.
+     * @returns - parser that runs the given parser zero to many times,
+     * and returns the result as a single string
+     */
     function manyWithJoin(parser) {
-        return transform(many(parser), (x) => x.join(""));
+        return (0, trace_1.trace)("manyWithJoin", (input) => {
+            const result = many(parser)(input);
+            if (result.success) {
+                return Object.assign(Object.assign({}, result), { result: result.result.join("") });
+            }
+            return result;
+        });
     }
     exports.manyWithJoin = manyWithJoin;
+    /**
+     * Same as `many1`, but joins the results into a single string.
+     *
+     * @param parser - parser to run. The parser must return a string as its result.
+     * @returns - parser that runs the given parser one to many times,
+     * and returns the result as a single string
+     */
     function many1WithJoin(parser) {
-        return transform(many1(parser), (x) => x.join(""));
+        return (0, trace_1.trace)("many1WithJoin", (input) => {
+            const result = many1(parser)(input);
+            if (result.success) {
+                return Object.assign(Object.assign({}, result), { result: result.result.join("") });
+            }
+            return result;
+        });
     }
     exports.many1WithJoin = many1WithJoin;
     /**
@@ -117,6 +194,14 @@
         });
     }
     exports.or = or;
+    /**
+     * Takes a parser and runs it. If the parser fails,
+     * optional returns a success with a null result.
+     *
+     * @param parser - parser to run
+     * @returns - a parser that runs the given parser.
+     * If it fails, returns a success with a null result.
+     */
     function optional(parser) {
         return (0, trace_1.trace)("optional", (input) => {
             let result = parser(input);
@@ -127,6 +212,16 @@
         });
     }
     exports.optional = optional;
+    /**
+     * Takes a parser and runs it. If the parser fails,
+     * `not` returns a success with a `null` result.
+     * If the parser succeeds, `not` returns a failure.
+     *
+     * @param parser - parser to run
+     * @returns - a parser that runs the given parser.
+     * If it fails, returns a success with a `null` result.
+     * If it succeeds, returns a failure.
+     */
     function not(parser) {
         return (0, trace_1.trace)("not", (input) => {
             let result = parser(input);
@@ -134,13 +229,24 @@
                 return {
                     success: false,
                     rest: input,
-                    message: "unexpected match",
+                    message: "expected parser not to succeed",
                 };
             }
             return (0, types_1.success)(null, input);
         });
     }
     exports.not = not;
+    /**
+     * Takes three parsers, `open`, `close`, and `parser`.
+     * `between` matches something that matches `parser`,
+     * surrounded by `open` and `close`. It returns the result of `parser`.
+     * If any of the parsers fail, `between` fails.
+     *
+     * @param open - parser for the opening delimiter
+     * @param close - parser for the closing delimiter
+     * @param parser - parser for the content
+     * @returns a parser that returns the result of `parser`.
+     */
     function between(open, close, parser) {
         return (input) => {
             const result1 = open(input);
@@ -159,6 +265,12 @@
         };
     }
     exports.between = between;
+    /**
+     * Parses many instances of the parser separated by separator.
+     * @param separator
+     * @param parser
+     * @returns a parser that runs the given parser zero to many times, separated by the separator parser.
+     */
     function sepBy(separator, parser) {
         return (input) => {
             let results = [];
@@ -179,14 +291,36 @@
         };
     }
     exports.sepBy = sepBy;
+    /**
+     * Convenience function to use as the second argument to `seq` to get all the results from `seq`
+     * @param results
+     * @param captures
+     * @returns `results`
+     */
     function getResults(results, captures) {
         return results;
     }
     exports.getResults = getResults;
+    /**
+     * Convenience function to use as the second argument to seq to get all the captures.
+     * @param results
+     * @param captures
+     * @returns `captures`
+     */
     function getCaptures(results, captures) {
         return captures;
     }
     exports.getCaptures = getCaptures;
+    /**
+     * `capture` is the only way to create a capture. Given a parser and a name,
+     * `capture` runs the parser and saves its result in a captures object
+     * with the given name as the key. It returns the result from the parser,
+     * and attaches the captures object along with it.
+     *
+     * @param parser - parser to run
+     * @param name - name of the capture
+     * @returns - the results of the parser, with the captures object attached.
+     */
     function capture(parser, name) {
         return (0, trace_1.trace)(`capture(${(0, utils_1.escape)(name)})`, (input) => {
             let result = parser(input);
@@ -200,18 +334,13 @@
         });
     }
     exports.capture = capture;
-    function wrap(parser, name) {
-        return (0, trace_1.trace)(`capture(${(0, utils_1.escape)(name)})`, (input) => {
-            let result = parser(input);
-            if (result.success) {
-                return Object.assign(Object.assign({}, result), { result: {
-                        [name]: result.result,
-                    } });
-            }
-            return result;
-        });
-    }
-    exports.wrap = wrap;
+    /**
+     * Returns a parser that consumes input till the given parser succeeds.
+     * @param parser - the stop parser
+     * @returns a parser that consumes the input string until the stop parser succeeds.
+     * Then it returns the consumed input as a string.
+     * The stop parser's match is not included in the result.
+     */
     function manyTill(parser) {
         return (input) => {
             let current = 0;
@@ -226,16 +355,95 @@
         };
     }
     exports.manyTill = manyTill;
-    function transform(parser, transformerFunc) {
-        return (0, trace_1.trace)(`transform(${transformerFunc})`, (input) => {
+    /**
+     * Just like `manyTill`, but fails unless at least one character of input is consumed.
+     * @param parser - the stop parser
+     * @returns a parser that consumes the input string until the stop parser succeeds.
+     */
+    function many1Till(parser) {
+        return (input) => {
+            let current = 0;
+            while (current < input.length) {
+                const parsed = parser(input.slice(current));
+                if (parsed.success) {
+                    if (current === 0) {
+                        return (0, types_1.failure)("expected to consume at least one character of input", input);
+                    }
+                    return (0, types_1.success)(input.slice(0, current), input.slice(current));
+                }
+                current++;
+            }
+            if (current === 0) {
+                return (0, types_1.failure)("expected to consume at least one character of input", input);
+            }
+            return (0, types_1.success)(input, "");
+        };
+    }
+    exports.many1Till = many1Till;
+    /**
+     * `manyTillStr` is an optimized version of `manyTill`.
+     * The `manyTill` combinator is slow because it runs the given parser
+     * on every character of the string until it succeeds. However, if you
+     * just want to consume input until you get to a substring,
+     * use `manyTillStr`. It uses `indexOf`, which is significantly faster
+     * than running a parser over every character.
+     *
+     * @param str - the string to stop at
+     * @param options - object of optional parameters. { caseInsensitive: boolean }
+     * @returns a parser that consumes the input string until the given string is found.
+     */
+    function manyTillStr(str, { caseInsensitive = false } = {}) {
+        return (0, trace_1.trace)(`manyTillStr(${str})`, (input) => {
+            const index = caseInsensitive
+                ? input.toLocaleLowerCase().indexOf(str.toLocaleLowerCase())
+                : input.indexOf(str);
+            if (index === -1) {
+                return (0, types_1.success)(input, "");
+            }
+            return (0, types_1.success)(input.slice(0, index), input.slice(index));
+        });
+    }
+    exports.manyTillStr = manyTillStr;
+    /**
+     * Like `manyTillStr`, but case insensitive.
+     * @param str - the string to stop at
+     * @returns a parser that consumes the input string until the given string is found.
+     */
+    function iManyTillStr(str) {
+        return manyTillStr(str, { caseInsensitive: true });
+    }
+    exports.iManyTillStr = iManyTillStr;
+    /**
+     * `map` is a parser combinator that takes a parser and a mapper function.
+     * If the parser succeeds, it maps its result using the mapper function.
+     * You can think of map as a general `map`, like for functors, applied to a parser.
+     * Since `map` itself is a parser, you can use it in `seq` or other combinators.
+     *
+     * @param parser - parser to run
+     * @param mapperFunc - function to map the result of the parser
+     * @returns
+     */
+    function map(parser, mapperFunc) {
+        return (0, trace_1.trace)(`map(${mapperFunc})`, (input) => {
             let parsed = parser(input);
             if (parsed.success) {
-                return Object.assign(Object.assign({}, parsed), { result: transformerFunc(parsed.result) });
+                return Object.assign(Object.assign({}, parsed), { result: mapperFunc(parsed.result) });
             }
             return parsed;
         });
     }
-    exports.transform = transform;
+    exports.map = map;
+    /**
+     * Given a parser that returns a string, `search` looks for all substrings in a string that match that parser.
+     * For example, given a parser that matches quoted strings, `search` will return an array of all the quoted strings
+     * it finds in the input, as an array.
+     *
+     * The rest of the input that isn't part of the result is simply joined together and returned as a string.
+     * If you need a more structured result + rest, you can use `within` instead.
+     *
+     * @param parser - a parser that returns a string
+     * @returns - a parser that returns an array of strings
+     */
     function search(parser) {
         return (0, trace_1.trace)("search", (input) => {
             let parsed = (0, within_1.within)(parser)(input);
@@ -330,6 +538,8 @@
      * and pass the remaining input to the next parser yourself.
      * seq also does some backtracking for you that you will need to do yourself.
      *
+     * Also see `seqR` and `seqC` for convenience functions that return the results or captures respectively.
+     *
      * @param parsers - parsers to run sequentially
      * @param transform - function to transform the results and captures. The params are the results and captures
      * @param debugName - optional name for trace debugging
@@ -384,19 +594,31 @@
         });
     }
     exports.seq = seq;
+    /** Just like seq except it returns the results.
+     * It's like using `seq([parsers], getResults)`.
+     */
     function seqR(...parsers) {
         return seq(parsers, getResults);
     }
     exports.seqR = seqR;
+    /** Just like seq except it returns the captures.
+     * It's like using `seq([parsers], getCaptures)`.
+     */
     function seqC(...parsers) {
         return seq(parsers, getCaptures);
     }
     exports.seqC = seqC;
+    /**
+     * Match takes an input string and a parser. If the parser matches the input string
+     * and consumes the entire input string, `match` returns `true`. Otherwise it returns `false`.
+     *
+     * @param input - input string
+     * @param parser - parser to match input against
+     * @returns - true if the parser matches the input and consumes all input, false otherwise
+     */
+    function match(input, parser) {
+        const result = parser(input);
+        return result.success && result.rest === "";
+    }
+    exports.match = match;
 });
-/*
-export function seqX<const T extends readonly GeneralParser<any, any>[], U>(
-  parsers: T,
-  transform: (results: MergedResults<T>[], captures: MergedCaptures<T>) => U,
-  debugName: string = ""
-): Parser<U> {
- */

package/dist/parsers/within.d.ts

@@ -1,2 +1,2 @@
-import { BetweenWithinResult, Parser } from "../types";
-export declare function within(parser: Parser<string>): Parser<BetweenWithinResult[]>;
+import { WithinResult, Parser } from "../types";
+export declare function within(parser: Parser<string>): Parser<WithinResult[]>;

package/dist/parsers.d.ts

@@ -10,10 +10,16 @@ export declare function char<const S extends string>(c: S): Parser<S>;
 /**
  * Takes a string. Returns a parser that parses that string.
  *
- * @param s - string to parse
+ * @param s - string to match on
  * @returns - parser that parses the given string
  */
 export declare function str<const S extends string>(s: S): Parser<S>;
+/**
+ * Like `str`, but case insensitive.
+ * @param s - string to match on, case insensitive
+ * @returns - parser that matches the given string, case insensitive
+ */
+export declare function istr<const S extends string>(s: S): Parser<S>;
 /**
  * Takes a string. Returns a parser that parses
  * one of the characters in that string.
@@ -38,15 +44,39 @@ export declare function noneOf(chars: string): Parser<string>;
  * @returns - ParserResult
  */
 export declare const anyChar: any;
+/** A parser that matches one of " \t\n\r". */
 export declare const space: Parser<string>;
+/** A parser that matches one or more spaces. */
 export declare const spaces: Parser<string>;
+/** A parser that matches one digit. */
 export declare const digit: Parser<string>;
+/** A parser that matches one letter, case insensitive. */
 export declare const letter: Parser<string>;
+/** A parser that matches one digit or letter, case insensitive. */
 export declare const alphanum: Parser<string>;
+/** A parser that matches one word, case insensitive. */
 export declare const word: Parser<string>;
+/** A parser that matches one or more digits. */
 export declare const num: Parser<string>;
+/** A parser that matches one single or double quote. */
 export declare const quote: Parser<string>;
+/** A parser that matches one tab character. */
 export declare const tab: Parser<string>;
+/** A parser that matches one newline ("\n" only) character. */
 export declare const newline: Parser<string>;
+/** A parser that succeeds on an empty string. Returns `null` as the result. */
 export declare const eof: Parser<null>;
+/** A parser that matches a quoted string, in single or double quotes.
+ * Returns the string as the result, including the quotes.
+ */
 export declare const quotedString: Parser<string>;
+/**
+ * Returns a parser that matches a regex. If you pass in a string,
+ * it will get converted to a regex. The regex should always match from the start of the input.
+ * If you pass in a string, a `^` will get prepended to it.
+ *
+ * @param str - regex string or RegExp instance to match
+ * @param options - regex options (i = ignore case, g = global, m = multiline, u = unicode)
+ * @returns - parser that matches the given regex
+ */
+export declare function regexParser(str: string | RegExp, options?: string): Parser<string>;

package/dist/parsers.js

@@ -9,7 +9,7 @@
 })(function (require, exports) {
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
-    exports.quotedString = exports.eof = exports.newline = exports.tab = exports.quote = exports.num = exports.word = exports.alphanum = exports.letter = exports.digit = exports.spaces = exports.space = exports.anyChar = exports.noneOf = exports.oneOf = exports.str = exports.char = exports.betweenWithin = void 0;
+    exports.regexParser = exports.quotedString = exports.eof = exports.newline = exports.tab = exports.quote = exports.num = exports.word = exports.alphanum = exports.letter = exports.digit = exports.spaces = exports.space = exports.anyChar = exports.noneOf = exports.oneOf = exports.istr = exports.str = exports.char = exports.betweenWithin = void 0;
     const combinators_1 = require("./combinators");
     const trace_1 = require("./trace");
     const types_1 = require("./types");
@@ -41,7 +41,7 @@
     /**
      * Takes a string. Returns a parser that parses that string.
      *
-     * @param s - string to parse
+     * @param s - string to match on
      * @returns - parser that parses the given string
      */
     function str(s) {
@@ -53,6 +53,20 @@
         });
     }
     exports.str = str;
+    /**
+     * Like `str`, but case insensitive.
+     * @param s - string to match on, case insensitive
+     * @returns - parser that matches the given string, case insensitive
+     */
+    function istr(s) {
+        return (0, trace_1.trace)(`istr(${(0, utils_1.escape)(s)})`, (input) => {
+            if (input.substring(0, s.length).toLocaleLowerCase() === s.toLocaleLowerCase()) {
+                return (0, types_1.success)(input.substring(0, s.length), input.slice(s.length));
+            }
+            return (0, types_1.failure)(`expected ${s}, got ${input.substring(0, s.length)}`, input);
+        });
+    }
+    exports.istr = istr;
     /**
      * Takes a string. Returns a parser that parses
      * one of the characters in that string.
@@ -105,16 +119,27 @@
         }
         return (0, types_1.success)(input[0], input.slice(1));
     });
+    /** A parser that matches one of " \t\n\r". */
     exports.space = oneOf(" \t\n\r");
+    /** A parser that matches one or more spaces. */
     exports.spaces = (0, combinators_1.many1WithJoin)(exports.space);
+    /** A parser that matches one digit. */
     exports.digit = oneOf("0123456789");
-    exports.letter = oneOf("abcdefghijklmnopqrstuvwxyz");
-    exports.alphanum = oneOf("abcdefghijklmnopqrstuvwxyz0123456789");
-    exports.word = (0, combinators_1.many1WithJoin)(exports.letter);
-    exports.num = (0, combinators_1.many1WithJoin)(exports.digit);
+    /** A parser that matches one letter, case insensitive. */
+    exports.letter = oneOf("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ");
+    /** A parser that matches one digit or letter, case insensitive. */
+    exports.alphanum = oneOf("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789");
+    /** A parser that matches one word, case insensitive. */
+    exports.word = regexParser("^[a-z]+", "ui");
+    /** A parser that matches one or more digits. */
+    exports.num = regexParser("^[0-9]+");
+    /** A parser that matches one single or double quote. */
     exports.quote = oneOf(`'"`);
+    /** A parser that matches one tab character. */
     exports.tab = char("\t");
+    /** A parser that matches one newline ("\n" only) character. */
     exports.newline = char("\n");
+    /** A parser that succeeds on an empty string. Returns `null` as the result. */
     const eof = (input) => {
         if (input === "") {
             return (0, types_1.success)(null, input);
@@ -122,5 +147,34 @@
         return (0, types_1.failure)("expected end of input", input);
     };
     exports.eof = eof;
+    /** A parser that matches a quoted string, in single or double quotes.
+     * Returns the string as the result, including the quotes.
+     */
     exports.quotedString = (0, combinators_1.seq)([exports.quote, (0, combinators_1.manyWithJoin)(noneOf(`"'`)), exports.quote], (results) => results.join(""));
+    /**
+     * Returns a parser that matches a regex. If you pass in a string,
+     * it will get converted to a regex. The regex should always match from the start of the input.
+     * If you pass in a string, a `^` will get prepended to it.
+     *
+     * @param str - regex string or RegExp instance to match
+     * @param options - regex options (i = ignore case, g = global, m = multiline, u = unicode)
+     * @returns - parser that matches the given regex
+     */
+    function regexParser(str, options = "") {
+        let re;
+        if (typeof str === "string") {
+            re = new RegExp(str.startsWith("^") ? str : `^${str}`, options);
+        }
+        else {
+            re = str;
+        }
+        return (0, trace_1.trace)(`regex(${str})`, (input) => {
+            const match = input.match(re);
+            if (match) {
+                return (0, types_1.success)(match[0], input.slice(match[0].length));
+            }
+            return (0, types_1.failure)(`expected ${str}, got ${input.slice(0, 10)}`, input);
+        });
+    }
+    exports.regexParser = regexParser;
 });

package/dist/trace.d.ts

@@ -1,3 +1,92 @@
 import { ParserResult } from "./types";
+/**
+ * This function is used internally by the `trace` function to create the string for each step.
+ * @param name - debug name for parser
+ * @param result - parser result
+ * @returns - A formatted string that describes the parser's result
+ */
 export declare function resultToString<T>(name: string, result: ParserResult<T>): string;
+/**
+ * This function is used internally with debug mode. Given a parser and a debug name for it,
+ * when the parser is called, `trace` will:
+ * 1. Print a line when the parser starts
+ * 2. print a line when the parser ends, indicating success or failure.
+ * 3. If the parser returns any captures, print the captures.
+ * 4. Count the number of times this parser has been run.
+ * 5. Track the total time this parser has taken.
+ * 6. Track the total number of steps your parser has taken (a step equals one parser invocation).
+ * So, for example, you may find out that your parser to parse Markdown has taken 50 steps to parse that file.
+ *
+ * All this happens only if debug mode is on, which you can turn on by using `parserDebug`, or setting the env var `DEBUG` to `1`.
+ *
+ * Caveat: If you have debug mode on through an environment variable, `trace` will capture counts and times
+ * for all parsers across your entire application. If you want to profile just a particular section of code, use `parserDebug` instead.
+ * If you *do* want to track constant times for all parsers, don't use `parserDebug` as it will reset those.
+ *
+ *
+ * `trace` works with tarsec's built-in parsers out of the box. You can easily set it up to work with your custom parser too.
+ *
+ * For example, if your parser looks like this:
+ *
+ * ```ts
+ * const myParser = (input:string) => {
+ *   if (input === "hello") {
+ *    return { success: true, result: "hello", rest: "" };
+ *  }
+ * return { success: false, message: "expected hello", rest: input };
+ * }
+ * ```
+ *
+ * You can wrap it in `trace` like this:
+ *
+ * ```ts
+ * const myParser = trace("myParser", (input:string) => {
+ *  if (input === "hello") {
+ *   return { success: true, result: "hello", rest: "" };
+ * }
+ * return { success: false, message: "expected hello", rest: input };
+ * });
+ * ```
+ *
+ * Now, when you run `myParser("hello")` with debug mode on,
+ * you will see the debug output.
+ *
+ * Some parsers, like `seq`, are very general. You might have a few parser that use `seq`.
+ * So when you see `seq` debug output, you might not know which `seq` parser that means.
+ * ou can pass `seq` a debug name as an optional third argument to be used in the debug output.
+ * This name is used to track count and time, so using this name will also mean this `seq` parser's
+ * count and time are tracked separately from the other `seq` parsers, which might be useful.
+ *
+ * @param name - debug name for parser
+ * @param parser - parser to run
+ * @returns
+ */
 export declare function trace(name: string, parser: any): any;
+/**
+ * Utility timing function. Given a callback, it times the callback
+ * and returns its runtime in milliseconds. It uses `performance.now()` to do this.
+ * If `performance.now()` is not available, it returns null.
+ *
+ * @param callback - callback to time
+ * @returns - time in milliseconds
+ */
+export declare function parserTime(callback: Function): number | null;
+/**
+ * Wrapper for parser time. Instead of returning the time in milliseconds,
+ * it console.logs it, in a nicely formatted string.
+ * @param name - debug name for timing
+ * @param callback - callback to time
+ */
+export declare function printTime(name: string, callback: Function): void;
+/**
+ * This is the recommended way to run a parser in debug mode.
+ * Takes a callback and turns debug mode on just for the callback.
+ * This enables `trace` to capture all sorts of information
+ * about any executed parsers and print them to console.log.
+ * `trace` tracks counts and times but they don't actually get reset to zero
+ * unless you use this function to wrap your code.
+ *
+ * @param name - debug name
+ * @param callback - callback to run in debug mode
+ */
+export declare function parserDebug(name: string, callback: Function): void;

package/dist/trace.js

@@ -9,9 +9,15 @@
 })(function (require, exports) {
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
-    exports.trace = exports.resultToString = void 0;
+    exports.parserDebug = exports.printTime = exports.parserTime = exports.trace = exports.resultToString = void 0;
     const utils_1 = require("./utils");
     const STEP = 2;
+    /**
+     * This function is used internally by the `trace` function to create the string for each step.
+     * @param name - debug name for parser
+     * @param result - parser result
+     * @returns - A formatted string that describes the parser's result
+     */
     function resultToString(name, result) {
         if (result.success) {
             return `✅ ${name} -- match: ${(0, utils_1.escape)(result.result)}, rest: ${(0, utils_1.escape)(result.rest)}`;
@@ -20,23 +26,165 @@
     }
     exports.resultToString = resultToString;
     let level = 0;
+    let counts = {};
+    let times = {};
+    let debugFlag = !!process.env.DEBUG;
+    let stepCount = 0;
+    let stepLimit = -1;
+    /**
+     * This function is used internally with debug mode. Given a parser and a debug name for it,
+     * when the parser is called, `trace` will:
+     * 1. Print a line when the parser starts
+     * 2. print a line when the parser ends, indicating success or failure.
+     * 3. If the parser returns any captures, print the captures.
+     * 4. Count the number of times this parser has been run.
+     * 5. Track the total time this parser has taken.
+     * 6. Track the total number of steps your parser has taken (a step equals one parser invocation).
+     * So, for example, you may find out that your parser to parse Markdown has taken 50 steps to parse that file.
+     *
+     * All this happens only if debug mode is on, which you can turn on by using `parserDebug`, or setting the env var `DEBUG` to `1`.
+     *
+     * Caveat: If you have debug mode on through an environment variable, `trace` will capture counts and times
+     * for all parsers across your entire application. If you want to profile just a particular section of code, use `parserDebug` instead.
+     * If you *do* want to track constant times for all parsers, don't use `parserDebug` as it will reset those.
+     *
+     *
+     * `trace` works with tarsec's built-in parsers out of the box. You can easily set it up to work with your custom parser too.
+     *
+     * For example, if your parser looks like this:
+     *
+     * ```ts
+     * const myParser = (input:string) => {
+     *   if (input === "hello") {
+     *    return { success: true, result: "hello", rest: "" };
+     *  }
+     * return { success: false, message: "expected hello", rest: input };
+     * }
+     * ```
+     *
+     * You can wrap it in `trace` like this:
+     *
+     * ```ts
+     * const myParser = trace("myParser", (input:string) => {
+     *  if (input === "hello") {
+     *   return { success: true, result: "hello", rest: "" };
+     * }
+     * return { success: false, message: "expected hello", rest: input };
+     * });
+     * ```
+     *
+     * Now, when you run `myParser("hello")` with debug mode on,
+     * you will see the debug output.
+     *
+     * Some parsers, like `seq`, are very general. You might have a few parser that use `seq`.
+     * So when you see `seq` debug output, you might not know which `seq` parser that means.
+     * ou can pass `seq` a debug name as an optional third argument to be used in the debug output.
+     * This name is used to track count and time, so using this name will also mean this `seq` parser's
+     * count and time are tracked separately from the other `seq` parsers, which might be useful.
+     *
+     * @param name - debug name for parser
+     * @param parser - parser to run
+     * @returns
+     */
     function trace(name, parser) {
         return (input) => {
-            if (process.env.DEBUG) {
+            if (debugFlag) {
                 console.log(" ".repeat(level) + `🔍 ${name} -- input: ${(0, utils_1.escape)(input)}`);
-            }
-            level += STEP;
-            const result = parser(input);
-            level -= STEP;
-            if (process.env.DEBUG) {
+                let result;
+                const time = parserTime(() => {
+                    level += STEP;
+                    result = parser(input);
+                    level -= STEP;
+                });
+                counts[name] = counts[name] ? counts[name] + 1 : 1;
+                stepCount += 1;
+                if (time) {
+                    times[name] = times[name] ? times[name] + time : time;
+                }
                 console.log(" ".repeat(level) + resultToString(name, result));
                 if (result.success && result.captures) {
                     console.log(" ".repeat(level) +
                         `⭐ ${name} -- captures: ${JSON.stringify(result.captures)}`);
                 }
+                return result;
+            }
+            else {
+                return parser(input);
             }
-            return result;
         };
     }
     exports.trace = trace;
+    /**
+     * Utility timing function. Given a callback, it times the callback
+     * and returns its runtime in milliseconds. It uses `performance.now()` to do this.
+     * If `performance.now()` is not available, it returns null.
+     *
+     * @param callback - callback to time
+     * @returns - time in milliseconds
+     */
+    function parserTime(callback) {
+        if (performance && performance.now) {
+            const start = performance.now();
+            callback();
+            const end = performance.now();
+            return end - start;
+        }
+        else {
+            console.error("performance.now not available");
+            callback();
+            return null;
+        }
+    }
+    exports.parserTime = parserTime;
+    /**
+     * Wrapper for parser time. Instead of returning the time in milliseconds,
+     * it console.logs it, in a nicely formatted string.
+     * @param name - debug name for timing
+     * @param callback - callback to time
+     */
+    function printTime(name, callback) {
+        const time = parserTime(callback);
+        if (time) {
+            console.log(`⏱ ${name} -- time: ${(0, utils_1.round)(time)}ms`);
+        }
+    }
+    exports.printTime = printTime;
+    /**
+     * This is the recommended way to run a parser in debug mode.
+     * Takes a callback and turns debug mode on just for the callback.
+     * This enables `trace` to capture all sorts of information
+     * about any executed parsers and print them to console.log.
+     * `trace` tracks counts and times but they don't actually get reset to zero
+     * unless you use this function to wrap your code.
+     *
+     * @param name - debug name
+     * @param callback - callback to run in debug mode
+     */
+    function parserDebug(name, callback) {
+        debugFlag = true;
+        stepCount = 0;
+        counts = {};
+        times = {};
+        printTime(name, callback);
+        debugFlag = false;
+        console.log("\n");
+        console.log(`📊 ${name} -- counts:`);
+        const sorted = Object.entries(counts).sort((a, b) => b[1] - a[1]);
+        for (const [name, count] of sorted) {
+            console.log(`  ${name}: ${count}`);
+        }
+        console.log("\n");
+        console.log(`📊 ${name} -- times:`);
+        const sortedTimes = Object.entries(times).sort((a, b) => b[1] - a[1]);
+        for (const [name, time] of sortedTimes) {
+            console.log(`  ${name}: ${(0, utils_1.round)(time)}ms`);
+        }
+        console.log("\n");
+        console.log(`📊 ${name} -- step count: ${stepCount}`);
+        console.log("\n\n");
+        stepCount = 0;
+        counts = {};
+        times = {};
+    }
+    exports.parserDebug = parserDebug;
 });

package/dist/types.d.ts

@@ -1,13 +1,21 @@
+/** A generic object type. */
 export type PlainObject = Record<string, unknown>;
+/** Represents a parse success with no captures. */
 export type ParserSuccess<T> = {
     success: true;
     result: T;
     rest: string;
-    nextParser?: GeneralParser<any, any>;
+    nextParser?: Parser<any>;
 };
-export type CaptureParserSuccess<T, C extends PlainObject> = ParserSuccess<T> & {
+/** Represents a parse success with captures. Notice nextParser is also a CaptureParser. */
+export type CaptureParserSuccess<T, C extends PlainObject> = {
+    success: true;
+    result: T;
+    rest: string;
     captures: C;
+    nextParser?: CaptureParser<any, any>;
 };
+/** Represents a parse failure. */
 export type ParserFailure = {
     success: false;
     rest: string;
@@ -15,22 +23,46 @@ export type ParserFailure = {
 };
 export type ParserResult<T> = ParserSuccess<T> | ParserFailure;
 export type CaptureParserResult<T, C extends PlainObject> = CaptureParserSuccess<T, C> | ParserFailure;
+/** A parser is any function that takes a string and returns a ParserResult. */
 export type Parser<T> = (input: string) => ParserResult<T>;
+/** A capture parser is any function that takes a string and returns a CaptureParserResult.
+ * A CaptureParserResult is the same as a ParserResult, except it also includes captures,
+ * i.e. matches selected using `capture`. */
 export type CaptureParser<T, C extends PlainObject> = (input: string) => CaptureParserResult<T, C>;
 export type GeneralParser<T, C extends PlainObject> = Parser<T> | CaptureParser<T, C>;
 export declare function isCaptureResult<T, C extends PlainObject>(result: ParserResult<T>): result is CaptureParserSuccess<T, C>;
+/** Convenience function to return a ParserSuccess */
 export declare function success<T>(result: T, rest: string): ParserSuccess<T>;
+/** Convenience function to return a CaptureParserSuccess */
 export declare function captureSuccess<T, C extends PlainObject>(result: T, rest: string, captures: C): CaptureParserSuccess<T, C>;
+/** Convenience function to return a ParserFailure */
 export declare function failure(message: string, rest: string): ParserFailure;
+/** Prettify an intersected type, to make it easier to read. */
 export type Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
+/** see <https://stackoverflow.com/a/50375286/3625> */
 export type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+/** Convenience type to get the result type out of a parser. */
 type ExtractResults<T> = T extends Parser<infer U> ? U : never;
+/** Convenience type to get the capture type out of a capture parser. */
 type ExtractCaptures<T> = T extends CaptureParser<any, infer U> ? U : never;
+/** Convenience type where given an array of parsers and capture parsers,
+ * it returns the types of the capture parsers, like
+ * CaptureParser<string, { name: string }> | CaptureParser<number, { age: number }>
+ */
 type ExtractCaptureParsers<T extends readonly GeneralParser<any, any>[]> = Extract<T[number], CaptureParser<any, any>>;
+/** Convenience type where given an array of parsers and capture parsers,
+ * it returns a single capture type that merges all the capture types. */
 export type MergedCaptures<T extends readonly GeneralParser<any, any>[]> = Prettify<UnionToIntersection<UnionOfCaptures<T>>>;
+/** Convenience type where given an array of parsers and capture parsers,
+ * it first gets the capture parsers, then extracts the capture types,
+ * and returns a union of all the capture types. Example:
+ * { name: string } | { age: number }
+ */
 export type UnionOfCaptures<T extends readonly GeneralParser<any, any>[]> = Prettify<ExtractCaptures<ExtractCaptureParsers<T>>>;
+/** Convenience type where given an array of parsers and capture parsers,
+ * it returns true if there are any capture parsers, otherwise false. */
 export type HasCaptureParsers<T extends readonly GeneralParser<any, any>[]> = ExtractCaptureParsers<T> extends never ? false : true;
 /**
  * For a given array of GeneralParsers, if any of them is a CaptureParser,
@@ -40,7 +72,18 @@ export type HasCaptureParsers<T extends readonly GeneralParser<any, any>[]> = Ex
  * which is not able to infer its return type correctly.
  */
 export type PickParserType<T extends readonly GeneralParser<any, any>[]> = HasCaptureParsers<T> extends true ? CaptureParser<MergedResults<T>, UnionOfCaptures<T>> : Parser<MergedResults<T>>;
+/** This is used to generate a return type for the `many` and `many1` combinators.
+ * Given a parser we want to apply `many` to. Suppose its type is `Parser<string>`.
+ * This will return `Parser<string[]>` as the return type.
+ *
+ * Suppose the parser is a `CaptureParser<string, { name: string }>`.
+ * This will return `CaptureParser<string[], { captures: { name: string }[] }>` as the return type.
+ */
+export type InferManyReturnType<T extends GeneralParser<any, any>> = T extends CaptureParser<infer R, infer C> ? CaptureParser<R[], {
+    captures: C[];
+}> : Parser<T[]>;
 export type MergedResults<T extends readonly GeneralParser<any, any>[]> = ExtractResults<T[number]>;
+/** Used to create a parser tree for backtracking. */
 export type Node = ParserNode | EmptyNode;
 export type ParserNode = {
     parent: Node;
@@ -50,8 +93,14 @@ export type ParserNode = {
     closed: boolean;
 };
 export type EmptyNode = null;
+/** Convenience function to create a ParserNode. */
 export declare function createNode(parent: Node | null, parser: GeneralParser<any, any>): ParserNode;
+/** Convenience function where, given an array of parsers, it creates a tree we can use for backtracking.
+ * This tree is what `seq` use. It's used to keep track of the parsers we've tried so far,
+ * so we can backtrack if we need to.
+ */
 export declare function createTree(parsers: readonly GeneralParser<any, any>[]): Node;
+/** Used by `within`. */
 export type Matched = {
     type: "matched";
     value: string;
@@ -60,5 +109,5 @@ export type Unmatched = {
     type: "unmatched";
     value: string;
 };
-export type BetweenWithinResult = Matched | Unmatched;
+export type WithinResult = Matched | Unmatched;
 export {};

package/dist/types.js

@@ -14,18 +14,22 @@
         return "captures" in result;
     }
     exports.isCaptureResult = isCaptureResult;
+    /** Convenience function to return a ParserSuccess */
     function success(result, rest) {
         return { success: true, result, rest };
     }
     exports.success = success;
+    /** Convenience function to return a CaptureParserSuccess */
     function captureSuccess(result, rest, captures) {
         return { success: true, result, rest, captures };
     }
     exports.captureSuccess = captureSuccess;
+    /** Convenience function to return a ParserFailure */
     function failure(message, rest) {
         return { success: false, message, rest };
     }
     exports.failure = failure;
+    /** Convenience function to create a ParserNode. */
     function createNode(parent, parser) {
         return {
             parent,
@@ -35,6 +39,10 @@
         };
     }
     exports.createNode = createNode;
+    /** Convenience function where, given an array of parsers, it creates a tree we can use for backtracking.
+     * This tree is what `seq` use. It's used to keep track of the parsers we've tried so far,
+     * so we can backtrack if we need to.
+     */
     function createTree(parsers) {
         if (parsers.length === 0) {
             return null;

package/dist/utils.d.ts

@@ -4,3 +4,4 @@ export declare function merge(a: any | any[], b: any | any[]): any[];
 export declare function mergeCaptures(a: Record<string, any>, b: Record<string, any>): Record<string, any>;
 export declare function findAncestorWithNextParser(node: Node, count?: number): [Node, number];
 export declare function popMany(arr: any[], count: number): void;
+export declare function round(num: number, places?: number): number;

package/dist/utils.js

@@ -9,7 +9,7 @@
 })(function (require, exports) {
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
-    exports.popMany = exports.findAncestorWithNextParser = exports.mergeCaptures = exports.merge = exports.escape = void 0;
+    exports.round = exports.popMany = exports.findAncestorWithNextParser = exports.mergeCaptures = exports.merge = exports.escape = void 0;
     function escape(str) {
         return JSON.stringify(str);
     }
@@ -63,4 +63,8 @@
         }
     }
     exports.popMany = popMany;
+    function round(num, places = 2) {
+        return Math.round(num * 10 ** places) / 10 ** places;
+    }
+    exports.round = round;
 });

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "tarsec",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "A parser combinator library for TypeScript, inspired by Parsec.",
   "homepage": "https://github.com/egonSchiele/tarsec",
   "scripts": {
     "test": "vitest",
+    "test:tsc": "tsc -p tests/tsconfig.json",
     "coverage": "vitest --coverage",
     "build": "rm -rf dist && tsc",
     "start": "cd dist && node index.js",
@@ -20,7 +21,8 @@
       "require": "./dist/index.js"
     }
   },
-  "keywords": [],
+  "types": "./dist/index.d.ts",
+  "keywords": ["parser", "parser combinator", "parsec"],
   "author": "",
   "license": "ISC",
   "devDependencies": {