tarsec 0.0.14 → 0.0.16

package/dist/parsers.js

@@ -1,180 +1,341 @@
-(function (factory) {
-    if (typeof module === "object" && typeof module.exports === "object") {
-        var v = factory(require, exports);
-        if (v !== undefined) module.exports = v;
+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);
     }
-    else if (typeof define === "function" && define.amd) {
-        define(["require", "exports", "./combinators", "./trace", "./types", "./utils", "./parsers/within"], factory);
+    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);
     }
-})(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.istr = 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 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.
-     *
-     * @param c - character to parse
-     * @returns - parser that parses the given character
-     */
-    function char(c) {
-        return (0, trace_1.trace)(`char(${(0, utils_1.escape)(c)})`, (input) => {
-            if (input.length === 0) {
-                return {
-                    success: false,
-                    rest: input,
-                    message: "unexpected end of input",
-                };
-            }
-            if (input[0] === c) {
-                return (0, types_1.success)(c, input.slice(1));
-            }
-            return (0, types_1.failure)(`expected ${(0, utils_1.escape)(c)}, got ${(0, utils_1.escape)(input[0])}`, 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);
     }
-    exports.char = char;
-    /**
-     * Takes a string. Returns a parser that parses that string.
-     *
-     * @param s - string to match on
-     * @returns - parser that parses the given string
-     */
-    function str(s) {
-        return (0, trace_1.trace)(`str(${(0, utils_1.escape)(s)})`, (input) => {
-            if (input.substring(0, s.length) === s) {
-                return (0, types_1.success)(s, input.slice(s.length));
-            }
-            return (0, types_1.failure)(`expected ${s}, got ${input.substring(0, s.length)}`, input);
-        });
+    else {
+        re = str;
     }
-    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);
-        });
+    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);
     }
-    exports.istr = istr;
-    /**
-     * 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
-     */
-    function oneOf(chars) {
-        return (0, trace_1.trace)(`oneOf(${(0, utils_1.escape)(chars)})`, (input) => {
-            if (input.length === 0) {
-                return (0, types_1.failure)("unexpected end of input", input);
-            }
-            const c = input[0];
-            if (chars.includes(c)) {
-                return char(c)(input);
-            }
-            return (0, types_1.failure)(`expected one of ${(0, utils_1.escape)(chars)}, got ${c}`, input);
-        });
+    else {
+        re = str;
     }
-    exports.oneOf = oneOf;
-    /**
-     * 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
-     */
-    function noneOf(chars) {
-        return (0, trace_1.trace)(`noneOf(${(0, utils_1.escape)(chars)})`, (input) => {
-            if (input.length === 0) {
-                return (0, types_1.failure)("unexpected end of input", input);
+    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 (chars.includes(input[0])) {
-                return (0, types_1.failure)(`expected none of ${(0, utils_1.escape)(chars)}, got ${input[0]}`, 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);
             }
-            return char(input[0])(input);
-        });
-    }
-    exports.noneOf = noneOf;
-    /**
-     * A parser that parses any one character.
-     * Fails on empty strings, succeeds otherwise.
-     *
-     * @param input - input string
-     * @returns - ParserResult
-     */
-    exports.anyChar = (0, trace_1.trace)("anyChar", (input) => {
-        if (input.length === 0) {
-            return (0, types_1.failure)("unexpected end of input", 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 (0, types_1.success)(input[0], input.slice(1));
+        return failure(`expected ${str}, got ${input.slice(0, 10)}`, input);
     });
-    /** 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, 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 = regexParser("^[0-9]+");
-    /** 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);
-        }
-        return (0, types_1.failure)("expected end of input", input);
-    };
-    exports.eof = eof;
-    /** 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(""));
-    /**
-     * 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);
+}
+/**
+ * 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);
         }
-        else {
-            re = str;
+        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 (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;
-});
+        return failure(`expected "${input}" to include "${substr}" (case-insensitive)`, input);
+    });
+}
+/**
+ * Returns a parser that takes some input, runs the transformer function over it,
+ * and returns the result as `rest`, so it can be chained to another parser.
+ * It always returns null as its result. Always succeeds.
+ *
+ * `shape` is useful for modifying the user's input before running parsers over it.
+ * For example, here is a parser that takes in a chapter
+ * and checks that its title starts with "Once upon a time"
+ *
+ * ```ts
+ * const parser = seqR(
+ * shape((c: Chapter) => c.title),
+ *   istr("Once upon a time"),
+ *   )
+ * );
+ * ```
+ *
+ * Now you might be thinking, why not just use the chapter's title as input?
+ * `shape` is most useful when you want to parse multiple properties.
+ *
+ * ```ts
+ * const titleParser = seqR(
+ *   shape((c: Chapter) => c.title),
+ *   istr("Once upon a time"),
+ * );
+ *
+ * const textParser = seqR(
+ *   shape((c: Chapter) => c.text),
+ *   istr("There was a princess"),
+ * );
+ *
+ * const parser = and(titleParser, textParser);
+ * ```
+ *
+ * `parser` now takes a chapter as input and parses its title and text correctly.
+ *
+ * @param transformer - function to transform the input
+ * @returns a parser that takes some input and runs the transformer function over it
+ */
+export function shape(transformer) {
+    return trace(`shape()`, (_input) => {
+        return success(null, transformer(_input));
+    });
+}

package/dist/trace.d.ts

@@ -1,4 +1,4 @@
-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
@@ -90,3 +90,10 @@ export declare function printTime(name: string, callback: Function): void;
  * @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;