tarsec 0.1.1 → 0.1.2

package/dist/combinators.d.ts

@@ -400,3 +400,41 @@ export declare function manyParsers<const T extends readonly GeneralParser<any,
  * @returns - An array of results, or a failure.
  */
 export declare function and<const T extends readonly GeneralParser<any, any>[]>(...parsers: T): PickParserType<T>;
+/**
+ * If any of the parsers fail, this parser throws an error. This can be handy for showing
+ * more specific error messages to users. For example, if you have a parser that parses these two statements:
+ *
+ * ```
+ * import "foo";
+ * greet "name"
+ * ```
+ *
+ * And the user gives this input:
+ *
+ * ```
+ * import;
+ * ```
+ *
+ * You don't want the parser to fail with a generic message, such as 'all parsers have failed'.
+ * You want a more specific error, such as 'expected string after `import` keyword'.
+ *
+ * You could accomplish that with `throwErrorUnless`:
+ *
+ * ```ts
+ * const parser = seqC(
+ *   str("import"),
+ *   captureCaptures(
+ *     throwErrorUnless(
+ *       "expected string after `import` keyword",
+ *       spaces,
+ *       capture(quotedString, "moduleName")
+ *     )
+ *   )
+ * )
+ *```
+
+ * @param _message message to fail with
+ * @param parsers parsers to run
+ * @returns
+ */
+export declare function parseError<const T extends readonly GeneralParser<any, any>[]>(_message: string, ...parsers: T): Parser<MergedCaptures<T>>;

package/dist/combinators.js

@@ -1,5 +1,6 @@
 import { within } from "./parsers/within.js";
-import { trace } from "./trace.js";
+import { TarsecError } from "./tarsecError.js";
+import { getInputStr, trace } from "./trace.js";
 import { captureSuccess, createTree, failure, isCaptureResult, isSuccess, success, } from "./types.js";
 import { escape, findAncestorWithNextParser, popMany } from "./utils.js";
 /**
@@ -826,3 +827,66 @@ export function and(...parsers) {
         return results;
     });
 }
+/**
+ * If any of the parsers fail, this parser throws an error. This can be handy for showing
+ * more specific error messages to users. For example, if you have a parser that parses these two statements:
+ *
+ * ```
+ * import "foo";
+ * greet "name"
+ * ```
+ *
+ * And the user gives this input:
+ *
+ * ```
+ * import;
+ * ```
+ *
+ * You don't want the parser to fail with a generic message, such as 'all parsers have failed'.
+ * You want a more specific error, such as 'expected string after `import` keyword'.
+ *
+ * You could accomplish that with `throwErrorUnless`:
+ *
+ * ```ts
+ * const parser = seqC(
+ *   str("import"),
+ *   captureCaptures(
+ *     throwErrorUnless(
+ *       "expected string after `import` keyword",
+ *       spaces,
+ *       capture(quotedString, "moduleName")
+ *     )
+ *   )
+ * )
+ *```
+
+ * @param _message message to fail with
+ * @param parsers parsers to run
+ * @returns
+ */
+export function parseError(_message, ...parsers) {
+    return (input) => {
+        const result = seqC(...parsers)(input);
+        if (result.success) {
+            return result;
+        }
+        else {
+            const inputStr = getInputStr();
+            const messages = [];
+            const prefix = "Near: ";
+            if (input.length > 0) {
+                const index = inputStr.length - input.length;
+                const start = Math.max(0, input.length - 20);
+                const end = Math.min(inputStr.length, input.length + 20);
+                messages.push(`${prefix}${inputStr.substring(start, end)}`);
+                messages.push(`${" ".repeat(index + prefix.length)}^`);
+            }
+            else {
+                messages.push(`${prefix}${input.substring(1, 100)}`);
+            }
+            messages.push(_message);
+            const message = messages.join("\n");
+            throw new TarsecError(message);
+        }
+    };
+}

package/dist/tarsecError.d.ts

@@ -0,0 +1,3 @@
+export declare class TarsecError extends Error {
+    constructor(message: string);
+}

package/dist/tarsecError.js

@@ -0,0 +1,6 @@
+export class TarsecError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TarsecError";
+    }
+}

package/dist/trace.d.ts

@@ -4,7 +4,7 @@ import { ParserResult, Parser, PlainObject, CaptureParser } from "./types.js";
  * @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,
@@ -111,3 +111,11 @@ export declare function parserDebug(name: string, callback: Function): void;
  * @param callback - callback to run
  */
 export declare function limitSteps(limit: number, callback: Function): void;
+/**
+ * Use this function in conjunction with the parseError combinator. Before running your parser,
+ * call this function, giving it the entire input. Then, if the parseError combinator throws an error,
+ * it will print out a nice message showing exactly what part of the string triggered the error.
+ * @param s full string to parse
+ */
+export declare function setInputStr(s: string): void;
+export declare function getInputStr(): string;

package/dist/trace.js

@@ -16,7 +16,7 @@ let debugMessages = [];
  * @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)}`;
@@ -152,3 +152,16 @@ export function limitSteps(limit, callback) {
     callback();
     stepLimit = -1;
 }
+let inputStr = "";
+/**
+ * Use this function in conjunction with the parseError combinator. Before running your parser,
+ * call this function, giving it the entire input. Then, if the parseError combinator throws an error,
+ * it will print out a nice message showing exactly what part of the string triggered the error.
+ * @param s full string to parse
+ */
+export function setInputStr(s) {
+    inputStr = s;
+}
+export function getInputStr() {
+    return inputStr;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tarsec",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "A parser combinator library for TypeScript, inspired by Parsec.",
   "homepage": "https://github.com/egonSchiele/tarsec",
   "scripts": {