tarsec 0.0.13 → 0.0.15

package/dist/trace.d.ts

@@ -1,6 +1,99 @@
-import { ParserResult } from "./types";
+import { ParserResult } from "./types.js";
+/**
+ * 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;
+/**
+ * Utility function to limit the number of steps a parser can take.
+ * This is useful for avoiding infinite loops in your parser.
+ * @param limit - number of steps to limit the parser to
+ * @param callback - callback to run
+ */
+export declare function limitSteps(limit: number, callback: Function): void;

package/dist/trace.js

@@ -1,104 +1,187 @@
-(function (factory) {
-    if (typeof module === "object" && typeof module.exports === "object") {
-        var v = factory(require, exports);
-        if (v !== undefined) module.exports = v;
+import { escape, round, shorten } from "./utils.js";
+import process from "process";
+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
+ */
+export function resultToString(name, result) {
+    if (result.success) {
+        return `✅ ${name} -- match: ${escape(result.result)}, rest: ${escape(result.rest)}`;
     }
-    else if (typeof define === "function" && define.amd) {
-        define(["require", "exports", "./utils"], factory);
+    return `❌ ${name} -- message: ${escape(result.message)}, rest: ${escape(result.rest)}`;
+}
+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
+ */
+export function trace(name, parser) {
+    if (stepLimit > 0 && stepCount > stepLimit) {
+        throw new Error(`parser step limit of ${stepLimit} exceeded, parser may be in an infinite loop`);
     }
-})(function (require, exports) {
-    "use strict";
-    Object.defineProperty(exports, "__esModule", { value: true });
-    exports.parserDebug = exports.printTime = exports.parserTime = exports.trace = exports.resultToString = void 0;
-    const utils_1 = require("./utils");
-    const STEP = 2;
-    function resultToString(name, result) {
-        if (result.success) {
-            return `✅ ${name} -- match: ${(0, utils_1.escape)(result.result)}, rest: ${(0, utils_1.escape)(result.rest)}`;
-        }
-        return `❌ ${name} -- message: ${(0, utils_1.escape)(result.message)}, rest: ${(0, utils_1.escape)(result.rest)}`;
-    }
-    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 (debugFlag) {
-                console.log(" ".repeat(level) + `🔍 ${name} -- input: ${(0, utils_1.escape)(input)}`);
-                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;
+    return (input) => {
+        if (debugFlag) {
+            console.log(" ".repeat(level) + `🔍 ${name} -- input: ${shorten(escape(input))}`);
+            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;
             }
-            else {
-                return parser(input);
+            console.log(" ".repeat(level) + resultToString(name, result));
+            if (result.success && result.captures) {
+                console.log(" ".repeat(level) +
+                    `⭐ ${name} -- captures: ${JSON.stringify(result.captures)}`);
             }
-        };
-    }
-    exports.trace = trace;
-    function parserTime(callback) {
-        if (performance && performance.now) {
-            const start = performance.now();
-            callback();
-            const end = performance.now();
-            return end - start;
+            return result;
         }
         else {
-            console.error("performance.now not available");
-            callback();
-            return null;
+            return parser(input);
         }
+    };
+}
+/**
+ * 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 function parserTime(callback) {
+    if (performance && performance.now) {
+        const start = performance.now();
+        callback();
+        const end = performance.now();
+        return end - start;
     }
-    exports.parserTime = parserTime;
-    function printTime(name, callback) {
-        const time = parserTime(callback);
-        if (time) {
-            console.log(`⏱ ${name} -- time: ${(0, utils_1.round)(time)}ms`);
-        }
+    else {
+        console.error("performance.now not available");
+        callback();
+        return null;
     }
-    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 = {};
+}
+/**
+ * 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 function printTime(name, callback) {
+    const time = parserTime(callback);
+    if (time) {
+        console.log(`⏱ ${name} -- time: ${round(time)}ms`);
+    }
+}
+/**
+ * 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 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}: ${round(time)}ms`);
     }
-    exports.parserDebug = parserDebug;
-});
+    console.log("\n");
+    console.log(`📊 ${name} -- step count: ${stepCount}`);
+    console.log("\n\n");
+    stepCount = 0;
+    counts = {};
+    times = {};
+}
+/**
+ * Utility function to limit the number of steps a parser can take.
+ * This is useful for avoiding infinite loops in your parser.
+ * @param limit - number of steps to limit the parser to
+ * @param callback - callback to run
+ */
+export function limitSteps(limit, callback) {
+    stepLimit = limit;
+    callback();
+    stepLimit = -1;
+}

package/dist/types.d.ts

@@ -81,7 +81,7 @@ export type PickParserType<T extends readonly GeneralParser<any, any>[]> = HasCa
  */
 export type InferManyReturnType<T extends GeneralParser<any, any>> = T extends CaptureParser<infer R, infer C> ? CaptureParser<R[], {
     captures: C[];
-}> : Parser<T[]>;
+}> : T extends Parser<infer R> ? Parser<R[]> : never;
 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;

package/dist/types.js

@@ -1,59 +1,40 @@
-(function (factory) {
-    if (typeof module === "object" && typeof module.exports === "object") {
-        var v = factory(require, exports);
-        if (v !== undefined) module.exports = v;
-    }
-    else if (typeof define === "function" && define.amd) {
-        define(["require", "exports"], factory);
-    }
-})(function (require, exports) {
-    "use strict";
-    Object.defineProperty(exports, "__esModule", { value: true });
-    exports.createTree = exports.createNode = exports.failure = exports.captureSuccess = exports.success = exports.isCaptureResult = void 0;
-    function isCaptureResult(result) {
-        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,
-            parser,
-            child: null,
-            closed: false,
-        };
-    }
-    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;
-        }
-        const rootNode = createNode(null, parsers[0]);
-        let currentNode = rootNode;
-        for (let i = 1; i < parsers.length; i++) {
-            currentNode.child = createNode(currentNode, parsers[i]);
-            currentNode = currentNode.child;
-        }
-        return rootNode;
-    }
-    exports.createTree = createTree;
-});
+export function isCaptureResult(result) {
+    return "captures" in result;
+}
+/** Convenience function to return a ParserSuccess */
+export function success(result, rest) {
+    return { success: true, result, rest };
+}
+/** Convenience function to return a CaptureParserSuccess */
+export function captureSuccess(result, rest, captures) {
+    return { success: true, result, rest, captures };
+}
+/** Convenience function to return a ParserFailure */
+export function failure(message, rest) {
+    return { success: false, message, rest };
+}
+/** Convenience function to create a ParserNode. */
+export function createNode(parent, parser) {
+    return {
+        parent,
+        parser,
+        child: null,
+        closed: false,
+    };
+}
+/** 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 function createTree(parsers) {
+    if (parsers.length === 0) {
+        return null;
+    }
+    const rootNode = createNode(null, parsers[0]);
+    let currentNode = rootNode;
+    for (let i = 1; i < parsers.length; i++) {
+        currentNode.child = createNode(currentNode, parsers[i]);
+        currentNode = currentNode.child;
+    }
+    return rootNode;
+}

package/dist/utils.d.ts

@@ -1,7 +1,8 @@
-import { Node } from "./types";
+import { Node } from "./types.js";
 export declare function escape(str: any): string;
 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;
+export declare function shorten(str: string, length?: number): string;

package/dist/utils.js

@@ -1,70 +1,57 @@
-(function (factory) {
-    if (typeof module === "object" && typeof module.exports === "object") {
-        var v = factory(require, exports);
-        if (v !== undefined) module.exports = v;
-    }
-    else if (typeof define === "function" && define.amd) {
-        define(["require", "exports"], factory);
-    }
-})(function (require, exports) {
-    "use strict";
-    Object.defineProperty(exports, "__esModule", { value: true });
-    exports.round = exports.popMany = exports.findAncestorWithNextParser = exports.mergeCaptures = exports.merge = exports.escape = void 0;
-    function escape(str) {
-        return JSON.stringify(str);
-    }
-    exports.escape = escape;
-    function merge(a, b) {
-        if (Array.isArray(a) && Array.isArray(b)) {
-            return [...a, ...b];
-        }
-        else if (Array.isArray(a)) {
-            return [...a, b];
-        }
-        else if (Array.isArray(b)) {
-            return [a, ...b];
+export function escape(str) {
+    return JSON.stringify(str);
+}
+export function merge(a, b) {
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return [...a, ...b];
+    }
+    else if (Array.isArray(a)) {
+        return [...a, b];
+    }
+    else if (Array.isArray(b)) {
+        return [a, ...b];
+    }
+    else {
+        return [a, b];
+    }
+}
+export function mergeCaptures(a, b) {
+    const result = {};
+    Object.keys(a).forEach((key) => {
+        result[key] = a[key];
+    });
+    Object.keys(b).forEach((key) => {
+        if (result[key]) {
+            result[key] = merge(result[key], b[key]);
         }
         else {
-            return [a, b];
-        }
-    }
-    exports.merge = merge;
-    function mergeCaptures(a, b) {
-        const result = {};
-        Object.keys(a).forEach((key) => {
-            result[key] = a[key];
-        });
-        Object.keys(b).forEach((key) => {
-            if (result[key]) {
-                result[key] = merge(result[key], b[key]);
-            }
-            else {
-                result[key] = b[key];
-            }
-        });
-        return result;
-    }
-    exports.mergeCaptures = mergeCaptures;
-    function findAncestorWithNextParser(node, count = 0) {
-        if (node === null)
-            return [null, count];
-        if (!node.closed) {
-            return [node, count];
-        }
-        if (node.parent) {
-            return findAncestorWithNextParser(node.parent, count + 1);
+            result[key] = b[key];
         }
+    });
+    return result;
+}
+export function findAncestorWithNextParser(node, count = 0) {
+    if (node === null)
         return [null, count];
-    }
-    exports.findAncestorWithNextParser = findAncestorWithNextParser;
-    function popMany(arr, count) {
-        for (let i = 0; i < count; i++) {
-            arr.pop();
-        }
-    }
-    exports.popMany = popMany;
-    function round(num, places = 2) {
-        return Math.round(num * 10 ** places) / 10 ** places;
-    }
-    exports.round = round;
-});
+    if (!node.closed) {
+        return [node, count];
+    }
+    if (node.parent) {
+        return findAncestorWithNextParser(node.parent, count + 1);
+    }
+    return [null, count];
+}
+export function popMany(arr, count) {
+    for (let i = 0; i < count; i++) {
+        arr.pop();
+    }
+}
+export function round(num, places = 2) {
+    return Math.round(num * 10 ** places) / 10 ** places;
+}
+export function shorten(str, length = 250) {
+    if (str.length > length) {
+        return str.substring(0, length) + "...";
+    }
+    return str;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tarsec",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "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": {