tarsec 0.0.18 → 0.0.19

package/README.md

@@ -19,14 +19,14 @@ npm install tarsec
 ## Hello world
 
 ```ts
-import { getResults, str, seq, space } from "tarsec";
+import { str, seqR, space } from "tarsec";
 
 // define a parser
-const parser = seq([
+const parser = seqR(
     str("hello"),
     space,
     str("world")
-], getResults);
+);
 
 // then use it
 parser("hello world"); // success

package/dist/combinators.d.ts

@@ -140,6 +140,87 @@ export declare function getCaptures<R, C>(results: R, captures: C): C;
  * @returns - the results of the parser, with the captures object attached.
  */
 export declare function capture<T, const S extends string>(parser: Parser<T>, name: S): CaptureParser<T, Record<S, T>>;
+/**
+ * `captureCaptures` lifts your captures up a level. Suppose you have a parser like this:
+ *
+ * ```ts
+ * const greeting = seqC(
+ *   str("hello"),
+ *   spaces,
+ *   capture(word, "name"),
+ *   str("!"),
+ *   spaces,
+ *   capture(manynTillStr("?"), "secondPart")
+ * )
+ *
+ * This parses a greeting like "hello Adit! How was your day?" into:
+ *
+ * ```ts
+ * {
+ *   name: "Adit",
+ *   secondPart: "How was your day?"
+ * }
+ * ```
+ *
+ * Now, suppose you decide to refactor this parser into two parsers:
+ *
+ * ```ts
+ * const firstPart = seqC(
+ *   str("hello"),
+ *   spaces,
+ *   capture(word, "name"),
+ *   str("!")
+ * )
+ *
+ * const secondPart = seqC(
+ *   spaces,
+ *   capture(manyTillStr("?"), "secondPart")
+ * )
+ * ```
+ *
+ * And put them together:
+ *
+ * ```ts
+ * const greeting = seqC(
+ *   firstPart,
+ *   secondPart
+ * )
+ * ```
+ *
+ * Unfortunately, this will no longer return an object in that shape,
+ * because it's not actually capturing anything. Captures in `firstPart`
+ * and `secondPart` won't get propagated up. Suppose you try to use `capture` like this:
+ * ```ts
+ * const greeting = seqC(
+ *   capture(firstPart, "firstPart"),
+ *   capture(secondPart, "secondPart")
+ * )
+ * ```
+ * Now you'll get an object that looks like this instead:
+ *
+ * ```ts
+ * {
+ *   firstPart: {
+ *     name: "Adit"
+ *   },
+ *   secondPart: {
+ *     secondPart: "How was your day?"
+ *   }
+ * }
+ * ```
+ *
+ * What you want is for the captures in the child parsers to get merged up to the parent parser. For that, use `captureCaptures`:
+ *
+ * ```ts
+ * const greeting = seqC(
+ *   captureCaptures(firstPart),
+ *   captureCaptures(secondPart)
+ * )
+ * ```
+ * @param parser - parser to capture captures from
+ * @returns - the parser's result set as the captures object
+ */
+export declare function captureCaptures<T extends PlainObject>(parser: Parser<T>): CaptureParser<T, T>;
 /**
  * Returns a parser that consumes input till the given parser succeeds.
  * @param parser - the stop parser

package/dist/combinators.js

@@ -311,6 +311,95 @@ export function capture(parser, name) {
         return result;
     });
 }
+/**
+ * `captureCaptures` lifts your captures up a level. Suppose you have a parser like this:
+ *
+ * ```ts
+ * const greeting = seqC(
+ *   str("hello"),
+ *   spaces,
+ *   capture(word, "name"),
+ *   str("!"),
+ *   spaces,
+ *   capture(manynTillStr("?"), "secondPart")
+ * )
+ *
+ * This parses a greeting like "hello Adit! How was your day?" into:
+ *
+ * ```ts
+ * {
+ *   name: "Adit",
+ *   secondPart: "How was your day?"
+ * }
+ * ```
+ *
+ * Now, suppose you decide to refactor this parser into two parsers:
+ *
+ * ```ts
+ * const firstPart = seqC(
+ *   str("hello"),
+ *   spaces,
+ *   capture(word, "name"),
+ *   str("!")
+ * )
+ *
+ * const secondPart = seqC(
+ *   spaces,
+ *   capture(manyTillStr("?"), "secondPart")
+ * )
+ * ```
+ *
+ * And put them together:
+ *
+ * ```ts
+ * const greeting = seqC(
+ *   firstPart,
+ *   secondPart
+ * )
+ * ```
+ *
+ * Unfortunately, this will no longer return an object in that shape,
+ * because it's not actually capturing anything. Captures in `firstPart`
+ * and `secondPart` won't get propagated up. Suppose you try to use `capture` like this:
+ * ```ts
+ * const greeting = seqC(
+ *   capture(firstPart, "firstPart"),
+ *   capture(secondPart, "secondPart")
+ * )
+ * ```
+ * Now you'll get an object that looks like this instead:
+ *
+ * ```ts
+ * {
+ *   firstPart: {
+ *     name: "Adit"
+ *   },
+ *   secondPart: {
+ *     secondPart: "How was your day?"
+ *   }
+ * }
+ * ```
+ *
+ * What you want is for the captures in the child parsers to get merged up to the parent parser. For that, use `captureCaptures`:
+ *
+ * ```ts
+ * const greeting = seqC(
+ *   captureCaptures(firstPart),
+ *   captureCaptures(secondPart)
+ * )
+ * ```
+ * @param parser - parser to capture captures from
+ * @returns - the parser's result set as the captures object
+ */
+export function captureCaptures(parser) {
+    return trace(`captureCaptures()`, (input) => {
+        let result = parser(input);
+        if (result.success) {
+            return Object.assign(Object.assign({}, result), { captures: result.result });
+        }
+        return result;
+    });
+}
 /**
  * Returns a parser that consumes input till the given parser succeeds.
  * @param parser - the stop parser

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tarsec",
-  "version": "0.0.18",
+  "version": "0.0.19",
   "description": "A parser combinator library for TypeScript, inspired by Parsec.",
   "homepage": "https://github.com/egonSchiele/tarsec",
   "scripts": {
@@ -23,7 +23,11 @@
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "keywords": ["parser", "parser combinator", "parsec"],
+  "keywords": [
+    "parser",
+    "parser combinator",
+    "parsec"
+  ],
   "author": "",
   "license": "ISC",
   "devDependencies": {
@@ -34,4 +38,4 @@
     "typescript": "^5.4.2",
     "vitest": "^1.4.0"
   }
-}
+}