@weborigami/language 0.0.35

package/src/runtime/evaluate.js

@@ -0,0 +1,90 @@
+import { Tree, isPlainObject } from "@weborigami/async-tree";
+import { format, ops } from "./internal.js";
+
+const expressionSymbol = Symbol("expression");
+
+/**
+ * Evaluate the given code and return the result.
+ *
+ * `this` should be the scope used to look up references found in the code.
+ *
+ * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("../../../language/src/compiler/code.js").Code} Code
+ *
+ * @this {Treelike|null}
+ * @param {Code} code
+ */
+export default async function evaluate(code) {
+  const scope = this;
+
+  if (code === ops.scope) {
+    // ops.scope is a placeholder for the context's scope.
+    return scope;
+  } else if (!(code instanceof Array)) {
+    // Simple scalar; return as is.
+    return code;
+  }
+
+  let evaluated;
+  const unevaluatedFns = [ops.lambda, ops.object, ops.tree];
+  if (unevaluatedFns.includes(code[0])) {
+    // Don't evaluate instructions, use as is.
+    evaluated = code;
+  } else {
+    // Evaluate each instruction in the code.
+    evaluated = await Promise.all(
+      code.map((instruction) => evaluate.call(scope, instruction))
+    );
+  }
+
+  // The head of the array is a tree or function, the rest are args or keys.
+  let [fn, ...args] = evaluated;
+
+  if (!fn) {
+    // The code wants to invoke something that's not in scope.
+    throw ReferenceError(
+      `Couldn't find function or tree key: ${format(code[0])}`
+    );
+  } else if (!(fn instanceof Object)) {
+    throw TypeError(`Can't invoke primitive value: ${format(code[0])}`);
+  } else if (!(fn instanceof Function) && typeof fn.unpack === "function") {
+    // The object has a unpack function; see if it returns a function.
+    const unpacked = await fn.unpack();
+    if (unpacked instanceof Function) {
+      fn = unpacked;
+    }
+  }
+
+  // Execute the function or traverse the tree.
+  let result;
+  try {
+    result =
+      fn instanceof Function
+        ? // Invoke the function
+          await fn.call(scope, ...args)
+        : // Traverse the tree.
+          await Tree.traverseOrThrow(fn, ...args);
+  } catch (/** @type {any} */ error) {
+    const message = `Error triggered by Origami expression: ${format(code)}`;
+    throw new Error(message, { cause: error });
+  }
+
+  // To aid debugging, add the expression source to the result.
+  if (
+    result &&
+    typeof result === "object" &&
+    Object.isExtensible(result) &&
+    !isPlainObject(result)
+  ) {
+    try {
+      result[expressionSymbol] = format(code);
+    } catch (error) {
+      // Setting a Symbol-keyed property on some objects fails with `TypeError:
+      // Cannot convert a Symbol value to a string` but it's unclear why
+      // implicit casting of the symbol to a string occurs. Since this is not a
+      // vital operation, we ignore such errors.
+    }
+  }
+
+  return result;
+}

package/src/runtime/expressionFunction.js

@@ -0,0 +1,33 @@
+/** @typedef {import("@weborigami/types").AsyncTree} AsyncTree */
+
+import { evaluate, format } from "./internal.js";
+
+/**
+ * Given parsed Origami code, return a function that executes that code.
+ *
+ * @param {string|number|Array} code - parsed Origami code
+ * @param {string} [name] - optional name of the function
+ */
+export function createExpressionFunction(code, name) {
+  /** @this {AsyncTree|null} */
+  async function fn() {
+    return evaluate.call(this, code);
+  }
+  if (name) {
+    Object.defineProperty(fn, "name", { value: name });
+  }
+  fn.code = code;
+  fn.source = format(code);
+  fn.toString = () => fn.source;
+  return fn;
+}
+
+/**
+ * Return true if the given object is a function that executes an Origami
+ * expression.
+ *
+ * @param {any} obj
+ */
+export function isExpressionFunction(obj) {
+  return typeof obj === "function" && obj.code;
+}

package/src/runtime/extname.js

@@ -0,0 +1,20 @@
+/**
+ * If the given path ends in an extension, return it. Otherwise, return the
+ * empty string.
+ *
+ * This is meant as a basic replacement for the standard Node `path.extname`.
+ * That standard function inaccurately returns an extension for a path that
+ * includes a near-final extension but ends in a final slash, like "foo.txt/".
+ * Node thinks that path has a ".txt" extension, but for our purposes it
+ * doesn't.
+ *
+ * @param {string} path
+ */
+export default function extname(path) {
+  // We want at least one character before the dot, then a dot, then a non-empty
+  // sequence of characters after the dot that aren't slahes or dots.
+  const extnameRegex = /[^/](?<ext>\.[^/\.]+)$/;
+  const match = path.match(extnameRegex);
+  const extension = match?.groups?.ext.toLowerCase() ?? "";
+  return extension;
+}

package/src/runtime/format.js

@@ -0,0 +1,126 @@
+import { ops } from "./internal.js";
+
+export default function format(code, implicitFunctionCall = false) {
+  if (code === null) {
+    return "";
+  } else if (typeof code === "string") {
+    return `'${code}'`;
+  } else if (typeof code === "symbol") {
+    return `«${code.description}»`;
+  } else if (!(code instanceof Array)) {
+    return code;
+  } else {
+    switch (code[0]) {
+      case ops.assign:
+        return formatAssignment(code);
+
+      case ops.concat:
+        return formatTemplate(code);
+
+      case ops.lambda:
+        return formatLambda(code);
+
+      case ops.object:
+        return formatObject(code);
+
+      case ops.scope:
+        return formatScopeTraversal(code, implicitFunctionCall);
+
+      case ops.tree:
+        return formatTree(code);
+
+      default:
+        return code[0] instanceof Array
+          ? formatFunctionCall(code)
+          : "** Unknown Origami code **";
+    }
+  }
+}
+
+function formatArgument(arg) {
+  return typeof arg === "string" ? `'${arg}'` : format(arg);
+}
+
+function formatArguments(args) {
+  const allStrings = args.every((arg) => typeof arg === "string");
+  return allStrings
+    ? // Use tree traversal syntax.
+      formatSlashPath(args)
+    : // Use function invocation syntax.
+      formatArgumentsList(args);
+}
+
+function formatArgumentsList(args) {
+  const formatted = args.map((arg) => formatArgument(arg));
+  const list = formatted.join(", ");
+  return `(${list})`;
+}
+
+function formatAssignment(code) {
+  const [_, declaration, expression] = code;
+  return `${declaration} = ${format(expression)}`;
+}
+
+function formatFunctionCall(code) {
+  const [fn, ...args] = code;
+  let formattedFn = format(fn);
+  if (formattedFn.includes("/") || formattedFn.includes("(")) {
+    formattedFn = `(${formattedFn})`;
+  }
+  return `${formattedFn}${formatArguments(args)}`;
+}
+
+function formatObject(code) {
+  const [_, ...entries] = code;
+  const formatted = entries.map(([key, value]) => {
+    return value === null ? key : `${key}: ${format(value)}`;
+  });
+  return formatted ? `{ ${formatted.join(", ")} }` : "{}";
+}
+
+function formatName(name) {
+  return typeof name === "string"
+    ? name
+    : name instanceof Array
+    ? `(${format(name)})`
+    : format(name);
+}
+
+function formatLambda(code) {
+  return `=${format(code[1])}`;
+}
+
+function formatScopeTraversal(code, implicitFunctionCall = false) {
+  const operands = code.slice(1);
+  const name = formatName(operands[0]);
+  if (operands.length === 1) {
+    return implicitFunctionCall ? `${name}()` : name;
+  }
+
+  const args = formatArguments(operands.slice(1));
+  return `${name}${args}`;
+}
+
+function formatSlashPath(args) {
+  return "/" + args.join("/");
+}
+
+function formatTemplate(code) {
+  const args = code.slice(1);
+  const formatted = args.map((arg) =>
+    typeof arg === "string" ? arg : `{{${format(arg)}}}`
+  );
+  return `\`${formatted.join("")}\``;
+}
+
+function formatTree(code) {
+  const [_, ...entries] = code;
+  const formatted = entries.map(([key, value]) => {
+    const rhs =
+      typeof value === "function" && value.code !== undefined
+        ? value.code
+        : value;
+    return `${key} = ${format(rhs)}`;
+  });
+  return formatted ? `{ ${formatted.join(", ")} }` : "{}";
+}

package/src/runtime/functionResultsMap.js

@@ -0,0 +1,28 @@
+import { map, Tree } from "@weborigami/async-tree";
+import Scope from "./Scope.js";
+
+/**
+ * When using `get` to retrieve a value from a tree, if the value is a
+ * function, invoke it and return the result.
+ *
+ * @type {import("@weborigami/async-tree").TreeTransform}
+ */
+export default function functionResultsMap(tree) {
+  return map({
+    description: "functionResultsMap",
+
+    valueMap: async (sourceValue, sourceKey, tree) => {
+      let resultValue;
+      if (typeof sourceValue === "function") {
+        const scope = Scope.getScope(tree);
+        resultValue = await sourceValue.call(scope);
+        if (Tree.isAsyncTree(resultValue)) {
+          resultValue.parent = tree;
+        }
+      } else {
+        resultValue = sourceValue;
+      }
+      return resultValue;
+    },
+  })(tree);
+}

package/src/runtime/internal.js

@@ -0,0 +1,20 @@
+//
+// The runtime includes a number of modules with circular dependencies. This
+// module exists to explicitly set the loading order for those modules. To
+// enforce use of this loading order, other modules should only load the modules
+// below via this module.
+//
+// About this pattern: https://medium.com/visual-development/how-to-fix-nasty-circular-dependency-issues-once-and-for-all-in-javascript-typescript-a04c987cf0de
+//
+
+export * as ops from "./ops.js";
+
+export { default as evaluate } from "./evaluate.js";
+
+export { default as format } from "./format.js";
+
+export * as expressionFunction from "./expressionFunction.js";
+
+export { default as ExpressionTree } from "./ExpressionTree.js";
+
+export { default as OrigamiTree } from "./OrigamiTree.js";

package/src/runtime/ops.js

@@ -0,0 +1,222 @@
+/**
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("@weborigami/async-tree").PlainObject} PlainObject
+ */
+
+import { SiteTree } from "@weborigami/async-tree";
+import FileLoadersTransform from "./FileLoadersTransform.js";
+import OrigamiFiles from "./OrigamiFiles.js";
+import Scope from "./Scope.js";
+import concatTreeValues from "./concatTreeValues.js";
+import { OrigamiTree, evaluate, expressionFunction } from "./internal.js";
+
+/**
+ * Construct an array.
+ *
+ * @this {AsyncTree|null}
+ * @param {any[]} items
+ */
+export async function array(...items) {
+  return Array(...items);
+}
+array.toString = () => "«ops.array»";
+
+// The assign op is a placeholder for an assignment declaration.
+// It is only used during parsing -- it shouldn't be executed.
+export const assign = "«ops.assign»";
+
+/**
+ * Concatenate the given arguments.
+ *
+ * @this {AsyncTree|null}
+ * @param {any[]} args
+ */
+export async function concat(...args) {
+  return concatTreeValues.call(this, args);
+}
+concat.toString = () => "«ops.concat»";
+
+/**
+ * Given a protocol, a host, and a list of keys, construct an href.
+ *
+ * @param {string} protocol
+ * @param {string} host
+ * @param  {...string|Symbol} keys
+ */
+function constructHref(protocol, host, ...keys) {
+  let href = [host, ...keys].join("/");
+  if (!href.startsWith(protocol)) {
+    if (!href.startsWith("//")) {
+      href = `//${href}`;
+    }
+    href = `${protocol}${href}`;
+  }
+  return href;
+}
+
+/**
+ * Fetch the resource at the given href.
+ *
+ * @param {string} href
+ */
+async function fetchResponse(href) {
+  const response = await fetch(href);
+  return response.ok ? await response.arrayBuffer() : undefined;
+}
+
+/**
+ * Construct a files tree for the filesystem root.
+ *
+ * @this {AsyncTree|null}
+ */
+export async function filesRoot() {
+  /** @type {AsyncTree} */
+  let root = new OrigamiFiles("/");
+
+  // The root itself needs a scope so that expressions evaluated within it
+  // (e.g., Origami expressions loaded from .ori files) will have access to
+  // things like the built-in functions.
+  root = Scope.treeWithScope(root, this);
+
+  return root;
+}
+
+/**
+ * Retrieve a web resource via HTTP.
+ *
+ * @this {AsyncTree|null}
+ * @param {string} host
+ * @param  {...string|Symbol} keys
+ */
+export async function http(host, ...keys) {
+  const href = constructHref("http:", host, ...keys);
+  return fetchResponse(href);
+}
+http.toString = () => "«ops.http»";
+
+/**
+ * Retrieve a web resource via HTTPS.
+ *
+ * @this {AsyncTree|null}
+ * @param {string} host
+ * @param  {...string|Symbol} keys
+ */
+export function https(host, ...keys) {
+  const href = constructHref("https:", host, ...keys);
+  return fetchResponse(href);
+}
+https.toString = () => "«ops.https»";
+
+/**
+ * Search the inherited scope -- i.e., exclude the current tree -- for the
+ * given key.
+ *
+ * @this {AsyncTree|null}
+ * @param {*} key
+ */
+export async function inherited(key) {
+  const scope = this;
+  const scopeTrees = /** @type {any} */ (scope).trees ?? scope;
+  const inheritedScope = new Scope(...scopeTrees.slice(1));
+  return inheritedScope.get(key);
+}
+inherited.toString = () => "«ops.inherited»";
+
+/**
+ * Return a function that will invoke the given code.
+ *
+ * @typedef {import("../../../language/src/compiler/code.js").Code} Code
+ * @this {AsyncTree|null}
+ * @param {Code} code
+ */
+export function lambda(code) {
+  /** @this {AsyncTree|null} */
+  async function invoke(input) {
+    // Add ambients to scope.
+    const ambients = {
+      _: input,
+      "@recurse": invoke,
+    };
+    const scope = new Scope(ambients, this);
+    const result = await evaluate.call(scope, code);
+    return result;
+  }
+  invoke.code = code;
+  return invoke;
+}
+lambda.toString = () => "«ops.lambda»";
+
+/**
+ * Construct an object. The keys will be the same as the given `obj`
+ * parameter's, and the values will be the results of evaluating the
+ * corresponding code values in `obj`.
+ *
+ * @this {AsyncTree|null}
+ * @param {any[]} entries
+ */
+export async function object(...entries) {
+  const scope = this;
+  const promises = entries.map(async ([key, value]) => [
+    key,
+    await evaluate.call(scope, value),
+  ]);
+  const evaluated = await Promise.all(promises);
+  return Object.fromEntries(evaluated);
+}
+object.toString = () => "«ops.object»";
+
+/**
+ * Construct an tree. This is similar to ops.object but the values are turned
+ * into functions rather than being immediately evaluated, and the result is an
+ * OrigamiTree.
+ *
+ * @this {AsyncTree|null}
+ * @param {any[]} entries
+ */
+export async function tree(...entries) {
+  const fns = entries.map(([key, code]) => {
+    const value =
+      code instanceof Array
+        ? expressionFunction.createExpressionFunction(code)
+        : code;
+    return [key, value];
+  });
+  const object = Object.fromEntries(fns);
+  return new OrigamiTree(object);
+}
+tree.toString = () => "«ops.tree»";
+
+/**
+ * A website tree via HTTP.
+ *
+ * @this {AsyncTree|null}
+ * @param {string} host
+ * @param  {...string|Symbol} keys
+ */
+export function treeHttp(host, ...keys) {
+  const href = constructHref("http:", host, ...keys);
+  /** @type {AsyncTree} */
+  let result = new (FileLoadersTransform(SiteTree))(href);
+  result = Scope.treeWithScope(result, this);
+  return result;
+}
+treeHttp.toString = () => "«ops.treeHttp»";
+
+/**
+ * A website tree via HTTPS.
+ *
+ * @this {AsyncTree|null}
+ * @param {string} host
+ * @param  {...string|Symbol} keys
+ */
+export function treeHttps(host, ...keys) {
+  const href = constructHref("https:", host, ...keys);
+  /** @type {AsyncTree} */
+  let result = new (FileLoadersTransform(SiteTree))(href);
+  result = Scope.treeWithScope(result, this);
+  return result;
+}
+treeHttps.toString = () => "«ops.treeHttps»";
+
+// The scope op is a placeholder for the tree's scope.
+export const scope = "«ops.scope»";

package/test/compiler/compile.test.js

@@ -0,0 +1,64 @@
+import { ObjectTree, Tree } from "@weborigami/async-tree";
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import * as compile from "../../src/compiler/compile.js";
+
+const scope = new ObjectTree({
+  greet: (name) => `Hello, ${name}!`,
+  name: "Alice",
+});
+
+describe("compile", () => {
+  test("array", async () => {
+    await assertCompile("[]", []);
+    await assertCompile("[ 1, 2, 3, ]", [1, 2, 3]);
+    await assertCompile("[\n'a'\n'b'\n'c'\n]", ["a", "b", "c"]);
+  });
+
+  test("functionComposition", async () => {
+    await assertCompile("greet()", "Hello, undefined!");
+    await assertCompile("greet(name)", "Hello, Alice!");
+    await assertCompile("greet 'world'", "Hello, world!");
+  });
+
+  test("tree", async () => {
+    const fn = compile.expression("{ message = greet(name) }");
+    const tree = await fn.call(null);
+    tree.scope = scope;
+    assert.deepEqual(await Tree.plain(tree), {
+      message: "Hello, Alice!",
+    });
+  });
+
+  test("number", async () => {
+    await assertCompile("1", 1);
+    await assertCompile("3.14159", 3.14159);
+    await assertCompile("-1", -1);
+  });
+
+  test("object", async () => {
+    await assertCompile("{a:1, b:2}", { a: 1, b: 2 });
+    await assertCompile("{ a: { b: { c: 0 } } }", { a: { b: { c: 0 } } });
+  });
+
+  test("templateDocument", async () => {
+    const fn = compile.templateDocument("Documents can contain ` backticks");
+    const templateFn = await fn.call(scope);
+    const value = await templateFn.call(null);
+    assert.deepEqual(value, "Documents can contain ` backticks");
+  });
+
+  test("templateLiteral", async () => {
+    await assertCompile("`Hello, {{name}}!`", "Hello, Alice!");
+    await assertCompile(
+      "`escape characters with \\`backslash\\``",
+      "escape characters with `backslash`"
+    );
+  });
+});
+
+async function assertCompile(text, expected) {
+  const fn = compile.expression(text);
+  const result = await fn.call(scope);
+  assert.deepEqual(result, expected);
+}