tarsec 0.0.16 → 0.0.17

package/dist/trace.js

@@ -1,187 +0,0 @@
-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)}`;
-    }
-    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`);
-    }
-    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;
-            }
-            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);
-        }
-    };
-}
-/**
- * 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;
-    }
-    else {
-        console.error("performance.now not available");
-        callback();
-        return 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 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`);
-    }
-    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

@@ -1,141 +0,0 @@
-/** A generic object type. */
-export type PlainObject = Record<string, unknown>;
-/** Represents a parse success with no captures. */
-export type ParserSuccess<T, R = string> = {
-    success: true;
-    result: T;
-    rest: R;
-    nextParser?: Parser<any>;
-};
-/** 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<R = string> = {
-    success: false;
-    rest: R;
-    message: string;
-};
-export type ParserResult<T, R = string> = ParserSuccess<T, R> | ParserFailure<R>;
-export type CaptureParserResult<T, C extends PlainObject, R = string> = CaptureParserSuccess<T, C> | ParserFailure<R>;
-/** A parser is any function that takes an arg and returns a ParserResult. */
-export type Parser<T, I = string> = (input: I) => ParserResult<T>;
-/** A string parser is any function that takes a string and returns a ParserResult. */
-export type StringParser<T> = (input: string) => ParserResult<T>;
-/** A capture parser is any function that takes an arg 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, I = string> = (input: I) => CaptureParserResult<T, C>;
-/** A string capture parser is any function that takes a string and returns a CaptureParserResult. */
-export type StringCaptureParser<T, C extends PlainObject> = (input: string) => CaptureParserResult<T, C>;
-export type GeneralParser<T, C extends PlainObject, I = string> = Parser<T, I> | CaptureParser<T, C, I>;
-export type GeneralStringParser<T, C extends PlainObject> = Parser<T, string> | CaptureParser<T, C, string>;
-export declare function isCaptureResult<T, C extends PlainObject>(result: ParserResult<T>): result is CaptureParserSuccess<T, C>;
-/**
- * This typed function is helpful in filtering out the successes
- * from an array of results while preserving type information. For example:
- *
- * ```
- * // type is ParserSuccess[]
- * results.filter(isSuccess);
- *
- * // type is ParserResult[]
- * results.filter(r => r.success);
- * ```
- * @param result - a parser result
- * @returns - true if the result is a success, otherwise false
- */
-export declare function isSuccess<T, R = string>(result: ParserResult<T, R>): result is ParserSuccess<T, R>;
-/** Convenience function to return a ParserSuccess */
-export declare function success<T, R = string>(result: T, rest: R): ParserSuccess<T, R>;
-/** 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<R = string>(message: string, rest: R): ParserFailure<R>;
-/** 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,
- * 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>[], I = string> = I extends string ? PickParserTypeString<T> : PickParserTypeGeneral<T, I>;
-/** split out to make types more readable */
-export type PickParserTypeGeneral<T extends readonly GeneralParser<any, any>[], I = string> = HasCaptureParsers<T> extends true ? CaptureParser<MergedResults<T>, UnionOfCaptures<T>, I> : Parser<MergedResults<T>, I>;
-export type PickParserTypeString<T extends readonly GeneralParser<any, any>[]> = HasCaptureParsers<T> extends true ? StringCaptureParser<MergedResults<T>, UnionOfCaptures<T>> : StringParser<MergedResults<T>>;
-/**
- * Like `PickParserType`, but the result is an array of the result types,
- * instead of just a union.
- */
-export type PickParserTypeArray<T extends readonly GeneralParser<any, any>[], I = string> = HasCaptureParsers<T> extends true ? CaptureParser<MergedResults<T>, UnionOfCaptures<T>, I> : Parser<MergedResults<T>[], I>;
-/** 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[];
-}> : 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;
-export type ParserNode = {
-    parent: Node;
-    parser: GeneralParser<any, any> | null;
-    input?: string;
-    child: Node;
-    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;
-};
-export type Unmatched = {
-    type: "unmatched";
-    value: string;
-};
-export type WithinResult = Matched | Unmatched;
-export {};

package/dist/types.js

@@ -1,57 +0,0 @@
-export function isCaptureResult(result) {
-    return "captures" in result;
-}
-/**
- * This typed function is helpful in filtering out the successes
- * from an array of results while preserving type information. For example:
- *
- * ```
- * // type is ParserSuccess[]
- * results.filter(isSuccess);
- *
- * // type is ParserResult[]
- * results.filter(r => r.success);
- * ```
- * @param result - a parser result
- * @returns - true if the result is a success, otherwise false
- */
-export function isSuccess(result) {
-    return result.success;
-}
-/** 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,8 +0,0 @@
-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,57 +0,0 @@
-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 {
-            result[key] = b[key];
-        }
-    });
-    return result;
-}
-export 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);
-    }
-    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;
-}