@thi.ng/proctext 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-07-22T13:15:57Z
+- **Last updated**: 2024-08-10T15:03:07Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,18 @@ 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.
 
+## [0.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/proctext@0.2.0) (2024-08-10)
+
+#### 🚀 Features
+
+- add `isAre` and `withArticle` modifiers ([b969d12](https://github.com/thi-ng/umbrella/commit/b969d12))
+- add `<empty>` var, update missing var handling ([350bc26](https://github.com/thi-ng/umbrella/commit/350bc26))
+  - add `<empty>` special var reference for empty strings
+  - add `GeneratorContext.missing` option to provide fallback for missing vars
+  - add custom error types
+  - fix: add missing `maxHist` default value
+  - update deps
+
 ## [0.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/proctext@0.1.0) (2024-07-19)
 
 #### 🚀 Features

package/README.md

@@ -67,7 +67,15 @@ var...
 Variables are case-sensitive (i.e. `NAME` is a different var than `name`) and
 can also be re-defined overridden in different parts of the document.
 
-Variables are referenced via: `<name>`:
+Variables are referenced via: `<name>`. By default, an error will be thrown if a
+variable cannot be resolved. Via the `missing` option given to `generate()` a
+default fallback value can be defined, which when given will **not** trigger an
+error in these cases.
+
+> [!NOTE]
+> The special variable reference `<empty>` can be used to produce an empty
+> string (or used as single value placeholder option inside another variable
+> definition). This variable can not be redefined.
 
 ```ts tangle:export/readme-intro.ts
 import { generate } from "@thi.ng/proctext";
@@ -358,13 +366,15 @@ For Node.js REPL:
 const pro = await import("@thi.ng/proctext");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.14 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 1.34 KB
 
 ## Dependencies
 
 - [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
 - [@thi.ng/arrays](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays)
+- [@thi.ng/checks](https://github.com/thi-ng/umbrella/tree/develop/packages/checks)
 - [@thi.ng/defmulti](https://github.com/thi-ng/umbrella/tree/develop/packages/defmulti)
+- [@thi.ng/errors](https://github.com/thi-ng/umbrella/tree/develop/packages/errors)
 - [@thi.ng/object-utils](https://github.com/thi-ng/umbrella/tree/develop/packages/object-utils)
 - [@thi.ng/parse](https://github.com/thi-ng/umbrella/tree/develop/packages/parse)
 - [@thi.ng/random](https://github.com/thi-ng/umbrella/tree/develop/packages/random)

package/api.d.ts

@@ -1,4 +1,4 @@
-import type { Fn, MaybePromise } from "@thi.ng/api";
+import type { Fn, FnU, MaybePromise } from "@thi.ng/api";
 import type { IRandom } from "@thi.ng/random";
 export interface Var {
     opts: string[];
@@ -32,5 +32,11 @@ export interface GeneratorContext {
      * @defaultValue 10
      */
     maxTrials: number;
+    /**
+     * If given, variable references which cannot be resolved will be replaced
+     * by this string. If undefined (default), throws an error when unable to
+     * resolve a var.
+     */
+    missing?: string | FnU<string>;
 }
 //# sourceMappingURL=api.d.ts.map

package/generate.d.ts

@@ -1,6 +1,51 @@
 import type { GeneratorContext } from "./api.js";
+export declare const CyclicReferenceError: {
+    new (msg?: string | undefined): {
+        origMessage: string;
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
+    stackTraceLimit: number;
+};
+export declare const UnknownModifierError: {
+    new (msg?: string | undefined): {
+        origMessage: string;
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
+    stackTraceLimit: number;
+};
+export declare const UnknownVariableError: {
+    new (msg?: string | undefined): {
+        origMessage: string;
+        name: string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
+    stackTraceLimit: number;
+};
 /**
- * Default variable modifiers (capitalize, uppercase, lowercase)
+ * Default variable modifiers
+ *
+ * @remarks
+ * Current list:
+ *
+ * - `cap`: capitalize body
+ * - `uc`: uppercase
+ * - `lc`: lowercase
+ * - `isAre`: append `is` or `are` verb (naive, english only)
+ * - `withArticle`: prepend `a` or `an` article (naive, english only)
  */
 export declare const DEFAULT_MODIFIERS: GeneratorContext["mods"];
 /**

package/generate.js

@@ -1,15 +1,25 @@
 import { peek } from "@thi.ng/arrays/peek";
+import { isString } from "@thi.ng/checks/is-string";
 import { DEFAULT, defmulti } from "@thi.ng/defmulti/defmulti";
+import { defError } from "@thi.ng/errors/deferror";
 import { mergeDeepObj } from "@thi.ng/object-utils/merge-deep";
 import { defContext } from "@thi.ng/parse/context";
 import { defGrammar } from "@thi.ng/parse/grammar";
 import { SYSTEM } from "@thi.ng/random/system";
 import { pickRandomUnique } from "@thi.ng/random/unique-indices";
 import { capitalize, lower, upper } from "@thi.ng/strings/case";
+const CyclicReferenceError = defError(
+  () => "error expanding variable",
+  (id) => `: "${id}" (cycle detected)`
+);
+const UnknownModifierError = defError(() => "unknown modifier");
+const UnknownVariableError = defError(() => "unknown variable");
 const DEFAULT_MODIFIERS = {
   cap: capitalize,
   uc: upper,
-  lc: lower
+  lc: lower,
+  withArticle: (x) => (/[aeiou]/i.test(x[0]) ? "an " : "a ") + x,
+  isAre: (x) => x + (x.endsWith("s") ? " are" : " is")
 };
 const GRAMMAR = defGrammar(`
 # main parser rule
@@ -46,6 +56,7 @@ const generate = async (src, ctx) => {
           vars: {},
           mods: DEFAULT_MODIFIERS,
           rnd: SYSTEM,
+          maxHist: 1,
           maxTrials: 10
         },
         ctx
@@ -117,29 +128,36 @@ const __resolveVarName = (name, ctx) => {
 };
 const __expandVar = async ({ children }, ctx) => {
   const id = __resolveVarName(children[0].result, ctx);
+  if (id === "empty") return "";
   const $var = ctx.vars[id];
-  if (!$var) throw new Error(`unknown variable: ${id}`);
+  if (!$var) {
+    if (ctx.missing !== void 0) {
+      return isString(ctx.missing) ? ctx.missing : ctx.missing(id);
+    }
+    throw new UnknownVariableError(id);
+  }
   pickRandomUnique(1, $var.opts, $var.history, ctx.maxTrials, ctx.rnd);
   if ($var.history.length > ctx.maxHist) $var.history.shift();
   const choice = peek($var.history);
   const result = await generate(choice, ctx);
   if (result.err) {
-    throw new Error(
-      result.err.message.includes("recursion") ? `error expanding variable: ${id} (cycle detected)` : result.err.message
-    );
+    throw result.err.message.includes("recursion") ? new CyclicReferenceError(id) : result.err;
   }
   let value = result.result;
   if (children[1].children) {
     for (let mod of children[1].children) {
       const modFn = ctx.mods[mod.result];
       if (modFn) value = await modFn(value);
-      else throw new Error(`unknown modifier: ${mod.result}`);
+      else throw new UnknownModifierError(mod.result);
     }
   }
   return value;
 };
 export {
+  CyclicReferenceError,
   DEFAULT_MODIFIERS,
   GRAMMAR,
+  UnknownModifierError,
+  UnknownVariableError,
   generate
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/proctext",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Extensible procedural text generation engine with dynamic, mutable state, indirection, randomizable & recursive variable expansions",
   "type": "module",
   "module": "./index.js",
@@ -36,22 +36,36 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.7",
-    "@thi.ng/arrays": "^2.9.13",
-    "@thi.ng/defmulti": "^3.0.45",
-    "@thi.ng/object-utils": "^1.1.0",
-    "@thi.ng/parse": "^2.4.48",
-    "@thi.ng/random": "^4.0.1",
-    "@thi.ng/strings": "^3.8.1"
+    "@thi.ng/api": "^8.11.8",
+    "@thi.ng/arrays": "^2.9.14",
+    "@thi.ng/checks": "^3.6.10",
+    "@thi.ng/defmulti": "^3.0.46",
+    "@thi.ng/errors": "^2.5.14",
+    "@thi.ng/object-utils": "^1.1.1",
+    "@thi.ng/parse": "^2.4.49",
+    "@thi.ng/random": "^4.0.2",
+    "@thi.ng/strings": "^3.8.2"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.47.0",
+    "@microsoft/api-extractor": "^7.47.5",
     "esbuild": "^0.23.0",
-    "typedoc": "^0.26.3",
-    "typescript": "^5.5.3"
+    "typedoc": "^0.26.5",
+    "typescript": "^5.5.4"
   },
   "keywords": [
-    "typescript"
+    "ast",
+    "bindings",
+    "generative",
+    "generator",
+    "grammar",
+    "parser",
+    "recursion",
+    "rewrite",
+    "syntax",
+    "template",
+    "text",
+    "typescript",
+    "variable"
   ],
   "publishConfig": {
     "access": "public"
@@ -82,5 +96,5 @@
     "status": "alpha",
     "year": 2023
   },
-  "gitHead": "bd22b0826134b79064169371665b4d6caa9b6066\n"
+  "gitHead": "ec78f98d015e4d214a0b840e72e497407807daf3\n"
 }