@weborigami/language 0.0.73 → 0.2.0

package/src/compiler/parserHelpers.js

@@ -1,45 +1,81 @@
 import { trailingSlash } from "@weborigami/async-tree";
+import codeFragment from "../runtime/codeFragment.js";
 import * as ops from "../runtime/ops.js";
 
 // Parser helpers
 
+/** @typedef {import("../../index.ts").Code} Code */
+
+// Marker for a reference that may be a builtin or a scope reference
+export const undetermined = Symbol("undetermined");
+
+const builtinRegex = /^[A-Za-z][A-Za-z0-9]*$/;
+
 /**
  * If a parse result is an object that will be evaluated at runtime, attach the
  * location of the source code that produced it for debugging and error messages.
+ *
+ * @param {Code} code
+ * @param {any} location
  */
-export function annotate(parseResult, location) {
-  if (typeof parseResult === "object" && parseResult !== null) {
-    parseResult.location = location;
+export function annotate(code, location) {
+  if (typeof code === "object" && code !== null && location) {
+    code.location = location;
+    code.source = codeFragment(location);
   }
-  return parseResult;
+  return code;
 }
 
-// The indicated code is being used to define a property named by the given key.
-// Rewrite any [ops.scope, key] calls to be [ops.inherited, key] to avoid
-// infinite recursion.
+/**
+ * The indicated code is being used to define a property named by the given key.
+ * Rewrite any [ops.scope, key] calls to be [ops.inherited, key] to avoid
+ * infinite recursion.
+ *
+ * @param {Code} code
+ * @param {string} key
+ */
 function avoidRecursivePropertyCalls(code, key) {
   if (!(code instanceof Array)) {
     return code;
   }
+  /** @type {Code} */
   let modified;
   if (
     code[0] === ops.scope &&
     trailingSlash.remove(code[1]) === trailingSlash.remove(key)
   ) {
     // Rewrite to avoid recursion
+    // @ts-ignore
     modified = [ops.inherited, code[1]];
   } else if (code[0] === ops.lambda && code[1].includes(key)) {
     // Lambda that defines the key; don't rewrite
     return code;
   } else {
     // Process any nested code
+    // @ts-ignore
     modified = code.map((value) => avoidRecursivePropertyCalls(value, key));
   }
-  // @ts-ignore
-  modified.location = code.location;
+  annotate(modified, code.location);
   return modified;
 }
 
+/**
+ * Downgrade a potential builtin reference to a scope reference.
+ *
+ * @param {Code} code
+ */
+export function downgradeReference(code) {
+  if (code && code.length === 2 && code[0] === undetermined) {
+    /** @type {Code} */
+    // @ts-ignore
+    const result = [ops.scope, code[1]];
+    annotate(result, code.location);
+    return result;
+  } else {
+    return code;
+  }
+}
+
 // Return true if the code will generate an async object.
 function isCodeForAsyncObject(code) {
   if (!(code instanceof Array)) {
@@ -89,56 +125,111 @@ export function makeArray(entries) {
 }
 
 /**
- * @typedef {import("../../index.ts").Code} Code
+ * Create a chain of binary operators. The head is the first value, and the tail
+ * is an array of [operator, value] pairs.
  *
+ * @param {Code} head
+ * @param {[any, Code][]} tail
+ */
+export function makeBinaryOperatorChain(head, tail) {
+  /** @type {Code} */
+  let value = head;
+  for (const [operatorToken, right] of tail) {
+    const left = value;
+    const operators = {
+      "===": ops.strictEqual,
+      "!==": ops.notStrictEqual,
+      "==": ops.equal,
+      "!=": ops.notEqual,
+    };
+    const op = operators[operatorToken];
+    // @ts-ignore
+    value = [op, left, right];
+    value.location = {
+      source: left.location.source,
+      start: left.location.start,
+      end: right.location.end,
+    };
+  }
+  return value;
+}
+
+/**
  * @param {Code} target
- * @param {Code[]} chain
- * @returns
+ * @param {any[]} args
  */
-export function makeFunctionCall(target, chain, location) {
+export function makeCall(target, args) {
   if (!(target instanceof Array)) {
     const error = new SyntaxError(`Can't call this like a function: ${target}`);
-    /** @type {any} */ (error).location = location;
+    /** @type {any} */ (error).location = /** @type {any} */ (target).location;
     throw error;
   }
 
-  let value = target;
   const source = target.location.source;
-  // The chain is an array of arguments (which are themselves arrays). We
-  // successively apply the top-level elements of that chain to build up the
-  // function composition.
   let start = target.location.start;
   let end = target.location.end;
-  for (const args of chain) {
-    /** @type {Code} */
-    let fnCall;
 
-    // @ts-ignore
-    fnCall =
-      args[0] !== ops.traverse
-        ? // Function call
-          [value, ...args]
-        : args.length > 1
-        ? // Traverse
-          [ops.traverse, value, ...args.slice(1)]
-        : // Traverse without arguments equates to unpack
-          [ops.unpack, value];
-
-    // Create a location spanning the newly-constructed function call.
-    if (args instanceof Array) {
-      if (args.location) {
-        end = args.location.end;
-      } else {
-        throw "Internal parser error: no location for function call argument";
+  let fnCall;
+  if (args[0] === ops.traverse) {
+    let tree = target;
+
+    if (tree[0] === undetermined) {
+      // In a traversal, downgrade ops.builtin references to ops.scope
+      tree = downgradeReference(tree);
+      if (tree[0] === ops.scope && !trailingSlash.has(tree[1])) {
+        // Target didn't parse with a trailing slash; add one
+        tree[1] = trailingSlash.add(tree[1]);
       }
     }
 
-    fnCall.location = { start, source, end };
+    if (args.length > 1) {
+      // Regular traverse
+      const keys = args.slice(1);
+      fnCall = [ops.traverse, tree, ...keys];
+    } else {
+      // Traverse without arguments equates to unpack
+      fnCall = [ops.unpack, tree];
+    }
+  } else if (args[0] === ops.template) {
+    // Tagged template
+    fnCall = [upgradeReference(target), ...args.slice(1)];
+  } else {
+    // Function call with explicit or implicit parentheses
+    fnCall = [upgradeReference(target), ...args];
+  }
 
-    value = fnCall;
+  // Create a location spanning the newly-constructed function call.
+  if (args instanceof Array) {
+    // @ts-ignore
+    end = args.location?.end ?? args.at(-1)?.location?.end;
+    if (end === undefined) {
+      throw "Internal parser error: no location for function call argument";
+    }
   }
 
-  return value;
+  // @ts-ignore
+  annotate(fnCall, { start, source, end });
+
+  return fnCall;
+}
+
+/**
+ * For functions that short-circuit arguments, we need to defer evaluation of
+ * the arguments until the function is called. Exception: if the argument is a
+ * literal, we leave it alone.
+ *
+ * @param {any[]} args
+ */
+export function makeDeferredArguments(args) {
+  return args.map((arg) => {
+    if (arg instanceof Array && arg[0] === ops.literal) {
+      return arg;
+    }
+    const fn = [ops.lambda, [], arg];
+    // @ts-ignore
+    annotate(fn, arg.location);
+    return fn;
+  });
 }
 
 export function makeObject(entries, op) {
@@ -189,13 +280,15 @@ export function makeObject(entries, op) {
 }
 
 // Similar to a function call, but the order is reversed.
-export function makePipeline(steps) {
-  const [first, ...rest] = steps;
-  let value = first;
-  for (const args of rest) {
-    value = [args, value];
-  }
-  return value;
+export function makePipeline(arg, fn) {
+  const upgraded = upgradeReference(fn);
+  const result = makeCall(upgraded, [arg]);
+  const source = fn.location.source;
+  let start = arg.location.start;
+  let end = fn.location.end;
+  // @ts-ignore
+  annotate(result, { start, source, end });
+  return result;
 }
 
 // Define a property on an object.
@@ -204,6 +297,21 @@ export function makeProperty(key, value) {
   return [key, modified];
 }
 
+export function makeReference(identifier) {
+  // We can't know for sure that an identifier is a builtin reference until we
+  // see whether it's being called as a function.
+  let op;
+  if (builtinRegex.test(identifier)) {
+    op = identifier.endsWith(":")
+      ? // Namespace is always a builtin reference
+        ops.builtin
+      : undetermined;
+  } else {
+    op = ops.scope;
+  }
+  return [op, identifier];
+}
+
 export function makeTemplate(op, head, tail) {
   const strings = [head];
   const values = [];
@@ -213,3 +321,27 @@ export function makeTemplate(op, head, tail) {
   }
   return [op, [ops.literal, strings], ...values];
 }
+
+export function makeUnaryOperatorCall(operator, value) {
+  const operators = {
+    "!": ops.logicalNot,
+  };
+  return [operators[operator], value];
+}
+
+/**
+ * Upgrade a potential builtin reference to an actual builtin reference.
+ *
+ * @param {Code} code
+ */
+export function upgradeReference(code) {
+  if (code.length === 2 && code[0] === undetermined) {
+    /** @type {Code} */
+    // @ts-ignore
+    const result = [ops.builtin, code[1]];
+    annotate(result, code.location);
+    return result;
+  } else {
+    return code;
+  }
+}

package/src/runtime/HandleExtensionsTransform.js

@@ -1,4 +1,4 @@
-import { handleExtension } from "./extensions.js";
+import { handleExtension } from "./handlers.js";
 
 /**
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree

package/src/runtime/ImportModulesMixin.js

@@ -1,7 +1,7 @@
 import * as fs from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import { maybeOrigamiSourceCode } from "./formatError.js";
+import { maybeOrigamiSourceCode } from "./errors.js";
 
 /**
  * @typedef {import("@weborigami/types").AsyncTree} AsyncTree

package/src/runtime/codeFragment.js

@@ -7,8 +7,8 @@ export default function codeFragment(location) {
       : // Use entire source
         source.text;
 
-  // Remove newlines and whitespace runs.
-  fragment = fragment.replace(/(\n|\s\s+)+/g, "");
+  // Replace newlines and whitespace runs with a single space.
+  fragment = fragment.replace(/(\n|\s\s+)+/g, " ");
 
   // If longer than 80 characters, truncate with an ellipsis.
   if (fragment.length > 80) {

package/src/runtime/errors.js

@@ -0,0 +1,104 @@
+// Text we look for in an error stack to guess whether a given line represents a
+
+import { scope as scopeFn, trailingSlash } from "@weborigami/async-tree";
+import codeFragment from "./codeFragment.js";
+import { typos } from "./typos.js";
+
+// function in the Origami source code.
+const origamiSourceSignals = [
+  "async-tree/src/",
+  "language/src/",
+  "origami/src/",
+  "at Scope.evaluate",
+];
+
+export async function builtinReferenceError(tree, builtins, key) {
+  const messages = [
+    `"${key}" is being called as if it were a builtin function, but it's not.`,
+  ];
+  // See if the key is in scope (but not as a builtin)
+  const scope = scopeFn(tree);
+  const value = await scope.get(key);
+  if (value === undefined) {
+    const typos = await formatScopeTypos(builtins, key);
+    messages.push(typos);
+  } else {
+    messages.push(`Use "${key}/" instead.`);
+  }
+  const message = messages.join(" ");
+  return new ReferenceError(message);
+}
+
+/**
+ * Format an error for display in the console.
+ *
+ * @param {Error} error
+ */
+export function formatError(error) {
+  let message;
+  if (error.stack) {
+    // Display the stack only until we reach the Origami source code.
+    message = "";
+    let lines = error.stack.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (maybeOrigamiSourceCode(line)) {
+        break;
+      }
+      if (message) {
+        message += "\n";
+      }
+      message += lines[i];
+    }
+  } else {
+    message = error.toString();
+  }
+
+  // Add location
+  let location = /** @type {any} */ (error).location;
+  if (location) {
+    const fragment = codeFragment(location);
+    let { source, start } = location;
+
+    message += `\nevaluating: ${fragment}`;
+    if (typeof source === "object" && source.url) {
+      message += `\n    at ${source.url.href}:${start.line}:${start.column}`;
+    } else if (source.text.includes("\n")) {
+      message += `\n    at line ${start.line}, column ${start.column}`;
+    }
+  }
+  return message;
+}
+
+export async function formatScopeTypos(scope, key) {
+  const keys = await scopeTypos(scope, key);
+  // Don't match deprecated keys
+  const filtered = keys.filter((key) => !key.startsWith("@"));
+  if (filtered.length === 0) {
+    return "";
+  }
+  const quoted = filtered.map((key) => `"${key}"`);
+  const list = quoted.join(", ");
+  return `Maybe you meant ${list}?`;
+}
+
+export function maybeOrigamiSourceCode(text) {
+  return origamiSourceSignals.some((signal) => text.includes(signal));
+}
+
+export async function scopeReferenceError(scope, key) {
+  const messages = [
+    `"${key}" is not in scope.`,
+    await formatScopeTypos(scope, key),
+  ];
+  const message = messages.join(" ");
+  return new ReferenceError(message);
+}
+
+// Return all possible typos for `key` in scope
+async function scopeTypos(scope, key) {
+  const scopeKeys = [...(await scope.keys())];
+  const normalizedScopeKeys = scopeKeys.map((key) => trailingSlash.remove(key));
+  const normalizedKey = trailingSlash.remove(key);
+  return typos(normalizedKey, normalizedScopeKeys);
+}

package/src/runtime/evaluate.js

@@ -68,10 +68,10 @@ export default async function evaluate(code) {
     if (!error.location) {
       // Attach the location of the code we tried to evaluate.
       error.location =
-        error.position !== undefined
+        error.position !== undefined && code[error.position + 1]?.location
           ? // Use location of the argument with the given position (need to
             // offset by 1 to skip the function).
-            code[error.position + 1].location
+            code[error.position + 1]?.location
           : // Use overall location.
             code.location;
     }
@@ -85,7 +85,7 @@ export default async function evaluate(code) {
   }
 
   // To aid debugging, add the code to the result.
-  if (Object.isExtensible(result) /* && !isPlainObject(result) */) {
+  if (Object.isExtensible(result)) {
     try {
       if (code.location && !result[sourceSymbol]) {
         Object.defineProperty(result, sourceSymbol, {

package/src/runtime/expressionObject.js

@@ -1,5 +1,5 @@
-import { ObjectTree, symbols } from "@weborigami/async-tree";
-import { extname, handleExtension } from "./extensions.js";
+import { extension, ObjectTree, symbols, Tree } from "@weborigami/async-tree";
+import { handleExtension } from "./handlers.js";
 import { evaluate, ops } from "./internal.js";
 
 /**
@@ -22,6 +22,9 @@ import { evaluate, ops } from "./internal.js";
 export default async function expressionObject(entries, parent) {
   // Create the object and set its parent
   const object = {};
+  if (parent !== null && !Tree.isAsyncTree(parent)) {
+    throw new TypeError(`Parent must be an AsyncTree or null`);
+  }
   Object.defineProperty(object, symbols.parent, {
     configurable: true,
     enumerable: false,
@@ -37,8 +40,8 @@ export default async function expressionObject(entries, parent) {
     // array), we need to define a getter -- but if that code takes the form
     // [ops.getter, <primitive>], we can define a regular property.
     let defineProperty;
-    const extension = extname(key);
-    if (extension) {
+    const extname = extension.extname(key);
+    if (extname) {
       defineProperty = false;
     } else if (!(value instanceof Array)) {
       defineProperty = true;
@@ -76,7 +79,7 @@ export default async function expressionObject(entries, parent) {
       }
 
       let get;
-      if (extension) {
+      if (extname) {
         // Key has extension, getter will invoke code then attach unpack method
         get = async () => {
           tree ??= new ObjectTree(object);

package/src/runtime/{extensions.js → handlers.js}

@@ -1,5 +1,6 @@
 import {
   box,
+  extension,
   isPacked,
   isStringLike,
   isUnpackable,
@@ -13,27 +14,6 @@ import {
 // Track extensions handlers for a given containing tree.
 const handlersForContainer = new Map();
 
-/**
- * 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 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 = String(path).match(extnameRegex);
-  const extension = match?.groups?.ext.toLowerCase() ?? "";
-  return extension;
-}
-
 /**
  * Find an extension handler for a file in the given container.
  *
@@ -95,9 +75,11 @@ export async function handleExtension(parent, value, key) {
     }
 
     // Special case: `.ori.<ext>` extensions are Origami documents.
-    const extension = key.match(/\.ori\.\S+$/) ? ".oridocument" : extname(key);
-    if (extension) {
-      const handler = await getExtensionHandler(parent, extension);
+    const extname = key.match(/\.ori\.\S+$/)
+      ? ".oridocument"
+      : extension.extname(key);
+    if (extname) {
+      const handler = await getExtensionHandler(parent, extname);
       if (handler) {
         if (hasSlash && handler.unpack) {
           // Key like `data.json/` ends in slash -- unpack immediately

package/src/runtime/internal.js

@@ -6,6 +6,7 @@
 //
 // 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 * as ops from "./ops.js";