@weborigami/language 0.0.41 → 0.0.43

package/index.ts

@@ -3,6 +3,15 @@ import { StringLike } from "../async-tree/index.js";
 
 export * from "./main.js";
 
+/**
+ * A chunk of compiled Origami code. This is just an Array with an additional
+ * `source` property.
+ */
+interface ArrayWithSource extends Array<any> {
+  source?: Source;
+}
+export type Code = ArrayWithSource;
+
 /**
  * A class constructor is an object with a `new` method that returns an
  * instance of the indicated type.
@@ -32,3 +41,12 @@ export type FileUnpackFunction = (
 export type Mixin<MixinMembers> = <T>(
   Base: Constructor<T>
 ) => Constructor<T & MixinMembers>;
+
+/**
+ * Source code representation used by the parser.
+ */
+export type Source = {
+  name: string;
+  text: string;
+  url: URL;
+}

package/main.js

@@ -17,5 +17,5 @@ export { default as concatTreeValues } from "./src/runtime/concatTreeValues.js";
 export { default as evaluate } from "./src/runtime/evaluate.js";
 export * as expressionFunction from "./src/runtime/expressionFunction.js";
 export { default as extname } from "./src/runtime/extname.js";
-export { default as format } from "./src/runtime/format.js";
+export { default as formatError } from "./src/runtime/formatError.js";
 export { default as functionResultsMap } from "./src/runtime/functionResultsMap.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weborigami/language",
-  "version": "0.0.41",
+  "version": "0.0.43",
   "description": "Web Origami expression language compiler and runtime",
   "type": "module",
   "main": "./main.js",
@@ -10,8 +10,8 @@
     "typescript": "5.3.3"
   },
   "dependencies": {
-    "@weborigami/async-tree": "0.0.41",
-    "@weborigami/types": "0.0.41",
+    "@weborigami/async-tree": "0.0.43",
+    "@weborigami/types": "0.0.43",
     "peggy": "3.0.2",
     "watcher": "2.3.0"
   },

package/src/compiler/compile.js

@@ -1,21 +1,27 @@
 import { createExpressionFunction } from "../runtime/expressionFunction.js";
 import { parse } from "./parse.js";
 
-function compile(text, startRule) {
+function compile(source, startRule) {
+  if (typeof source === "string") {
+    source = { text: source };
+  }
   // Trim whitespace from template blocks before we begin lexing, as our
   // heuristics are non-local and hard to implement in our parser.
-  const preprocessed = trimTemplateWhitespace(text);
-  const code = parse(preprocessed, { startRule });
+  const preprocessed = trimTemplateWhitespace(source.text);
+  const code = parse(preprocessed, {
+    grammarSource: source,
+    startRule,
+  });
   const fn = createExpressionFunction(code);
   return fn;
 }
 
-export function expression(text) {
-  return compile(text, "expression");
+export function expression(source) {
+  return compile(source, "expression");
 }
 
-export function templateDocument(text) {
-  return compile(text, "templateDocument");
+export function templateDocument(source) {
+  return compile(source, "templateDocument");
 }
 
 // Trim the whitespace around and in substitution blocks in a template. There's
@@ -24,14 +30,14 @@ export function templateDocument(text) {
 //
 // Example:
 //
-//     {{ if `
+//     ${ if `
 //       true text
 //     `, `
 //       false text
-//     ` }}
+//     ` }
 //
 // Case 1: a substitution that starts the text or starts a line (there's only
-// whitespace before the `{{`), and has the line end with the start of a
+// whitespace before the `${`), and has the line end with the start of a
 // template literal (there's only whitespace after the backtick) marks the start
 // of a block.
 //
@@ -39,17 +45,17 @@ export function templateDocument(text) {
 // another is an internal break in the block. Edge case: three backticks in a
 // row, like ```, are common in markdown and are not treated as a break.
 //
-// Case 3: a line that ends a template literal and ends with `}}` or ends the
+// Case 3: a line that ends a template literal and ends with `}` or ends the
 // text marks the end of the block.
 //
 // In all three cases, we trim spaces and tabs from the start and end of the
 // line. In case 1, we also remove the preceding newline.
 function trimTemplateWhitespace(text) {
-  const regex1 = /(^|\n)[ \t]*({{.*?`)[ \t]*\n/g;
+  const regex1 = /(^|\n)[ \t]*((?:{{|\${).*?`)[ \t]*\n/g;
   const regex2 = /\n[ \t]*(`(?!`).*?`)[ \t]*\n/g;
-  const regex3 = /\n[ \t]*(`(?!`).*?}})[ \t]*(?:\n|$)/g;
+  const regex3js = /\n[ \t]*(`(?!`).*?(?:}}|[^\\]}))[ \t]*(?:\n|$)/g;
   const trimBlockStarts = text.replace(regex1, "$1$2");
   const trimBlockBreaks = trimBlockStarts.replace(regex2, "\n$1");
-  const trimBlockEnds = trimBlockBreaks.replace(regex3, "\n$1");
+  const trimBlockEnds = trimBlockBreaks.replace(regex3js, "\n$1");
   return trimBlockEnds;
 }

package/src/compiler/origami.pegjs

@@ -7,7 +7,17 @@
 //
 
 import * as ops from "../runtime/ops.js";
-import { makeFunctionCall, makeTemplate } from "./parserHelpers.js";
+import { makeFunctionCall, makePipeline, makeTemplate } from "./parserHelpers.js";
+
+// 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.
+function annotate(parseResult, location) {
+  if (typeof parseResult === "object" && parseResult !== null) {
+    parseResult.location = location;
+  }
+  return parseResult;
+}
+
 }}
 
 // A block of optional whitespace
@@ -15,12 +25,23 @@ __
   = (inlineSpace / newLine / comment)*  { return ""; }
 
 // A filesystem path that begins with a slash: `/foo/bar`
+// We take care to avoid treating two consecutive leading slashes as a path;
+// that starts a comment.
 absoluteFilePath "absolute file path"
-  = path:leadingSlashPath { return [[ops.filesRoot], ...path]; }
+  = !"//" path:leadingSlashPath {
+      return annotate([[ops.filesRoot], ...path], location());
+    }
 
 args "function arguments"
   = parensArgs
-  / path:leadingSlashPath { return [ops.traverse, ...path]; }
+  / path:leadingSlashPath {
+      return annotate([ops.traverse, ...path], location());
+    }
+
+array "array"
+  = "[" __ list:list? __ closingBracket {
+      return annotate([ops.array, ...(list ?? [])], location());
+    }
 
 // An assignment statement: `foo = 1`
 assignment "tree assignment"
@@ -28,10 +49,9 @@ assignment "tree assignment"
 
 assignmentOrShorthand
   = assignment
-  / key:identifier { return [key, [ops.inherited, key]]; }
-
-array "array"
-  = "[" __ list:list? "]" { return [ops.array, ...(list ?? [])]; }
+  / key:identifier {
+      return annotate([key, [ops.inherited, key]], location());
+    }
 
 // Something that can be called. This is more restrictive than the `expr`
 // parser; it doesn't accept regular function calls.
@@ -46,13 +66,41 @@ callTarget "function call"
   / group
   / scopeReference
 
+// Required closing curly brace. We use this for the `tree` term: it's the last
+// term in the `step` parser that starts with a curly brace, so if that parser
+// sees a left curly brace, here we must see a right curly brace.
+closingBrace
+  = "}"
+  / .? {
+    error("Expected right curly brace");
+  }
+
+// Required closing bracket
+closingBracket
+  = "]"
+  / .? {
+    error("Expected right bracket");
+  }
+
+// Required closing parenthesis. We use this for the `group` term: it's the last
+// term in the `step` parser that starts with a parenthesis, so if that parser
+// sees a left parenthesis, here we must see a right parenthesis.
+closingParen
+  = ")"
+  / .? {
+    error("Expected right parenthesis");
+  }
+
 // A single line comment
 comment "comment"
-  = "#" [^\n\r]*
+  = multiLineComment
+  / singleLineComment
 
 digits
   = @[0-9]+
 
+doubleArrow = "⇒" / "=>"
+
 doubleQuoteString "double quote string"
   = '"' chars:doubleQuoteStringChar* '"' { return chars.join(""); }
 
@@ -63,27 +111,8 @@ escapedChar "backslash-escaped character"
   = "\\" @.
 
 // An Origami expression, no leading/trailing whitespace
-expr "expression"
-  // Try function calls first, as they can start with expression types that
-  // follow (array, object, etc.); we want to parse the largest thing first.
-  = implicitParensCall
-  / functionComposition
-  // Then try parsers that look for a distinctive token at the start: an opening
-  // slash, bracket, curly brace, etc.
-  / absoluteFilePath
-  / array
-  / object
-  / tree
-  / templateLiteral
-  / lambda
-  / parameterizedLambda
-  / group
-  / string
-  / number
-  // Protocol calls are distinguished by a colon, but it's not at the start.
-  / protocolCall
-  // Least distinctive option is a simple scope reference, so it comes last.
-  / scopeReference
+expr
+  = pipeline
 
 // Top-level Origami expression, possible leading/trailing whitepsace.
 expression "Origami expression"
@@ -97,36 +126,36 @@ float "floating-point number"
 // Parse a function and its arguments, e.g. `fn(arg)`, possibly part of a chain
 // of function calls, like `fn(arg1)(arg2)(arg3)`.
 functionComposition "function composition"
-  // = target:callTarget chain:argsChain { return makeFunctionCall(target, chain); }
-  = target:callTarget chain:args+ { return makeFunctionCall(target, chain); }
+  = target:callTarget chain:args* end:implicitParensArgs? {
+    if (end) {
+      chain.push(end);
+    }
+    return annotate(makeFunctionCall(target, chain), location());
+  }
 
 // An expression in parentheses: `(foo)`
 group "parenthetical group"
-  = "(" __ @expr __ ")"
+  = "(" __ @expr __ closingParen
+
+// A host identifier that may include a colon and port number: `example.com:80`.
+// This is used as a special case at the head of a path, where we want to
+// interpret a colon as part of a text identifier.
+host "HTTP/HTTPS host"
+  = identifier (":" number)? { return text(); }
 
 identifier "identifier"
   = chars:identifierChar+ { return chars.join(""); }
 
 identifierChar
-  = [^(){}\[\]<>,/:=\`"'\\# \t\n\r] // No unescaped whitespace or special chars
+  = [^(){}\[\]<>\-=,/:\`"'\\# →⇒\t\n\r] // No unescaped whitespace or special chars
+  / @'-' !'>' // Accept a hyphen but not in a single arrow combination
   / escapedChar
 
 identifierList
-  = head:identifier tail:(separator @identifier)* separator? {
-    return [head].concat(tail);
-  }
-
-// A function call with implicit parentheses: `fn 1, 2, 3`
-implicitParensCall "function call with implicit parentheses"
-  = target:(functionComposition / callTarget) inlineSpace+ args:list {
-      return [target, ...args];
-    }
+  = @identifier|1.., separator| separator?
 
-// A host identifier that may include a colon and port number: `example.com:80`.
-// This is used as a special case at the head of a path, where we want to
-// interpret a colon as part of a text identifier.
-host "HTTP/HTTPS host"
-  = identifier (":" number)? { return text(); }
+implicitParensArgs "arguments with implicit parentheses"
+  = inlineSpace+ @list
 
 inlineSpace
   = [ \t]
@@ -138,16 +167,21 @@ integer "integer"
 
 // A lambda expression: `=foo()`
 lambda "lambda function"
-  = "=" __ expr:expr { return [ops.lambda, null, expr]; }
+  = "=" __ expr:expr {
+      return annotate([ops.lambda, null, expr], location());
+    }
 
 // A path that begins with a slash: `/foo/bar`
 leadingSlashPath "path with a leading slash"
   = "/" @path
-  / "/" { return [""]; }
+  / "/" { return annotate([""], location()); }
 
 // A separated list of expressions
 list "list"
-  = head:expr tail:(separator @expr)* separator? { return [head].concat(tail); }
+  = @expr|1.., separator| separator?
+
+multiLineComment
+  = "/*" (!"*/" .)* "*/" { return null; }
 
 newLine
   = "\n"
@@ -164,13 +198,13 @@ number "number"
 // TODO: Use Object.fromEntries with array of key/value pairs
 //
 object "object literal"
-  = "{" __ properties:objectProperties? "}" { return [ops.object, ...(properties ?? [])]; }
+  = "{" __ properties:objectProperties? __ "}" {
+      return annotate([ops.object, ...(properties ?? [])], location());
+    }
 
 // A separated list of object properties or shorthands
 objectProperties
-  = head:objectPropertyOrShorthand tail:(separator @objectPropertyOrShorthand)* separator? __ {
-      return [head].concat(tail);
-    }
+  = @objectPropertyOrShorthand|1.., separator| separator?
 
 // A single object property with key and value: `x: 1`
 objectProperty "object property"
@@ -178,28 +212,29 @@ objectProperty "object property"
 
 objectPropertyOrShorthand
   = objectProperty
-  / key:identifier { return [key, [ops.scope, key]]; }
+  / key:identifier {
+      return annotate([key, [ops.scope, key]], location());
+    }
 
 parameterizedLambda
-  = "(" __ parameters:identifierList? ")" __ ("=>"/"⇒") __ expr:expr {
-    return [ops.lambda, parameters ?? [], expr];
+  = "(" __ parameters:identifierList? __ ")" __ doubleArrow __ expr:expr {
+    return annotate([ops.lambda, parameters ?? [], expr], location());
   }
 
 // Function arguments in parentheses
 parensArgs "function arguments in parentheses"
-  = "(" __ list:list? ")" { return list ?? [undefined]; }
-
-separator
-  = __ "," __
-  / whitespaceWithNewLine
+  = "(" __ list:list? __ ")" {
+      return list ?? annotate([undefined], location());
+    }
 
-sign
-  = [+\-]
+pipeline
+  = steps:(@step|1.., __ singleArrow __ |) {
+      return annotate(makePipeline(steps), location());
+    }
 
 // A slash-separated path of keys
 path "slash-separated path"
-  = head:pathKey "/" tail:path { return [head].concat(tail); }
-  / key:pathKey { return [key]; }
+  = pathKey|1.., "/"|
 
 // A single key in a slash-separated path
 pathKey "path element"
@@ -209,7 +244,7 @@ pathKey "path element"
 // There can be zero, one, or two slashes after the colon.
 protocolCall "function call using protocol: syntax"
   = protocol:protocol ":" "/"|0..2| host:host path:leadingSlashPath? {
-      return [protocol, host, ...(path ?? [])];
+      return annotate([protocol, host, ...(path ?? [])], location());
     }
 
 protocol "protocol"
@@ -225,7 +260,22 @@ reservedProtocol "reserved protocol"
   / "tree" { return ops.treeHttps; } // Alias
 
 scopeReference "scope reference"
-  = key:identifier { return [ops.scope, key]; }
+  = key:identifier {
+      return annotate([ops.scope, key], location());
+    }
+
+separator
+  = __ "," __
+  / whitespaceWithNewLine
+
+sign
+  = [+\-]
+
+singleArrow = "→" / "->"
+
+singleLineComment
+  = "#" [^\n\r]* { return null; }
+  / "//" [^\n\r]* { return null; }
 
 singleQuoteString "single quote string"
   = "'" chars:singleQuoteStringChar* "'" { return chars.join(""); }
@@ -233,6 +283,29 @@ singleQuoteString "single quote string"
 singleQuoteStringChar
   = !("'" / newLine) @textChar
 
+// A single step in a pipeline, or a top-level expression
+step
+  // Literals that can't start a function call
+  = number
+  // Try functions next; they can start with expression types that follow
+  // (array, object, etc.), and we want to parse the larger thing first.
+  / functionComposition
+  // Then try parsers that look for a distinctive token at the start: an opening
+  // slash, bracket, curly brace, etc.
+  / absoluteFilePath
+  / array
+  / object
+  / tree
+  / lambda
+  / parameterizedLambda
+  / templateLiteral
+  / string
+  / group
+  // Protocol calls are distinguished by a colon, but it's not at the start.
+  / protocolCall
+  // Least distinctive option is a simple scope reference, so it comes last.
+  / scopeReference
+
 start
   = number
 
@@ -243,15 +316,19 @@ string "string"
 // A top-level document defining a template. This is the same as a template
 // literal, but can contain backticks at the top level.
 templateDocument "template"
-  = contents:templateDocumentContents { return [ops.lambda, null, contents]; }
+  = contents:templateDocumentContents {
+      return annotate([ops.lambda, null, contents], location());
+    }
 
 // Template documents can contain backticks at the top level.
 templateDocumentChar
-  = !"{{" @textChar
+  = !("{{" / "${") @textChar
 
 // The contents of a template document containing plain text and substitutions
 templateDocumentContents
-  = parts:(templateDocumentText / templateSubstitution)* { return makeTemplate(parts); }
+  = parts:(templateDocumentText / templateSubstitution)* {
+      return annotate(makeTemplate(parts), location());
+    }
 
 templateDocumentText "template text"
   = chars:templateDocumentChar+ { return chars.join(""); }
@@ -261,11 +338,13 @@ templateLiteral "template literal"
   = "`" @templateLiteralContents "`"
 
 templateLiteralChar
-  = !("`" / "{{") @textChar
+  = !("`" / "{{" / "${") @textChar
 
 // The contents of a template literal containing plain text and substitutions
 templateLiteralContents
-  = parts:(templateLiteralText / templateSubstitution)* { return makeTemplate(parts); }
+  = parts:(templateLiteralText / templateSubstitution)* {
+      return annotate(makeTemplate(parts), location());
+    }
 
 // Plain text in a template literal
 templateLiteralText
@@ -274,19 +353,20 @@ templateLiteralText
 // A substitution in a template literal: `{{ fn() }}`
 templateSubstitution "template substitution"
   = "{{" @expression "}}"
+  / "${" @expression "}"
 
 textChar
   = escapedChar / .
 
 // A tree literal: `{ index.html = "Hello" }`
 tree "tree literal"
-  = "{" __ assignments:treeAssignments? "}" { return [ops.tree, ...(assignments ?? [])]; }
+  = "{" __ assignments:treeAssignments? __ closingBrace {
+      return annotate([ops.tree, ...(assignments ?? [])], location());
+    }
 
 // A separated list of assignments or shorthands
 treeAssignments
-  = head:assignmentOrShorthand tail:(separator @assignmentOrShorthand)* separator? __ {
-      return [head].concat(tail);
-    }
+  = @assignmentOrShorthand|1.., separator| separator?
 
 whitespaceWithNewLine
   = inlineSpace* comment? newLine __

package/src/compiler/parse.d.ts

@@ -0,0 +1,3 @@
+import { Code } from "../../index.ts";
+
+export function parse(input: string, options: any): Code;