@thi.ng/parse 2.4.64 → 2.6.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-01-14T12:23:33Z
+- **Last updated**: 2025-01-21T11:16:50Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,43 @@ 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.6.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/parse@2.6.0) (2025-01-21)
+
+#### 🚀 Features
+
+- expose more built-in grammar presets ([6e5a057](https://github.com/thi-ng/umbrella/commit/6e5a057))
+  - expose as new builtins:
+    - `BINARY_UINT`
+    - `HEX_UINT`
+    - `SPACE`
+    - `UINT`
+
+#### ⏱ Performance improvements
+
+- optimize char selection grammar compilation ([0476baa](https://github.com/thi-ng/umbrella/commit/0476baa))
+  - check if char selection only contains characters (no ranges)
+  - if so, compile using `oneOf()` instead of `alt()` (avoiding extra level of iteration)
+- update grammar rule compilation ([8341af6](https://github.com/thi-ng/umbrella/commit/8341af6))
+  - avoid `dynamic()` wrapper for grammar rules which don't require it (to avoid extraneous indirection)
+
+## [2.5.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/parse@2.5.0) (2025-01-17)
+
+#### 🚀 Features
+
+- update `DynamicParser`, add `IDeref` support ([cf0d51c](https://github.com/thi-ng/umbrella/commit/cf0d51c))
+
+#### ♻️ Refactoring
+
+- remove `ParseState.last`, update `IReader` & impls ([20fc5cf](https://github.com/thi-ng/umbrella/commit/20fc5cf))
+  - remove `ParseState.last` to lower RAM usage
+  - add `IReader.prev()` to obtain previous char, add docs
+  - update reader impls
+  - update anchor parsers
+  - update tests
+- minor internal updates ([ef97aee](https://github.com/thi-ng/umbrella/commit/ef97aee))
+  - update `ParseContext.start()`
+  - update `check()` combinator impl
+
 ### [2.4.64](https://github.com/thi-ng/umbrella/tree/@thi.ng/parse@2.4.64) (2025-01-14)
 
 #### ♻️ Refactoring

package/README.md

@@ -103,7 +103,7 @@ For Node.js REPL:
 const parse = await import("@thi.ng/parse");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 5.27 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 5.40 KB
 
 ## Dependencies
 
@@ -387,42 +387,50 @@ Custom transforms functions can be supplied via an additional arg to
 be overwritten) and correspond to the [above mentioned
 transforms](#transformers):
 
-- `binary` - parse as binary number
-- `collect` - collect sub terms into array
-- `discard` - discard result
-- `float` - join & parse as floating point number
-- `hex` - join & parse as hex integer
-- `hoist` - replace AST node with its 1st child
-- `hoistR` - use result of 1st child term only
-- `int` - join & parse as integer
-- `join` - join sub terms into single string
-- `json` - join & parse as JSON
-- `print` - print out node's subtree (AST)
-- `trim` - trim result
+| **Transform** | **Description**                       |
+|---------------|---------------------------------------|
+| `binary`      | parse as binary number                |
+| `collect`     | collect sub terms into array          |
+| `discard`     | discard result                        |
+| `float`       | join & parse as floating point number |
+| `hex`         | join & parse as hex integer           |
+| `hoist`       | replace AST node with its 1st child   |
+| `hoistR`      | use result of 1st child term only     |
+| `int`         | join & parse as integer               |
+| `join`        | join sub terms into single string     |
+| `json`        | join & parse as JSON                  |
+| `print`       | print out node's subtree (AST)        |
+| `trim`        | trim result                           |
 
 For convenience, the following built-in parser presets are available as
 rule references in the grammar definition as well:
 
-- `ALPHA`
-- `ALPHA_NUM`
-- `BIT`
-- `DIGIT`
-- `DNL` - discarded newline
-- `END` - input end
-- `ESC` - escape sequences
-- `FLOAT`
-- `HEX_DIGIT`
-- `INT`
-- `LEND` - line end
-- `LSTART` - line start
-- `NL` - newline chars
-- `START` - input start
-- `STRING`
-- `UNICODE`
-- `WB` - word boundary
-- `WS`
-- `WS0`
-- `WS1`
+| **Preset**    | **Description**                                            |
+|---------------|------------------------------------------------------------|
+| `ALPHA`       | single alphabetical char `[A-Za-z]`                        |
+| `ALPHA_NUM`   | single alphanumeric char `[A-Za-z0-9]`                     |
+| `BIT`         | single 0 or 1 digit                                        |
+| `BINARY_UINT` | unprefixed & unsigned binary integer (parsed as JS number) |
+| `DIGIT`       | single decimal digit                                       |
+| `DNL`         | discarded single newline char                              |
+| `END`         | input end                                                  |
+| `ESC`         | single escape sequence                                     |
+| `FLOAT`       | floating point number (parsed as JS number)                |
+| `HEX_DIGIT`   | single hex digit `[0-9a-fA-F]`                             |
+| `HEX_UINT`    | unprefixed & unsigned hex integer (parsed as JS number)    |
+| `INT`         | signed/unsigned decimal integer (parsed as JS number)      |
+| `LEND`        | line end                                                   |
+| `LSTART`      | line start                                                 |
+| `NL`          | single newline char `[\n\r]`                               |
+| `SPACE`       | single space or tab `[ \t]`                                |
+| `START`       | input start                                                |
+| `STRING`      | quoted string, incl. escapes, `"foo\"bar\u2587"`           |
+| `UNICODE`     | unicode escape sequence `\uxxxx`                           |
+| `UINT`        | unsigned decimal integer (parsed as JS number)             |
+| `WB`          | word boundary                                              |
+| `WS`          | single whitespace char                                     |
+| `WS0`         | zero or more whitespace chars                              |
+| `WS1`         | one or more whitespace chars                               |
 
 ## Examples
 

package/api.d.ts

@@ -1,16 +1,48 @@
-import type { Fn, Fn0, IObjectOf, Nullable } from "@thi.ng/api";
+import type { Fn, Fn0, IDeref, IObjectOf, Maybe, Nullable } from "@thi.ng/api";
 import type { ParseContext, ParseScope, ParseState } from "./context.js";
 export interface IReader<T> {
+    /**
+     * Returns the char/value at the current read position. No bounds checking
+     * done, assumes reader is not yet {@link IReader.isDone}.
+     *
+     * @param state
+     */
     read(state: ParseState<T>): T;
+    /**
+     * Returns the char/value at the previous read position (if any).
+     *
+     * @param state
+     */
+    prev(state: ParseState<T>): Maybe<T>;
+    /**
+     * Updates the reader's read position.
+     *
+     * @param state
+     */
     next(state: ParseState<T>): void;
+    /**
+     * Returns true if the reader already consumed all chars/values.
+     *
+     * @param state
+     */
     isDone(state: ParseState<T>): boolean;
+    /**
+     * Returns a string formatted version of the reader's position.
+     *
+     * @param state
+     */
     format(state: ParseState<T>): string;
 }
 export type Parser<T> = Fn<ParseContext<T>, boolean>;
 export type LitParser<T> = Parser<T> & {
     __lit: true;
 };
-export type DynamicParser<T> = Parser<T> & {
+/**
+ * A {@link Parser} wrapper, whose actual implementation can (and must!) be
+ * defined dynamically via the exposed `.set()` function and which can be
+ * retrieved via `.deref()`.
+ */
+export type DynamicParser<T> = Parser<T> & IDeref<Maybe<Parser<T>>> & {
     set: Fn<Parser<T>, void>;
 };
 export type PassValue<T> = T | Fn0<T>;
@@ -43,7 +75,7 @@ export interface ContextOpts {
      * Max recursion depth failsafe. Parsing will terminate once this limit is
      * reached.
      *
-     * @defaultVal 64
+     * @defaultValue 64
      */
     maxDepth: number;
     /**

package/combinators/check.js

@@ -1,9 +1,9 @@
 import { parseError } from "../error.js";
 import { xform } from "./xform.js";
-const check = (parser, pred, msg = "check failed") => xform(parser, (scope, ctx) => {
-  if (!pred(scope)) parseError(ctx, msg);
-  return scope;
-});
+const check = (parser, pred, msg = "check failed") => xform(
+  parser,
+  (scope, ctx) => pred(scope) ? scope : parseError(ctx, msg)
+);
 export {
   check
 };

package/combinators/dynamic.d.ts

@@ -4,7 +4,7 @@ import type { DynamicParser } from "../api.js";
  * later stage via calling `.set()`. The parser always fails until set, after
  * which it then delegates to the chosen impl.
  *
- * @examples
+ * @example
  * ```ts tangle:../../export/dynamic.ts
  * import { defContext, dynamic,lit  } from "@thi.ng/parse";
  *

package/combinators/dynamic.js

@@ -1,6 +1,7 @@
 const dynamic = () => {
   let impl;
-  const wrapper = (ctx) => impl ? impl(ctx) : false;
+  const wrapper = (ctx) => impl?.(ctx) ?? false;
+  wrapper.deref = () => impl;
   wrapper.set = (p) => impl = p;
   return wrapper;
 };

package/context.d.ts

@@ -5,8 +5,7 @@ export declare class ParseState<T> implements ICopy<ParseState<T>> {
     l: number;
     c: number;
     done?: boolean | undefined;
-    last?: T | undefined;
-    constructor(p: number, l: number, c: number, done?: boolean | undefined, last?: T | undefined);
+    constructor(p: number, l: number, c: number, done?: boolean | undefined);
     copy(): ParseState<T>;
 }
 export declare class ParseScope<T> implements ICopy<ParseScope<T>> {

package/context.js

@@ -5,15 +5,14 @@ import { defArrayReader } from "./readers/array-reader.js";
 import { defStringReader } from "./readers/string-reader.js";
 import { __indent } from "./utils.js";
 class ParseState {
-  constructor(p, l, c, done, last) {
+  constructor(p, l, c, done) {
     this.p = p;
     this.l = l;
     this.c = c;
     this.done = done;
-    this.last = last;
   }
   copy() {
-    return new ParseState(this.p, this.l, this.c, this.done, this.last);
+    return new ParseState(this.p, this.l, this.c, this.done);
   }
 }
 class ParseScope {
@@ -57,15 +56,12 @@ class ParseContext {
   }
   start(id) {
     const { _scopes: scopes, _maxDepth } = this;
-    if (scopes.length >= _maxDepth) {
+    const num = scopes.length;
+    if (num >= _maxDepth) {
       parseError(this, `recursion limit reached ${_maxDepth}`);
     }
-    const scope = new ParseScope(
-      id,
-      scopes[scopes.length - 1].state.copy()
-    );
-    scopes.push(scope);
-    this._peakDepth = Math.max(this._peakDepth, scopes.length);
+    const scope = new ParseScope(id, scopes[num - 1].state.copy());
+    this._peakDepth = Math.max(this._peakDepth, scopes.push(scope));
     this._debug && console.log(
       `${__indent(scopes.length)}start: ${id} (${scope.state.p})`
     );

package/grammar.js

@@ -11,13 +11,13 @@ import { seq, seqD } from "./combinators/seq.js";
 import { xform } from "./combinators/xform.js";
 import { defContext } from "./context.js";
 import { ALPHA, ALPHA_NUM } from "./presets/alpha.js";
-import { BIT } from "./presets/bits.js";
+import { BINARY_UINT, BIT } from "./presets/bits.js";
 import { DIGIT } from "./presets/digits.js";
 import { ESC, UNICODE } from "./presets/escape.js";
-import { HEX_DIGIT } from "./presets/hex.js";
+import { HEX_DIGIT, HEX_UINT } from "./presets/hex.js";
 import { FLOAT, INT, UINT } from "./presets/numbers.js";
 import { STRING } from "./presets/string.js";
-import { DNL, NL, WS, WS0, WS1 } from "./presets/whitespace.js";
+import { DNL, NL, SPACE, WS, WS0, WS1 } from "./presets/whitespace.js";
 import { always, alwaysD } from "./prims/always.js";
 import {
   inputEnd,
@@ -121,6 +121,15 @@ 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 __hasDynRuleRefs = (term, builtins) => {
+  let res = term.id === "ref" && !builtins.has(__first(term).result);
+  if (term.children) {
+    for (let x of term.children) {
+      res ||= __hasDynRuleRefs(x, builtins);
+    }
+  }
+  return res;
+};
 const __compile = defmulti(
   (scope) => scope.id,
   {
@@ -130,15 +139,25 @@ const __compile = defmulti(
     [DEFAULT]: ($) => unsupported(`unknown op: ${$.id}`),
     root: ($, lang, opts, flags) => {
       const rules = __first($).children;
-      rules.reduce(
-        (acc, r) => (acc[__first(r).result] = dynamic(), acc),
-        lang.rules
-      );
+      const builtins = new Set(Object.keys(lang.rules));
+      const staticRules = /* @__PURE__ */ new Set();
+      const dynamicRules = /* @__PURE__ */ new Set();
       for (let r of rules) {
+        if (__hasDynRuleRefs(r, builtins)) {
+          lang.rules[__first(r).result] = dynamic();
+          dynamicRules.add(r);
+        } else {
+          staticRules.add(r);
+        }
+      }
+      for (let r of [...staticRules, ...dynamicRules]) {
         const id = __first(r).result;
-        lang.rules[id].set(
-          __compile(r, lang, opts, flags)
-        );
+        const parser = __compile(r, lang, opts, flags);
+        if (dynamicRules.has(r)) {
+          lang.rules[id].set(parser);
+        } else {
+          lang.rules[id] = parser;
+        }
       }
       return lang;
     },
@@ -233,11 +252,21 @@ 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)
-      );
+      let parser;
+      const children = __nth($, 1).children;
+      if (children.length === 1) {
+        parser = __compile(children[0], lang, opts, flags);
+      } else {
+        const onlyChars = children.every((x) => x.id === "char");
+        if (onlyChars) {
+          parser = oneOf(children.map((x) => x.result).join(""));
+        } else {
+          parser = alt(
+            children.map((c) => __compile(c, lang, opts, flags))
+          );
+        }
+      }
       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;
     }
@@ -315,19 +344,23 @@ const defGrammar = (rules, env, opts) => {
           ALPHA_NUM,
           ALPHA,
           BIT,
+          BINARY_UINT,
           DIGIT,
           DNL,
           END: inputEnd,
           ESC,
           FLOAT,
           HEX_DIGIT,
+          HEX_UINT,
           INT,
           LEND: lineEnd,
           LSTART: lineStart,
           NL,
+          SPACE,
           START: inputStart,
           STRING,
           UNICODE,
+          UINT,
           WB: wordBoundary,
           WS,
           WS0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/parse",
-  "version": "2.4.64",
+  "version": "2.6.0",
   "description": "Purely functional parser combinators & AST generation for generic inputs",
   "type": "module",
   "module": "./index.js",
@@ -44,7 +44,7 @@
     "@thi.ng/checks": "^3.6.19",
     "@thi.ng/defmulti": "^3.0.55",
     "@thi.ng/errors": "^2.5.22",
-    "@thi.ng/strings": "^3.9.0"
+    "@thi.ng/strings": "^3.9.1"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.48.1",
@@ -246,5 +246,5 @@
     ],
     "year": 2020
   },
-  "gitHead": "6542b842120bef47cc18d45a1b1db68307a7f04b\n"
+  "gitHead": "56e7a1724e7b0cb5c41119f60320b6ff0e8a3c1c\n"
 }

package/prims/anchor.js

@@ -1,9 +1,9 @@
 import { ALPHA_NUM } from "@thi.ng/strings/groups";
-const anchor = (fn) => ({ reader, state }) => fn(state.last, state.done ? null : reader.read(state));
-const inputStart = (ctx) => ctx.state.last == null;
+const anchor = (fn) => ({ reader, state }) => fn(reader.prev(state), state.done ? null : reader.read(state));
+const inputStart = (ctx) => ctx.reader.prev(ctx.state) == null;
 const inputEnd = ({ reader, state }) => state.done || reader.read(state) === void 0;
 const lineStart = (ctx) => {
-  const l = ctx.state.last;
+  const l = ctx.reader.prev(ctx.state);
   return l == null || l === "\n" || l === "\r";
 };
 const lineEnd = ({ reader, state }) => {

package/readers/array-reader.d.ts

@@ -1,9 +1,11 @@
+import type { Maybe } from "@thi.ng/api";
 import type { IReader } from "../api.js";
 import type { ParseState } from "../context.js";
 export declare class ArrayReader<T> implements IReader<T> {
     protected _src: ArrayLike<T>;
     constructor(_src: ArrayLike<T>);
     read(state: ParseState<T>): T;
+    prev(state: ParseState<T>): Maybe<T>;
     next(state: ParseState<T>): void;
     isDone(state: ParseState<T>): boolean;
     format(state: ParseState<T>): string;

package/readers/array-reader.js

@@ -5,9 +5,11 @@ class ArrayReader {
   read(state) {
     return this._src[state.p];
   }
+  prev(state) {
+    return this._src[state.p - 1];
+  }
   next(state) {
     if (state.done) return;
-    state.last = this._src[state.p];
     state.done = ++state.p >= this._src.length;
   }
   isDone(state) {

package/readers/string-reader.d.ts

@@ -1,9 +1,11 @@
+import type { Maybe } from "@thi.ng/api";
 import type { IReader } from "../api.js";
 import type { ParseState } from "../context.js";
 export declare class StringReader implements IReader<string> {
     protected _src: string;
     constructor(_src: string);
     read(state: ParseState<string>): string;
+    prev(state: ParseState<string>): Maybe<string>;
     next(state: ParseState<string>): void;
     isDone(state: ParseState<string>): boolean;
     format(state: ParseState<string>): string;

package/readers/string-reader.js

@@ -5,10 +5,12 @@ class StringReader {
   read(state) {
     return this._src[state.p];
   }
+  prev(state) {
+    return this._src[state.p - 1];
+  }
   next(state) {
     if (state.done) return;
-    state.last = this._src[state.p];
-    if (state.last === "\n") {
+    if (this._src[state.p] === "\n") {
       state.l++;
       state.c = 1;
     } else {