@weborigami/language 0.5.5 → 0.5.6

package/src/compiler/parserHelpers.js

@@ -259,8 +259,8 @@ function makeMerge(spreads, location) {
       // Also add an object to the result with indirect references
       const indirectEntries = spread.slice(1).map((entry) => {
         const [key] = entry;
-        const context = annotate([ops.context, 1], entry.location);
-        const reference = annotate([context, key], entry.location);
+        const parent = annotate([ops.inherited, 1], entry.location);
+        const reference = annotate([parent, key], entry.location);
         const getter = annotate([ops.getter, reference], entry.location);
         return annotate([key, getter], entry.location);
       });

package/src/handlers/css_handler.js

@@ -0,0 +1,7 @@
+// .css files use the .txt loader
+import txt_handler from "./txt_handler.js";
+
+export default {
+  ...txt_handler,
+  mediaType: "text/css",
+};

package/src/handlers/csv_handler.js

@@ -0,0 +1,129 @@
+import { symbols, toString } from "@weborigami/async-tree";
+
+export default {
+  mediaType: "text/csv",
+
+  unpack(packed, options = {}) {
+    const parent = options.parent ?? null;
+    const text = toString(packed);
+    if (text === null) {
+      throw new TypeError("CSV handler can only unpack text");
+    }
+    const data = csvParse(text);
+    // Define `parent` as non-enumerable property
+    Object.defineProperty(data, symbols.parent, {
+      configurable: true,
+      enumerable: false,
+      value: parent,
+      writable: true,
+    });
+    return data;
+  },
+};
+
+/**
+ * Parse text as CSV following RFC 4180
+ *
+ * This assumes the presence of a header row, and accepts both CRLF and LF line
+ * endings.
+ *
+ * @param {string} text
+ * @returns {any[]}
+ */
+function csvParse(text) {
+  const rows = [];
+  let currentRow = [];
+  let currentField = "";
+
+  const pushField = () => {
+    // Push the completed field and reset for the next field.
+    currentRow.push(currentField);
+    currentField = "";
+  };
+
+  const pushRow = () => {
+    // Push the row if there is at least one field (accounts for potential trailing newline)
+    rows.push(currentRow);
+    currentRow = [];
+  };
+
+  // Main state machine
+  let i = 0;
+  let inQuotes = false;
+  while (i < text.length) {
+    const char = text[i];
+
+    if (inQuotes) {
+      // In a quoted field
+      if (char === '"') {
+        // Check if next character is also a quote
+        if (i + 1 < text.length && text[i + 1] === '"') {
+          // Append a literal double quote and skip the next character
+          currentField += '"';
+          i += 2;
+          continue;
+        } else {
+          // End of the quoted field
+          inQuotes = false;
+          i++;
+          continue;
+        }
+      } else {
+        // All other characters within quotes are taken literally.
+        currentField += char;
+        i++;
+        continue;
+      }
+    } else if (char === '"') {
+      // Start of a quoted field
+      inQuotes = true;
+      i++;
+      continue;
+    } else if (char === ",") {
+      // End of field
+      pushField();
+      i++;
+      continue;
+    } else if (char === "\n" || (char === "\r" && text[i + 1] === "\n")) {
+      // End of row: push the last field, then row.
+      pushField();
+      pushRow();
+      if (char === "\r" && text[i + 1] === "\n") {
+        i++; // Handle CRLF line endings
+      }
+      i++;
+      continue;
+    } else {
+      // Regular character
+      currentField += char;
+      i++;
+      continue;
+    }
+  }
+
+  // Handle any remaining data after the loop.
+  // This will capture the last field/row if the text did not end with a newline.
+  if (inQuotes) {
+    // Mismatched quotes: you might choose to throw an error or handle it gracefully.
+    throw new Error("CSV parsing error: unmatched quote in the input.");
+  }
+  if (currentField !== "" || text.at(-1) === ",") {
+    pushField();
+  }
+  if (currentRow.length > 0) {
+    pushRow();
+  }
+
+  // The first row is assumed to be the header.
+  if (rows.length === 0) {
+    return [];
+  }
+
+  const header = rows.shift();
+
+  const data = rows.map((row) =>
+    Object.fromEntries(row.map((value, index) => [header[index], value]))
+  );
+
+  return data;
+}

package/src/handlers/handlers.js

@@ -0,0 +1,33 @@
+//
+// This library 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
+//
+// Note: to avoid having VS Code auto-sort the imports, keep lines between them.
+
+export { default as js_handler } from "./js_handler.js";
+export { default as ts_handler } from "./ts_handler.js";
+
+export { default as ori_handler } from "./ori_handler.js";
+
+export { default as oridocument_handler } from "./oridocument_handler.js";
+
+export { default as txt_handler } from "./txt_handler.js";
+
+export { default as css_handler } from "./css_handler.js";
+export { default as csv_handler } from "./csv_handler.js";
+export { default as htm_handler } from "./htm_handler.js";
+export { default as html_handler } from "./html_handler.js";
+export { default as jpeg_handler } from "./jpeg_handler.js";
+export { default as jpg_handler } from "./jpg_handler.js";
+export { default as json_handler } from "./json_handler.js";
+export { default as md_handler } from "./md_handler.js";
+export { default as mjs_handler } from "./mjs_handler.js";
+export { default as wasm_handler } from "./wasm_handler.js";
+export { default as xhtml_handler } from "./xhtml_handler.js";
+export { default as yaml_handler } from "./yaml_handler.js";
+export { default as yml_handler } from "./yml_handler.js";

package/src/handlers/htm_handler.js

@@ -0,0 +1,2 @@
+// .htm is a synonynm for .html
+export { html_handler as default } from "./handlers.js";

package/src/handlers/html_handler.js

@@ -0,0 +1,7 @@
+// .html files use the .txt loader
+import txt_handler from "./txt_handler.js";
+
+export default {
+  ...txt_handler,
+  mediaType: "text/html",
+};

package/src/handlers/jpeg_handler.js

@@ -0,0 +1,62 @@
+import exifParser from "exif-parser";
+
+const exifDateTags = [
+  "ModifyDate",
+  "MDPrepDate",
+  "DateTimeOriginal",
+  "CreateDate",
+  "PreviewDateTime",
+  "GPSDateStamp",
+];
+
+/**
+ * A JPEG file with possible Exif metadata
+ */
+export default {
+  mediaType: "image/jpeg",
+
+  /** @type {import("@weborigami/async-tree").UnpackFunction} */
+  async unpack(packed, options) {
+    if (packed instanceof Uint8Array) {
+      // Downgrade to old Node Buffer for exif-parser.
+      packed = Buffer.from(packed);
+    }
+    const parser = exifParser.create(packed);
+    parser.enableTagNames(true);
+    parser.enableSimpleValues(true);
+    const parsed = await parser.parse();
+
+    // The exif-parser `enableSimpleValues` option should convert dates to
+    // JavaScript Date objects, but that doesn't seem to work. Ensure dates are
+    // Date objects.
+    const exif = parsed.tags;
+    for (const tag of exifDateTags) {
+      if (typeof exif[tag] === "number") {
+        exif[tag] = new Date(exif[tag] * 1000);
+      }
+    }
+
+    const result = {
+      height: parsed.imageSize.height,
+      width: parsed.imageSize.width,
+      exif,
+    };
+
+    // Promote some Exif properties to the top level.
+    const tagsToPromote = {
+      ImageDescription: "caption",
+      ModifyDate: "modified",
+      Orientation: "orientation",
+    };
+    for (const [tag, key] of Object.entries(tagsToPromote)) {
+      if (exif[tag] !== undefined) {
+        result[key] = exif[tag];
+      }
+    }
+
+    // Add aspect ratio for use with `aspect-ratio` CSS.
+    result.aspectRatio = result.width / result.height;
+
+    return result;
+  },
+};

package/src/handlers/jpg_handler.js

@@ -0,0 +1,2 @@
+// .jpg is a synonym for .jpeg
+export { jpeg_handler as default } from "./handlers.js";

package/src/handlers/js_handler.js

@@ -0,0 +1,51 @@
+/**
+ * A JavaScript file
+ *
+ * Unpacking a JavaScript file returns its default export, or its set of exports
+ * if there is more than one.
+ */
+export default {
+  mediaType: "application/javascript",
+
+  /** @type {import("@weborigami/async-tree").UnpackFunction} */
+  async unpack(packed, options = {}) {
+    const { key, parent } = options;
+    if (!(parent && "import" in parent)) {
+      throw new TypeError(
+        "The parent tree must support importing modules to unpack JavaScript files."
+      );
+    }
+
+    const object = await /** @type {any} */ (parent).import?.(key);
+
+    let bound;
+    if ("default" in object) {
+      // Module with a default export; return that.
+      bound = bindToParent(object.default, parent);
+    } else {
+      // Module with multiple named exports.
+      bound = {};
+      for (const [name, value] of Object.entries(object)) {
+        bound[name] = bindToParent(value, parent);
+      }
+    }
+
+    return bound;
+  },
+};
+
+// If the value is a function, bind it to the parent so that the function can,
+// e.g., find local files. Note: evaluate() supports a related but separate
+// mechanism called `containerAsTarget`. We want to use binding here so that, if
+// a function is handed to another to be called later, it still has the correct
+// `this`.
+function bindToParent(value, parent) {
+  if (typeof value === "function") {
+    const result = value.bind(parent);
+    // Copy over any properties that were attached to the function
+    Object.assign(result, value);
+    return result;
+  } else {
+    return value;
+  }
+}

package/src/handlers/json_handler.js

@@ -0,0 +1,26 @@
+import { symbols, toString } from "@weborigami/async-tree";
+
+/**
+ * A JSON file
+ *
+ * Unpacking a JSON file returns the parsed data.
+ */
+export default {
+  mediaType: "application/json",
+
+  /** @type {import("@weborigami/async-tree").UnpackFunction} */
+  unpack(packed) {
+    const json = toString(packed);
+    if (!json) {
+      throw new Error("Tried to parse something as JSON but it wasn't text.");
+    }
+    const data = JSON.parse(json);
+    if (data && typeof data === "object" && Object.isExtensible(data)) {
+      Object.defineProperty(data, symbols.deep, {
+        enumerable: false,
+        value: true,
+      });
+    }
+    return data;
+  },
+};

package/src/handlers/md_handler.js

@@ -0,0 +1,7 @@
+// .md files use the .txt loader
+import txt_handler from "./txt_handler.js";
+
+export default {
+  ...txt_handler,
+  mediaType: "text/markdown",
+};

package/src/handlers/mjs_handler.js

@@ -0,0 +1,2 @@
+// .mjs is a synonynm for .js
+export { js_handler as default } from "./handlers.js";

package/src/handlers/ori_handler.js

@@ -0,0 +1,47 @@
+import { getParent, toString } from "@weborigami/async-tree";
+import * as compile from "../compiler/compile.js";
+import projectGlobals from "../project/projectGlobals.js";
+
+/**
+ * An Origami expression file
+ *
+ * Unpacking an Origami file returns the result of evaluating the expression.
+ */
+export default {
+  mediaType: "text/plain",
+
+  /** @type {import("@weborigami/async-tree").UnpackFunction} */
+  async unpack(packed, options = {}) {
+    const parent = getParent(packed, options);
+
+    // Construct an object to represent the source code.
+    const sourceName = options.key;
+    let url;
+    if (sourceName && /** @type {any} */ (parent)?.url) {
+      let parentHref = /** @type {any} */ (parent).url.href;
+      if (!parentHref.endsWith("/")) {
+        parentHref += "/";
+      }
+      url = new URL(sourceName, parentHref);
+    }
+
+    const source = {
+      text: toString(packed),
+      name: options.key,
+      url,
+    };
+
+    // Compile the source code as an Origami program and evaluate it.
+    const compiler = options.compiler ?? compile.program;
+    const globals = options.globals ?? (await projectGlobals());
+
+    const fn = compiler(source, {
+      globals,
+      mode: "program",
+      parent,
+    });
+
+    const result = await fn();
+    return result;
+  },
+};

package/src/handlers/oridocument_handler.js

@@ -0,0 +1,77 @@
+import {
+  extension,
+  getParent,
+  toString,
+  trailingSlash,
+} from "@weborigami/async-tree";
+import * as compile from "../compiler/compile.js";
+import projectGlobals from "../project/projectGlobals.js";
+
+/**
+ * An Origami template document: a plain text file that contains Origami
+ * expressions.
+ */
+export default {
+  mediaType: "text/plain",
+
+  /** @type {import("@weborigami/async-tree").UnpackFunction} */
+  async unpack(packed, options = {}) {
+    const parent = getParent(packed, options);
+
+    // Unpack as a text document
+    const text = toString(packed);
+
+    // See if we can construct a URL to use in error messages
+    const key = options.key;
+    let url;
+    if (key && /** @type {any} */ (parent)?.url) {
+      let parentHref = /** @type {any} */ (parent).url.href;
+      if (!parentHref.endsWith("/")) {
+        parentHref += "/";
+      }
+      url = new URL(key, parentHref);
+    }
+
+    // Compile the text as an Origami template document
+    const source = {
+      name: key,
+      text,
+      url,
+    };
+
+    const globals = options.globals ?? (await projectGlobals());
+
+    const defineFn = compile.templateDocument(source, {
+      front: options.front,
+      globals,
+      mode: "program",
+      parent,
+    });
+
+    // Invoke the definition to get back the template function
+    const result = await defineFn();
+
+    const resultExtension = key ? extension.extname(key) : null;
+    if (resultExtension && Object.isExtensible(result)) {
+      // Add sidecar function so this template can be used in a map.
+      result.key = addExtension(resultExtension);
+    }
+
+    return result;
+  },
+};
+
+// Return a function that adds the given extension
+function addExtension(resultExtension) {
+  return (sourceValue, sourceKey) => {
+    if (sourceKey === undefined) {
+      return undefined;
+    }
+    const normalizedKey = trailingSlash.remove(sourceKey);
+    const sourceExtension = extension.extname(normalizedKey);
+    const resultKey = sourceExtension
+      ? extension.replace(normalizedKey, sourceExtension, resultExtension)
+      : normalizedKey + resultExtension;
+    return resultKey;
+  };
+}

package/src/handlers/parseFrontMatter.js

@@ -0,0 +1,16 @@
+import isOrigamiFrontMatter from "../compiler/isOrigamiFrontMatter.js";
+
+export default function parseFrontMatter(text) {
+  const regex =
+    /^(---\r?\n(?<frontText>[\s\S]*?\r?\n?)---\r?\n)(?<body>[\s\S]*$)/;
+  const match = regex.exec(text);
+  if (!match?.groups) {
+    return null;
+  }
+  const isOrigami = isOrigamiFrontMatter(match.groups.frontText);
+  return {
+    body: match.groups.body,
+    frontText: match.groups.frontText,
+    isOrigami,
+  };
+}

package/src/handlers/ts_handler.js

@@ -0,0 +1 @@
+export { js_handler as default } from "./handlers.js";

package/src/handlers/txt_handler.js

@@ -0,0 +1,108 @@
+import {
+  isPacked,
+  symbols,
+  toPlainValue,
+  toString,
+} from "@weborigami/async-tree";
+import * as YAMLModule from "yaml";
+import * as compile from "../compiler/compile.js";
+import projectGlobals from "../project/projectGlobals.js";
+import parseFrontMatter from "./parseFrontMatter.js";
+
+// The "yaml" package doesn't seem to provide a default export that the browser can
+// recognize, so we have to handle two ways to accommodate Node and the browser.
+// @ts-ignore
+const YAML = YAMLModule.default ?? YAMLModule.YAML;
+
+/**
+ * A text file with possible front matter
+ *
+ * The unpacking 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.
+ *
+ * If there is no front matter, the document will be treated as plain text and
+ * returned as a String object.
+ *
+ * If there is front matter, any Origami expressions in the front matter will be
+ * evaluated. The result will be a plain JavaScript object with the evaluated
+ * data and a `_body` property containing the document text.
+ */
+export default {
+  mediaType: "text/plain",
+
+  /**
+   * If the input is already in some packed format, it will be returned as is.
+   *
+   * Otherwise, the properties of the object will be formatted as YAML. If the
+   * object has a `_body` property, that will be used as the body of the text
+   * document; otherwise, an empty string will be used.
+   *
+   * @param {any} object
+   * @returns {Promise<import("@weborigami/async-tree").Packed>}
+   */
+  async pack(object) {
+    if (isPacked(object)) {
+      return object;
+    } else if (!object || typeof object !== "object") {
+      throw new TypeError("The input to pack must be a JavaScript object.");
+    }
+
+    const isDocument = object._body !== undefined;
+    const text = isDocument ? object._body : toString(object);
+
+    /** @type {any} */
+    const dataWithoutText = Object.assign({}, object);
+    delete dataWithoutText._body;
+    if (Object.keys(dataWithoutText).length > 0) {
+      const serializable = await toPlainValue(dataWithoutText);
+      const yamlText = YAML.stringify(serializable);
+      const frontMatter = yamlText.trimEnd();
+      return `---\n${frontMatter}\n---\n${text}`;
+    } else {
+      return text;
+    }
+  },
+
+  /** @type {import("@weborigami/async-tree").UnpackFunction} */
+  async unpack(packed, options = {}) {
+    const parent = options.parent ?? null;
+    const text = toString(packed);
+    if (text === null) {
+      throw new Error("Tried to treat a file as text but it wasn't text.");
+    }
+
+    const parsed = parseFrontMatter(text);
+    let unpacked;
+    if (parsed) {
+      // Document object with front matter
+      const { body, frontText, isOrigami } = parsed;
+      let frontData;
+      if (isOrigami) {
+        const globals = await projectGlobals();
+        const compiled = compile.expression(frontText.trim(), {
+          globals,
+          parent,
+        });
+        frontData = await compiled();
+      } else {
+        frontData = YAML.parse(frontText);
+      }
+      unpacked = { ...frontData };
+      Object.defineProperty(unpacked, "_body", {
+        configurable: true,
+        enumerable: true,
+        value: body,
+        writable: true,
+      });
+    } else {
+      // Plain text
+      unpacked = new String(text);
+    }
+
+    unpacked[symbols.parent] = parent;
+
+    return unpacked;
+  },
+};

package/src/handlers/wasm_handler.js

@@ -0,0 +1,15 @@
+/**
+ * A WebAssembly module
+ *
+ * Unpacking a WebAssembly module returns its exports.
+ */
+export default {
+  mediaType: "application/wasm",
+
+  /** @type {import("@weborigami/async-tree").UnpackFunction} */
+  async unpack(packed) {
+    const wasmModule = await WebAssembly.instantiate(packed);
+    // @ts-ignore TypeScript thinks wasmModule is already an Instance.
+    return wasmModule.instance.exports;
+  },
+};

package/src/handlers/xhtml_handler.js

@@ -0,0 +1,2 @@
+// .xhtml is a synonynm for .html
+export { html_handler as default } from "./handlers.js";

package/src/handlers/yaml_handler.js

@@ -0,0 +1,33 @@
+import { symbols, toString } from "@weborigami/async-tree";
+import * as YAMLModule from "yaml";
+
+// The "yaml" package doesn't seem to provide a default export that the browser can
+// recognize, so we have to handle two ways to accommodate Node and the browser.
+// @ts-ignore
+const YAML = YAMLModule.default ?? YAMLModule.YAML;
+
+/**
+ * A YAML file
+ *
+ * Unpacking a YAML file returns the parsed data.
+ *
+ */
+export default {
+  mediaType: "application/yaml",
+
+  /** @type {import("@weborigami/async-tree").UnpackFunction} */
+  unpack(packed) {
+    const yaml = toString(packed);
+    if (!yaml) {
+      throw new Error("Tried to parse something as YAML but it wasn't text.");
+    }
+    const data = YAML.parse(yaml);
+    if (data && typeof data === "object" && Object.isExtensible(data)) {
+      Object.defineProperty(data, symbols.deep, {
+        enumerable: false,
+        value: true,
+      });
+    }
+    return data;
+  },
+};

package/src/handlers/yml_handler.js

@@ -0,0 +1,2 @@
+// .yml is a synonym for .yaml
+export { yaml_handler as default } from "./handlers.js";

package/src/project/builtins.js

@@ -0,0 +1,5 @@
+/**
+ * Consumers of the compiler (e.g., the Origami CLI) should inject their own
+ * builtin functions into this object.
+ */
+export default {};