tarsec 0.0.13 → 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

@@ -7,7 +7,6 @@ import { CaptureParser, GeneralParser, InferManyReturnType, MergedCaptures, Merg
  * { 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
@@ -20,6 +19,12 @@ export declare function many<const T extends GeneralParser<any, any>>(parser: T)
  * @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.
@@ -27,7 +32,7 @@ export declare function many1<const T extends GeneralParser<any, any>>(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 exactly<T>(num: number, parser: Parser<T>): Parser<T[]>;
 /**
  * Same as `many`, but joins the results into a single string.
  *
@@ -103,9 +108,37 @@ export declare function not(parser: Parser<any>): Parser<null>;
  * @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>>;
 /**
  * Returns a parser that consumes input till the given parser succeeds.
@@ -115,9 +148,55 @@ export declare function capture<T, const S extends string>(parser: Parser<T>, na
  * The stop parser's match is not included in the result.
  */
 export declare function manyTill<T>(parser: Parser<T>): Parser<string>;
+/**
+ * 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>;
-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>;
+/**
+ * `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.
@@ -146,6 +225,20 @@ export declare function search(parser: Parser<string>): Parser<string[]>;
  * @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,7 +9,7 @@
 })(function (require, exports) {
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
-    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;
+    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");
@@ -22,7 +22,6 @@
      * { 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
@@ -81,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.
@@ -88,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++) {
@@ -103,7 +117,7 @@
             return (0, types_1.success)(results, rest);
         });
     }
-    exports.count = count;
+    exports.exactly = exactly;
     /**
      * Same as `many`, but joins the results into a single string.
      *
@@ -251,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 = [];
@@ -271,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);
@@ -313,6 +355,11 @@
         };
     }
     exports.manyTill = manyTill;
+    /**
+     * 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;
@@ -333,9 +380,23 @@
         };
     }
     exports.many1Till = many1Till;
-    function manyTillStr(str) {
+    /**
+     * `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 = input.indexOf(str);
+            const index = caseInsensitive
+                ? input.toLocaleLowerCase().indexOf(str.toLocaleLowerCase())
+                : input.indexOf(str);
             if (index === -1) {
                 return (0, types_1.success)(input, "");
             }
@@ -343,16 +404,46 @@
         });
     }
     exports.manyTillStr = manyTillStr;
-    function transform(parser, transformerFunc) {
-        return (0, trace_1.trace)(`transform(${transformerFunc})`, (input) => {
+    /**
+     * 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);
@@ -503,14 +594,28 @@
         });
     }
     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 === "";

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.
@@ -44,11 +50,11 @@ export declare const space: Parser<string>;
 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. */
+/** A parser that matches one letter, case insensitive. */
 export declare const letter: Parser<string>;
-/** A parser that matches one digit or letter, currently lowercase only. */
+/** A parser that matches one digit or letter, case insensitive. */
 export declare const alphanum: Parser<string>;
-/** A parser that matches one lowercase word. */
+/** 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>;
@@ -64,4 +70,13 @@ export declare const eof: Parser<null>;
  * Returns the string as the result, including the quotes.
  */
 export declare const quotedString: Parser<string>;
-export declare function regexParser(str: string | RegExp): 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.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;
+    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.
@@ -111,14 +125,14 @@
     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 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 = (0, combinators_1.many1WithJoin)(exports.digit);
+    exports.num = regexParser("^[0-9]+");
     /** A parser that matches one single or double quote. */
     exports.quote = oneOf(`'"`);
     /** A parser that matches one tab character. */
@@ -137,8 +151,23 @@
      * 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;
+    /**
+     * 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) {

package/dist/trace.d.ts

@@ -1,6 +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

@@ -12,6 +12,12 @@
     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)}`;
@@ -25,6 +31,61 @@
     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 (debugFlag) {
@@ -53,6 +114,14 @@
         };
     }
     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();
@@ -67,6 +136,12 @@
         }
     }
     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) {
@@ -74,6 +149,17 @@
         }
     }
     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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tarsec",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "description": "A parser combinator library for TypeScript, inspired by Parsec.",
   "homepage": "https://github.com/egonSchiele/tarsec",
   "scripts": {
@@ -21,7 +21,8 @@
       "require": "./dist/index.js"
     }
   },
-  "keywords": [],
+  "types": "./dist/index.d.ts",
+  "keywords": ["parser", "parser combinator", "parsec"],
   "author": "",
   "license": "ISC",
   "devDependencies": {