@thi.ng/parse 2.4.63 → 2.5.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-01-04T21:07:38Z
+- **Last updated**: 2025-01-17T14:10:58Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,30 @@ 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.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
+
+- various minor updates ([42ce3f6](https://github.com/thi-ng/umbrella/commit/42ce3f6))
+
 ### [2.4.52](https://github.com/thi-ng/umbrella/tree/@thi.ng/parse@2.4.52) (2024-08-29)
 
 #### ⏱ Performance improvements

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})`
     );
@@ -88,8 +84,7 @@ class ParseContext {
     );
     child.state = this._retain ? parent.state.copy() : null;
     parent.state = cstate;
-    const children = parent.children;
-    children ? children.push(child) : parent.children = [child];
+    parent.children?.push(child) ?? (parent.children = [child]);
     this._curr = parent;
     return true;
   }
@@ -104,8 +99,7 @@ class ParseContext {
     this._debug && console.log(
       `${__indent(this._scopes.length + 1)}addChild: ${id} (${curr.state.p})`
     );
-    const children = curr.children;
-    children ? children.push(child) : curr.children = [child];
+    curr.children?.push(child) ?? (curr.children = [child]);
     if (newState !== false) {
       newState === true ? this.reader.next(curr.state) : this._curr.state = newState;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/parse",
-  "version": "2.4.63",
+  "version": "2.5.0",
   "description": "Purely functional parser combinators & AST generation for generic inputs",
   "type": "module",
   "module": "./index.js",
@@ -41,8 +41,8 @@
   },
   "dependencies": {
     "@thi.ng/api": "^8.11.16",
-    "@thi.ng/checks": "^3.6.18",
-    "@thi.ng/defmulti": "^3.0.54",
+    "@thi.ng/checks": "^3.6.19",
+    "@thi.ng/defmulti": "^3.0.55",
     "@thi.ng/errors": "^2.5.22",
     "@thi.ng/strings": "^3.9.0"
   },
@@ -246,5 +246,5 @@
     ],
     "year": 2020
   },
-  "gitHead": "56c1d57a96565bbcc8c06c73779a619bba0db368\n"
+  "gitHead": "d888087b36b086fd8c3e7dc98d35857266f78942\n"
 }

package/prims/anchor.js

@@ -1,18 +1,14 @@
 import { ALPHA_NUM } from "@thi.ng/strings/groups";
-const anchor = (fn) => (ctx) => {
-  const state = ctx.state;
-  return fn(state.last, state.done ? null : ctx.reader.read(state));
-};
-const inputStart = (ctx) => ctx.state.last == null;
-const inputEnd = (ctx) => ctx.state.done || ctx.reader.read(ctx.state) === void 0;
+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 = (ctx) => {
-  const state = ctx.state;
+const lineEnd = ({ reader, state }) => {
   let c;
-  return state.done || (c = ctx.reader.read(state)) === "\n" || c === "\r";
+  return state.done || (c = reader.read(state)) === "\n" || c === "\r";
 };
 const wordBoundaryP = (prev, next) => {
   return prev ? next ? ALPHA_NUM[prev] && !ALPHA_NUM[next] : ALPHA_NUM[prev] : next ? ALPHA_NUM[next] : false;

package/prims/lit.js

@@ -1,7 +1,7 @@
 import { satisfyD, satisfy } from "./satisfy.js";
 const litP = (c) => (x) => x === c;
-const lit = (c, id = "lit") => satisfy(litP(c), id);
-const litD = (c) => satisfyD(litP(c));
+const lit = (c, id = "lit") => satisfy((x) => x === c, id);
+const litD = (c) => satisfyD((x) => x === c);
 export {
   lit,
   litD,

package/prims/none-of.js

@@ -1,7 +1,7 @@
 import { isPlainObject } from "@thi.ng/checks/is-plain-object";
 import { isSet } from "@thi.ng/checks/is-set";
 import { satisfy, satisfyD } from "./satisfy.js";
-const noneOfP = (opts) => isSet(opts) ? (x) => !opts.has(x) : isPlainObject(opts) ? (x) => !opts[x] : (x) => opts.indexOf(x) < 0;
+const noneOfP = (opts) => isSet(opts) ? (x) => !opts.has(x) : isPlainObject(opts) ? (x) => !opts[x] : (x) => !opts.includes(x);
 function noneOf(opts, id = "noneOf") {
   return satisfy(noneOfP(opts), id);
 }

package/prims/one-of.js

@@ -1,7 +1,7 @@
 import { isPlainObject } from "@thi.ng/checks/is-plain-object";
 import { isSet } from "@thi.ng/checks/is-set";
 import { satisfy, satisfyD } from "./satisfy.js";
-const oneOfP = (opts) => isSet(opts) ? (x) => opts.has(x) : isPlainObject(opts) ? (x) => opts[x] : (x) => opts.indexOf(x) >= 0;
+const oneOfP = (opts) => isSet(opts) ? (x) => opts.has(x) : isPlainObject(opts) ? (x) => opts[x] : (x) => opts.includes(x);
 function oneOf(opts, id = "oneOf") {
   return satisfy(oneOfP(opts), id);
 }

package/prims/satisfy.js

@@ -5,8 +5,7 @@ const satisfy = (pred, id = "satisfy") => (ctx) => {
 };
 const satisfyD = (pred) => (ctx) => {
   if (ctx.done) return false;
-  const state = ctx.state;
-  const reader = ctx.reader;
+  const { reader, state } = ctx;
   return pred(reader.read(state)) ? (reader.next(state), true) : false;
 };
 export {

package/prims/string.js

@@ -5,8 +5,7 @@ const string = (str, id = "string") => (ctx) => {
   const reader = ctx.reader;
   for (let i = 0, n = str.length; i < n; i++) {
     if (state.done) return false;
-    const r = reader.read(state);
-    if (r !== str[i]) {
+    if (reader.read(state) !== str[i]) {
       return ctx.discard();
     }
     reader.next(state);
@@ -20,8 +19,7 @@ const stringD = (str) => (ctx) => {
   const reader = ctx.reader;
   for (let i = 0, n = str.length; i < n; i++) {
     if (state.done) return false;
-    const r = reader.read(state);
-    if (r !== str[i]) {
+    if (reader.read(state) !== str[i]) {
       return false;
     }
     reader.next(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 {