tarsec 0.1.0 → 0.1.2

package/dist/combinators.d.ts

@@ -142,12 +142,22 @@ export declare function between<O, C, P>(open: Parser<O>, close: Parser<C>, pars
 export declare function between1<O, C, P>(open: Parser<O>, close: Parser<C>, parser: Parser<P>): Parser<P[]>;
 /**
  * Parses many instances of the parser separated by separator.
- * The parser needs to succeed at least once, otherwise sepBy fails.
+ * The parser will succeed even if it consumes zero instances.
+ * To require at least one instance, use `sepBy1`.
  * @param separator
  * @param parser
  * @returns a parser that runs the given parser zero to many times, separated by the separator parser.
  */
 export declare function sepBy<S, P>(separator: Parser<S>, parser: Parser<P>): Parser<P[]>;
+/**
+ * Parses many instances of the parser separated by separator.
+ * The parser needs to succeed at least once, otherwise sepBy fails.
+ * To not require at least one instance, use `sepBy`.
+ * @param separator
+ * @param parser
+ * @returns a parser that runs the given parser one to many times, separated by the separator parser.
+ */
+export declare function sepBy1<S, P>(separator: Parser<S>, parser: Parser<P>): Parser<P[]>;
 /**
  * Convenience function to use as the second argument to `seq` to get all the results from `seq`
  * @param results
@@ -390,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";
 /**
@@ -300,7 +301,8 @@ export function between1(open, close, parser) {
 }
 /**
  * Parses many instances of the parser separated by separator.
- * The parser needs to succeed at least once, otherwise sepBy fails.
+ * The parser will succeed even if it consumes zero instances.
+ * To require at least one instance, use `sepBy1`.
  * @param separator
  * @param parser
  * @returns a parser that runs the given parser zero to many times, separated by the separator parser.
@@ -312,28 +314,37 @@ export function sepBy(separator, parser) {
         while (true) {
             const result = parser(rest);
             if (!result.success) {
-                if (results.length === 0) {
-                    return failure(result.message, input);
-                }
-                else {
-                    return success(results, rest);
-                }
+                return success(results, rest);
             }
             results.push(result.result);
             rest = result.rest;
             const sepResult = separator(rest);
             if (!sepResult.success) {
-                if (results.length === 0) {
-                    return failure(sepResult.message, input);
-                }
-                else {
-                    return success(results, rest);
-                }
+                return success(results, rest);
             }
             rest = sepResult.rest;
         }
     };
 }
+/**
+ * Parses many instances of the parser separated by separator.
+ * The parser needs to succeed at least once, otherwise sepBy fails.
+ * To not require at least one instance, use `sepBy`.
+ * @param separator
+ * @param parser
+ * @returns a parser that runs the given parser one to many times, separated by the separator parser.
+ */
+export function sepBy1(separator, parser) {
+    return (input) => {
+        const result = sepBy(separator, parser)(input);
+        if (result.success) {
+            if (result.result.length === 0) {
+                return failure("expected at least one match", input);
+            }
+        }
+        return result;
+    };
+}
 /**
  * Convenience function to use as the second argument to `seq` to get all the results from `seq`
  * @param results
@@ -816,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.0",
+  "version": "0.1.2",
   "description": "A parser combinator library for TypeScript, inspired by Parsec.",
   "homepage": "https://github.com/egonSchiele/tarsec",
   "scripts": {