@weborigami/origami 0.0.48 → 0.0.50

package/src/builtins/@group.js

@@ -0,0 +1,20 @@
+import getTreeArgument from "../misc/getTreeArgument.js";
+import groupFn from "./@groupFn.js";
+
+/**
+ * Map a tree to a new tree with the values from the original tree grouped by
+ * the given function.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @this {AsyncTree|null}
+ * @param {import("@weborigami/async-tree").Treelike} treelike
+ * @param {import("../../index.ts").Invocable} groupKey
+ */
+export default async function groupBuiltin(treelike, groupKey) {
+  const tree = await getTreeArgument(this, arguments, treelike, "@sort");
+  return groupFn.call(this, groupKey)(tree);
+}
+
+groupBuiltin.usage = `@group <tree>, <fn>\tGroup a tree's values using the given function`;
+groupBuiltin.documentation = "https://weborigami.org/builtins/@group.html";

package/src/builtins/@groupFn.js

@@ -0,0 +1,30 @@
+import { groupFn } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import { toFunction } from "../common/utilities.js";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+
+/**
+ * Return a function that maps a tree to a new tree with the values from the
+ * original tree grouped by the given function.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @this {AsyncTree|null}
+ * @param {import("../../index.ts").Invocable} groupKey
+ */
+export default function groupFnBuiltin(groupKey) {
+  assertScopeIsDefined(this);
+  const scope = this;
+  const groupKeyFn = toFunction(groupKey);
+  // @ts-ignore
+  const fn = groupFn(groupKeyFn);
+  return async (treelike) => {
+    const grouped = await fn(treelike);
+    const scoped = Scope.treeWithScope(grouped, scope);
+    return scoped;
+  };
+}
+
+groupFnBuiltin.usage = `@groupBy <tree>, [groupKeyFn]\tReturn a new tree with the original's values grouped`;
+groupFnBuiltin.documentation =
+  "https://weborigami.org/cli/builtins.html#@group";

package/src/builtins/@if.js

@@ -16,7 +16,8 @@ export default async function ifCommand(value, trueResult, falseResult) {
     condition = keys.length > 0;
   }
 
-  let result = condition ? trueResult : falseResult;
+  // 0 is true, null/undefined/false is false
+  let result = condition || condition === 0 ? trueResult : falseResult;
   if (typeof result === "function") {
     result = await result.call(this);
   }

package/src/builtins/@image/format.js

@@ -1,39 +1,18 @@
-import sharp from "sharp";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+import imageFormatFn from "./formatFn.js";
 
 /**
  * Return the image in a different format.
  *
  * @this {import("@weborigami/types").AsyncTree|null}
  *
- * @typedef {import("sharp").ResizeOptions} ResizeOptions
- *
- * @overload
- * @param {any} param1
- * @param {any} param2
- * @returns {(buffer: Buffer) => Promise<Buffer>}
- *
- * @overload
- * @param {Buffer} param1
- * @param {any} param2
- * @param {any} param3
- * @returns {Promise<Buffer>}
+ * @this {import("@weborigami/types").AsyncTree|null}
+ * @param {Buffer} buffer
+ * @param {keyof import("sharp").FormatEnum|import("sharp").AvailableFormatInfo}
+ * format
+ * @param {any} options
  */
-export default function format(param1, param2, param3) {
-  // Identify which overload was used.
-  let buffer;
-  let format;
-  let options;
-  if (param1 instanceof Buffer) {
-    buffer = param1;
-    format = param2;
-    options = param3;
-  } else {
-    format = param1;
-    options = param2;
-  }
-
-  const transform = (buffer) =>
-    sharp(buffer).toFormat(format, options).toBuffer();
-
-  return buffer ? transform(buffer) : transform;
+export default async function imageFormat(buffer, format, options) {
+  assertScopeIsDefined(this, "image/format");
+  return imageFormatFn.call(this, format, options)(buffer);
 }

package/src/builtins/@image/formatFn.js

@@ -0,0 +1,15 @@
+import sharp from "sharp";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Return a function that transforms an input image to a different format.
+ *
+ * @this {import("@weborigami/types").AsyncTree|null}
+ * @param {keyof import("sharp").FormatEnum|import("sharp").AvailableFormatInfo}
+ * format
+ * @param {any} options
+ */
+export default function imageFormatFn(format, options) {
+  assertScopeIsDefined(this, "image/formatFn");
+  return (buffer) => sharp(buffer).toFormat(format, options).toBuffer();
+}

package/src/builtins/@image/resize.js

@@ -1,35 +1,14 @@
-import sharp from "sharp";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+import imageResizeFn from "./resizeFn.js";
 
 /**
  * Resize an image.
  *
  * @this {import("@weborigami/types").AsyncTree|null}
- *
- * @typedef {import("sharp").ResizeOptions} ResizeOptions
- *
- * @overload
- * @param {ResizeOptions} param1
- * @returns {(buffer: Buffer) => Promise<Buffer>}
- *
- * @overload
- * @param {Buffer} param1
- * @param {ResizeOptions} param2
- * @returns {Promise<Buffer>}
+ * @param {Buffer} buffer
+ * @param {import("sharp").ResizeOptions} options
  */
-export default function resize(param1, param2) {
-  // Identify which overload was used.
-  let buffer;
-  let options;
-  if (param2 === undefined) {
-    options = param1;
-  } else {
-    buffer = param1;
-    options = param2;
-  }
-
-  // Include `rotate()` to auto-rotate according to EXIF data.
-  const transform = (buffer) =>
-    sharp(buffer).rotate().resize(options).toBuffer();
-
-  return buffer ? transform(buffer) : transform;
+export default async function resize(buffer, options) {
+  assertScopeIsDefined(this, "image/resize");
+  return imageResizeFn.call(this, options)(buffer);
 }

package/src/builtins/@image/resizeFn.js

@@ -0,0 +1,14 @@
+import sharp from "sharp";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Return a function that resizes an image.
+ *
+ * @this {import("@weborigami/types").AsyncTree|null}
+ * @param {import("sharp").ResizeOptions} options
+ */
+export default function imageResizeFn(options) {
+  assertScopeIsDefined(this, "image/resizeFn");
+  // Include `rotate()` to auto-rotate according to EXIF data.
+  return (buffer) => sharp(buffer).rotate().resize(options).toBuffer();
+}

package/src/builtins/@inline.js

@@ -1,4 +1,4 @@
-import { isUnpackable, symbols } from "@weborigami/async-tree";
+import { ObjectTree, isUnpackable, symbols } from "@weborigami/async-tree";
 import { compile } from "@weborigami/language";
 import documentObject from "../common/documentObject.js";
 import { toString } from "../common/utilities.js";
@@ -24,7 +24,13 @@ export default async function inline(input) {
   }
   const inputIsDocument = input["@text"] !== undefined;
   const origami = inputIsDocument ? input["@text"] : toString(input);
-  const parent = input.parent ?? input[symbols.parent];
+
+  let parent = /** @type {any} */ (input).parent ?? input[symbols.parent];
+  if (!parent) {
+    // Construct a temporary parent that has the right scope.
+    parent = new ObjectTree({});
+    parent.scope = this;
+  }
 
   // If the input document is a plain object, include it in scope for the
   // evaluated expression.

package/src/builtins/@invoke.js

@@ -3,7 +3,7 @@ import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
 import builtins from "./@builtins.js";
 
 /**
- * Invoke the given function.
+ * Invoke the given text as an Origami function.
  *
  * This built-in exists to facilitate executing an Origami file as a script via
  * a [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) directive.

package/src/builtins/@json.js

@@ -1,4 +1,5 @@
 /** @typedef {import("@weborigami/types").AsyncTree} AsyncTree */
+import { isUnpackable } from "@weborigami/async-tree";
 import * as serialize from "../common/serialize.js";
 import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
 
@@ -20,9 +21,12 @@ export default async function json(obj) {
   if (obj === undefined) {
     return undefined;
   }
+  if (isUnpackable(obj)) {
+    obj = await obj.unpack();
+  }
   const value = await serialize.toJsonValue(obj);
   return JSON.stringify(value, null, 2);
 }
 
 json.usage = "@json <obj>\tRender the object as text in JSON format";
-json.documentation = "https://weborigami.org/language/@json.html";
+json.documentation = "https://weborigami.org/builtins/@json.html";

package/src/builtins/@jsonParse.js

@@ -0,0 +1,9 @@
+import { toString } from "../common/utilities.js";
+
+export default async function jsonParse(input) {
+  const text = toString(input);
+  return text ? JSON.parse(text) : undefined;
+}
+
+jsonParse.usage = `@jsonParse <text>\tParse text as JSON`;
+jsonParse.documentation = "https://weborigami.org/builtins/@jsonParse.html";

package/src/builtins/@map.js

@@ -1,179 +1,19 @@
-import {
-  cachedKeyFunctions,
-  keyFunctionsForExtensions,
-  map,
-} from "@weborigami/async-tree";
-import { Scope } from "@weborigami/language";
-import addValueKeyToScope from "../common/addValueKeyToScope.js";
-import { toFunction } from "../common/utilities.js";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+import mapFn from "./@mapFn.js";
 
 /**
  * Map a hierarchical tree of keys and values to a new tree of keys and values.
  *
- * @typedef {import("@weborigami/async-tree").KeyFn} KeyFn
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  * @typedef {import("@weborigami/async-tree").Treelike} Treelike
  * @typedef {import("@weborigami/async-tree").ValueKeyFn} ValueKeyFn
- * @typedef {import("@weborigami/async-tree").TreeTransform} TreeTransform
- * @typedef {import("../../index.ts").TreelikeTransform} TreelikeTransform
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
- *
- * @typedef {{ deep?: boolean, description?: string, extension?: string,
- * extensions?: string, inverseKey?: KeyFn, key?: ValueKeyFn, keyMap?:
- * ValueKeyFn, value?: ValueKeyFn, valueFn?: ValueKeyFn }} TreeMapOptions
- *
- * @this {import("@weborigami/types").AsyncTree|null}
- *
- * @overload
- * @param {ValueKeyFn} param1
- * @returns {TreelikeTransform}
- *
- * @overload
- * @param {TreeMapOptions} param1
- * @returns {TreelikeTransform}
- *
- * @overload
- * @param {Treelike} param1
- * @param {ValueKeyFn} param2
- * @returns {AsyncTree}
- *
- * @overload
- * @param {Treelike} param1
- * @param {TreeMapOptions} param2
- * @returns {AsyncTree}
- */
-export default function treeMap(param1, param2) {
-  // Identify whether the valueFn/options are the first parameter
-  // or the second.
-  let source;
-  let options;
-  if (arguments.length === 0) {
-    throw new TypeError(
-      `@map: You must give @map a function or a dictionary of options.`
-    );
-  } else if (!param1) {
-    throw new TypeError(`@map: The first argument was undefined.`);
-  } else if (arguments.length === 1) {
-    options = param1;
-  } else if (!param2) {
-    throw new TypeError(`@map: The second argument was undefined.`);
-  } else {
-    source = param1;
-    options = param2;
-  }
-
-  // Identify whether the valueFn/options is a valueFn function
-  // or an options dictionary.
-  let valueFn;
-  if (
-    typeof options === "function" ||
-    typeof (/** @type {any} */ (options)?.unpack) === "function"
-  ) {
-    valueFn = options;
-    options = {};
-  } else if (!options) {
-    throw new TypeError(
-      `@map: You must specify a value function or options dictionary.`
-    );
-  } else {
-    valueFn = options.value ?? options.valueMap;
-  }
-
-  let { deep, description, inverseKey, needsSourceValue } = options;
-  let extension = options.extension ?? options.extensions;
-  let keyFn = options.keyMap ?? options.key;
-
-  description ??= `@map ${extension ?? ""}`;
-
-  if (extension && (keyFn || inverseKey)) {
-    throw new TypeError(
-      `@map: You can't specify extensions and also a key or inverseKey function`
-    );
-  }
-
-  const baseScope = Scope.getScope(this);
-
-  // Extend the value function to include the value and key in scope.
-  let extendedValueFn;
-  if (valueFn) {
-    const resolvedValueFn = toFunction(valueFn);
-    extendedValueFn = function (sourceValue, sourceKey, tree) {
-      const scope = addValueKeyToScope(baseScope, sourceValue, sourceKey);
-      return resolvedValueFn.call(scope, sourceValue, sourceKey, tree);
-    };
-  }
-
-  // Extend the key function to include the value and key in scope.
-  let extendedKeyFn;
-  let extendedInverseKeyFn;
-  if (extension) {
-    let { resultExtension, sourceExtension } = parseExtensions(extension);
-    const keyFns = keyFunctionsForExtensions({
-      resultExtension,
-      sourceExtension,
-    });
-    extendedKeyFn = keyFns.key;
-    extendedInverseKeyFn = keyFns.inverseKey;
-  } else if (keyFn) {
-    const resolvedKeyFn = toFunction(keyFn);
-    async function scopedKeyFn(sourceKey, tree) {
-      const sourceValue = await tree.get(sourceKey);
-      const scope = addValueKeyToScope(baseScope, sourceValue, sourceKey);
-      const resultKey = await resolvedKeyFn.call(
-        scope,
-        sourceValue,
-        sourceKey,
-        tree
-      );
-      return resultKey;
-    }
-    const keyFns = cachedKeyFunctions(scopedKeyFn);
-    extendedKeyFn = keyFns.key;
-    extendedInverseKeyFn = keyFns.inverseKey;
-  } else {
-    // Use sidecar keyFn/inverseKey functions if the valueFn defines them.
-    extendedKeyFn = valueFn?.key;
-    extendedInverseKeyFn = valueFn?.inverseKey;
-  }
-
-  const transform = function mapTreelike(treelike) {
-    return map({
-      deep,
-      description,
-      inverseKey: extendedInverseKeyFn,
-      key: extendedKeyFn,
-      needsSourceValue,
-      value: extendedValueFn,
-    })(treelike);
-  };
-
-  return source ? transform(source) : transform;
-}
-
-/**
- * Given a string specifying an extension or a mapping of one extension to another,
- * return the source and result extensions.
- *
- * Syntax:
- *   foo
- *   foo→bar      Unicode Rightwards Arrow
- *   foo->bar     hyphen and greater-than sign
+ * @typedef {import("./map.d.ts").TreeMapOptions} TreeMapOptions
  *
- * @param {string} specifier
+ * @this {AsyncTree|null}
+ * @param {Treelike} source
+ * @param {ValueKeyFn|TreeMapOptions} operation
  */
-function parseExtensions(specifier) {
-  const lowercase = specifier?.toLowerCase() ?? "";
-  const extensionRegex =
-    /^\.?(?<sourceExtension>\S*)(?:\s*(→|->)\s*)\.?(?<extension>\S+)$/;
-  let resultExtension;
-  let sourceExtension;
-  const match = lowercase.match(extensionRegex);
-  if (match?.groups) {
-    // foo→bar
-    ({ extension: resultExtension, sourceExtension } = match.groups);
-  } else {
-    // foo
-    resultExtension = lowercase;
-    sourceExtension = lowercase;
-  }
-  return { resultExtension, sourceExtension };
+export default function map(source, operation) {
+  assertScopeIsDefined(this, "map");
+  return mapFn.call(this, operation)(source);
 }

package/src/builtins/@mapFn.js

@@ -0,0 +1,143 @@
+import {
+  cachedKeyFunctions,
+  isPlainObject,
+  keyFunctionsForExtensions,
+  mapFn,
+} from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import { toFunction } from "../common/utilities.js";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+
+/**
+ * Return a function that transforms a tree of keys and values to a new tree of
+ * keys and values.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("@weborigami/async-tree").ValueKeyFn} ValueKeyFn
+ * @typedef {import("./map.d.ts").TreeMapOptions} TreeMapOptions
+ *
+ * @this {AsyncTree|null}
+ * @param {ValueKeyFn|TreeMapOptions} operation
+ */
+export default function mapFnBuiltin(operation) {
+  assertScopeIsDefined(this, "map");
+  const scope = this;
+
+  // Identify whether the map instructions take the form of a value function or
+  // a dictionary of options.
+  /** @type {TreeMapOptions} */
+  let options;
+  /** @type {ValueKeyFn|undefined} */
+  let valueFn;
+  if (isPlainObject(operation)) {
+    // @ts-ignore
+    options = operation;
+    valueFn = options?.value;
+  } else if (
+    typeof operation === "function" ||
+    typeof (/** @type {any} */ (operation)?.unpack) === "function"
+  ) {
+    valueFn = operation;
+    options = {};
+  } else {
+    throw new TypeError(
+      `@mapFn: You must specify a value function or options dictionary as the first parameter.`
+    );
+  }
+
+  const { deep, extension, needsSourceValue } = options;
+  const description = options.description ?? `@mapFn ${extension ?? ""}`;
+  const keyFn = options.key;
+  const inverseKeyFn = options.inverseKey;
+
+  if (extension && (keyFn || inverseKeyFn)) {
+    throw new TypeError(
+      `@mapFn: You can't specify extensions and also a key or inverseKey function`
+    );
+  }
+
+  // Extend the value function to include the value and key in scope.
+  let extendedValueFn;
+  if (valueFn) {
+    const resolvedValueFn = toFunction(valueFn);
+    extendedValueFn = (sourceValue, sourceKey, tree) =>
+      resolvedValueFn.call(scope, sourceValue, sourceKey, tree);
+  }
+
+  // Extend the key function to include the value and key in scope.
+  let extendedKeyFn;
+  let extendedInverseKeyFn;
+  if (extension) {
+    let { resultExtension, sourceExtension } = parseExtensions(extension);
+    const keyFns = keyFunctionsForExtensions({
+      resultExtension,
+      sourceExtension,
+    });
+    extendedKeyFn = keyFns.key;
+    extendedInverseKeyFn = keyFns.inverseKey;
+  } else if (keyFn) {
+    const resolvedKeyFn = toFunction(keyFn);
+    async function scopedKeyFn(sourceKey, tree) {
+      const sourceValue = await tree.get(sourceKey);
+      const resultKey = await resolvedKeyFn.call(
+        scope,
+        sourceValue,
+        sourceKey,
+        tree
+      );
+      return resultKey;
+    }
+    const keyFns = cachedKeyFunctions(scopedKeyFn);
+    extendedKeyFn = keyFns.key;
+    extendedInverseKeyFn = keyFns.inverseKey;
+  } else {
+    // Use sidecar keyFn/inverseKey functions if the valueFn defines them.
+    extendedKeyFn = /** @type {any} */ (valueFn)?.key;
+    extendedInverseKeyFn = /** @type {any} */ (valueFn)?.inverseKey;
+  }
+
+  const fn = mapFn({
+    deep,
+    description,
+    inverseKey: extendedInverseKeyFn,
+    key: extendedKeyFn,
+    needsSourceValue,
+    value: extendedValueFn,
+  });
+
+  return (treelike) => {
+    const mapped = fn(treelike);
+    const scoped = Scope.treeWithScope(mapped, scope);
+    return scoped;
+  };
+}
+
+/**
+ * Given a string specifying an extension or a mapping of one extension to another,
+ * return the source and result extensions.
+ *
+ * Syntax:
+ *   foo
+ *   foo→bar      Unicode Rightwards Arrow
+ *   foo->bar     hyphen and greater-than sign
+ *
+ * @param {string} specifier
+ */
+function parseExtensions(specifier) {
+  const lowercase = specifier?.toLowerCase() ?? "";
+  const extensionRegex =
+    /^\.?(?<sourceExtension>\S*)(?:\s*(→|->)\s*)\.?(?<extension>\S+)$/;
+  let resultExtension;
+  let sourceExtension;
+  const match = lowercase.match(extensionRegex);
+  if (match?.groups) {
+    // foo→bar
+    ({ extension: resultExtension, sourceExtension } = match.groups);
+  } else {
+    // foo
+    resultExtension = lowercase;
+    sourceExtension = lowercase;
+  }
+  return { resultExtension, sourceExtension };
+}

package/src/builtins/@mdHtml.js

@@ -26,6 +26,8 @@ marked.use(
 );
 
 /**
+ * Transform markdown to HTML.
+ *
  * @typedef {import("@weborigami/async-tree").StringLike} StringLike
  * @typedef {import("@weborigami/async-tree").Unpackable<StringLike>} UnpackableStringlike
  *

package/src/builtins/@mdTree.js

@@ -0,0 +1,69 @@
+import { toString } from "../common/utilities.js";
+
+/**
+ * Returns the tree structure of a markdown document.
+ *
+ * @typedef {import("@weborigami/async-tree").StringLike} StringLike
+ * @typedef {import("@weborigami/async-tree").Unpackable<StringLike>}
+ * UnpackableStringlike
+ *
+ * @this {import("@weborigami/types").AsyncTree|null|void}
+ * @param {StringLike|UnpackableStringlike} input
+ */
+export default function mdStructure(input) {
+  const markdown = toString(input);
+  if (markdown === null) {
+    throw new Error("No markdown text provided.");
+  }
+
+  // The document acts as an entry for heading level zero. All level one
+  // headings will end up as its children.
+  const document = {};
+  const activeHeadings = [document];
+
+  // Split the text by lines that contain markdown headings.
+  const lines = markdown.split("\n");
+  lines.forEach((line) => {
+    const match = line.match(/^(?<levelMarkers>#{1,6})\s(?<heading>.*)$/);
+    if (!match?.groups) {
+      return;
+    }
+    const { levelMarkers, heading } = match.groups;
+    const level = levelMarkers.length;
+
+    // If we've gone up a level (or more), pop completed entries off the stack.
+    while (activeHeadings.length > level) {
+      activeHeadings.pop();
+    }
+
+    // If we've skipped a level (or more), add intermediate entries using
+    // symbols to avoid name collisions.
+    while (activeHeadings.length < level) {
+      const entry = {};
+      const parentEntry = activeHeadings[activeHeadings.length - 1];
+      parentEntry[Symbol()] = entry;
+      activeHeadings.push(entry);
+    }
+
+    // Add a new entry to the list of children under construction.
+    const entry = {};
+    const parentEntry = activeHeadings[activeHeadings.length - 1];
+    parentEntry[heading] = entry;
+    activeHeadings.push(entry);
+  });
+
+  return pruneEmptyObjects(document) ?? {};
+}
+
+// Replace empty objects in the tree with nulls.
+function pruneEmptyObjects(tree) {
+  const keys = [...Object.keys(tree), ...Object.getOwnPropertySymbols(tree)];
+  if (keys.length === 0) {
+    return null;
+  }
+  const result = {};
+  for (const key of keys) {
+    result[key] = pruneEmptyObjects(tree[key]);
+  }
+  return result;
+}

package/src/builtins/@naturalOrder.js

@@ -0,0 +1 @@
+export { naturalOrder as default } from "@weborigami/async-tree";

package/src/builtins/@ori.js

@@ -62,7 +62,7 @@ async function formatResult(result) {
   } else if (
     !(result instanceof Array) &&
     (typeof result !== "object" ||
-      result.toString !== getRealmObjectPrototype(result).toString)
+      result.toString !== getRealmObjectPrototype(result)?.toString)
   ) {
     text = result.toString();
   } else if (typeof result === "object") {