tarsec 0.0.22 → 0.1.1

package/dist/combinators.d.ts

@@ -98,23 +98,66 @@ export declare function optional<T>(parser: Parser<T>): Parser<T | null>;
 export declare function not(parser: Parser<any>): Parser<null>;
 /**
  * Takes three parsers, `open`, `close`, and `parser`.
- * `between` matches something that matches `parser`,
+ * `between` matches multiple instances of `parser`,
  * surrounded by `open` and `close`. It returns the result of `parser`.
- * If any of the parsers fail, `between` fails.
  *
+ * This is a look-ahead combinator. It keeps trying the `close` parser until it succeeds.
+ * That means you can use it like this, and `parser` won't consume the ending quote:
+ *
+ * ```ts
+ * const quotedString = between(quote, quote, anyChar);
+ * ```
+ *
+ * This combinator succeeds even if it parses zero instances of `parser`.
+ * So for the above parser, this input would succeed: `""`.
+ *
+ * If you want it to consume at least one instance of `parser`, use `between1`.
+ *
+ * Even though this is a look-ahead combinator, it won't work if you supply a greedy parser.
+ * You can make the above parser fail simply by adding `many1`:
+ *
+ * ```ts
+ * const quotedString = between(quote, quote, many1(anyChar));
+ * ```
+ *
+ * `many1(anyChar)` will consume all input until the end of the string,
+ *  not giving the `close` parser a chance to succeed.
+ *
+ * This combinator is obviously expensive, as it applies the `close` parser at every step.
+ * This combinator can also get into an infinite loop if `parser` succeeds without consuming any input.
+ *
+ * @param open - parser for the opening delimiter
+ * @param close - parser for the closing delimiter
+ * @param parser - parser for the content
+ * @returns the result of `parser`.
+ */
+export declare function between<O, C, P>(open: Parser<O>, close: Parser<C>, parser: Parser<P>): Parser<P[]>;
+/**
+ * Like `between`, but fails unless it consumes at least one instance of the `parser`.
  * @param open - parser for the opening delimiter
  * @param close - parser for the closing delimiter
  * @param parser - parser for the content
- * @returns a parser that returns the result of `parser`.
+ * @returns the result of `parser`.
  */
-export declare function between<O, C, P>(open: Parser<O>, close: Parser<C>, parser: Parser<P>): Parser<P>;
+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 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
@@ -293,10 +336,10 @@ export declare function map<R, C extends PlainObject, X>(parser: GeneralParser<R
  * The rest of the input that isn't part of the result is simply joined together and returned as a string.
  * If you need a more structured result + rest, you can use `within` instead.
  *
- * @param parser - a parser that returns a string
+ * @param parser - the parser to search for
  * @returns - a parser that returns an array of strings
  */
-export declare function search(parser: Parser<string>): Parser<string[]>;
+export declare function search<T>(parser: Parser<T>): Parser<T[]>;
 /**
  * seq takes an array of parsers and runs them sequentially.
  * If any of the parsers fail, seq fails without consuming any input.

package/dist/combinators.js

@@ -221,14 +221,38 @@ export function not(parser) {
 }
 /**
  * Takes three parsers, `open`, `close`, and `parser`.
- * `between` matches something that matches `parser`,
+ * `between` matches multiple instances of `parser`,
  * surrounded by `open` and `close`. It returns the result of `parser`.
- * If any of the parsers fail, `between` fails.
+ *
+ * This is a look-ahead combinator. It keeps trying the `close` parser until it succeeds.
+ * That means you can use it like this, and `parser` won't consume the ending quote:
+ *
+ * ```ts
+ * const quotedString = between(quote, quote, anyChar);
+ * ```
+ *
+ * This combinator succeeds even if it parses zero instances of `parser`.
+ * So for the above parser, this input would succeed: `""`.
+ *
+ * If you want it to consume at least one instance of `parser`, use `between1`.
+ *
+ * Even though this is a look-ahead combinator, it won't work if you supply a greedy parser.
+ * You can make the above parser fail simply by adding `many1`:
+ *
+ * ```ts
+ * const quotedString = between(quote, quote, many1(anyChar));
+ * ```
+ *
+ * `many1(anyChar)` will consume all input until the end of the string,
+ *  not giving the `close` parser a chance to succeed.
+ *
+ * This combinator is obviously expensive, as it applies the `close` parser at every step.
+ * This combinator can also get into an infinite loop if `parser` succeeds without consuming any input.
  *
  * @param open - parser for the opening delimiter
  * @param close - parser for the closing delimiter
  * @param parser - parser for the content
- * @returns a parser that returns the result of `parser`.
+ * @returns the result of `parser`.
  */
 export function between(open, close, parser) {
     return (input) => {
@@ -236,19 +260,48 @@ export function between(open, close, parser) {
         if (!result1.success) {
             return result1;
         }
-        const parserResult = parser(result1.rest);
-        if (!parserResult.success) {
-            return parserResult;
+        let rest = result1.rest;
+        // keep looking for close
+        let result2 = close(rest);
+        let successResult = [];
+        // while we don't succeed, keep trying to parse with parser
+        while (!result2.success) {
+            const parserResult = parser(rest);
+            // the parser should keep succeeding until we find the closer
+            // if it doesn't, we fail
+            if (!parserResult.success) {
+                return failure(parserResult.message, input);
+            }
+            successResult.push(parserResult.result);
+            rest = parserResult.rest;
+            result2 = close(rest);
         }
-        const result2 = close(parserResult.rest);
-        if (!result2.success) {
-            return result2;
+        // we found the closer. Note we consume the closer and return the rest
+        return success(successResult, result2.rest);
+    };
+}
+/**
+ * Like `between`, but fails unless it consumes at least one instance of the `parser`.
+ * @param open - parser for the opening delimiter
+ * @param close - parser for the closing delimiter
+ * @param parser - parser for the content
+ * @returns the result of `parser`.
+ */
+export function between1(open, close, parser) {
+    return (input) => {
+        const result = between(open, close, parser)(input);
+        if (result.success) {
+            if (result.result.length === 0) {
+                return failure("expected at least one match", input);
+            }
         }
-        return success(parserResult.result, result2.rest);
+        return result;
     };
 }
 /**
  * Parses many instances of the parser separated by separator.
+ * 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.
@@ -272,6 +325,25 @@ export function sepBy(separator, parser) {
         }
     };
 }
+/**
+ * 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
@@ -531,7 +603,7 @@ export function map(parser, mapperFunc) {
  * The rest of the input that isn't part of the result is simply joined together and returned as a string.
  * If you need a more structured result + rest, you can use `within` instead.
  *
- * @param parser - a parser that returns a string
+ * @param parser - the parser to search for
  * @returns - a parser that returns an array of strings
  */
 export function search(parser) {
@@ -545,6 +617,7 @@ export function search(parser) {
                 .filter((x) => x.type === "unmatched")
                 .map((x) => x.value)
                 .join(" ");
+            // @ts-ignore
             return success(result, rest);
         }
         return success([], input);

package/dist/parsers/within.d.ts

@@ -1,2 +1,59 @@
 import { WithinResult, Parser } from "../types.js";
-export declare function within(parser: Parser<string>): Parser<WithinResult[]>;
+/**
+ * `within` is a funny combinator. It finds zero or more instances of `parser` within the input.
+ * It always succeeds and returns an array of results, each one being a matched or unmatched string.
+ * You could think of "within" as a glorified search. For example, you can use it to
+ * look for quoted text or multiline comments within an input.
+ *
+ * Example:
+ *
+ * ```ts
+ *   const multilineComments = seq(
+ *   [str("/*"), manyWithJoin(noneOf(`*\/`)), str("*\/")],
+ *   (results: string[]) => results.join("")
+ * );
+ *   const parser = within(multilineComments);
+ *   const input = `code before /* this is a comment *\/ code after /* another comment *\/ end`;
+ *
+ *   const result = parser(input);
+ *   console.log(JSON.stringify(result, null, 2));
+ * ```
+ *
+ * Result:
+ *
+ * ```json
+ * {
+ * "success": true,
+ * "result": [
+ *   {
+ *     "type": "unmatched",
+ *     "value": "code before "
+ *   },
+ *   {
+ *     "type": "matched",
+ *     "value": "/* this is a comment *\/"
+ *   },
+ *   {
+ *     "type": "unmatched",
+ *     "value": " code after "
+ *   },
+ *   {
+ *     "type": "matched",
+ *     "value": "/* another comment *\/"
+ *   },
+ *   {
+ *     "type": "unmatched",
+ *     "value": " end"
+ *   }
+ * ],
+ * "rest": ""
+ * }
+ * ```
+ *
+ * This parser is somewhat expensive, as it will go down the input string one character
+ * at a time, applying the given parser each time.
+ *
+ * @param parser - parser to find within the input
+ * @returns - an array of matched and unmatched strings
+ */
+export declare function within<T>(parser: Parser<T>): Parser<WithinResult<T>[]>;

package/dist/parsers/within.js

@@ -1,5 +1,62 @@
 import { trace } from "../trace.js";
 import { success } from "../types.js";
+/**
+ * `within` is a funny combinator. It finds zero or more instances of `parser` within the input.
+ * It always succeeds and returns an array of results, each one being a matched or unmatched string.
+ * You could think of "within" as a glorified search. For example, you can use it to
+ * look for quoted text or multiline comments within an input.
+ *
+ * Example:
+ *
+ * ```ts
+ *   const multilineComments = seq(
+ *   [str("/*"), manyWithJoin(noneOf(`*\/`)), str("*\/")],
+ *   (results: string[]) => results.join("")
+ * );
+ *   const parser = within(multilineComments);
+ *   const input = `code before /* this is a comment *\/ code after /* another comment *\/ end`;
+ *
+ *   const result = parser(input);
+ *   console.log(JSON.stringify(result, null, 2));
+ * ```
+ *
+ * Result:
+ *
+ * ```json
+ * {
+ * "success": true,
+ * "result": [
+ *   {
+ *     "type": "unmatched",
+ *     "value": "code before "
+ *   },
+ *   {
+ *     "type": "matched",
+ *     "value": "/* this is a comment *\/"
+ *   },
+ *   {
+ *     "type": "unmatched",
+ *     "value": " code after "
+ *   },
+ *   {
+ *     "type": "matched",
+ *     "value": "/* another comment *\/"
+ *   },
+ *   {
+ *     "type": "unmatched",
+ *     "value": " end"
+ *   }
+ * ],
+ * "rest": ""
+ * }
+ * ```
+ *
+ * This parser is somewhat expensive, as it will go down the input string one character
+ * at a time, applying the given parser each time.
+ *
+ * @param parser - parser to find within the input
+ * @returns - an array of matched and unmatched strings
+ */
 export function within(parser) {
     return trace("within", (input) => {
         let start = 0;
@@ -19,7 +76,7 @@ export function within(parser) {
                     type: "matched",
                     value: parsed.result,
                 });
-                current += parsed.result.length;
+                current = input.length - parsed.rest.length;
                 start = current;
             }
             else {

package/dist/parsers.d.ts

@@ -1,5 +1,5 @@
 import { CaptureParser, Parser, Prettify } from "./types.js";
-export { within as betweenWithin } from "./parsers/within.js";
+export { within } from "./parsers/within.js";
 /**
  * Takes a character. Returns a parser that parses that character.
  *

package/dist/parsers.js

@@ -2,7 +2,7 @@ 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";
+export { within } from "./parsers/within.js";
 /**
  * Takes a character. Returns a parser that parses that character.
  *

package/dist/types.d.ts

@@ -116,13 +116,13 @@ export declare function createNode(parent: Node | null, parser: GeneralParser<an
  */
 export declare function createTree(parsers: readonly GeneralParser<any, any>[]): Node;
 /** Used by `within`. */
-export type Matched = {
+export type Matched<T> = {
     type: "matched";
-    value: string;
+    value: T;
 };
 export type Unmatched = {
     type: "unmatched";
     value: string;
 };
-export type WithinResult = Matched | Unmatched;
+export type WithinResult<T> = Matched<T> | Unmatched;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tarsec",
-  "version": "0.0.22",
+  "version": "0.1.1",
   "description": "A parser combinator library for TypeScript, inspired by Parsec.",
   "homepage": "https://github.com/egonSchiele/tarsec",
   "scripts": {
@@ -38,4 +38,4 @@
     "typescript": "^5.4.2",
     "vitest": "^1.4.0"
   }
-}
+}