@rohal12/spindle 0.56.0 → 0.57.0

package/dist/pkg/headless.js

@@ -16468,9 +16468,23 @@ var slice = (src, [start, end]) => src.slice(start, end);
 function readText(src) {
 	return readWholeQuoted(src) ?? stripLooseQuotes(src);
 }
+/**
+* An argument that doesn't have its parameter's form: a `string` parameter
+* given anything but one quoted string.
+*/
+var MacroArgumentError = class extends Error {
+	constructor(param, src) {
+		super(`The ${param.name} must be a quoted string ("…" or '…'), not ${src}`);
+		this.name = "MacroArgumentError";
+	}
+};
 function readValue(param, src) {
 	switch (param.type) {
-		case "string": return readWholeQuoted(src) ?? void 0;
+		case "string": {
+			const value = readWholeQuoted(src);
+			if (value === null) throw new MacroArgumentError(param, src);
+			return value;
+		}
 		case "text": return readText(src);
 		case "names": return src.split(",").map((name) => name.trim());
 		case "delay": return parseDelay(src);
@@ -16592,8 +16606,16 @@ function readGroup(params, src, args) {
 	let from = 0;
 	let to = spans.length;
 	for (const param of positional.slice(0, restIndex)) args[param.name] = from < to ? read(param, slice(text, spans[from++])) : unset(param);
+	const readTrailing = (param, value) => {
+		try {
+			return read(param, value);
+		} catch (error) {
+			if (error instanceof MacroArgumentError) return void 0;
+			throw error;
+		}
+	};
 	for (const param of positional.slice(restIndex + 1).reverse()) {
-		const value = from < to && !endsWithOperator(text.slice(0, spans[to - 1][0])) ? read(param, slice(text, spans[to - 1])) : void 0;
+		const value = from < to && !endsWithOperator(text.slice(0, spans[to - 1][0])) ? readTrailing(param, slice(text, spans[to - 1])) : void 0;
 		args[param.name] = value ?? unset(param);
 		if (value !== void 0) to--;
 	}
@@ -16662,8 +16684,11 @@ function parseVarArgs(rawArgs) {
 /** The parameters of an `{option}` sub-macro: its value. */
 var OPTION_PARAMETERS = [{
 	name: "value",
-	type: "string"
+	type: "string",
+	required: true
 }];
+/** The parameters of the built-in sub-macros that take arguments. */
+var SUB_MACRO_PARAMETERS = { option: OPTION_PARAMETERS };
 /**
 * Walk AST children to find {option} macro nodes, returning their values.
 */
@@ -16671,7 +16696,7 @@ function extractOptions(children) {
 	const options = [];
 	for (const node of children) if (node.type === "macro" && node.name === "option") {
 		const { value } = parseMacroArgs(node.rawArgs, OPTION_PARAMETERS);
-		options.push(value ?? node.rawArgs.trim().replace(/^(["'])(.+)\1$/s, "$2"));
+		options.push(value ?? "");
 	}
 	return options;
 }
@@ -16708,8 +16733,18 @@ function defineMacro(config, source = "builtin") {
 			...renderOptions,
 			...options
 		});
+		let args;
+		try {
+			args = parseMacroArgs(props.rawArgs, parameters);
+		} catch (error) {
+			if (error instanceof MacroArgumentError) return h(MacroError, {
+				macro: config.name,
+				error
+			});
+			throw error;
+		}
 		const ctx = {
-			args: parseMacroArgs(props.rawArgs, parameters),
+			args,
 			collectText,
 			sourceLocation: currentSourceLocation,
 			parseVarArgs,
@@ -16748,7 +16783,15 @@ function defineMacro(config, source = "builtin") {
 				});
 			};
 		}
-		return config.render(props, ctx);
+		try {
+			return config.render(props, ctx);
+		} catch (error) {
+			if (error instanceof MacroArgumentError) return h(MacroError, {
+				macro: config.name,
+				error
+			});
+			throw error;
+		}
 	}
 	registerMacro(config.name, Wrapper);
 	const text = config.text;
@@ -17118,10 +17161,7 @@ var CODE_IN_STRINGS = { watch: {
 	run: "statements"
 } };
 /** The `string` parameters of a macro that name a passage. */
-var PASSAGE_STRINGS = {
-	link: ["passage"],
-	watch: ["goto", "dialog"]
-};
+var PASSAGE_STRINGS = { watch: ["goto", "dialog"] };
 /** Block macros whose body is the name of a passage. */
 var PASSAGE_BODIES = new Set(["dialog"]);
 /** The goal of the code an argument of this type holds, if it is code. */
@@ -17225,7 +17265,19 @@ function* codeAndText(src, tokens, parametersOf) {
 }
 /** The code and text in the arguments `args` (at `offset`) of `macro`. */
 function* argPieces(args, offset, params, macro, label) {
-	const values = parseMacroArgs(args, params);
+	let values;
+	try {
+		values = parseMacroArgs(args, params);
+	} catch (error) {
+		if (!(error instanceof MacroArgumentError)) throw error;
+		yield {
+			kind: "argument-error",
+			message: error.message,
+			offset,
+			label
+		};
+		return;
+	}
 	const inStrings = CODE_IN_STRINGS[macro.toLowerCase()] ?? {};
 	const passageStrings = PASSAGE_STRINGS[macro.toLowerCase()] ?? [];
 	let cursor = 0;
@@ -17725,7 +17777,7 @@ function validateMarkup(passages, options) {
 			report(passage, base + token.start, `${where}Unknown macro {${token.name}}.${didYouMean(token.name, names, (n) => `{${n}}`)}`);
 		}
 	};
-	const parametersOf = options.parametersOf ?? (() => void 0);
+	const parametersOf = (name) => options.parametersOf?.(name) ?? SUB_MACRO_PARAMETERS[name.toLowerCase()];
 	/**
 	* Check `tokens`, the tokens of `src`, which starts at `base` in the
 	* passage: their macros, the code in them and the markup in their text.
@@ -17734,6 +17786,10 @@ function validateMarkup(passages, options) {
 		checkMacros(passage, tokens, base, where);
 		for (const piece of codeAndText(src, tokens, parametersOf)) {
 			const at = base + piece.offset;
+			if (piece.kind === "argument-error") {
+				report(passage, at, `${where}${piece.message} in ${piece.label}`);
+				continue;
+			}
 			if (piece.kind === "passage") {
 				if (options.checkPassageNames !== false && !passageNames.has(piece.name)) {
 					const hint = didYouMean(piece.name, passageNames, JSON.stringify);
@@ -18403,18 +18459,24 @@ defineMacro({
 	name: "link",
 	block: true,
 	interpolate: true,
+	merged: true,
 	parameters: [{
 		name: "text",
 		type: "string",
 		required: true
 	}, {
 		name: "passage",
-		type: "string"
+		type: "passage"
 	}],
-	render({ rawArgs, children = [] }, ctx) {
-		const { text } = ctx.args;
-		const display = text ?? rawArgs.trim();
-		const passage = text === void 0 ? null : ctx.args.passage ?? null;
+	render({ children = [] }, ctx) {
+		const display = ctx.args.text ?? "";
+		let passage = null;
+		let failure;
+		if (ctx.args.passage !== void 0) try {
+			passage = evaluatePassageName(ctx.args.passage, ctx.evaluate, useStoryStore.getState());
+		} catch (error) {
+			failure = { error };
+		}
 		const runBody = useDetachedBody();
 		const perform = () => {
 			runBody(children);
@@ -18432,6 +18494,10 @@ defineMacro({
 			target: passage ?? void 0,
 			perform
 		});
+		if (failure) return /* @__PURE__ */ jsx(MacroError, {
+			macro: "link",
+			error: failure.error
+		});
 		return /* @__PURE__ */ jsx("a", {
 			id: ctx.id,
 			class: ctx.cls,

package/dist/pkg/macro-registry.json

@@ -145,6 +145,7 @@
     "block": true,
     "subMacros": [],
     "interpolate": true,
+    "merged": true,
     "parameters": [
       {
         "name": "text",
@@ -153,7 +154,7 @@
       },
       {
         "name": "passage",
-        "type": "string"
+        "type": "passage"
       }
     ],
     "source": "builtin"

package/dist/pkg/story-variables.js

@@ -9756,9 +9756,23 @@ var slice = (src, [start, end]) => src.slice(start, end);
 function readText(src) {
 	return readWholeQuoted(src) ?? stripLooseQuotes(src);
 }
+/**
+* An argument that doesn't have its parameter's form: a `string` parameter
+* given anything but one quoted string.
+*/
+var MacroArgumentError = class extends Error {
+	constructor(param, src) {
+		super(`The ${param.name} must be a quoted string ("…" or '…'), not ${src}`);
+		this.name = "MacroArgumentError";
+	}
+};
 function readValue(param, src) {
 	switch (param.type) {
-		case "string": return readWholeQuoted(src) ?? void 0;
+		case "string": {
+			const value = readWholeQuoted(src);
+			if (value === null) throw new MacroArgumentError(param, src);
+			return value;
+		}
 		case "text": return readText(src);
 		case "names": return src.split(",").map((name) => name.trim());
 		case "delay": return parseDelay(src);
@@ -9880,8 +9894,16 @@ function readGroup(params, src, args) {
 	let from = 0;
 	let to = spans.length;
 	for (const param of positional.slice(0, restIndex)) args[param.name] = from < to ? read(param, slice(text, spans[from++])) : unset(param);
+	const readTrailing = (param, value) => {
+		try {
+			return read(param, value);
+		} catch (error) {
+			if (error instanceof MacroArgumentError) return void 0;
+			throw error;
+		}
+	};
 	for (const param of positional.slice(restIndex + 1).reverse()) {
-		const value = from < to && !endsWithOperator(text.slice(0, spans[to - 1][0])) ? read(param, slice(text, spans[to - 1])) : void 0;
+		const value = from < to && !endsWithOperator(text.slice(0, spans[to - 1][0])) ? readTrailing(param, slice(text, spans[to - 1])) : void 0;
 		args[param.name] = value ?? unset(param);
 		if (value !== void 0) to--;
 	}
@@ -9993,10 +10015,7 @@ var CODE_IN_STRINGS = { watch: {
 	run: "statements"
 } };
 /** The `string` parameters of a macro that name a passage. */
-var PASSAGE_STRINGS = {
-	link: ["passage"],
-	watch: ["goto", "dialog"]
-};
+var PASSAGE_STRINGS = { watch: ["goto", "dialog"] };
 /** Block macros whose body is the name of a passage. */
 var PASSAGE_BODIES = new Set(["dialog"]);
 /** The goal of the code an argument of this type holds, if it is code. */
@@ -10100,7 +10119,19 @@ function* codeAndText(src, tokens, parametersOf) {
 }
 /** The code and text in the arguments `args` (at `offset`) of `macro`. */
 function* argPieces(args, offset, params, macro, label) {
-	const values = parseMacroArgs(args, params);
+	let values;
+	try {
+		values = parseMacroArgs(args, params);
+	} catch (error) {
+		if (!(error instanceof MacroArgumentError)) throw error;
+		yield {
+			kind: "argument-error",
+			message: error.message,
+			offset,
+			label
+		};
+		return;
+	}
 	const inStrings = CODE_IN_STRINGS[macro.toLowerCase()] ?? {};
 	const passageStrings = PASSAGE_STRINGS[macro.toLowerCase()] ?? [];
 	let cursor = 0;
@@ -10154,6 +10185,12 @@ function locate(text, part, from) {
 	const anywhere = text.indexOf(part);
 	return anywhere >= 0 ? anywhere : from;
 }
+/** The parameters of the built-in sub-macros that take arguments. */
+var SUB_MACRO_PARAMETERS = { option: [{
+	name: "value",
+	type: "string",
+	required: true
+}] };
 //#endregion
 //#region src/markup/validate.ts
 /**
@@ -10275,7 +10312,7 @@ function validateMarkup(passages, options) {
 			report(passage, base + token.start, `${where}Unknown macro {${token.name}}.${didYouMean(token.name, names, (n) => `{${n}}`)}`);
 		}
 	};
-	const parametersOf = options.parametersOf ?? (() => void 0);
+	const parametersOf = (name) => options.parametersOf?.(name) ?? SUB_MACRO_PARAMETERS[name.toLowerCase()];
 	/**
 	* Check `tokens`, the tokens of `src`, which starts at `base` in the
 	* passage: their macros, the code in them and the markup in their text.
@@ -10284,6 +10321,10 @@ function validateMarkup(passages, options) {
 		checkMacros(passage, tokens, base, where);
 		for (const piece of codeAndText(src, tokens, parametersOf)) {
 			const at = base + piece.offset;
+			if (piece.kind === "argument-error") {
+				report(passage, at, `${where}${piece.message} in ${piece.label}`);
+				continue;
+			}
 			if (piece.kind === "passage") {
 				if (options.checkPassageNames !== false && !passageNames.has(piece.name)) {
 					const hint = didYouMean(piece.name, passageNames, JSON.stringify);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rohal12/spindle",
-  "version": "0.56.0",
+  "version": "0.57.0",
   "type": "module",
   "description": "A Preact-based story format for Twine 2.",
   "license": "Unlicense",

package/src/code-check.ts

@@ -29,7 +29,10 @@ import { isCodeAttribute, splitSigilTemplate } from './markup/code-attributes';
 import { CodeSyntaxError, parseCode, type JsGoal } from './js-lexer';
 import type { ParsedCode } from './js-lexer';
 import type { ParameterDef } from './registry';
-import { parseMacroArgs } from './components/macros/macro-args';
+import {
+  MacroArgumentError,
+  parseMacroArgs,
+} from './components/macros/macro-args';
 import { readWholeQuoted } from './components/macros/arg-utils';
 
 /** While a pass runs: the code it parsed so far, by goal and source. */
@@ -88,6 +91,15 @@ export interface PassagePiece {
   label: string;
 }
 
+/** Macro arguments that don't have their parameters' forms. */
+export interface ArgumentErrorPiece {
+  kind: 'argument-error';
+  message: string;
+  offset: number;
+  /** The markup it is in, for the error: `{link Go}`. */
+  label: string;
+}
+
 /** Text in markup that may hold markup of its own, at `offset` in it. */
 export interface TextPiece {
   kind: 'text';
@@ -107,14 +119,13 @@ const CODE_IN_STRINGS: Record<string, Record<string, JsGoal>> = {
 
 /** The `string` parameters of a macro that name a passage. */
 const PASSAGE_STRINGS: Record<string, readonly string[]> = {
-  link: ['passage'],
   watch: ['goto', 'dialog'],
 };
 
 /** Block macros whose body is the name of a passage. */
 const PASSAGE_BODIES = new Set(['dialog']);
 
-type Piece = CodePiece | TextPiece | PassagePiece;
+type Piece = CodePiece | TextPiece | PassagePiece | ArgumentErrorPiece;
 
 /** The goal of the code an argument of this type holds, if it is code. */
 function codeGoal(param: ParameterDef): JsGoal | undefined {
@@ -246,7 +257,14 @@ function* argPieces(
   macro: string,
   label: string,
 ): Generator<Piece> {
-  const values = parseMacroArgs(args, params) as Record<string, unknown>;
+  let values: Record<string, unknown>;
+  try {
+    values = parseMacroArgs(args, params) as Record<string, unknown>;
+  } catch (error) {
+    if (!(error instanceof MacroArgumentError)) throw error;
+    yield { kind: 'argument-error', message: error.message, offset, label };
+    return;
+  }
   const inStrings = CODE_IN_STRINGS[macro.toLowerCase()] ?? {};
   const passageStrings = PASSAGE_STRINGS[macro.toLowerCase()] ?? [];
   let cursor = 0;

package/src/components/macros/MacroLink.tsx

@@ -1,21 +1,36 @@
 import { useStoryStore } from '../../store';
 import { defineMacro } from '../../define-macro';
 import { useDetachedBody } from './detached-body';
+import { evaluatePassageName } from './macro-args';
+import { MacroError } from './MacroError';
 
 defineMacro({
   name: 'link',
   block: true,
   interpolate: true,
-  // {link "text" "Passage"} or {link "text"}; unquoted, the whole arguments
-  // are the text.
+  merged: true,
+  // {link "text" passage} or {link "text"}; the passage is a quoted name or
+  // an expression, as in {goto}.
   parameters: [
     { name: 'text', type: 'string', required: true },
-    { name: 'passage', type: 'string' },
+    { name: 'passage', type: 'passage' },
   ],
-  render({ rawArgs, children = [] }, ctx) {
-    const { text } = ctx.args;
-    const display = text ?? rawArgs.trim();
-    const passage = text === undefined ? null : (ctx.args.passage ?? null);
+  render({ children = [] }, ctx) {
+    const display = ctx.args.text ?? '';
+    let passage: string | null = null;
+    // Boxed: anything can be thrown, including null and other falsy values
+    let failure: { error: unknown } | undefined;
+    if (ctx.args.passage !== undefined) {
+      try {
+        passage = evaluatePassageName(
+          ctx.args.passage,
+          ctx.evaluate!,
+          useStoryStore.getState(),
+        );
+      } catch (error) {
+        failure = { error };
+      }
+    }
     const runBody = useDetachedBody();
 
     const perform = () => {
@@ -39,6 +54,14 @@ defineMacro({
       perform,
     });
 
+    if (failure) {
+      return (
+        <MacroError
+          macro="link"
+          error={failure.error}
+        />
+      );
+    }
     return (
       <a
         id={ctx.id}

package/src/components/macros/macro-args.ts

@@ -50,10 +50,24 @@ export function readText(src: string): string {
   return readWholeQuoted(src) ?? stripLooseQuotes(src);
 }
 
+/**
+ * An argument that doesn't have its parameter's form: a `string` parameter
+ * given anything but one quoted string.
+ */
+export class MacroArgumentError extends Error {
+  constructor(param: ParameterDef, src: string) {
+    super(`The ${param.name} must be a quoted string ("…" or '…'), not ${src}`);
+    this.name = 'MacroArgumentError';
+  }
+}
+
 function readValue(param: ParameterDef, src: string): unknown {
   switch (param.type) {
-    case 'string':
-      return readWholeQuoted(src) ?? undefined;
+    case 'string': {
+      const value = readWholeQuoted(src);
+      if (value === null) throw new MacroArgumentError(param, src);
+      return value;
+    }
     case 'text':
       return readText(src);
     case 'names':
@@ -220,10 +234,20 @@ function readGroup(
     args[param.name] =
       from < to ? read(param, slice(text, spans[from++]!)) : unset(param);
   }
+  // Optional ones at the end: a term that doesn't have their form (a
+  // `string` that isn't quoted) belongs to the rest, as in {meter $hp 100}
+  const readTrailing = (param: ParameterDef, value: string) => {
+    try {
+      return read(param, value);
+    } catch (error) {
+      if (error instanceof MacroArgumentError) return undefined;
+      throw error;
+    }
+  };
   for (const param of positional.slice(restIndex + 1).reverse()) {
     const value =
       from < to && !endsWithOperator(text.slice(0, spans[to - 1]![0]))
-        ? read(param, slice(text, spans[to - 1]!))
+        ? readTrailing(param, slice(text, spans[to - 1]!))
         : undefined;
     args[param.name] = value ?? unset(param);
     if (value !== undefined) to--;

package/src/components/macros/option-utils.ts

@@ -1,5 +1,6 @@
 import type { ASTNode } from '../../markup/ast';
 import { parseMacroArgs } from './macro-args';
+import type { ParameterDef } from '../../registry';
 
 /** `$var "placeholder"`, the arguments of the input macros. */
 export function parseVarArgs(rawArgs: string): {
@@ -14,7 +15,14 @@ export function parseVarArgs(rawArgs: string): {
 }
 
 /** The parameters of an `{option}` sub-macro: its value. */
-const OPTION_PARAMETERS = [{ name: 'value', type: 'string' }] as const;
+const OPTION_PARAMETERS = [
+  { name: 'value', type: 'string', required: true },
+] as const;
+
+/** The parameters of the built-in sub-macros that take arguments. */
+export const SUB_MACRO_PARAMETERS: Record<string, readonly ParameterDef[]> = {
+  option: OPTION_PARAMETERS,
+};
 
 /**
  * Walk AST children to find {option} macro nodes, returning their values.
@@ -23,12 +31,9 @@ export function extractOptions(children: ASTNode[]): string[] {
   const options: string[] = [];
   for (const node of children) {
     if (node.type === 'macro' && node.name === 'option') {
-      // {option "Long Sword"} gives `Long Sword`. A value that isn't one
-      // quoted string loses a matching pair of quotes around it, if any.
+      // {option "Long Sword"} gives `Long Sword`
       const { value } = parseMacroArgs(node.rawArgs, OPTION_PARAMETERS);
-      options.push(
-        value ?? node.rawArgs.trim().replace(/^(["'])(.+)\1$/s, '$2'),
-      );
+      options.push(value ?? '');
     }
   }
   return options;

package/src/define-macro.ts

@@ -30,9 +30,11 @@ import { currentSourceLocation } from './utils/source-location';
 import { parseVarArgs, extractOptions } from './components/macros/option-utils';
 import { wrapContent } from './components/macros/display';
 import {
+  MacroArgumentError,
   parseMacroArgs,
   readBoundVariable,
 } from './components/macros/macro-args';
+import { MacroError } from './components/macros/MacroError';
 import {
   checkParameterTypes,
   registerMacro,
@@ -162,8 +164,18 @@ export function defineMacro<const P extends readonly ParameterDef[] = []>(
         raw?: boolean;
       },
     ) => _renderNodes(nodes, { ...renderOptions, ...options });
+    let args: MacroArgs<P>;
+    try {
+      args = parseMacroArgs(props.rawArgs, parameters) as MacroArgs<P>;
+    } catch (error) {
+      // Shown in place, as other macro errors are
+      if (error instanceof MacroArgumentError) {
+        return h(MacroError, { macro: config.name, error });
+      }
+      throw error;
+    }
     const ctx: MacroContext<MacroArgs<P>> = {
-      args: parseMacroArgs(props.rawArgs, parameters) as MacroArgs<P>,
+      args,
       collectText,
       sourceLocation: currentSourceLocation,
       parseVarArgs,
@@ -224,7 +236,15 @@ export function defineMacro<const P extends readonly ParameterDef[] = []>(
       };
     }
 
-    return config.render(props, ctx);
+    try {
+      return config.render(props, ctx);
+    } catch (error) {
+      // An argument read while rendering, e.g. a sub-macro's ({option})
+      if (error instanceof MacroArgumentError) {
+        return h(MacroError, { macro: config.name, error });
+      }
+      throw error;
+    }
   }
 
   registerMacro(config.name, Wrapper);

package/src/markup/validate.ts

@@ -11,6 +11,7 @@ import { parseWidgetDef } from '../widgets/widget-def';
 import { codeAndText, parseOrError, withParseCache } from '../code-check';
 import { CodeSyntaxError } from '../js-lexer';
 import type { ParameterDef } from '../registry';
+import { SUB_MACRO_PARAMETERS } from '../components/macros/option-utils';
 
 /** A passage to validate. */
 export interface MarkupPassage {
@@ -220,7 +221,8 @@ export function validateMarkup(
     }
   };
 
-  const parametersOf = options.parametersOf ?? (() => undefined);
+  const parametersOf = (name: string) =>
+    options.parametersOf?.(name) ?? SUB_MACRO_PARAMETERS[name.toLowerCase()];
 
   /**
    * Check `tokens`, the tokens of `src`, which starts at `base` in the
@@ -236,6 +238,10 @@ export function validateMarkup(
     checkMacros(passage, tokens, base, where);
     for (const piece of codeAndText(src, tokens, parametersOf)) {
       const at = base + piece.offset;
+      if (piece.kind === 'argument-error') {
+        report(passage, at, `${where}${piece.message} in ${piece.label}`);
+        continue;
+      }
       if (piece.kind === 'passage') {
         if (
           options.checkPassageNames !== false &&