7.8.User functions %name(args) (Since 1.1.2)

A user function is a lexicon entry {name, arity, rules} that rewrites a call into script text. Expansion is a text pre-pass that runs before tokenizing (§7.2), so the token grammar never contains %.

• Call. % followed by ident and a parenthesized argument text that contains no parentheses. The % namespace is separate from $: %pause and $pause may coexist.
• Name. MUST match [A-Za-z_][A-Za-z0-9_]*, at most 64 characters (a store MAY truncate a longer name), unique case-insensitively; calls resolve case-insensitively.
• Rules. An ordered list of 1 to 200 {pattern, template} pairs. The argument text is split on ,, each argument trimmed, and the parts re-joined with ,. Rules are tried in order; the first whose pattern matches anywhere in that string wins (patterns are unanchored unless written with ^/$), and the call is replaced by its template.
• Templates. \1–\9 insert a capture group; \{1}–\{9} is the same, for use before a digit; \\ is a literal backslash. A reference to a group the pattern does not define is rejected when the function is saved; an unmatched optional group inserts nothing.
• Arity is 0–9 and is metadata only; it never gates matching.
• Passes. One pass replaces every call in the current text, left to right; text produced by a pass is scanned again only in the next pass. At most 32 passes run, and at most 500 substitutions are made per script. Calls left after 32 passes are an error (expansion too deep); exceeding 500 is an error (expanded too many items).
• Portable regex subset. A pattern MUST be at most 2000 characters and a template at most 4000; a store MAY truncate longer values. Patterns are matched over Unicode code points, with \d, \w, \s meaning their ASCII classes. A pattern MUST NOT use backreferences (\1–\9, \k), lookahead or lookbehind ((?=, (?!, (?<=, (?<!), named groups ((?P<, (?<, (?'), or any other (? form except the non-capturing (?:. Outside a character class, a backslash MAY only escape one of d D w W s S b B n r t f v 0 x u \ ^ $ . | ? * + ( ) [ ] { } /. A violating function is rejected when it is saved.
• Errors. An unknown function, a call whose arguments no rule matches, and a pattern that fails to compile are errors; the failed call is removed from the text and the error is reported with the script's other errors.