@rohal12/spindle 0.52.5 → 0.52.6

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

@@ -0,0 +1,280 @@
+/**
+ * The macro argument layer: reads a macro's raw argument text into the
+ * parameters its definition declares (see ParameterDef), so every macro
+ * splits and unquotes its arguments the same way. defineMacro() passes the
+ * result to the macro as `ctx.args`.
+ *
+ * Arguments are read in groups, split at `separator` parameters. A group's
+ * `flag` parameters are taken off its start or end first. Its last
+ * `expression` or `text` parameter (without one, its last parameter) reads
+ * the text the others leave; each parameter before it reads one term from
+ * the start, and each after it one term from the end. Terms are separated by
+ * whitespace outside literals and brackets (see arg-utils.ts), and a term
+ * that follows an operator belongs to the expression before it. A parameter
+ * with nothing to read is unset (a flag or separator is false, options are
+ * empty).
+ */
+import { parseDelay } from '../../utils/parse-delay';
+import type { MacroArgs, ParameterDef } from '../../registry';
+import {
+  endsWithOperator,
+  isWhitespace,
+  readQuoted,
+  readWholeQuoted,
+  stripLooseQuotes,
+  topLevelIndices,
+} from './arg-utils';
+
+type Span = [start: number, end: number];
+
+/** The terms of `src`: the runs of text between its depth-0 whitespace. */
+function terms(src: string): Span[] {
+  const spans: Span[] = [];
+  let start = 0;
+  for (const i of [...topLevelIndices(src, isWhitespace), src.length]) {
+    if (i > start) spans.push([start, i]);
+    start = i + 1;
+  }
+  return spans;
+}
+
+const slice = (src: string, [start, end]: Span) => src.slice(start, end);
+
+/**
+ * The value of a `text` argument: one quoted string, or the text with any
+ * loose quotes stripped (`"Red` → `Red`).
+ */
+export function readText(src: string): string {
+  return readWholeQuoted(src) ?? stripLooseQuotes(src);
+}
+
+function readValue(param: ParameterDef, src: string): unknown {
+  switch (param.type) {
+    case 'string':
+      return readWholeQuoted(src) ?? undefined;
+    case 'text':
+      return readText(src);
+    case 'names':
+      return src.split(',').map((name) => name.trim());
+    case 'delay':
+      return parseDelay(src);
+    case 'number':
+      return Number(src);
+    case 'options':
+      return readOptions(param.parameters ?? [], src);
+    default:
+      return src;
+  }
+}
+
+function unset(param: ParameterDef): unknown {
+  if (param.type === 'flag' || param.type === 'separator') return false;
+  return param.type === 'options' ? {} : undefined;
+}
+
+const WORD_RE = /\w+/y;
+const DIGITS_RE = /\d+/y;
+
+/** Match the sticky regex `re` at `pos`, returning the matched text. */
+function matchAt(re: RegExp, src: string, pos: number): string | null {
+  re.lastIndex = pos;
+  return re.exec(src)?.[0] ?? null;
+}
+
+/**
+ * Read keyword options (`goto "X" priority 5 once`). A keyword takes the
+ * quoted string or digit run after it as its value; keywords that aren't
+ * declared, and their values, are skipped.
+ */
+function readOptions(
+  params: readonly ParameterDef[],
+  src: string,
+): Record<string, unknown> {
+  const options: Record<string, unknown> = {};
+  let i = 0;
+  while (i < src.length) {
+    const key = matchAt(WORD_RE, src, i);
+    if (!key) {
+      // Skip whitespace and stray characters, or a stray quoted string.
+      i = readQuoted(src, i)?.end ?? i + 1;
+      continue;
+    }
+    i += key.length;
+
+    // A value is a quoted string or a digit run, after whitespace.
+    let val: string | undefined;
+    let j = i;
+    while (j < src.length && isWhitespace(src[j]!)) j++;
+    if (j > i) {
+      const quoted = readQuoted(src, j);
+      const digits = quoted ? null : matchAt(DIGITS_RE, src, j);
+      if (quoted) {
+        val = quoted.value;
+        i = quoted.end;
+      } else if (digits) {
+        val = digits;
+        i = j + digits.length;
+      }
+    }
+
+    const param = params.find((p) => p.name === key);
+    if (param?.type === 'flag') options[key] = true;
+    else if (param?.type === 'number') options[key] = Number(val ?? 0);
+    else if (param) options[key] = val;
+  }
+  return options;
+}
+
+/** `inline %name` reads a transient variable; `inline % 2` is modulo. */
+const LEADING_OPERATOR_RE = /^(?:[-+*/&|^=<>?:,.]|%(?![A-Za-z_]))/;
+
+/**
+ * The rest of `src` without the flag `word` as its last or first term, or
+ * `null` if it has no such flag. Next to a binary operator the word is an
+ * operand (`"a" + inline`), not a flag; the closing `/` of a regex literal
+ * is not one.
+ */
+function takeFlag(src: string, word: string): string | null {
+  const spans = terms(src);
+  if (spans.length < 2) return null;
+  if (slice(src, spans[spans.length - 1]!) === word) {
+    const rest = src.slice(0, spans[spans.length - 2]![1]);
+    if (!endsWithOperator(rest)) return rest;
+  }
+  if (slice(src, spans[0]!) === word) {
+    const rest = src.slice(spans[1]![0]);
+    if (!LEADING_OPERATOR_RE.test(rest)) return rest;
+  }
+  return null;
+}
+
+/**
+ * Where the separator `word` splits `src`, as the end of the text before it
+ * and the start of the text after it, or `null` if it doesn't. A word is a
+ * term with terms on both sides; `=` is an assignment at depth 0, not part
+ * of `==` or `!=`.
+ */
+function findSeparator(src: string, word: string): Span | null {
+  if (word === '=') {
+    const indices = topLevelIndices(src, (ch) => ch === '=');
+    for (let k = 0; k < indices.length; k++) {
+      const i = indices[k]!;
+      if (src[i + 1] === '=') {
+        k++;
+        continue;
+      }
+      if (src[i - 1] !== '!') return [i, i + 1];
+    }
+    return null;
+  }
+  const spans = terms(src);
+  for (let k = 1; k < spans.length - 1; k++) {
+    if (slice(src, spans[k]!) === word) {
+      return [spans[k - 1]![1], spans[k + 1]![0]];
+    }
+  }
+  return null;
+}
+
+const takesRest = (param: ParameterDef) =>
+  param.type === undefined ||
+  param.type === 'expression' ||
+  param.type === 'text';
+
+/** Read the parameters of one group from `src` (`null`: no text) into `args`. */
+function readGroup(
+  params: readonly ParameterDef[],
+  src: string | null,
+  args: Record<string, unknown>,
+): void {
+  let text = src?.trim() ?? '';
+  for (const flag of params.filter((p) => p.type === 'flag')) {
+    const rest = src === null ? null : takeFlag(text, flag.name);
+    args[flag.name] = rest !== null;
+    text = rest ?? text;
+  }
+  const positional = params.filter((p) => p.type !== 'flag');
+  if (positional.length === 0) return;
+
+  // The last expression or text parameter, else the last one, reads the rest.
+  const lastText = positional.findIndex(
+    (p, i) => takesRest(p) && !positional.slice(i + 1).some(takesRest),
+  );
+  const restIndex = lastText < 0 ? positional.length - 1 : lastText;
+  const read = (param: ParameterDef, value: string) =>
+    value === '' ? unset(param) : readValue(param, value);
+
+  // One parameter reads the whole text: no need to split it.
+  if (positional.length === 1) {
+    args[positional[0]!.name] = read(positional[0]!, text);
+    return;
+  }
+
+  const spans = terms(text);
+  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);
+  }
+  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]!))
+        : undefined;
+    args[param.name] = value ?? unset(param);
+    if (value !== undefined) to--;
+  }
+  const rest = positional[restIndex]!;
+  args[rest.name] =
+    from < to
+      ? read(rest, text.slice(spans[from]![0], spans[to - 1]![1]))
+      : unset(rest);
+}
+
+/** Read `rawArgs` into the declared `parameters` (see above). */
+export function parseMacroArgs<const P extends readonly ParameterDef[]>(
+  rawArgs: string,
+  parameters: P,
+): MacroArgs<P> {
+  const args: Record<string, unknown> = {};
+  // The text after the last separator read, null once one is missing
+  let rest: string | null = rawArgs.trim();
+  let groupStart = 0;
+  parameters.forEach((separator, i) => {
+    if (separator.type !== 'separator') return;
+    const at = rest === null ? null : findSeparator(rest, separator.name);
+    args[separator.name] = at !== null;
+    const before = at ? rest!.slice(0, at[0]) : rest;
+    readGroup(parameters.slice(groupStart, i), before, args);
+    rest = at ? rest!.slice(at[1]) : null;
+    groupStart = i + 1;
+  });
+  readGroup(parameters.slice(groupStart), rest, args);
+  return args as MacroArgs<P>;
+}
+
+/**
+ * The passage a passage-name argument names: the value of its expression
+ * or, when that can't be evaluated (`{goto Bob's room}`), its text.
+ */
+export function evaluatePassageName(
+  expr: string | undefined,
+  evaluate: (expr: string) => unknown,
+): string {
+  try {
+    return String(evaluate(expr ?? ''));
+  } catch {
+    return readText(expr ?? '');
+  }
+}
+
+/**
+ * The variable a `storeVar` macro binds: its first term, as written. Custom
+ * macros may bind one without declaring parameters.
+ */
+export function readBoundVariable(rawArgs: string): string {
+  const src = rawArgs.trim();
+  const first = terms(src)[0];
+  return first ? slice(src, first) : '';
+}

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

@@ -1,22 +1,17 @@
 import type { ASTNode } from '../../markup/ast';
 import { readWholeQuoted } from './arg-utils';
+import { parseMacroArgs } from './macro-args';
 
+/** `$var "placeholder"`, the arguments of the input macros. */
 export function parseVarArgs(rawArgs: string): {
   varName: string;
   placeholder: string;
 } {
-  // `s`: a quoted placeholder may span lines.
-  const match = rawArgs.match(/^\s*(["']?\$[\w.]+["']?)\s*(["'].*["'])?\s*$/s);
-  if (!match) {
-    return { varName: rawArgs.trim(), placeholder: '' };
-  }
-  const varName = match[1]!.replace(/["']/g, '');
-  // A quoted placeholder accepts \" \' and \\ escapes.
-  const quoted = match[2];
-  const placeholder = quoted
-    ? (readWholeQuoted(quoted) ?? quoted.slice(1, -1))
-    : '';
-  return { varName, placeholder };
+  const { variable = '', placeholder = '' } = parseMacroArgs(rawArgs, [
+    { name: 'variable', type: 'variable' },
+    { name: 'placeholder', type: 'string' },
+  ]);
+  return { varName: variable.replace(/["']/g, ''), placeholder };
 }
 
 /**

package/src/define-macro.ts

@@ -11,12 +11,9 @@ import {
 } from 'preact/hooks';
 import { useInterpolate } from './hooks/use-interpolate';
 import { useMergedLocals } from './hooks/use-merged-locals';
+import { useRenderOptions } from './hooks/use-render-options';
 import {
   LocalsUpdateContext,
-  LocalsValuesContext,
-  NobrContext,
-  InlineContext,
-  RawTextContext,
   renderNodes as _renderNodes,
   renderInlineNodes,
 } from './markup/render';
@@ -31,23 +28,34 @@ import type { UseActionOptions } from './hooks/use-action';
 import { collectText } from './utils/extract-text';
 import { currentSourceLocation } from './utils/source-location';
 import { parseVarArgs, extractOptions } from './components/macros/option-utils';
+import {
+  parseMacroArgs,
+  readBoundVariable,
+} from './components/macros/macro-args';
 import {
   registerMacro,
   registerMacroText,
   registerSubMacro,
   registerMacroMetadata,
 } from './registry';
-import type { MacroProps, MacroTextContext, ParameterDef } from './registry';
+import type {
+  MacroArgs,
+  MacroProps,
+  MacroTextContext,
+  ParameterDef,
+} from './registry';
 import { registerBlockMacro } from './markup/ast';
 
-export type { MacroTextContext };
+export type { MacroArgs, MacroTextContext, ParameterDef };
 
 export function macroClass(type: string, className?: string): string {
   const base = `macro-${type}`;
   return className ? `${base} ${className}` : base;
 }
 
-export interface MacroContext {
+export interface MacroContext<A = MacroArgs> {
+  /** The arguments, read into the declared parameters (see ParameterDef). */
+  args: A;
   className?: string;
   id?: string;
   resolve?: (s: string | undefined) => string | undefined;
@@ -86,7 +94,9 @@ export interface MacroContext {
   };
 }
 
-export interface MacroDefinition {
+export interface MacroDefinition<
+  P extends readonly ParameterDef[] = ParameterDef[],
+> {
   name: string;
   subMacros?: string[];
   block?: boolean;
@@ -94,14 +104,20 @@ export interface MacroDefinition {
   merged?: boolean;
   storeVar?: boolean;
   description?: string;
-  parameters?: ParameterDef[];
-  render: (props: MacroProps, ctx: MacroContext) => ComponentChildren;
+  parameters?: P;
+  render: (
+    props: MacroProps,
+    ctx: MacroContext<MacroArgs<P>>,
+  ) => ComponentChildren;
   /**
    * The macro's text form, used where markup becomes a string: HTML
    * attribute values, image alt text and link titles, macro labels. Without
    * one, the macro can't be used there and is reported as an error.
    */
-  text?: (props: MacroProps, ctx: MacroTextContext) => string;
+  text?: (
+    props: MacroProps,
+    ctx: MacroTextContext & { args: MacroArgs<P> },
+  ) => string;
 }
 
 const sharedHooks = {
@@ -114,10 +130,12 @@ const sharedHooks = {
   useContext,
 };
 
-export function defineMacro(
-  config: MacroDefinition,
+export function defineMacro<const P extends readonly ParameterDef[] = []>(
+  config: MacroDefinition<P>,
   source: 'builtin' | 'user' = 'builtin',
 ): void {
+  const parameters: readonly ParameterDef[] = config.parameters ?? [];
+
   function Wrapper(props: MacroProps) {
     // className/id resolved first (interpolate may transform them)
     let className = props.className;
@@ -131,10 +149,7 @@ export function defineMacro(
 
     // Always-on: cssClass + mutation
     const { update, getValues } = useContext(LocalsUpdateContext);
-    const nobr = useContext(NobrContext);
-    const inline = useContext(InlineContext);
-    const raw = useContext(RawTextContext);
-    const localsValues = useContext(LocalsValuesContext);
+    const renderOptions = useRenderOptions();
     const renderNodes = (
       nodes: ASTNode[],
       options?: {
@@ -143,15 +158,9 @@ export function defineMacro(
         inline?: boolean;
         raw?: boolean;
       },
-    ) =>
-      _renderNodes(nodes, {
-        nobr,
-        inline,
-        raw,
-        locals: localsValues,
-        ...options,
-      });
-    const ctx: MacroContext = {
+    ) => _renderNodes(nodes, { ...renderOptions, ...options });
+    const ctx: MacroContext<MacroArgs<P>> = {
+      args: parseMacroArgs(props.rawArgs, parameters) as MacroArgs<P>,
       collectText,
       sourceLocation: currentSourceLocation,
       parseVarArgs,
@@ -183,8 +192,7 @@ export function defineMacro(
     }
 
     if (config.storeVar) {
-      const firstToken =
-        props.rawArgs.trim().split(/\s+/)[0]?.replace(/["']/g, '') ?? '';
+      const firstToken = readBoundVariable(props.rawArgs).replace(/["']/g, '');
 
       if (firstToken.startsWith('%')) {
         return h(
@@ -220,7 +228,16 @@ export function defineMacro(
   }
 
   registerMacro(config.name, Wrapper);
-  registerMacroText(config.name, config.text);
+  const text = config.text;
+  registerMacroText(
+    config.name,
+    text &&
+      ((props, ctx) =>
+        text(props, {
+          ...ctx,
+          args: parseMacroArgs(props.rawArgs, parameters) as MacroArgs<P>,
+        })),
+  );
 
   // Store metadata for tooling API
   const isBlock =
@@ -234,7 +251,7 @@ export function defineMacro(
     interpolate: config.interpolate,
     merged: config.merged,
     description: config.description,
-    parameters: config.parameters,
+    parameters: config.parameters && [...config.parameters],
     source,
   });
 

package/src/hooks/use-render-options.ts

@@ -0,0 +1,26 @@
+import { useContext } from 'preact/hooks';
+import {
+  InlineContext,
+  LocalsValuesContext,
+  NobrContext,
+  RawTextContext,
+} from '../markup/render';
+
+/**
+ * The renderNodes() options of the enclosing content: nobr, inline and raw
+ * rendering and the locals in scope. A macro or widget body rendered with
+ * them renders as the content around it does.
+ */
+export function useRenderOptions(): {
+  nobr: boolean;
+  inline: boolean;
+  raw: boolean;
+  locals: Record<string, unknown>;
+} {
+  return {
+    nobr: useContext(NobrContext),
+    inline: useContext(InlineContext),
+    raw: useContext(RawTextContext),
+    locals: useContext(LocalsValuesContext),
+  };
+}

package/src/markup/render.tsx

@@ -9,6 +9,7 @@ import { markdownToHtml } from './markdown';
 import { h } from 'preact';
 import type { ASTNode, HtmlNode, MacroNode } from './ast';
 import { useTextScope } from '../hooks/use-interpolate';
+import { useRenderOptions } from '../hooks/use-render-options';
 import {
   hasInterpolation,
   interpolateCode,
@@ -524,11 +525,8 @@ function resolveAttributeValue(
 
 function HtmlNodeRenderer({ node }: { node: HtmlNode }) {
   const scope = useTextScope();
-  const nobr = useContext(NobrContext);
-  const locals = useContext(LocalsValuesContext);
-  const inRaw = useContext(RawTextContext);
+  const { nobr, locals, raw: inRaw, inline: parentInline } = useRenderOptions();
   const inSvg = useContext(SvgContext);
-  const parentInline = useContext(InlineContext);
   const tag = node.tag.toLowerCase();
   const isSvgRoot = tag === 'svg';
   const isRawRoot = !inRaw && (isSvgRoot || PREFORMATTED_ELEMENTS.has(tag));

package/src/registry.ts

@@ -67,12 +67,60 @@ export function isSubMacro(name: string): boolean {
   return subMacros.has(name.toLowerCase());
 }
 
+/**
+ * How a macro argument is read (see components/macros/macro-args.ts).
+ * Quoted strings accept `\"`, `\'` and `\\` escapes.
+ * - `expression`: code, as written (the default).
+ * - `variable`: a variable reference such as `$name` or `"$name"`, as written.
+ * - `string`: one quoted string; anything else leaves the argument unset.
+ * - `text`: one quoted string, or text with any loose quotes stripped.
+ * - `names`: a comma-separated list of names (`@item, @i`).
+ * - `delay`: a duration (`2s`, `500ms`, `300`) in milliseconds.
+ * - `number`: a number.
+ * - `flag`: a keyword, the parameter's name, at the start or end; a boolean.
+ * - `separator`: a word (`of`) or `=` separating the parameters before it
+ *   from those after it; a boolean.
+ * - `options`: keywords, the names of its `parameters`, each followed by a
+ *   quoted string or a number unless it is a flag.
+ */
+export type ParameterType =
+  | 'expression'
+  | 'variable'
+  | 'string'
+  | 'text'
+  | 'names'
+  | 'delay'
+  | 'number'
+  | 'flag'
+  | 'separator'
+  | 'options';
+
 export interface ParameterDef {
   name: string;
   required?: boolean;
   description?: string;
+  type?: ParameterType;
+  /** The options of an `options` parameter. */
+  parameters?: readonly ParameterDef[];
 }
 
+type ArgValue<T, D> = T extends 'flag' | 'separator'
+  ? boolean
+  : T extends 'names'
+    ? string[] | undefined
+    : T extends 'delay' | 'number'
+      ? number | undefined
+      : T extends 'options'
+        ? D extends { parameters: infer Q extends readonly ParameterDef[] }
+          ? Partial<MacroArgs<Q>>
+          : Partial<MacroArgs>
+        : string | undefined;
+
+/** The arguments of a macro declaring `parameters`, by parameter name. */
+export type MacroArgs<P extends readonly ParameterDef[] = ParameterDef[]> = {
+  [D in P[number] as D['name']]: ArgValue<D['type'], D>;
+};
+
 export interface MacroMetadata {
   name: string;
   block: boolean;