@weborigami/origami 0.0.35

package/src/builtins/@map.js

@@ -0,0 +1,182 @@
+import {
+  cachedKeyMaps,
+  keyMapsForExtensions,
+  map,
+  Tree,
+} from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import addValueKeyToScope from "../common/addValueKeyToScope.js";
+import { toFunction } from "../common/utilities.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/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, extensions?: string,
+ * inverseKeyMap?: KeyFn, keyMap?: ValueKeyFn, keyName?: string, valueMap?:
+ * ValueKeyFn, valueName?: string }} 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 valueMap/options are the first parameter
+  // or the second.
+  let source;
+  let options;
+  if (param2 === undefined) {
+    options = param1;
+  } else {
+    source = param1;
+    options = param2;
+  }
+
+  // Identify whether the valueMap/options is a valueMap function
+  // or an options dictionary.
+  let valueMap;
+  if (
+    typeof options === "function" ||
+    typeof (/** @type {any} */ (options)?.unpack) === "function"
+  ) {
+    valueMap = options;
+    options = {};
+  } else {
+    valueMap = options.valueMap;
+  }
+
+  let {
+    deep,
+    description,
+    extensions,
+    inverseKeyMap,
+    keyMap,
+    keyName,
+    valueName,
+  } = options;
+
+  description ??= `@map ${extensions ?? ""}`;
+
+  if (extensions && (keyMap || inverseKeyMap)) {
+    throw new TypeError(
+      `@map: You can't specify both extensions and a keyMap or inverseKeyMap`
+    );
+  }
+
+  const baseScope = Scope.getScope(this);
+
+  // Extend the value function to include the value and key in scope.
+  let extendedValueFn;
+  if (valueMap) {
+    const resolvedValueFn = toFunction(valueMap);
+    extendedValueFn = function (sourceValue, sourceKey, tree) {
+      const scope = addValueKeyToScope(
+        baseScope,
+        sourceValue,
+        sourceKey,
+        valueName,
+        keyName
+      );
+      return resolvedValueFn.call(scope, sourceValue, sourceKey, tree);
+    };
+  }
+
+  // Extend the key function to include the value and key in scope.
+  let extendedKeyMap;
+  let extendedInnerKeyMap;
+  if (extensions) {
+    let { resultExtension, sourceExtension } = parseExtensions(extensions);
+    const keyFns = keyMapsForExtensions({
+      resultExtension,
+      sourceExtension,
+    });
+    extendedKeyMap = keyFns.keyMap;
+    extendedInnerKeyMap = keyFns.inverseKeyMap;
+  } else if (keyMap) {
+    const resolvedKeyFn = toFunction(keyMap);
+    async function scopedKeyFn(sourceKey, tree) {
+      const sourceValue = await tree.get(sourceKey);
+      const scope = addValueKeyToScope(
+        baseScope,
+        sourceValue,
+        sourceKey,
+        valueName,
+        keyName
+      );
+      const resultKey = await resolvedKeyFn.call(
+        scope,
+        sourceValue,
+        sourceKey,
+        tree
+      );
+      return resultKey;
+    }
+    const keyFns = cachedKeyMaps(scopedKeyFn);
+    extendedKeyMap = keyFns.keyMap;
+    extendedInnerKeyMap = keyFns.inverseKeyMap;
+  }
+
+  const transform = function mapTreelike(treelike) {
+    const tree = Tree.from(treelike);
+    return map({
+      deep,
+      description,
+      inverseKeyMap: extendedInnerKeyMap,
+      keyMap: extendedKeyMap,
+      valueMap: extendedValueFn,
+    })(tree);
+  };
+
+  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
+ *
+ * @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/@match.js

@@ -0,0 +1,92 @@
+import { Tree } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+
+/**
+ * Return a tree with the indicated keys (if provided).
+ *
+ * The pattern can a string with a simplified pattern syntax that tries to match
+ * against the entire key and uses brackets to identify named wildcard values.
+ * E.g. `[name].html` will match `Alice.html` with wildcard values { name:
+ * "Alice" }.
+ *
+ * The pattern can also be a JavaScript regular expression.
+ *
+ * If a key is requested, match against the given pattern and, if matches,
+ * incorporate the matched pattern's wildcard values into the scope and invoke
+ * the indicated function to produce a result.
+ *
+ * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("../../index.ts").Invocable} Invocable
+ *
+ * @param {string|RegExp} pattern
+ * @param {Invocable} resultFn
+ * @param {Treelike} [keys]
+ * @this {AsyncTree|null}
+ */
+export default function match(pattern, resultFn, keys = []) {
+  assertScopeIsDefined(this);
+  let regex;
+  if (typeof pattern === "string") {
+    // Convert the simple pattern format into a regular expression.
+    const regexText = pattern.replace(
+      /\[(?<variable>.+)\]/g,
+      (match, p1, offset, string, groups) => `(?<${groups.variable}>.+)`
+    );
+    regex = new RegExp(`^${regexText}$`);
+  } else if (pattern instanceof RegExp) {
+    regex = pattern;
+  } else {
+    throw new Error(`match(): Unsupported pattern`);
+  }
+
+  // Remember the scope used to invoke this function so we can extend it below.
+  const scope = this;
+
+  /** @type {AsyncTree} */
+  let result = {
+    async get(key) {
+      const keyMatch = regex.exec(key);
+      if (!keyMatch) {
+        return undefined;
+      }
+
+      if (
+        typeof resultFn !== "function" &&
+        !(Tree.isAsyncTree(resultFn) && "parent" in resultFn)
+      ) {
+        // Simple return value; return as is
+        return resultFn;
+      }
+
+      // If the pattern contained named wildcards, extend the scope. It appears
+      // that the `groups` property of a match is *not* a real plain object, so
+      // we have to make one.
+      const bindings = keyMatch.groups
+        ? Object.fromEntries(Object.entries(keyMatch.groups))
+        : null;
+      const fnScope = bindings ? new Scope(bindings, scope) : scope;
+
+      // Invoke the result function with the extended scope.
+      let value;
+      if (typeof resultFn === "function") {
+        value = await resultFn.call(fnScope);
+      } else {
+        value = Object.create(resultFn);
+      }
+
+      return value;
+    },
+
+    async keys() {
+      return typeof keys === "function" ? await keys.call(scope) : keys;
+    },
+  };
+
+  result = Scope.treeWithScope(result, this);
+  return result;
+}
+
+match.usage = `@match <pattern>, <fn>, [<keys>]\tMatches simple patterns or regular expressions`;
+match.documentation = "https://graphorigami.org/language/@match.html";

package/src/builtins/@mdHtml.js

@@ -0,0 +1,45 @@
+import highlight from "highlight.js";
+import { marked } from "marked";
+import { gfmHeadingId as markedGfmHeadingId } from "marked-gfm-heading-id";
+import { markedHighlight } from "marked-highlight";
+import { markedSmartypants } from "marked-smartypants";
+
+marked.use(
+  markedGfmHeadingId(),
+  markedHighlight({
+    highlight(code, lang) {
+      const language = highlight.getLanguage(lang) ? lang : "plaintext";
+      return highlight.highlight(code, { language }).value;
+    },
+
+    langPrefix: "hljs language-",
+  }),
+  markedSmartypants(),
+  {
+    gfm: true, // Use GitHub-flavored markdown.
+    // @ts-ignore
+    mangle: false,
+  }
+);
+
+/**
+ * @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 async function mdHtml(input) {
+  if (/** @type {any} */ (input).unpack) {
+    input = await /** @type {any} */ (input).unpack();
+  }
+  const inputDocument = input["@text"] ? input : null;
+  const markdown = inputDocument?.["@text"] ?? String(input);
+  const html = marked(markdown);
+  return inputDocument
+    ? Object.assign({}, inputDocument, { "@text": html })
+    : html;
+}
+
+mdHtml.usage = `@mdHtml <markdown>\tRender the markdown text as HTML`;
+mdHtml.documentation = "https://graphorigami.org/language/@mdHtml.html";

package/src/builtins/@new.js

@@ -0,0 +1,6 @@
+export default function newBuiltin(constructor, ...args) {
+  return Reflect.construct(constructor, args);
+}
+
+newBuiltin.usage = "@new <classFn>\tCreate a new instance of the given class";
+newBuiltin.documentation = "https://graphorigami.org/language/@new.html";

package/src/builtins/@node.js

@@ -0,0 +1,15 @@
+import path from "node:path";
+import process from "node:process";
+import url from "node:url";
+
+const node = {
+  Buffer,
+  path,
+  process,
+  url,
+};
+
+node.usage = "@node\tAccess Node classes and utility functions";
+node.documentation = "https://graphorigami.org/language/@node.html";
+
+export default node;

package/src/builtins/@not.js

@@ -0,0 +1,6 @@
+export default function not(value) {
+  return !value;
+}
+
+not.usage = `@not <value>\tThe logical inverse of the value`;
+not.documentation = "https://graphorigami.org/language/@not.html";

package/src/builtins/@or.js

@@ -0,0 +1,6 @@
+export default function or(...args) {
+  return args.find((arg) => arg);
+}
+
+or.usage = `@or ...values\tReturns the first truthy value`;
+or.documentation = "https://graphorigami.org/language/@or.html";

package/src/builtins/@ori.js

@@ -0,0 +1,83 @@
+import { Tree, getRealmObjectPrototype } from "@weborigami/async-tree";
+import * as compile from "../../../language/src/compiler/compile.js";
+import builtins from "../builtins/@builtins.js";
+import { toYaml } from "../common/serialize.js";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+
+const TypedArray = Object.getPrototypeOf(Uint8Array);
+
+/**
+ * Parse an Origami expression, evaluate it in the context of a tree (provided
+ * by `this`), and return the result as text.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @this {AsyncTree|null}
+ * @param {string} expression
+ */
+export default async function ori(expression) {
+  assertScopeIsDefined(this);
+  // In case expression is a Buffer, cast it to a string.
+  expression = String(expression);
+
+  // Obtain the scope from `this` or builtins.
+  let scope = this ?? builtins;
+
+  // Parse
+  const fn = compile.expression(expression);
+
+  // Execute
+  let result = await fn.call(scope);
+
+  // If result was a function, execute it.
+  if (typeof result === "function") {
+    result = await result.call(scope);
+  }
+
+  const formatted = await formatResult(result);
+  return formatted;
+}
+
+async function formatResult(result) {
+  if (typeof result === "string" || result instanceof TypedArray) {
+    // Use as is
+    return result;
+  }
+
+  /** @type {string|String|undefined} */
+  let text;
+
+  // Does the result have a meaningful toString() method (and not the dumb
+  // Object.toString)? Exception: if the result is an array, we'll use YAML
+  // instead.
+  if (!result) {
+    // Return falsy values as is.
+    text = result;
+  } else if (
+    !(result instanceof Array) &&
+    (typeof result !== "object" ||
+      result.toString !== getRealmObjectPrototype(result).toString)
+  ) {
+    text = result.toString();
+  } else if (typeof result === "object") {
+    // Render YAML
+    text = await toYaml(result);
+  } else {
+    // Use result itself.
+    text = result;
+  }
+
+  // If the result is a tree, attach the tree to the text output.
+  if (Tree.isTreelike(result)) {
+    if (typeof text === "string") {
+      // @ts-ignore
+      text = new String(text);
+    }
+    /** @type {any} */ (text).unpack = () => Tree.from(result);
+  }
+
+  return text;
+}
+
+ori.usage = `@ori <text>\tEvaluates the text as an Origami expression`;
+ori.documentation = "https://graphorigami.org/language/@ori.html";

package/src/builtins/@pack.js

@@ -0,0 +1,13 @@
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+
+/**
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @this {AsyncTree|null}
+ * @param {any} obj
+ * @returns
+ */
+export default function pack(obj) {
+  assertScopeIsDefined(this);
+  return obj?.pack?.();
+}

package/src/builtins/@parse/json.js

@@ -0,0 +1,7 @@
+export default async function parseJson(text) {
+  return text ? JSON.parse(text) : undefined;
+}
+
+parseJson.usage = `parseJson <text>\tParse text as JSON`;
+parseJson.documentation =
+  "https://graphorigami.org/cli/builtins.html#parseJson";

package/src/builtins/@parse/yaml.js

@@ -0,0 +1,9 @@
+import * as serialize from "../../common/serialize.js";
+
+export default async function parseYaml(text) {
+  return text ? serialize.parseYaml(String(text)) : undefined;
+}
+
+parseYaml.usage = `parseYaml <text>\tParse text as YAML (including JSON)`;
+parseYaml.documentation =
+  "https://graphorigami.org/cli/builtins.html#parseYaml";

package/src/builtins/@project.js

@@ -0,0 +1,71 @@
+/** @typedef {import("@weborigami/types").AsyncTree} AsyncTree */
+import { OrigamiFiles, Scope } from "@weborigami/language";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+import builtins from "./@builtins.js";
+
+const configFileName = "ori.config.js";
+
+/**
+ * Return the tree for the current project's root folder.
+ *
+ * This searches the current directory and its ancestors for an Origami
+ * configuration file. If an Origami configuration file is found, the containing
+ * folder is considered to be the project root. This returns a tree for that
+ * folder, with the exported configuration as the context for that folder — that
+ * is, the tree exported by the configuration will be the scope.
+ *
+ * If no Origami configuration file is found, the current folder will be
+ * returned as a tree, with the builtins as its parent.
+ *
+ * @this {AsyncTree|null}
+ * @param {any} [key]
+ */
+export default async function project(key) {
+  assertScopeIsDefined(this);
+
+  const dirname = process.cwd();
+  const currentTree = new OrigamiFiles(dirname);
+  let projectTree = await findConfigContainer(currentTree);
+
+  let config;
+  if (projectTree) {
+    // Load the configuration.
+    config = await projectTree.import(configFileName);
+    if (!config) {
+      throw new Error(
+        `Couldn't load the Origami configuration in ${projectTree.path}`
+      );
+    }
+  } else {
+    projectTree = currentTree;
+    config = builtins;
+  }
+
+  // Add the configuration as the context for the project root.
+  const result = Scope.treeWithScope(projectTree, config);
+  return key === undefined ? result : result.get(key);
+}
+
+async function findConfigContainer(start) {
+  let current = start;
+  while (current) {
+    const config = await current.get(configFileName);
+    if (config) {
+      // Found a configuration; its container is the project root.
+      return current;
+    }
+    // Not found; try the parent.
+    const parent = await current.get("..");
+    if (
+      !parent ||
+      (parent.path && current.path && parent.path === current.path)
+    ) {
+      break;
+    }
+    current = parent;
+  }
+  return undefined;
+}
+
+project.usage = `@project\tThe root of the current Tree Origami project`;
+project.documentation = "https://graphorigami.org/language/@project.html";

package/src/builtins/@repeat.js

@@ -0,0 +1,8 @@
+export default async function repeat(count, content) {
+  const array = new Array(count);
+  array.fill(content);
+  return array;
+}
+
+repeat.usage = `@repeat <count>, <content>\tRepeats the content the given number of times`;
+repeat.documentation = "https://graphorigami.org/language/@repeat.html";

package/src/builtins/@rss.js

@@ -0,0 +1,49 @@
+import { Tree } from "@weborigami/async-tree";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+
+/**
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @this {AsyncTree|null}
+ * @param {Treelike} jsonFeedTree
+ */
+export default async function rss(jsonFeedTree) {
+  assertScopeIsDefined(this);
+  const jsonFeed = await Tree.plain(jsonFeedTree);
+  const { description, home_page_url, items, feed_url, title } = jsonFeed;
+
+  // Presume that the RSS feed lives in same location as feed_url.
+  const parts = feed_url.split("/");
+  parts.pop();
+  parts.push("rss.xml");
+  const rssUrl = parts.join("/");
+
+  const itemsRss = items?.map((story) => itemRss(story)).join("\n") ?? [];
+
+  return `<?xml version="1.0" ?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+  <channel>
+    <atom:link href="${rssUrl}" rel="self" type="application/rss+xml"/>
+    <title>${title}</title>
+    <link>${home_page_url}</link>
+    <description>${description}</description>
+  ${itemsRss}</channel>
+</rss>`;
+}
+
+function itemRss(jsonFeedItem) {
+  const { content_html, date_published, id, title, url } = jsonFeedItem;
+  // RSS wants dates in RFC-822.
+  const date = date_published?.toUTCString() ?? null;
+  const dateElement = date ? `      <pubDate>${date}</pubDate>\n` : "";
+  return `    <item>
+      ${dateElement}<title>${title}</title>
+      <link>${url}</link>
+      <guid>${id}</guid>
+      <description><![CDATA[${content_html}]]></description>
+    </item>
+`;
+}
+
+rss.usage = `@rss <feed>\tTransforms a JSON Feed tree to RSS XML`;
+rss.documentation = "https://graphorigami.org/language/@rss.html";

package/src/builtins/@scope/extend.js

@@ -0,0 +1,22 @@
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+import setScope from "./set.js";
+
+/**
+ * Return a copy of the given tree whose scope includes the given trees *and*
+ * the current scope.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @this {AsyncTree|null}
+ * @param {Treelike} treelike
+ * @param  {...Treelike} scopeTrees
+ * @this {AsyncTree|null}
+ */
+export default function extendScope(treelike, ...scopeTrees) {
+  assertScopeIsDefined(this);
+  const scope = this;
+  return setScope.call(scope, treelike, ...scopeTrees, scope);
+}
+
+extendScope.usage = `@scope/extend <tree>, <...trees>\tExtends tree's scope with the given trees`;
+extendScope.documentation = "https://graphorigami.org/cli/builtins.html#@scope";

package/src/builtins/@scope/get.js

@@ -0,0 +1,25 @@
+import { Tree } from "@weborigami/async-tree";
+import { Scope } from "@weborigami/language";
+import assertScopeIsDefined from "../../misc/assertScopeIsDefined.js";
+
+/**
+ * Returns the scope of the indicated tree or the current scope.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @this {AsyncTree|null}
+ * @param {any} [obj]
+ */
+export default async function getScope(obj) {
+  assertScopeIsDefined(this);
+  if (obj) {
+    /** @type {any}  */
+    const tree = Tree.from(obj);
+    return Scope.getScope(tree);
+  } else {
+    return this;
+  }
+}
+
+getScope.usage = `@scope/get [<tree>]\tReturns the scope of the tree or the current scope`;
+getScope.documentation = "https://graphorigami.org/cli/builtins.html#@scope";

package/src/builtins/@scope/invoke.js

@@ -0,0 +1,22 @@
+import { Scope } from "@weborigami/language";
+import { toFunction } from "../../common/utilities.js";
+
+/**
+ * Invokes the given function in the context of the current scope.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("../../../index.ts").Invocable} Invocable
+ *
+ * @this {AsyncTree|null}
+ * @param {AsyncTree} context
+ * @param {Invocable} invocable
+ */
+export default async function invoke(context, invocable, ...args) {
+  const scope = Scope.getScope(context);
+  const fn = toFunction(invocable);
+  const result = await fn.call(scope, ...args);
+  return result;
+}
+
+invoke.usage = `@scope/invoke fn, <...args>\tInvoke the function in the current scope`;
+invoke.documentation = "https://graphorigami.org/cli/builtins.html#@scope";