tarsec 0.0.17 → 0.0.19

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./parsers.js";
+export * from "./combinators.js";
+export * from "./trace.js";
+export * from "./types.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./parsers.js";
+export * from "./combinators.js";
+export * from "./trace.js";
+export * from "./types.js";

package/dist/parsers/within.d.ts

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

package/dist/parsers/within.js

@@ -0,0 +1,37 @@
+import { trace } from "../trace.js";
+import { success } from "../types.js";
+export function within(parser) {
+    return trace("within", (input) => {
+        let start = 0;
+        let current = 0;
+        const results = [];
+        while (current < input.length) {
+            const parsed = parser(input.slice(current));
+            if (parsed.success) {
+                const unmatchedValue = input.slice(start, current);
+                if (unmatchedValue.length > 0) {
+                    results.push({
+                        type: "unmatched",
+                        value: unmatchedValue,
+                    });
+                }
+                results.push({
+                    type: "matched",
+                    value: parsed.result,
+                });
+                current += parsed.result.length;
+                start = current;
+            }
+            else {
+                current += 1;
+            }
+        }
+        if (start < current) {
+            results.push({
+                type: "unmatched",
+                value: input.slice(start, current),
+            });
+        }
+        return success(results, "");
+    });
+}

package/dist/parsers.d.ts

@@ -0,0 +1,172 @@
+import { CaptureParser, Parser, Prettify } from "./types.js";
+export { within as betweenWithin } from "./parsers/within.js";
+/**
+ * Takes a character. Returns a parser that parses that character.
+ *
+ * @param c - character to parse
+ * @returns - parser that parses the given character
+ */
+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 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.
+ *
+ * @param chars - string of possible characters
+ * @returns - parser that parses one of the given characters
+ */
+export declare function oneOf(chars: string): Parser<string>;
+/**
+ * Takes a string. Returns a parser that parses one character
+ * that's not any of the characters in the given string
+ *
+ * @param chars - string of characters to avoid
+ * @returns - parser that parses a character that is not in the given string
+ */
+export declare function noneOf(chars: string): Parser<string>;
+/**
+ * A parser that parses any one character.
+ * Fails on empty strings, succeeds otherwise.
+ *
+ * @param input - input string
+ * @returns - ParserResult
+ */
+export declare const anyChar: any;
+/** A parser that matches one of " \t\n\r". */
+export declare const space: Parser<string>;
+/** A parser that matches one or more spaces. */
+export declare const spaces: Parser<string>;
+/** A parser that matches one digit. */
+export declare const digit: Parser<string>;
+/** A parser that matches one letter, case insensitive. */
+export declare const letter: Parser<string>;
+/** A parser that matches one digit or letter, case insensitive. */
+export declare const alphanum: Parser<string>;
+/** 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>;
+/** A parser that matches one single or double quote. */
+export declare const quote: Parser<string>;
+/** A parser that matches one tab character. */
+export declare const tab: Parser<string>;
+/** A parser that matches one newline ("\n" only) character. */
+export declare const newline: Parser<string>;
+/** A parser that succeeds on an empty string. Returns `null` as the result. */
+export declare const eof: Parser<null>;
+/** A parser that matches a quoted string, in single or double quotes.
+ * Returns the string as the result, including the quotes.
+ */
+export declare const quotedString: Parser<string>;
+/**
+ * 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>;
+/**
+ * Like `regexParser`, but you can name your capture groups
+ * and get them back as the result instead.
+ * Fails if it doesn't have the same number of names as capture groups.
+ *
+ * @param str - regex string or RegExp instance to match
+ * @param options - string of regex options (i = ignore case, g = global, m = multiline, u = unicode)
+ * @param captureNames - names of the captures
+ * @returns - parser that matches the given regex
+ */
+export declare function captureRegex<const T extends string[]>(str: string | RegExp, options?: string, ...captureNames: T): Parser<Prettify<Record<(typeof captureNames)[number], string>>>;
+/**
+ * Return a parser that takes a key and a value.
+ * The parser consumes no input and always succeeds,
+ * and returns `null` as the result. It also returns a captures object
+ * with that key-value pair set. This is useful when you need to inject
+ * a key-value pair into captures for a `seq`.
+ *
+ * For example, here is a Markdown heading parser.
+
+ * ```ts
+ * export const headingParser: Parser<Heading> = seqC(
+ *   capture(count(char("#")), "level"),
+ *   spaces,
+ *   capture(many1Till(or(char("\n"), eof)), "content")
+ * );
+```
+ *
+ * This parser returns
+ *
+ * ```ts
+ * {
+ *   level: number,
+ *   content: string
+ * }
+ * ```
+ * but the type of heading is actually
+ *
+ * ```ts
+ * type Heading = {
+ *   type: "heading";
+ *   level: number;
+ *   content: string;
+ * };
+ * ```
+ *
+ * The `type` key is missing. You can use `set` to inject the `type`
+ * key-value pair into captures:
+ *
+ * ```ts
+ * export const headingParser: Parser<Heading> = seqC(
+ *   set("type", "heading"),
+ *   capture(count(char("#")), "level"),
+ *   spaces,
+ *   capture(many1Till(or(char("\n"), eof)), "content")
+ * );
+ * ```
+ *
+ * @param key - key to set on captures object
+ * @param value - value to set on captures object
+ * @returns
+ */
+export declare function set<const K extends string, const V>(key: K, value: V): CaptureParser<null, Record<K, V>>;
+/**
+ * A parser that always succeeds with the given value.
+ * @param value - value to succeed with
+ * @returns value
+ */
+export declare function succeed<T>(value: T): Parser<T>;
+/**
+ * A parser that always fails with the given message.
+ * @param message - message to fail with
+ * @returns failure
+ */
+export declare function fail(message: string): Parser<never>;
+/**
+ * Takes a string. Succeeds if the given input contains that string.
+ * Consumes no input.
+ *
+ * @param substr - substring to find
+ * @returns - parser that succeeds if the given input contains that string
+ */
+export declare function includes<const S extends string>(substr: S): Parser<S>;
+/**
+ * Like `includes`, but case-insensitive.
+ *
+ * @param substr - substring to find
+ * @returns - parser that succeeds if the given input contains that string
+ */
+export declare function iIncludes<const S extends string>(substr: S): Parser<S>;

package/dist/parsers.js

@@ -0,0 +1,297 @@
+import { many1WithJoin, manyWithJoin, seq } from "./combinators.js";
+import { trace } from "./trace.js";
+import { captureSuccess, failure, success, } from "./types.js";
+import { escape } from "./utils.js";
+export { within as betweenWithin } from "./parsers/within.js";
+/**
+ * Takes a character. Returns a parser that parses that character.
+ *
+ * @param c - character to parse
+ * @returns - parser that parses the given character
+ */
+export function char(c) {
+    return trace(`char(${escape(c)})`, (input) => {
+        if (input.length === 0) {
+            return {
+                success: false,
+                rest: input,
+                message: "unexpected end of input",
+            };
+        }
+        if (input[0] === c) {
+            return success(c, input.slice(1));
+        }
+        return failure(`expected ${escape(c)}, got ${escape(input[0])}`, input);
+    });
+}
+/**
+ * Takes a string. Returns a parser that parses that string.
+ *
+ * @param s - string to match on
+ * @returns - parser that parses the given string
+ */
+export function str(s) {
+    return trace(`str(${escape(s)})`, (input) => {
+        if (input.substring(0, s.length) === s) {
+            return success(s, input.slice(s.length));
+        }
+        return failure(`expected ${s}, got ${input.substring(0, s.length)}`, input);
+    });
+}
+/**
+ * Like `str`, but case insensitive.
+ * @param s - string to match on, case insensitive
+ * @returns - parser that matches the given string, case insensitive
+ */
+export function istr(s) {
+    return trace(`istr(${escape(s)})`, (input) => {
+        if (input.substring(0, s.length).toLocaleLowerCase() === s.toLocaleLowerCase()) {
+            return success(input.substring(0, s.length), input.slice(s.length));
+        }
+        return failure(`expected ${s}, got ${input.substring(0, s.length)}`, input);
+    });
+}
+/**
+ * Takes a string. Returns a parser that parses
+ * one of the characters in that string.
+ *
+ * @param chars - string of possible characters
+ * @returns - parser that parses one of the given characters
+ */
+export function oneOf(chars) {
+    return trace(`oneOf(${escape(chars)})`, (input) => {
+        if (input.length === 0) {
+            return failure("unexpected end of input", input);
+        }
+        const c = input[0];
+        if (chars.includes(c)) {
+            return char(c)(input);
+        }
+        return failure(`expected one of ${escape(chars)}, got ${c}`, input);
+    });
+}
+/**
+ * Takes a string. Returns a parser that parses one character
+ * that's not any of the characters in the given string
+ *
+ * @param chars - string of characters to avoid
+ * @returns - parser that parses a character that is not in the given string
+ */
+export function noneOf(chars) {
+    return trace(`noneOf(${escape(chars)})`, (input) => {
+        if (input.length === 0) {
+            return failure("unexpected end of input", input);
+        }
+        if (chars.includes(input[0])) {
+            return failure(`expected none of ${escape(chars)}, got ${input[0]}`, input);
+        }
+        return char(input[0])(input);
+    });
+}
+/**
+ * A parser that parses any one character.
+ * Fails on empty strings, succeeds otherwise.
+ *
+ * @param input - input string
+ * @returns - ParserResult
+ */
+export const anyChar = trace("anyChar", (input) => {
+    if (input.length === 0) {
+        return failure("unexpected end of input", input);
+    }
+    return success(input[0], input.slice(1));
+});
+/** A parser that matches one of " \t\n\r". */
+export const space = oneOf(" \t\n\r");
+/** A parser that matches one or more spaces. */
+export const spaces = many1WithJoin(space);
+/** A parser that matches one digit. */
+export const digit = oneOf("0123456789");
+/** A parser that matches one letter, case insensitive. */
+export const letter = oneOf("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ");
+/** A parser that matches one digit or letter, case insensitive. */
+export const alphanum = oneOf("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789");
+/** A parser that matches one word, case insensitive. */
+export const word = regexParser("^[a-z]+", "ui");
+/** A parser that matches one or more digits. */
+export const num = regexParser("^[0-9]+");
+/** A parser that matches one single or double quote. */
+export const quote = oneOf(`'"`);
+/** A parser that matches one tab character. */
+export const tab = char("\t");
+/** A parser that matches one newline ("\n" only) character. */
+export const newline = char("\n");
+/** A parser that succeeds on an empty string. Returns `null` as the result. */
+export const eof = (input) => {
+    if (input === "") {
+        return success(null, input);
+    }
+    return failure("expected end of input", input);
+};
+/** A parser that matches a quoted string, in single or double quotes.
+ * Returns the string as the result, including the quotes.
+ */
+export const quotedString = seq([quote, manyWithJoin(noneOf(`"'`)), quote], (results) => results.join(""));
+/**
+ * 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 function regexParser(str, options = "") {
+    let re;
+    if (typeof str === "string") {
+        re = new RegExp(str.startsWith("^") ? str : `^${str}`, options);
+    }
+    else {
+        re = str;
+    }
+    return trace(`regex(${str})`, (input) => {
+        const match = input.match(re);
+        if (match) {
+            return success(match[0], input.slice(match[0].length));
+        }
+        return failure(`expected ${str}, got ${input.slice(0, 10)}`, input);
+    });
+}
+/**
+ * Like `regexParser`, but you can name your capture groups
+ * and get them back as the result instead.
+ * Fails if it doesn't have the same number of names as capture groups.
+ *
+ * @param str - regex string or RegExp instance to match
+ * @param options - string of regex options (i = ignore case, g = global, m = multiline, u = unicode)
+ * @param captureNames - names of the captures
+ * @returns - parser that matches the given regex
+ */
+export function captureRegex(str, options = "", ...captureNames) {
+    let re;
+    if (typeof str === "string") {
+        re = new RegExp(str.startsWith("^") ? str : `^${str}`, options);
+    }
+    else {
+        re = str;
+    }
+    return trace(`captureRegex(${str})`, (input) => {
+        const match = input.match(re);
+        if (match) {
+            if (match.slice(1).length > captureNames.length) {
+                return failure(`more capture groups than names. ${match.slice(1).length} capture groups, ${captureNames.length} names`, input);
+            }
+            if (match.slice(1).length < captureNames.length) {
+                return failure(`fewer capture groups than names. ${match.slice(1).length} capture groups, ${captureNames.length} names`, input);
+            }
+            const captures = Object.assign({}, Object.fromEntries(match.slice(1).map((value, index) => [captureNames[index], value])));
+            return success(captures, input.slice(match[0].length));
+        }
+        return failure(`expected ${str}, got ${input.slice(0, 10)}`, input);
+    });
+}
+/**
+ * Return a parser that takes a key and a value.
+ * The parser consumes no input and always succeeds,
+ * and returns `null` as the result. It also returns a captures object
+ * with that key-value pair set. This is useful when you need to inject
+ * a key-value pair into captures for a `seq`.
+ *
+ * For example, here is a Markdown heading parser.
+
+ * ```ts
+ * export const headingParser: Parser<Heading> = seqC(
+ *   capture(count(char("#")), "level"),
+ *   spaces,
+ *   capture(many1Till(or(char("\n"), eof)), "content")
+ * );
+```
+ *
+ * This parser returns
+ *
+ * ```ts
+ * {
+ *   level: number,
+ *   content: string
+ * }
+ * ```
+ * but the type of heading is actually
+ *
+ * ```ts
+ * type Heading = {
+ *   type: "heading";
+ *   level: number;
+ *   content: string;
+ * };
+ * ```
+ *
+ * The `type` key is missing. You can use `set` to inject the `type`
+ * key-value pair into captures:
+ *
+ * ```ts
+ * export const headingParser: Parser<Heading> = seqC(
+ *   set("type", "heading"),
+ *   capture(count(char("#")), "level"),
+ *   spaces,
+ *   capture(many1Till(or(char("\n"), eof)), "content")
+ * );
+ * ```
+ *
+ * @param key - key to set on captures object
+ * @param value - value to set on captures object
+ * @returns
+ */
+export function set(key, value) {
+    return trace(`set(${key}, ${value})`, (input) => {
+        return captureSuccess(null, input, { [key]: value });
+    });
+}
+/**
+ * A parser that always succeeds with the given value.
+ * @param value - value to succeed with
+ * @returns value
+ */
+export function succeed(value) {
+    return trace(`succeed(${value})`, (input) => {
+        return success(value, input);
+    });
+}
+/**
+ * A parser that always fails with the given message.
+ * @param message - message to fail with
+ * @returns failure
+ */
+export function fail(message) {
+    return trace(`fail(${message})`, (input) => {
+        return failure(message, input);
+    });
+}
+/**
+ * Takes a string. Succeeds if the given input contains that string.
+ * Consumes no input.
+ *
+ * @param substr - substring to find
+ * @returns - parser that succeeds if the given input contains that string
+ */
+export function includes(substr) {
+    return trace(`includes(${substr})`, (input) => {
+        if (input.includes(substr)) {
+            return success(substr, input);
+        }
+        return failure(`expected ${escape(input)} to include ${escape(substr)}`, input);
+    });
+}
+/**
+ * Like `includes`, but case-insensitive.
+ *
+ * @param substr - substring to find
+ * @returns - parser that succeeds if the given input contains that string
+ */
+export function iIncludes(substr) {
+    return trace(`iIncludes(${substr})`, (input) => {
+        if (input.toLowerCase().includes(substr.toLowerCase())) {
+            return success(substr, input);
+        }
+        return failure(`expected "${input}" to include "${substr}" (case-insensitive)`, input);
+    });
+}

package/dist/trace.d.ts

@@ -0,0 +1,99 @@
+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;