tarsec 0.0.11 → 0.0.13

package/dist/parsers.js

@@ -4,18 +4,18 @@
         if (v !== undefined) module.exports = v;
     }
     else if (typeof define === "function" && define.amd) {
-        define(["require", "exports", "./combinators", "./trace", "./types", "./utils", "./parsers/betweenWithin"], factory);
+        define(["require", "exports", "./combinators", "./trace", "./types", "./utils", "./parsers/within"], factory);
     }
 })(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");
     const utils_1 = require("./utils");
-    var betweenWithin_1 = require("./parsers/betweenWithin");
-    Object.defineProperty(exports, "betweenWithin", { enumerable: true, get: function () { return betweenWithin_1.betweenWithin; } });
+    var within_1 = require("./parsers/within");
+    Object.defineProperty(exports, "betweenWithin", { enumerable: true, get: function () { return within_1.within; } });
     /**
      * Takes a character. Returns a parser that parses that character.
      *
@@ -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;
-    exports.quotedString = (0, combinators_1.seq)([exports.quote, exports.word, exports.quote], (results) => results.join(""));
+    /** 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,67 @@ 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>>;
-export type MergedCaptures<T extends readonly GeneralParser<any, any>[]> = Prettify<UnionToIntersection<ExtractCaptures<ExtractCaptureParsers<T>>>>;
+/** 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,
+ * PickParserType says the array is an array of CaptureParsers,
+ * otherwise it's an array of Parsers. It also correctly merges
+ * the result and capture types. This is useful for a combinator like `or`
+ * 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;
@@ -40,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;
@@ -50,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.11",
+  "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",

package/dist/parsers/betweenWithin.d.ts

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

package/dist/parsers/betweenWithin.js

@@ -1,68 +0,0 @@
-(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", "../trace", "../types"], factory);
-    }
-})(function (require, exports) {
-    "use strict";
-    Object.defineProperty(exports, "__esModule", { value: true });
-    exports.betweenWithin = void 0;
-    const trace_1 = require("../trace");
-    const types_1 = require("../types");
-    function betweenWithin(parser) {
-        return (0, trace_1.trace)("betweenWithin", (input) => {
-            let start = 0;
-            let current = 0;
-            let currentlyMatching = false;
-            const results = [];
-            while (current < input.length) {
-                const parsed = parser(input.slice(current));
-                if (parsed.success) {
-                    if (currentlyMatching) {
-                        const value = input.slice(start, current + parsed.result.length);
-                        if (value.length > 0) {
-                            results.push({
-                                type: "matched",
-                                value,
-                            });
-                        }
-                        current += parsed.result.length;
-                        start = current;
-                        currentlyMatching = false;
-                    }
-                    else {
-                        const value = input.slice(start, current);
-                        if (value.length > 0) {
-                            results.push({
-                                type: "unmatched",
-                                value,
-                            });
-                        }
-                        currentlyMatching = true;
-                        start = current;
-                        current += parsed.result.length;
-                    }
-                }
-                else {
-                    current += 1;
-                }
-            }
-            if (start < current) {
-                if (currentlyMatching) {
-                    return (0, types_1.failure)("unexpected end of input", "");
-                }
-                else {
-                    results.push({
-                        type: "unmatched",
-                        value: input.slice(start, current),
-                    });
-                }
-            }
-            return (0, types_1.success)(results, "");
-        });
-    }
-    exports.betweenWithin = betweenWithin;
-});