@weborigami/language 0.2.7 → 0.2.8

package/src/compiler/parserHelpers.js

@@ -4,6 +4,9 @@ import * as ops from "../runtime/ops.js";
 
 // Parser helpers
 
+/** @typedef {import("../../index.ts").AnnotatedCode} AnnotatedCode */
+/** @typedef {import("../../index.ts").AnnotatedCodeItem} AnnotatedCodeItem */
+/** @typedef {import("../../index.ts").CodeLocation} CodeLocation */
 /** @typedef {import("../../index.ts").Code} Code */
 
 // Marker for a reference that may be a builtin or a scope reference
@@ -15,15 +18,16 @@ 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
+ * @param {Code[]} code
+ * @param {CodeLocation} location
  */
 export function annotate(code, location) {
-  if (typeof code === "object" && code !== null && location) {
-    code.location = location;
-    code.source = codeFragment(location);
-  }
-  return code;
+  /** @type {AnnotatedCode} */
+  // @ts-ignore - Need to add annotation below before type is correct
+  const annotated = code.slice();
+  annotated.location = location;
+  annotated.source = codeFragment(location);
+  return annotated;
 }
 
 /**
@@ -31,7 +35,7 @@ export function annotate(code, location) {
  * Rewrite any [ops.scope, key] calls to be [ops.inherited, key] to avoid
  * infinite recursion.
  *
- * @param {Code} code
+ * @param {AnnotatedCode} code
  * @param {string} key
  */
 function avoidRecursivePropertyCalls(code, key) {
@@ -45,45 +49,49 @@ function avoidRecursivePropertyCalls(code, key) {
     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));
   }
-  annotate(modified, code.location);
-  return modified;
+  return annotate(modified, code.location);
 }
 
 /**
  * Downgrade a potential builtin reference to a scope reference.
  *
- * @param {Code} code
+ * @param {AnnotatedCode} 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;
+    return annotate([ops.scope, code[1]], code.location);
   } else {
     return code;
   }
 }
 
-export function makeArray(entries) {
+/**
+ * Create an array
+ *
+ * @param {AnnotatedCode[]} entries
+ * @param {CodeLocation} location
+ */
+export function makeArray(entries, location) {
   let currentEntries = [];
   const spreads = [];
 
   for (const value of entries) {
     if (Array.isArray(value) && value[0] === ops.spread) {
       if (currentEntries.length > 0) {
-        spreads.push([ops.array, ...currentEntries]);
+        const location = { ...currentEntries[0].location };
+        location.end = currentEntries[currentEntries.length - 1].location.end;
+        /** @type {AnnotatedCodeItem} */
+        const fn = ops.array;
+        const spread = annotate([fn, ...currentEntries], location);
+        spreads.push(spread);
         currentEntries = [];
       }
       spreads.push(...value.slice(1));
@@ -98,21 +106,24 @@ export function makeArray(entries) {
     currentEntries = [];
   }
 
+  let result;
   if (spreads.length > 1) {
-    return [ops.merge, ...spreads];
-  }
-  if (spreads.length === 1) {
-    return spreads[0];
+    result = [ops.merge, ...spreads];
+  } else if (spreads.length === 1) {
+    result = spreads[0];
   } else {
-    return [ops.array];
+    result = [ops.array];
   }
+
+  return annotate(result, location);
 }
 
 /**
  * Create a chain of binary operators. The head is the first value, and the tail
- * is an array of [operator, value] pairs.
+ * is a [operator, value] pair as an array.
  *
- * @param {Code} left
+ * @param {AnnotatedCode} left
+ * @param {[token: any, right: AnnotatedCode]} tail
  */
 export function makeBinaryOperation(left, [operatorToken, right]) {
   const operators = {
@@ -139,20 +150,19 @@ export function makeBinaryOperation(left, [operatorToken, right]) {
   };
   const op = operators[operatorToken];
 
-  /** @type {Code} */
-  // @ts-ignore
-  const value = [op, left, right];
-  value.location = {
+  const location = {
     source: left.location.source,
     start: left.location.start,
     end: right.location.end,
   };
 
-  return value;
+  return annotate([op, left, right], location);
 }
 
 /**
- * @param {Code} target
+ * Create a function call.
+ *
+ * @param {AnnotatedCode} target
  * @param {any[]} args
  */
 export function makeCall(target, args) {
@@ -162,10 +172,6 @@ export function makeCall(target, args) {
     throw error;
   }
 
-  const source = target.location.source;
-  let start = target.location.start;
-  let end = target.location.end;
-
   let fnCall;
   if (args[0] === ops.traverse) {
     let tree = target;
@@ -196,18 +202,21 @@ export function makeCall(target, args) {
   }
 
   // Create a location spanning the newly-constructed function call.
+  const location = { ...target.location };
   if (args instanceof Array) {
-    // @ts-ignore
-    end = args.location?.end ?? args.at(-1)?.location?.end;
+    let end;
+    if ("location" in args) {
+      end = /** @type {any} */ (args).location.end;
+    } else if ("location" in args.at(-1)) {
+      end = args.at(-1).location.end;
+    }
     if (end === undefined) {
       throw "Internal parser error: no location for function call argument";
     }
+    location.end = end;
   }
 
-  // @ts-ignore
-  annotate(fnCall, { start, source, end });
-
-  return fnCall;
+  return annotate(fnCall, location);
 }
 
 /**
@@ -215,25 +224,32 @@ export function makeCall(target, args) {
  * the arguments until the function is called. Exception: if the argument is a
  * literal, we leave it alone.
  *
- * @param {any[]} args
+ * @param {AnnotatedCode[]} 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;
+    const lambdaParameters = annotate([], arg.location);
+    /** @type {AnnotatedCodeItem} */
+    const fn = [ops.lambda, lambdaParameters, arg];
+    return annotate(fn, arg.location);
   });
 }
 
-export function makeObject(entries, op) {
+/**
+ * Make an object.
+ *
+ * @param {AnnotatedCode[]} entries
+ * @param {CodeLocation} location
+ */
+export function makeObject(entries, location) {
   let currentEntries = [];
   const spreads = [];
 
-  for (let [key, value] of entries) {
+  for (let entry of entries) {
+    const [key, value] = entry;
     if (key === ops.spread) {
       if (value[0] === ops.object) {
         // Spread of an object; fold into current object
@@ -241,7 +257,10 @@ export function makeObject(entries, op) {
       } else {
         // Spread of a tree; accumulate
         if (currentEntries.length > 0) {
-          spreads.push([op, ...currentEntries]);
+          const location = { ...currentEntries[0].location };
+          location.end = currentEntries[currentEntries.length - 1].location.end;
+          const spread = annotate([ops.object, ...currentEntries], location);
+          spreads.push(spread);
           currentEntries = [];
         }
         spreads.push(value);
@@ -256,39 +275,50 @@ export function makeObject(entries, op) {
         value[1][0] === ops.literal
       ) {
         // Optimize a getter for a primitive value to a regular property
-        value = value[1];
+        entry = annotate([key, value[1]], entry.location);
       }
     }
 
-    currentEntries.push([key, value]);
+    currentEntries.push(entry);
   }
 
   // Finish any current entries.
   if (currentEntries.length > 0) {
-    spreads.push([op, ...currentEntries]);
+    const location = { ...currentEntries[0].location };
+    location.end = currentEntries[currentEntries.length - 1].location.end;
+    const spread = annotate([ops.object, ...currentEntries], location);
+    spreads.push(spread);
     currentEntries = [];
   }
 
+  let code;
   if (spreads.length > 1) {
-    return [ops.merge, ...spreads];
-  }
-  if (spreads.length === 1) {
-    return spreads[0];
+    // Merge multiple spreads
+    code = [ops.merge, ...spreads];
+  } else if (spreads.length === 1) {
+    // A single spread can just be the object
+    code = spreads[0];
   } else {
-    return [op];
+    // Empty object
+    code = [ops.object];
   }
+
+  return annotate(code, location);
 }
 
-// Similar to a function call, but the order is reversed.
+/**
+ * Make a pipline: similar to a function call, but the order is reversed.
+ *
+ * @param {AnnotatedCode} arg
+ * @param {AnnotatedCode} fn
+ */
 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;
+  return annotate(result, { start, source, end });
 }
 
 // Define a property on an object.
@@ -312,38 +342,55 @@ export function makeReference(identifier) {
   return [op, identifier];
 }
 
-export function makeTemplate(op, head, tail) {
-  const strings = [head];
+/**
+ * Make a template
+ *
+ * @param {any} op
+ * @param {AnnotatedCode} head
+ * @param {AnnotatedCode} tail
+ * @param {CodeLocation} location
+ */
+export function makeTemplate(op, head, tail, location) {
+  const strings = [head[1]];
   const values = [];
-  for (const [value, string] of tail) {
-    values.push([ops.concat, value]);
-    strings.push(string);
+  for (const [value, literal] of tail) {
+    const concat = annotate([ops.concat, value], value.location);
+    values.push(concat);
+    strings.push(literal[1]);
   }
-  return [op, [ops.literal, strings], ...values];
+  const stringsCode = annotate(strings, location);
+  /** @type {AnnotatedCodeItem} */
+  const fn = ops.literal;
+  const literalCode = annotate([fn, stringsCode], location);
+  return annotate([op, literalCode, ...values], location);
 }
 
-export function makeUnaryOperation(operator, value) {
+/**
+ * Make a unary operation.
+ *
+ * @param {AnnotatedCode} operator
+ * @param {AnnotatedCode} value
+ * @param {CodeLocation} location
+ */
+export function makeUnaryOperation(operator, value, location) {
   const operators = {
     "!": ops.logicalNot,
     "+": ops.unaryPlus,
     "-": ops.unaryMinus,
     "~": ops.bitwiseNot,
   };
-  return [operators[operator], value];
+  return annotate([operators[operator], value], location);
 }
 
 /**
  * Upgrade a potential builtin reference to an actual builtin reference.
  *
- * @param {Code} code
+ * @param {AnnotatedCode} 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;
+    return annotate(result, code.location);
   } else {
     return code;
   }

package/src/runtime/errors.js

@@ -79,13 +79,16 @@ export function formatError(error) {
   // Add location
   if (location) {
     let { source, start } = location;
+    // Adjust line number with offset if present (for example, if the code is in
+    // an Origami template document with front matter that was stripped)
+    let line = start.line + (source.offset ?? 0);
     if (!fragmentInMessage) {
       message += `\nevaluating: ${fragment}`;
     }
     if (typeof source === "object" && source.url) {
-      message += `\n    at ${source.url.href}:${start.line}:${start.column}`;
+      message += `\n    at ${source.url.href}:${line}:${start.column}`;
     } else if (source.text.includes("\n")) {
-      message += `\n    at line ${start.line}, column ${start.column}`;
+      message += `\n    at line ${line}, column ${start.column}`;
     }
   }
 

package/src/runtime/evaluate.js

@@ -9,7 +9,7 @@ import { codeSymbol, scopeSymbol, sourceSymbol } from "./symbols.js";
  * `this` should be the tree used as the context for the evaluation.
  *
  * @this {import("@weborigami/types").AsyncTree|null}
- * @param {import("../../index.ts").Code} code
+ * @param {import("../../index.ts").AnnotatedCode} code
  */
 export default async function evaluate(code) {
   const tree = this;
@@ -54,15 +54,6 @@ export default async function evaluate(code) {
     fn = await fn.unpack();
   }
 
-  if (!Tree.isTreelike(fn)) {
-    const text = fn.toString?.() ?? codeFragment(code[0].location);
-    const error = new TypeError(
-      `Not a callable function or tree: ${text.slice(0, 80)}`
-    );
-    /** @type {any} */ (error).location = code.location;
-    throw error;
-  }
-
   // Execute the function or traverse the tree.
   let result;
   try {

package/src/runtime/expressionFunction.js

@@ -5,7 +5,7 @@ import { evaluate } from "./internal.js";
 /**
  * Given parsed Origami code, return a function that executes that code.
  *
- * @param {import("../../index.js").Code} code - parsed Origami expression
+ * @param {import("../../index.js").AnnotatedCode} code - parsed Origami expression
  * @param {string} [name] - optional name of the function
  */
 export function createExpressionFunction(code, name) {

package/src/runtime/ops.js

@@ -1,7 +1,8 @@
 /**
- * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
+ * @typedef {import("../../index.ts").AnnotatedCode} AnnotatedCode
  * @typedef {import("@weborigami/async-tree").PlainObject} PlainObject
  * @typedef {import("@weborigami/async-tree").Treelike} Treelike
+ * @typedef {import("@weborigami/types").AsyncTree} AsyncTree
  */
 
 import {
@@ -83,6 +84,7 @@ export async function builtin(key) {
 
   return value;
 }
+addOpLabel(builtin, "«ops.builtin»");
 
 /**
  * JavaScript comma operator, returns the last argument.
@@ -107,7 +109,8 @@ export async function concat(...args) {
 addOpLabel(concat, "«ops.concat»");
 
 export async function conditional(condition, truthy, falsy) {
-  return condition ? truthy() : falsy();
+  const value = condition ? truthy : falsy;
+  return value instanceof Function ? await value() : value;
 }
 
 export function division(a, b) {
@@ -154,6 +157,7 @@ export async function external(path, code, cache) {
 
   return value;
 }
+addOpLabel(external, "«ops.external»");
 
 /**
  * This op is only used during parsing. It signals to ops.object that the
@@ -181,6 +185,7 @@ export async function homeDirectory() {
   tree.parent = this ? Tree.root(this) : null;
   return tree;
 }
+addOpLabel(homeDirectory, "«ops.homeDirectory»");
 
 /**
  * Search the parent's scope -- i.e., exclude the current tree -- for the given
@@ -201,10 +206,9 @@ addOpLabel(inherited, "«ops.inherited»");
 /**
  * Return a function that will invoke the given code.
  *
- * @typedef {import("../../index.ts").Code} Code
  * @this {AsyncTree|null}
  * @param {string[]} parameters
- * @param {Code} code
+ * @param {AnnotatedCode} code
  */
 export function lambda(parameters, code) {
   const context = this;
@@ -271,6 +275,9 @@ addOpLabel(lessThanOrEqual, "«ops.lessThanOrEqual»");
 
 /**
  * Return a primitive value
+ *
+ * This op is optimized away during compilation, with the exception of array
+ * literals.
  */
 export async function literal(value) {
   return value;
@@ -296,6 +303,7 @@ export async function logicalAnd(head, ...tail) {
   // Return the last value (not `true`)
   return lastValue;
 }
+addOpLabel(logicalAnd, "«ops.logicalAnd»");
 
 /**
  * Logical NOT operator
@@ -303,6 +311,7 @@ export async function logicalAnd(head, ...tail) {
 export async function logicalNot(value) {
   return !value;
 }
+addOpLabel(logicalNot, "«ops.logicalNot»");
 
 /**
  * Logical OR operator
@@ -323,12 +332,13 @@ export async function logicalOr(head, ...tail) {
 
   return lastValue;
 }
+addOpLabel(logicalOr, "«ops.logicalOr»");
 
 /**
  * Merge the given trees. If they are all plain objects, return a plain object.
  *
  * @this {AsyncTree|null}
- * @param {Code[]} codes
+ * @param {AnnotatedCode[]} codes
  */
 export async function merge(...codes) {
   // First pass: evaluate the direct property entries in a single object
@@ -400,6 +410,7 @@ export async function nullishCoalescing(head, ...tail) {
 
   return lastValue;
 }
+addOpLabel(nullishCoalescing, "«ops.nullishCoalescing»");
 
 /**
  * Construct an object. The keys will be the same as the given `obj`
@@ -432,6 +443,7 @@ export async function rootDirectory(key) {
   tree.parent = this ? Tree.root(this) : null;
   return key ? tree.get(key) : tree;
 }
+addOpLabel(rootDirectory, "«ops.rootDirectory»");
 
 /**
  * Look up the given key in the scope for the current tree.
@@ -527,3 +539,4 @@ addOpLabel(unaryPlus, "«ops.unaryPlus»");
 export async function unpack(value) {
   return isUnpackable(value) ? value.unpack() : value;
 }
+addOpLabel(unpack, "«ops.unpack»");

package/test/compiler/{stripCodeLocations.js → codeHelpers.js}

@@ -1,4 +1,28 @@
 import { isPlainObject } from "@weborigami/async-tree";
+import assert from "node:assert";
+
+export function assertCodeEqual(actual, expected) {
+  const actualStripped = stripCodeLocations(actual);
+  const expectedStripped = stripCodeLocations(expected);
+  assert.deepEqual(actualStripped, expectedStripped);
+}
+
+/**
+ * Adds a fake source to code.
+ *
+ * @returns {import("../../index.ts").AnnotatedCode}
+ */
+export function createCode(array) {
+  const code = array;
+  /** @type {any} */ (code).location = {
+    end: 0,
+    source: {
+      text: "",
+    },
+    start: 0,
+  };
+  return code;
+}
 
 // For comparison purposes, strip the `location` property added by the parser.
 export function stripCodeLocations(parseResult) {

package/test/compiler/compile.test.js

@@ -3,7 +3,7 @@ import assert from "node:assert";
 import { describe, test } from "node:test";
 import * as compile from "../../src/compiler/compile.js";
 import { ops } from "../../src/runtime/internal.js";
-import { stripCodeLocations } from "./stripCodeLocations.js";
+import { assertCodeEqual } from "./codeHelpers.js";
 
 const shared = new ObjectTree({
   greet: (name) => `Hello, ${name}!`,
@@ -70,7 +70,7 @@ describe("compile", () => {
     let saved;
     const scope = new ObjectTree({
       tag: (strings, ...values) => {
-        assert.deepEqual(strings, ["Hello, ", "!"]);
+        assertCodeEqual(strings, ["Hello, ", "!"]);
         if (saved) {
           assert.equal(strings, saved);
         } else {
@@ -96,7 +96,7 @@ describe("compile", () => {
       },
     });
     const code = fn.code;
-    assert.deepEqual(stripCodeLocations(code), [ops.object, ["a", literal]]);
+    assertCodeEqual(code, [ops.object, ["a", 1]]);
   });
 });
 

package/test/compiler/optimize.test.js

@@ -1,9 +1,8 @@
-import assert from "node:assert";
 import { describe, test } from "node:test";
 import * as compile from "../../src/compiler/compile.js";
 import optimize from "../../src/compiler/optimize.js";
 import { ops } from "../../src/runtime/internal.js";
-import { stripCodeLocations } from "./stripCodeLocations.js";
+import { assertCodeEqual, createCode } from "./codeHelpers.js";
 
 describe("optimize", () => {
   test("optimize non-local ops.scope calls to ops.external", async () => {
@@ -17,12 +16,12 @@ describe("optimize", () => {
     `;
     const fn = compile.expression(expression);
     const code = fn.code;
-    assert.deepEqual(stripCodeLocations(code), [
+    assertCodeEqual(code, [
       ops.lambda,
       ["name"],
       [
         ops.object,
-        ["a", [ops.literal, 1]],
+        ["a", 1],
         ["b", [ops.scope, "a"]],
         ["c", [ops.external, "elsewhere", [ops.scope, "elsewhere"], {}]],
         ["d", [ops.scope, "name"]],
@@ -32,13 +31,12 @@ describe("optimize", () => {
 
   test("optimize scope traversals with all literal keys", async () => {
     // Compilation of `x/y.js`
-    const code = [ops.traverse, [ops.scope, "x/"], [ops.literal, "y.js"]];
-    const optimized = optimize(code);
-    assert.deepEqual(stripCodeLocations(optimized), [
-      ops.external,
-      "x/y.js",
-      code,
-      {},
+    const code = createCode([
+      ops.traverse,
+      [ops.scope, "x/"],
+      [ops.literal, "y.js"],
     ]);
+    const optimized = optimize(code);
+    assertCodeEqual(optimized, [ops.external, "x/y.js", code, {}]);
   });
 });