tarsec 0.0.12 → 0.0.13

package/dist/combinators.d.ts

@@ -1,6 +1,25 @@
-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> }
+ * ```
+ *
+ * Fails on empty strings
+ * @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 n times, and returns the results as an array.
  * If it cannot run the parser n times, it fails without consuming input.
@@ -9,7 +28,21 @@ export declare function many1<T>(parser: Parser<T>): Parser<T[]>;
  * @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>;
+/**
+ * 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 +71,53 @@ 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>;
 export declare function sepBy<S, P>(separator: Parser<S>, parser: Parser<P>): Parser<P[]>;
 export declare function getResults<R, C>(results: R, captures: C): R;
 export declare function getCaptures<R, C>(results: R, captures: C): C;
 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>;
+export declare function many1Till<T>(parser: Parser<T>): Parser<string>;
+export declare function manyTillStr(str: string): Parser<string>;
+export declare function transform<R, C extends PlainObject, X>(parser: GeneralParser<R, C>, transformerFunc: (x: R) => X): GeneralParser<X, C>;
 export declare function search(parser: Parser<string>): Parser<string[]>;
 /**
  * seq takes an array of parsers and runs them sequentially.
@@ -68,6 +138,8 @@ 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
@@ -76,3 +148,4 @@ export declare function search(parser: Parser<string>): Parser<string[]>;
 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>;
 export declare function seqR<const T extends readonly GeneralParser<any, any>[]>(...parsers: T): Parser<MergedResults<T>[]>;
 export declare function seqC<const T extends readonly GeneralParser<any, any>[]>(...parsers: T): Parser<MergedCaptures<T>>;
+export declare function match(input: string, parser: GeneralParser<any, any>): boolean;

package/dist/combinators.js

@@ -9,26 +9,63 @@
 })(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.transform = 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.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> }
+     * ```
+     *
+     * Fails on empty strings
+     * @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);
@@ -67,12 +104,38 @@
         });
     }
     exports.count = count;
+    /**
+     * 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 +180,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 +198,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 +215,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);
@@ -200,18 +292,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,6 +313,36 @@
         };
     }
     exports.manyTill = manyTill;
+    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;
+    function manyTillStr(str) {
+        return (0, trace_1.trace)(`manyTillStr(${str})`, (input) => {
+            const index = 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;
     function transform(parser, transformerFunc) {
         return (0, trace_1.trace)(`transform(${transformerFunc})`, (input) => {
             let parsed = parser(input);
@@ -330,6 +447,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
@@ -392,11 +511,9 @@
         return seq(parsers, getCaptures);
     }
     exports.seqC = seqC;
+    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

@@ -38,15 +38,30 @@ 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, currently lowercase only. */
 export declare const letter: Parser<string>;
+/** A parser that matches one digit or letter, currently lowercase only. */
 export declare const alphanum: Parser<string>;
+/** A parser that matches one lowercase word. */
 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>;
+export declare function regexParser(str: string | RegExp): 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.str = exports.char = exports.betweenWithin = void 0;
     const combinators_1 = require("./combinators");
     const trace_1 = require("./trace");
     const types_1 = require("./types");
@@ -105,16 +105,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");
+    /** A parser that matches one letter, currently lowercase only. */
     exports.letter = oneOf("abcdefghijklmnopqrstuvwxyz");
+    /** A parser that matches one digit or letter, currently lowercase only. */
     exports.alphanum = oneOf("abcdefghijklmnopqrstuvwxyz0123456789");
+    /** A parser that matches one lowercase word. */
     exports.word = (0, combinators_1.many1WithJoin)(exports.letter);
+    /** A parser that matches one or more digits. */
     exports.num = (0, combinators_1.many1WithJoin)(exports.digit);
+    /** 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 +133,19 @@
         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(""));
+    function regexParser(str) {
+        const re = typeof str === "string" ? new RegExp(`^(${str})`) : 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,6 @@
 import { ParserResult } from "./types";
 export declare function resultToString<T>(name: string, result: ParserResult<T>): string;
 export declare function trace(name: string, parser: any): any;
+export declare function parserTime(callback: Function): number | null;
+export declare function printTime(name: string, callback: Function): void;
+export declare function parserDebug(name: string, callback: Function): void;

package/dist/trace.js

@@ -9,7 +9,7 @@
 })(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;
     function resultToString(name, result) {
@@ -20,23 +20,85 @@
     }
     exports.resultToString = resultToString;
     let level = 0;
+    let counts = {};
+    let times = {};
+    let debugFlag = !!process.env.DEBUG;
+    let stepCount = 0;
+    let stepLimit = -1;
     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;
+    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;
+    function printTime(name, callback) {
+        const time = parserTime(callback);
+        if (time) {
+            console.log(`⏱ ${name} -- time: ${(0, utils_1.round)(time)}ms`);
+        }
+    }
+    exports.printTime = printTime;
+    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.13",
   "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",