@thi.ng/parse 2.4.42 → 2.4.44

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-05-08T18:24:31Z
+- **Last updated**: 2024-06-29T09:28:36Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,13 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+### [2.4.43](https://github.com/thi-ng/umbrella/tree/@thi.ng/parse@2.4.43) (2024-06-21)
+
+#### ♻️ Refactoring
+
+- rename various rest args to be more semantically meaningful ([8088a56](https://github.com/thi-ng/umbrella/commit/8088a56))
+- enforce uniform naming convention of internal functions ([56992b2](https://github.com/thi-ng/umbrella/commit/56992b2))
+
 ### [2.4.5](https://github.com/thi-ng/umbrella/tree/@thi.ng/parse@2.4.5) (2023-11-09)
 
 #### ♻️ Refactoring

package/README.md

@@ -7,7 +7,7 @@
 [![Mastodon Follow](https://img.shields.io/mastodon/follow/109331703950160316?domain=https%3A%2F%2Fmastodon.thi.ng&style=social)](https://mastodon.thi.ng/@toxi)
 
 > [!NOTE]
-> This is one of 192 standalone projects, maintained as part
+> This is one of 189 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -73,7 +73,6 @@ grammars](https://makertube.net/w/ursFuQNJQQskmejx1ydL7q)
 
 ## Related packages
 
-- [@thi.ng/fsm](https://github.com/thi-ng/umbrella/tree/develop/packages/fsm) - Composable primitives for building declarative, transducer based Finite-State Machines & matchers for arbitrary data streams
 - [@thi.ng/transducers-fsm](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers-fsm) - Transducer-based Finite State Machine transformer
 
 ## Installation
@@ -102,7 +101,7 @@ For Node.js REPL:
 const parse = await import("@thi.ng/parse");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 5.22 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 5.21 KB
 
 ## Dependencies
 

package/combinators/dynamic.d.ts

@@ -1,16 +1,17 @@
 import type { DynamicParser } from "../api.js";
 /**
- * Returns a parser function placeholder, whose implementation can be
- * set at a later stage via calling `.set()`.
+ * Returns a parser function placeholder, whose implementation can be set at a
+ * later stage via calling `.set()`. The parser always fails until set, after
+ * which it then delegates to the chosen impl.
  *
  * @examples
- * ```ts
- * import { defContext, dynamic } from "@thi.ng/parse";
+ * ```ts tangle:../../export/dynamic.ts
+ * import { defContext, dynamic,lit  } from "@thi.ng/parse";
  *
  * const parser = dynamic<string>();
  * parser.set(lit("a"));
  *
- * parser(defContext("a"));
+ * console.log(parser(defContext("a")));
  * // true
  * ```
  */

package/combinators/lookahead.d.ts

@@ -25,8 +25,8 @@ import type { Parser } from "../api.js";
  * behavior and not a bug.
  *
  * @example
- * ```ts
- * import { defContext, lookahead, oneOf, stringD } from "@thi.ng/parse";
+ * ```ts tangle:../../export/lookahead.ts
+ * import { defContext, join, lookahead, oneOf, stringD } from "@thi.ng/parse";
  *
  * const ctx = defContext("ababaaabbabba");
  *
@@ -34,30 +34,34 @@ import type { Parser } from "../api.js";
  * // note the use of `stringD()` to discard lookahead result
  *
  * // non-capturing lookahead
- * join(lookahead(oneOf("ab"), stringD("abba")))(ctx)
+ * console.log(
+ *   join(lookahead(oneOf("ab"), stringD("abba")))(ctx)
+ * );
  * // true
  *
- * ctx.result
+ * console.log(ctx.result);
  * // "ababaa"
  *
- * ctx.state
+ * console.log(ctx.state);
  * // { p: 6, l: 1, c: 7, done: false, last: 'a' }
  * ```
  *
  * @example
- * ```ts
- * import { defContext, lookahead, oneOf, string } from "@thi.ng/parse";
+ * ```ts tangle:../../export/lookahead-2.ts
+ * import { defContext, join, lookahead, oneOf, string } from "@thi.ng/parse";
  *
  * const ctx = defContext("ababaaabbabba");
  *
  * // capturing lookahead
- * join(lookahead(oneOf("ab"), string("abba"), true))(ctx)
+ * console.log(
+ *   join(lookahead(oneOf("ab"), string("abba"), true))(ctx)
+ * );
  * // true
  *
- * ctx.result
+ * console.log(ctx.result);
  * // "ababaaabba"
  *
- * ctx.state
+ * console.log(ctx.state);
  * // { p: 10, l: 1, c: 11, done: false, last: 'a' }
  * ```
  *

package/context.js

@@ -3,7 +3,7 @@ import { isString } from "@thi.ng/checks/is-string";
 import { parseError } from "./error.js";
 import { defArrayReader } from "./readers/array-reader.js";
 import { defStringReader } from "./readers/string-reader.js";
-import { indent } from "./utils.js";
+import { __indent } from "./utils.js";
 class ParseContext {
   constructor(reader, opts) {
     this.reader = reader;
@@ -46,7 +46,7 @@ class ParseContext {
     scopes.push(scope);
     this._peakDepth = Math.max(this._peakDepth, scopes.length);
     this._debug && console.log(
-      `${indent(scopes.length)}start: ${id} (${scope.state.p})`
+      `${__indent(scopes.length)}start: ${id} (${scope.state.p})`
     );
     return this._curr = scope;
   }
@@ -54,7 +54,7 @@ class ParseContext {
     const scopes = this._scopes;
     const child = scopes.pop();
     this._curr = scopes[scopes.length - 1];
-    this._debug && console.log(`${indent(scopes.length + 1)}discard: ${child.id}`);
+    this._debug && console.log(`${__indent(scopes.length + 1)}discard: ${child.id}`);
     return false;
   }
   end() {
@@ -64,7 +64,7 @@ class ParseContext {
     const cstate = child.state;
     let pstate;
     this._debug && console.log(
-      `${indent(scopes.length + 1)}end: ${child.id} (${cstate.p})`
+      `${__indent(scopes.length + 1)}end: ${child.id} (${cstate.p})`
     );
     child.state = this._retain ? (pstate = parent.state, { p: pstate.p, l: pstate.l, c: pstate.c }) : null;
     parent.state = cstate;
@@ -83,7 +83,7 @@ class ParseContext {
       result
     };
     this._debug && console.log(
-      `${indent(this._scopes.length + 1)}addChild: ${id} (${cstate.p})`
+      `${__indent(this._scopes.length + 1)}addChild: ${id} (${cstate.p})`
     );
     const children = curr.children;
     children ? children.push(child) : curr.children = [child];

package/grammar.js

@@ -43,8 +43,8 @@ import { print, xfPrint } from "./xform/print.js";
 import { xfReplace } from "./xform/replace.js";
 import { xfTrim } from "./xform/trim.js";
 import { withID } from "./xform/with-id.js";
-const apos = litD("'");
-const dash = litD("-");
+const APOS = litD("'");
+const DASH = litD("-");
 const REPEAT = maybe(
   alt([
     oneOf("?*+", "repeat"),
@@ -58,7 +58,7 @@ const REPEAT = maybe(
 );
 const DISCARD = maybe(lit("!"), void 0, "discard");
 const CHAR_OR_ESC = alt([UNICODE, ESC, always()]);
-const CHAR_RANGE = seq([CHAR_OR_ESC, dash, CHAR_OR_ESC], "charRange");
+const CHAR_RANGE = seq([CHAR_OR_ESC, DASH, CHAR_OR_ESC], "charRange");
 const CHAR_SEL = seq(
   [
     litD("["),
@@ -69,7 +69,7 @@ const CHAR_SEL = seq(
   "charSel"
 );
 const ANY = lit(".", "any");
-const LIT = hoistResult(seq([apos, CHAR_OR_ESC, apos], "char"));
+const LIT = hoistResult(seq([APOS, CHAR_OR_ESC, APOS], "char"));
 const SYM = join(oneOrMore(alt([ALPHA_NUM, oneOf(".-_$")]), "sym"));
 const RULE_REF = seq([litD("<"), SYM, litD(">")], "ref");
 const TERM_BODY = alt([RULE_REF, ANY, LIT, STRING, CHAR_SEL]);
@@ -119,9 +119,9 @@ const RULE = seq(
 );
 const COMMENT = seqD([WS0, litD("#"), lookahead(always(), DNL)]);
 const GRAMMAR = zeroOrMore(alt([RULE, COMMENT]), "rules");
-const first = ($) => $.children[0];
-const nth = ($, n) => $.children[n];
-const compile = defmulti(
+const __first = ($) => $.children[0];
+const __nth = ($, n) => $.children[n];
+const __compile = defmulti(
   (scope) => scope.id,
   {
     unicode: "char"
@@ -129,15 +129,15 @@ const compile = defmulti(
   {
     [DEFAULT]: ($) => unsupported(`unknown op: ${$.id}`),
     root: ($, lang, opts, flags) => {
-      const rules = first($).children;
+      const rules = __first($).children;
       rules.reduce(
-        (acc, r) => (acc[first(r).result] = dynamic(), acc),
+        (acc, r) => (acc[__first(r).result] = dynamic(), acc),
         lang.rules
       );
       for (let r of rules) {
-        const id = first(r).result;
+        const id = __first(r).result;
         lang.rules[id].set(
-          compile(r, lang, opts, flags)
+          __compile(r, lang, opts, flags)
         );
       }
       return lang;
@@ -147,7 +147,7 @@ const compile = defmulti(
       opts.debug && console.log(`rule: ${id.result}`, xf);
       const acc = [];
       for (let b of body.children) {
-        const c = compile(b, lang, opts, flags);
+        const c = __compile(b, lang, opts, flags);
         c && acc.push(c);
       }
       let parser = acc.length > 1 ? seq(acc, id.result) : withID(id.result, acc[0]);
@@ -156,7 +156,7 @@ const compile = defmulti(
         if (!$xf) illegalArgs(`missing xform: ${xf.result}`);
         parser = xform(parser, $xf);
       } else if (xf.id === "ref") {
-        const $id = first(xf).result;
+        const $id = __first(xf).result;
         if ($id === id) illegalArgs(`self-referential: ${$id}`);
         const $xf = lang.rules[$id];
         if (!$xf) illegalArgs(`missing xform rule: ${$id}`);
@@ -167,7 +167,7 @@ const compile = defmulti(
       return parser;
     },
     ref: ($, lang, opts, flags) => {
-      const id = first($).result;
+      const id = __first($).result;
       opts.debug && console.log(`ref: ${id}`, flags);
       const ref = lang.rules[id];
       return ref ? flags.discard ? discard(ref) : ref : illegalArgs(`invalid rule ref: ${id}`);
@@ -175,8 +175,8 @@ const compile = defmulti(
     term: ($, lang, opts, flags) => {
       const [term, repeat2, discard2, lookahead2] = $.children;
       opts.debug && console.log(`term: ${term.id}`, flags);
-      return compileRDL(
-        (discard3) => compile(term, lang, opts, { ...flags, discard: discard3 }),
+      return __compileRDL(
+        (discard3) => __compile(term, lang, opts, { ...flags, discard: discard3 }),
         repeat2,
         discard2,
         lookahead2,
@@ -187,8 +187,8 @@ const compile = defmulti(
     lhterm: ($, lang, opts, flags) => {
       const [term, repeat2, discard2] = $.children;
       opts.debug && console.log(`lhterm: ${term.id}`);
-      return compileRD(
-        (discard3) => compile(term, lang, opts, { ...flags, discard: discard3 }),
+      return __compileRD(
+        (discard3) => __compile(term, lang, opts, { ...flags, discard: discard3 }),
         repeat2,
         discard2,
         opts
@@ -197,13 +197,13 @@ const compile = defmulti(
     alt: ($, lang, opts, flags) => {
       opts.debug && console.log(`alt: ${$.id}`, flags);
       const [term0, { children: terms }, repeat2, disc, lookahead2] = $.children;
-      const acc = [compile(term0, lang, opts, flags)];
+      const acc = [__compile(term0, lang, opts, flags)];
       if (terms) {
         for (let c of terms) {
-          acc.push(compile(first(c), lang, opts, flags));
+          acc.push(__compile(__first(c), lang, opts, flags));
         }
       }
-      return compileRDL(
+      return __compileRDL(
         (optimize) => optimize || flags.discard ? acc.length > 1 ? altD(acc) : discard(acc[0]) : acc.length > 1 ? alt(acc) : acc[0],
         repeat2,
         disc,
@@ -233,17 +233,17 @@ const compile = defmulti(
     },
     charSel: ($, lang, opts, flags) => {
       opts.debug && console.log("charSel", flags);
-      const choices = nth($, 1).children.map(
-        (c) => compile(c, lang, opts, flags)
+      const choices = __nth($, 1).children.map(
+        (c) => __compile(c, lang, opts, flags)
       );
-      const invert = first($).result;
+      const invert = __first($).result;
       const parser = choices.length > 1 ? alt(choices) : choices[0];
       opts.debug && console.log(`invert: ${invert}`);
       return invert ? not(parser, flags.discard ? alwaysD() : always()) : parser;
     }
   }
 );
-const compileRepeat = (parser, rspec, opts) => {
+const __compileRepeat = (parser, rspec, opts) => {
   opts.debug && console.log(`repeat: ${rspec.id}`);
   if (rspec.id === "repeat") {
     switch (rspec.result) {
@@ -262,24 +262,29 @@ const compileRepeat = (parser, rspec, opts) => {
   }
   return parser;
 };
-const compileDiscard = (parser, dspec, opts) => {
+const __compileDiscard = (parser, dspec, opts) => {
   opts.debug && console.log(`discard:`, dspec.result);
   return dspec.result === "!" ? discard(parser) : parser;
 };
-const compileLookahead = (parser, spec, lang, opts) => {
+const __compileLookahead = (parser, spec, lang, opts) => {
   opts.debug && console.log(`lookahead:`, spec.id);
   return spec.id === "lhspec" ? lookahead(
     parser,
-    compile(nth(spec, 1), lang, opts, {}),
-    first(spec).result === "+"
+    __compile(__nth(spec, 1), lang, opts, {}),
+    __first(spec).result === "+"
   ) : parser;
 };
-const compileRD = (parser, rspec, dspec, opts) => dspec.result != null && rspec.result == null ? parser(true) : compileDiscard(
-  compileRepeat(parser(false), rspec, opts),
+const __compileRD = (parser, rspec, dspec, opts) => dspec.result != null && rspec.result == null ? parser(true) : __compileDiscard(
+  __compileRepeat(parser(false), rspec, opts),
   dspec,
   opts
 );
-const compileRDL = (parser, rspec, dspec, lhspec, lang, opts) => compileLookahead(compileRD(parser, rspec, dspec, opts), lhspec, lang, opts);
+const __compileRDL = (parser, rspec, dspec, lhspec, lang, opts) => __compileLookahead(
+  __compileRD(parser, rspec, dspec, opts),
+  lhspec,
+  lang,
+  opts
+);
 const defGrammar = (rules, env, opts) => {
   opts = { debug: false, optimize: true, ...opts };
   env = {
@@ -301,7 +306,7 @@ const defGrammar = (rules, env, opts) => {
   const ctx = defContext(rules);
   const result = (opts.debug ? print(GRAMMAR) : GRAMMAR)(ctx);
   if (result) {
-    return compile(
+    return __compile(
       ctx.root,
       {
         env,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/parse",
-  "version": "2.4.42",
+  "version": "2.4.44",
   "description": "Purely functional parser combinators & AST generation for generic inputs",
   "type": "module",
   "module": "./index.js",
@@ -10,7 +10,7 @@
     "type": "git",
     "url": "https://github.com/thi-ng/umbrella.git"
   },
-  "homepage": "https://github.com/thi-ng/umbrella/tree/develop/packages/parse#readme",
+  "homepage": "https://thi.ng/parse",
   "funding": [
     {
       "type": "github",
@@ -36,17 +36,17 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.2",
-    "@thi.ng/checks": "^3.6.4",
-    "@thi.ng/defmulti": "^3.0.39",
-    "@thi.ng/errors": "^2.5.7",
-    "@thi.ng/strings": "^3.7.33"
+    "@thi.ng/api": "^8.11.4",
+    "@thi.ng/checks": "^3.6.6",
+    "@thi.ng/defmulti": "^3.0.41",
+    "@thi.ng/errors": "^2.5.9",
+    "@thi.ng/strings": "^3.7.35"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.43.2",
-    "esbuild": "^0.21.1",
+    "@microsoft/api-extractor": "^7.47.0",
+    "esbuild": "^0.21.5",
     "typedoc": "^0.25.13",
-    "typescript": "^5.4.5"
+    "typescript": "^5.5.2"
   },
   "keywords": [
     "ast",
@@ -241,5 +241,5 @@
     ],
     "year": 2020
   },
-  "gitHead": "df34b4a9e650cc7323575356de207d78933bdcf3\n"
+  "gitHead": "7b950c112fba0b2e7c450765b15624c3382f1354\n"
 }

package/presets/string.js

@@ -5,9 +5,9 @@ import { litD } from "../prims/lit.js";
 import { noneOf } from "../prims/none-of.js";
 import { join } from "../xform/join.js";
 import { ESC, UNICODE } from "./escape.js";
-const quote = litD('"');
+const QUOTE = litD('"');
 const STRING = join(
-  seq([quote, zeroOrMore(alt([UNICODE, ESC, noneOf('"')])), quote], "string")
+  seq([QUOTE, zeroOrMore(alt([UNICODE, ESC, noneOf('"')])), QUOTE], "string")
 );
 export {
   STRING

package/prims/skip.d.ts

@@ -7,16 +7,17 @@ import type { Parser } from "../api.js";
  * of the input is reached, this parser will return true.
  *
  * @example
- * ```ts
- * import { defContext, litD, noneOfP, seqD, skipWhile } from "@thi.ng/parse";
+ * ```ts tangle:../../export/skip-while.ts
+ * import { defContext, litD, NL, noneOfP, seqD, skipWhile } from "@thi.ng/parse";
  *
  * const comment = seqD([litD("#"), skipWhile(noneOfP("\n")), NL]);
  *
  * const ctx = defContext("# ignore more!\n");
- * comment(ctx);
+ *
+ * console.log(comment(ctx));
  * // true
  *
- * ctx.state
+ * console.log(ctx.state);
  * // { p: 15, l: 2, c: 1, done: true, last: '\n' }
  * ```
  *

package/utils.d.ts

@@ -5,5 +5,5 @@
  *
  * @internal
  */
-export declare const indent: (x: number) => string;
+export declare const __indent: (x: number) => string;
 //# sourceMappingURL=utils.d.ts.map

package/utils.js

@@ -1,5 +1,5 @@
-const cache = [];
-const indent = (x) => cache[x] = "  ".repeat(x);
+const CACHE = [];
+const __indent = (x) => CACHE[x] = "  ".repeat(x);
 export {
-  indent
+  __indent
 };

package/xform/comp.d.ts

@@ -3,7 +3,7 @@ import type { ScopeTransform } from "../api.js";
  * Takes any number of {@link ScopeTransform}s and composes them into
  * new xform w/ left to right order of execution.
  *
- * @param xs -
+ * @param xforms -
  */
-export declare const comp: <T>(...xs: ScopeTransform<T>[]) => ScopeTransform<T>;
+export declare const comp: <T>(...xforms: ScopeTransform<T>[]) => ScopeTransform<T>;
 //# sourceMappingURL=comp.d.ts.map

package/xform/comp.js

@@ -1,6 +1,6 @@
-const comp = (...xs) => {
-  const [a, b, c, d] = xs;
-  switch (xs.length) {
+const comp = (...xforms) => {
+  const [a, b, c, d] = xforms;
+  switch (xforms.length) {
     case 0:
       return (x) => x;
     case 1:
@@ -12,7 +12,7 @@ const comp = (...xs) => {
     case 4:
       return (scope, ctx, user) => d(c(b(a(scope, ctx, user), ctx, user), ctx, user), ctx, user);
     default:
-      return (scope, ctx, user) => xs.reduce((scope2, x) => x(scope2, ctx, user), scope);
+      return (scope, ctx, user) => xforms.reduce((scope2, x) => x(scope2, ctx, user), scope);
   }
 };
 export {

package/xform/print.d.ts

@@ -18,16 +18,16 @@ export declare const xfPrint: (fn?: Fn<string, void>) => ScopeTransform<any>;
  * Syntax sugar for `xform(parser, xfPrint)`.
  *
  * @example
- * ```ts
- * import { defContext, lit, oneOrMore, seq, ALPHA } from "@thi.ng/parse";
+ * ```ts tangle:../../export/print.ts
+ * import { ALPHA, defContext, lit, oneOrMore, print, seq } from "@thi.ng/parse";
  *
- * print(seq([lit("["), oneOrMore(ALPHA), lit("]")]))(defContext("[abc]"))
+ * print(seq([lit("["), oneOrMore(ALPHA), lit("]")]))(defContext("[abc]"));
  * // seq: null
  * //   lit: "["
  * //   repeat1: null
- * //     lit: "a"
- * //     lit: "b"
- * //     lit: "c"
+ * //     oneOf: "a"
+ * //     oneOf: "b"
+ * //     oneOf: "c"
  * //   lit: "]"
  * ```
  *

package/xform/print.js

@@ -1,9 +1,9 @@
 import { xform } from "../combinators/xform.js";
-import { indent } from "../utils.js";
+import { __indent } from "../utils.js";
 const xfPrint = (fn = console.log) => {
   const $print = (scope, _, level = 0) => {
     if (!scope) return;
-    const prefix = indent(level);
+    const prefix = __indent(level);
     const state = scope.state;
     const info = state ? ` (${state.l}:${state.c})` : "";
     fn(`${prefix}${scope.id}${info}: ${JSON.stringify(scope.result)}`);