@weborigami/origami 0.0.35

package/src/builtins/@files.js

@@ -0,0 +1,22 @@
+import { OrigamiFiles, Scope } from "@weborigami/language";
+import path from "node:path";
+import process from "node:process";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+
+/**
+ * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @this {AsyncTree|null}
+ * @param {string[]} keys
+ */
+export default async function files(...keys) {
+  assertScopeIsDefined(this);
+  const resolved = path.resolve(process.cwd(), ...keys);
+  /** @type {AsyncTree} */
+  let result = new OrigamiFiles(resolved);
+  result = Scope.treeWithScope(result, this);
+  return result;
+}
+
+files.usage = `@files [path]\tTree of files at the given path`;
+files.documentation = "https://graphorigami.org/language/@files.html";

package/src/builtins/@filter.js

@@ -0,0 +1,23 @@
+import { Scope } from "@weborigami/language";
+import FilterTree from "../common/FilterTree.js";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+
+/**
+ * Apply a filter to a tree.
+ *
+ * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @this {AsyncTree|null}
+ * @param {Treelike} treelike
+ * @param {Treelike} filterVariant
+ */
+export default async function filter(treelike, filterVariant) {
+  assertScopeIsDefined(this);
+  /** @type {AsyncTree} */
+  let result = new FilterTree(treelike, filterVariant);
+  result = Scope.treeWithScope(result, this);
+  return result;
+}
+
+filter.usage = `@filter <tree>, <filter>\tOnly returns values whose keys match the filter`;
+filter.documentation = "https://graphorigami.org/language/@filter.html";

package/src/builtins/@globs.js

@@ -0,0 +1,23 @@
+import { Scope } from "@weborigami/language";
+import GlobTree from "../common/GlobTree.js";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+
+/**
+ * Define a tree whose keys are globs.
+ *
+ * @typedef  {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ *
+ * @param {Treelike} tree
+ * @this {AsyncTree|null}
+ */
+export default async function globs(tree) {
+  assertScopeIsDefined(this);
+  /** @type {AsyncTree} */
+  let result = new GlobTree(tree);
+  result = Scope.treeWithScope(result, this);
+  return result;
+}
+
+globs.usage = `@globs <patterns>\tDefine a tree whose keys can include wildcard globs`;
+globs.documentation = "https://graphorigami.org/language/@globs.html";

package/src/builtins/@help.js

@@ -0,0 +1,49 @@
+/** @typedef {import("@weborigami/types").AsyncTree} AsyncTree */
+import child_process from "node:child_process";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+
+const groupUrls = {
+  "@cache": "https://graphorigami.org/language/@cache.html",
+  "@tree": "https://graphorigami.org/language/@tree.html",
+  "@image": "https://graphorigami.org/language/@image.html",
+  "@parse": "https://graphorigami.org/language/@parse.html",
+  "@scope": "https://graphorigami.org/language/@scope.html",
+};
+
+/**
+ * @this {AsyncTree|null}
+ * @param {string} [name]
+ */
+export default async function help(name) {
+  assertScopeIsDefined(this);
+  let url;
+  const scope = this;
+  if (scope && name) {
+    if (groupUrls[name]) {
+      url = groupUrls[name];
+    } else {
+      const fn = await scope.get(name);
+      url = fn?.documentation;
+    }
+    if (!url) {
+      console.error(
+        `help: ${name} does not have a property called "documentation" linking to its documentation`
+      );
+      return;
+    }
+  } else {
+    url = "https://graphorigami.org/cli/";
+  }
+  const platform = process.platform;
+  const start =
+    platform === "darwin"
+      ? "open"
+      : platform === "win32"
+      ? "start"
+      : "xdg-open";
+  const command = `${start} ${url}`;
+  child_process.exec(command);
+}
+
+help.usage = `@help/<name>\tOpens documentation for the named built-in command`;
+help.documentation = "https://graphorigami.org/language/@help.html";

package/src/builtins/@http.js

@@ -0,0 +1,19 @@
+import { ops } from "@weborigami/language";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+
+/**
+ * Retrieve the indicated web resource via HTTP.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @this {AsyncTree|null}
+ * @param {string} host
+ * @param  {...string} keys
+ */
+export default async function http(host, ...keys) {
+  assertScopeIsDefined(this);
+  return ops.http.call(this, host, ...keys);
+}
+
+http.usage = `@http <host>, <...keys>\tA web resource via HTTP`;
+http.documentation = "https://graphorigami.org/language/@http.html";

package/src/builtins/@https.js

@@ -0,0 +1,19 @@
+import { ops } from "@weborigami/language";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+
+/**
+ * Retrieve the indicated web resource via HTTPS.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ *
+ * @this {AsyncTree|null}
+ * @param {string} host
+ * @param  {...string} keys
+ */
+export default async function https(host, ...keys) {
+  assertScopeIsDefined(this);
+  return ops.https.call(this, host, ...keys);
+}
+
+https.usage = `@https <host>, <...keys>\tA web resource via HTTPS`;
+https.documentation = "https://graphorigami.org/language/@https.html";

package/src/builtins/@if.js

@@ -0,0 +1,27 @@
+/** @typedef {import("@weborigami/types").AsyncTree} AsyncTree */
+import { Tree } from "@weborigami/async-tree";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+
+/**
+ * @this {AsyncTree|null}
+ * @param {any} value
+ * @param {any} trueResult
+ * @param {any} [falseResult]
+ */
+export default async function ifCommand(value, trueResult, falseResult) {
+  assertScopeIsDefined(this);
+  let condition = await value;
+  if (Tree.isAsyncTree(condition)) {
+    const keys = Array.from(await condition.keys());
+    condition = keys.length > 0;
+  }
+
+  let result = condition ? trueResult : falseResult;
+  if (typeof result === "function") {
+    result = await result.call(this);
+  }
+  return result;
+}
+
+ifCommand.usage = `@if <value>, <true>, [<false>]\tThe true or false result based on the value`;
+ifCommand.documentation = "https://graphorigami.org/language/@if.html";

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

@@ -0,0 +1,5 @@
+import sharp from "sharp";
+
+export default function format(buffer, format, options) {
+  return sharp(buffer).toFormat(format, options).toBuffer();
+}

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

@@ -0,0 +1,5 @@
+import sharp from "sharp";
+
+export default function resize(buffer, options) {
+  return sharp(buffer).resize(options).toBuffer();
+}

package/src/builtins/@index.js

@@ -0,0 +1,72 @@
+import { Tree } from "@weborigami/async-tree";
+import { keySymbol } from "../common/utilities.js";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+
+/**
+ * Return a default index.html page for the current tree.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @this {AsyncTree|null}
+ * @param {Treelike} [treelike]
+ */
+export default async function index(treelike) {
+  assertScopeIsDefined(this);
+  treelike = treelike ?? (await this?.get("@current"));
+  if (treelike === undefined) {
+    return undefined;
+  }
+  const tree = Tree.from(treelike);
+  const keys = Array.from(await tree.keys());
+
+  // Skip system-ish files that start with a period. Also skip `index.html`.
+  const filtered = keys.filter(
+    (key) => !(key.startsWith?.(".") || key === "index.html")
+  );
+
+  const links = [];
+  for (const key of filtered) {
+    const keyText = String(key);
+    // Simple key.
+    const link = `<li><a href="${keyText}">${keyText}</a></li>`;
+    links.push(link);
+  }
+
+  const heading = tree[keySymbol] ?? "Index";
+  const list = `
+    <h1>${heading.trim()}</h1>
+    <ul>\n${links.join("\n").trim()}\n</ul>
+  `;
+
+  const html = `
+    <!DOCTYPE html>
+    <html lang="en">
+      <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width,initial-scale=1" />
+        <style>
+          li {
+            margin-bottom: 0.20em;
+          }
+
+          a {
+            text-decoration: none;
+          }
+          a:hover {
+            text-decoration: revert;
+          }
+        </style>
+      </head>
+      <body>
+        ${list.trim()}
+      </body>
+    </html>`;
+
+  /** @type {any} */
+  const result = new String(html.trim());
+  result.unpack = () => tree;
+  return result;
+}
+
+index.usage = `@index\tReturn a default index.html page for the current tree`;
+index.documentation = "https://graphorigami.org/language/@index.html";

package/src/builtins/@inherited.js

@@ -0,0 +1,17 @@
+/** @typedef {import("@weborigami/types").AsyncTree} AsyncTree */
+import { ops } from "@weborigami/language";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+
+/**
+ * Return the inherited value (if any) for the indicated key.
+ *
+ * @param {any} key
+ * @this {AsyncTree|null}
+ */
+export default async function inherited(key) {
+  assertScopeIsDefined(this);
+  return ops.inherited.call(this, key);
+}
+
+inherited.usage = `@inherited <key>\tThe value of the key in the tree's inherited scope`;
+inherited.documentation = "https://graphorigami.org/language/@inherited.html";

package/src/builtins/@inline.js

@@ -0,0 +1,29 @@
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+import unpackOrigamiTemplate from "./@loaders/orit.js";
+
+/**
+ * Inline any Origami expressions found inside {{...}} placeholders in the input
+ * text.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").StringLike} StringLike
+ *
+ * @this {AsyncTree|null}
+ * @param {StringLike} input
+ */
+export default async function inline(input) {
+  assertScopeIsDefined(this);
+  if (/** @type {any} */ (input).unpack) {
+    input = await /** @type {any} */ (input).unpack();
+  }
+  const inputDocument = input["@text"] ? input : null;
+  const templateInput = inputDocument ?? input;
+  const templateFn = await unpackOrigamiTemplate(templateInput);
+  const text = await templateFn(inputDocument);
+  return inputDocument
+    ? Object.assign({}, inputDocument, { "@text": String(text) })
+    : text;
+}
+
+inline.usage = `@inline <text>\tInline Origami expressions found in the text`;
+inline.documentation = "https://graphorigami.org/language/@inline.html";

package/src/builtins/@invoke.js

@@ -0,0 +1,30 @@
+import builtins from "./@builtins.js";
+
+/**
+ * Invoke the given 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.
+ *
+ * You can execute a foo.ori file as a script by adding the following shebang
+ * directive to the top of the file:
+ *
+ * ```sh
+ * #!/usr/bin/env ori @invoke
+ * ```
+ *
+ * Then mark the file as executable:
+ *
+ * ```sh
+ * chmod +x foo.ori
+ * ```
+ *
+ * @this {import("@weborigami/types").AsyncTree|null}
+ */
+export default async function invoke(fn) {
+  if (typeof fn !== "function" && fn.unpack) {
+    fn = await fn.unpack();
+  }
+  const scope = (await this?.get("@current")) ?? builtins;
+  return typeof fn === "function" ? fn.call(scope) : fn;
+}

package/src/builtins/@js.js

@@ -0,0 +1,33 @@
+const js = {
+  Array,
+  Boolean,
+  Date,
+  Error,
+  Infinity,
+  Intl,
+  JSON,
+  Math,
+  NaN,
+  Number,
+  Object,
+  RegExp,
+  String,
+  Symbol,
+  decodeURI,
+  decodeURIComponent,
+  encodeURI,
+  encodeURIComponent,
+  false: false,
+  isFinite,
+  isNaN,
+  null: null,
+  parseFloat,
+  parseInt,
+  true: true,
+  undefined: undefined,
+};
+
+js.usage = "@js\tAccess JavaScript classes and utility functions";
+js.documentation = "https://graphorigami.org/language/@js.html";
+
+export default js;

package/src/builtins/@json.js

@@ -0,0 +1,22 @@
+/** @typedef {import("@weborigami/types").AsyncTree} AsyncTree */
+import * as serialize from "../common/serialize.js";
+import assertScopeIsDefined from "../misc/assertScopeIsDefined.js";
+
+/**
+ * Render the given object in JSON format.
+ *
+ * @this {AsyncTree|null}
+ * @param {any} [obj]
+ */
+export default async function json(obj) {
+  assertScopeIsDefined(this);
+  obj = obj ?? (await this?.get("@current"));
+  if (obj === undefined) {
+    return undefined;
+  }
+  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://graphorigami.org/language/@json.html";

package/src/builtins/@loaders/css.js

@@ -0,0 +1,4 @@
+import unpackText from "./txt.js";
+
+// Load this file type as text with possible front matter.
+export default unpackText;

package/src/builtins/@loaders/htm.js

@@ -0,0 +1,4 @@
+import unpackText from "./txt.js";
+
+// Load this file type as text with possible front matter.
+export default unpackText;

package/src/builtins/@loaders/html.js

@@ -0,0 +1,4 @@
+import unpackText from "./txt.js";
+
+// Load this file type as text with possible front matter.
+export default unpackText;

package/src/builtins/@loaders/js.js

@@ -0,0 +1,14 @@
+import processUnpackedContent from "../../common/processUnpackedContent.js";
+
+/**
+ * Load a .js file as module's default export or exports.
+ *
+ * @type {import("@weborigami/language").FileUnpackFunction}
+ */
+export default async function unpackModule(input, options = {}) {
+  const { key, parent } = options;
+  if (parent && "import" in parent) {
+    const content = await /** @type {any} */ (parent).import?.(key);
+    return processUnpackedContent(content, parent);
+  }
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Load a file as JSON.
+ *
+ * @type {import("@weborigami/language").FileUnpackFunction}
+ */
+export default function unpackJson(input) {
+  return JSON.parse(String(input));
+}

package/src/builtins/@loaders/md.js

@@ -0,0 +1,4 @@
+import unpackText from "./txt.js";
+
+// Load this file type as text with possible front matter.
+export default unpackText;

package/src/builtins/@loaders/mjs.js

@@ -0,0 +1,4 @@
+import unpackModule from "./js.js";
+
+// .mjs modules use the same loader as .js modules.
+export default unpackModule;

package/src/builtins/@loaders/ori.js

@@ -0,0 +1,21 @@
+import { Scope } from "@weborigami/language";
+import * as compile from "../../../../language/src/compiler/compile.js";
+import processUnpackedContent from "../../common/processUnpackedContent.js";
+import builtins from "../@builtins.js";
+
+/**
+ * Load and evaluate an Origami expression from a file.
+ *
+ * @type {import("@weborigami/language").FileUnpackFunction}
+ */
+export default async function unpackOrigamiExpression(input, options = {}) {
+  const parent = options.parent ?? null;
+
+  // Compile the body text as an Origami expression and evaluate it.
+  const text = String(input);
+  const fn = compile.expression(text);
+  const parentScope = parent ? Scope.getScope(parent) : builtins;
+  let content = await fn.call(parentScope);
+
+  return processUnpackedContent(content, parent);
+}

package/src/builtins/@loaders/orit.js

@@ -0,0 +1,48 @@
+import { Scope } from "@weborigami/language";
+import * as compile from "../../../../language/src/compiler/compile.js";
+import processUnpackedContent from "../../common/processUnpackedContent.js";
+import * as utilities from "../../common/utilities.js";
+import builtins from "../@builtins.js";
+import unpackText from "./txt.js";
+
+/**
+ * Load and evaluate an Origami template from a file.
+ *
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @type {import("@weborigami/language").FileUnpackFunction}
+ */
+export default async function unpackOrigamiTemplate(input, options = {}) {
+  const parent =
+    options.parent ??
+    /** @type {any} */ (input).parent ??
+    /** @type {any} */ (input)[utilities.parentSymbol];
+
+  // Get the input text and any attached front matter.
+  let inputDocument;
+  if (input["@text"]) {
+    inputDocument = input;
+  } else {
+    // Unpack the input as a text document with possible front matter.
+    inputDocument = await unpackText(input, options);
+  }
+  const text = utilities.toString(inputDocument);
+
+  // Compile the body text as an Origami expression and evaluate it.
+  const expression = compile.templateDocument(text);
+  const parentScope = parent ? Scope.getScope(parent) : builtins;
+  const lambda = await expression.call(parentScope);
+
+  // Wrap the lambda with a function that will attach the input data to the
+  // result.
+  /** @this {AsyncTree|null} */
+  const fn = async function createTemplateResult(templateInput) {
+    const text = await lambda.call(this, templateInput);
+    /** @type {any} */
+    const result = new String(text);
+    result.unpack = () => templateInput;
+    return result;
+  };
+  fn.code = lambda.code;
+
+  return processUnpackedContent(fn, parent, inputDocument);
+}

package/src/builtins/@loaders/txt.js

@@ -0,0 +1,33 @@
+import TextDocument from "../../common/TextDocument.js";
+import { evaluateYaml } from "../../common/serialize.js";
+
+/**
+ * Load a file as text document with possible front matter.
+ *
+ * This process will parse out any YAML or JSON front matter and attach it to
+ * the document as data. The first line of the text must be "---", followed by a
+ * block of JSON or YAML, followed by another line of "---". Any lines following
+ * will be treated as the document text.
+ *
+ * Any Origami expressions in the front matter will be evaluated and the results
+ * incorporated into the document data.
+ *
+ * @type {import("@weborigami/language").FileUnpackFunction}
+ */
+export default async function unpackText(input, options = {}) {
+  const parent = options.parent ?? null;
+  const text = String(input);
+  const regex =
+    /^(---\r?\n(?<frontText>[\s\S]*?\r?\n)---\r?\n)(?<body>[\s\S]*$)/;
+  const match = regex.exec(text);
+
+  const body = match?.groups?.body ?? text;
+
+  const frontData = match?.groups
+    ? await evaluateYaml(match.groups.frontText, parent)
+    : null;
+
+  const object = Object.assign({}, frontData, { "@text": body });
+
+  return new TextDocument(object, options.parent);
+}

package/src/builtins/@loaders/xhtml.js

@@ -0,0 +1,4 @@
+import unpackText from "./txt.js";
+
+// Load this file type as text with possible front matter.
+export default unpackText;

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

@@ -0,0 +1,18 @@
+import * as YAMLModule from "yaml";
+import processUnpackedContent from "../../common/processUnpackedContent.js";
+import { evaluateYaml } from "../../common/serialize.js";
+
+// See notes at serialize.js
+// @ts-ignore
+const YAML = YAMLModule.default ?? YAMLModule.YAML;
+
+/**
+ * Load a file as YAML.
+ *
+ * @type {import("@weborigami/language").FileUnpackFunction}
+ */
+export default async function unpackYaml(input, options = {}) {
+  const parent = options.parent ?? null;
+  const data = evaluateYaml(String(input), options.parent);
+  return processUnpackedContent(data, parent);
+}

package/src/builtins/@loaders/yml.js

@@ -0,0 +1,4 @@
+import yaml from "./yaml.js";
+
+// .yml files uses the YAML loader
+export default yaml;