Named Arguments

A named argument is an argument passed under a name alongside its position. Code reads it with %<name>, or with r(<name>, args), where it would read %0 with %0 or r(0, args).

&FUN`ROW me=%<name> has %<count> posts.
think uargs(me/FUN`ROW, name, Bob, count, 3)

Output: Bob has 3 posts.

Names are case-insensitive: %<count> and %<COUNT> are the same argument.
The name inside %<...> is evaluated, so %<item[add(1,1)]> reads item2.
%<0> is %0, so a number reads the argument in that position.
A name nobody passed is empty.
Named arguments belong to one call, as %0-%9 do. The attribute’s own u() calls don’t see them, and nothing is left behind when it returns. Q-registers (setq()) stay set for the rest of the queue entry, so a value handed to a helper is better passed by name.

An unclosed %< is a parse error, as an unclosed %q< is.

Passing named arguments

Where	Passes
uargs(`<obj>/<attr>`, `<name>`, `<value>`, …)	each value by its name and by its position
@trigger/args `<obj>/<attr>`=`<name>`,`<value>`,…	each value by its name and by its position
@include/args `<obj>/<attr>`=`<name>`,`<value>`,…	each value by its name and position, on top of the caller’s arguments
stepargs(`<obj>/<attr>`, `<list>`, `<names>`)	each run’s elements under `<names>` and by position

&FUN`PAIR me=%<name>=%<count>
think stepargs(me/FUN`PAIR,Bob 3 Alice 1,name count,,|)

Output: Bob=3|Alice=1

&DO`GREET me=&LAST`GREETING me=Welcome, %<who>.
@include/args me/DO`GREET=who,Bob
think get(me/LAST`GREETING)

Output: Welcome, Bob.

Included and repeated arguments

@include/args passes the arguments it names on top of the caller’s. @include/args me/X=who,Bob makes %<who> Bob and %0 Bob, and leaves the caller’s %1 and the rest as they were. @include/chain/args works the same way.

A name given twice keeps both values in their positions, and the name reads the last one. A name that is a number must be its value’s own position, counted from 0.

hasarg() tells whether an argument exists, even an empty one, and whether this call was passed it or only sees it from its caller.

With @trigger/match/args, the pattern’s captures come first, as %0, %1 and so on, and the named values then replace the positions they take. Captures they do not replace stay. The string being matched is not one of the arguments.

Naming a function’s arguments

A global function made with @function gets its arguments as %0, %1 and so on. @function/args <function>=<names> also passes them under space-separated names, in order. Needs the config.admin permission. Owner-local functions use @function/local/args <name>=<names> with the same signature grammar and their existing owner scope. Redefining the function clears its names, so set them after it in the same @startup.

&FN`GREET me=Hello, %<who>. You have %<count> new posts.
@function greet=me,FN`GREET
@function/args greet=who count
think greet(Bob,3)

Output: Hello, Bob. You have 3 new posts.

%0 and %1 still hold Bob and 3. @function/args greet= clears the names, and @function greet lists them.

The rest of the arguments

The last name can take every argument after the ones before it. These are the shapes the built-in functions’ own parameter lists use, as an editor shows them (switch() reads string, expression...|list..., default):

Last name	The rest arrive as
`items...`	`items1`, `items2`, …, and their number as `itemscount`
`key...\|value...`	dealt out in turn: `key1`, `value1`, `key2`, `value2`, …, each with its count (`keycount`, `valuecount`)
`case...\|result... default`	as above, and `default` takes the argument left over after whole groups, as switch() does
`...`	name and value pairs the caller names

&FN`GLUE me=[iter(lnum(1,%<itemscount>),%<items##>,%b,%<sep>)]
@function glue=me,FN`GLUE
@function/args glue=sep items...
think glue(-,a,b c,d)

Output: a-b c-d

&FN`LABELS me=[iter(lnum(1,%<keycount>),%<key##>: %<value##>,%b,%b|%b)]
@function labels=me,FN`LABELS
@function/args labels=key...|value...
think labels(Name,Bob,Rank,Captain)

Output: Name: Bob | Rank: Captain

Defaults, caller names and errors

A default after the groups takes the argument left over:

&FN`PICK me=[firstof(trim(iter(lnum(1,%<casecount>),if(strmatch(%<value>,%<case##>),%<result##>))),%<default>)]
@function pick=me,FN`PICK
@function/args pick=value case...|result... default
think pick(b,a,1,b,2,none)
think pick(c,a,1,b,2,none)

Output: 2, then none.

With a bare ..., the caller picks the names, as with uargs():

&FN`CARD me=%<title>: %<name>, %<rank>
@function card=me,FN`CARD
@function/args card=title ...
think card(Crew,name,Bob,rank,Captain)

Output: Crew: Bob, Captain

A call that leaves a pair unfinished returns #-1 NAMED ARGUMENTS COME IN PAIRS. A pair whose name is empty, a number, or one of the function’s own names returns #-1 ARGUMENT NAME INVALID.

@function/args returns #-1 ARGUMENT NAME INVALID for repeated/numeric names, multiple rest groups, names after items..., or collisions with generated slots (key1, keycount). Rest prefixes must also produce distinct slots.

Naming a command’s arguments

An @hook reads its command’s arguments as LS, RS, LSA1, LSA2 and the others in @hook registers. @command/args <command>=<names> names them as well, in order: the left side, then each right-side argument. The rest shapes above work here too. It needs the config.admin permission and lasts until the server restarts, like the other @command switches.

&HOOK`CHOWN me=[attrib_set(me/LAST`CHOWN,%<attribute> to %<owner>)]
@command/args @atrchown=attribute owner
@hook/before @atrchown=me,HOOK`CHOWN
&NOTE me=hello
@atrchown me/NOTE=me
think get(me/LAST`CHOWN)

Output: me/NOTE to me

A hook can’t refuse its command, so when a command named with ... is given an unfinished pair, its hook gets none of the pairs.

Arguments the game names

@hook attributes: ARGS, LS, RS, EQUALS, SWITCHES, LSAC and LSA<n> (see @hook registers).
@http callbacks: %<status> and %<content-type>, with the body in %0 (see [@http]).
@input callbacks: %<reason> (see @input).
Event handlers: each argument by the name the event shows, such as %<destination> for object`move (see event list).
@feed tie-ins and taps: %<id>, %<key>, %<speaker>, %<style>, %<text>, %<name> and the rest of their table (see @feed tie-ins).
The http_handler: %<path>, %<body>, %<viewer>, %<headers> and %<hdr.<name>> for each header (see [http requests]).
@chatformat and MOGRIFY`FORMAT: %<type>, %<channel>, %<message>, %<name>, %<title>, %<default>, %<says>, %<options> (see @chatformat, mogrifier).
The other MOGRIFY` attributes: the same names, and %<value> for the part being rewritten (see mogrifier).

Arguments formats and queries name

@pageformat and @outpageformat: %<message>, %<type>, %<alias>, %<recipients>, %<default> (see @pageformat).
@speechmod: %<message>, %<type> (see @speechmod).
@mailfilter: %<sender>, %<subject>, %<body>, %<flags> (see @mailfilter).
Look formats: @nameformat’s %<object> and %<name>, @descformat’s and @idescformat’s %<description>, @conformat’s %<contents> and %<names>, @exitformat’s %<exits> (see @nameformat).
rendermarkdowncustom() templates: %<text>, %<url> and the other names in their list (see rendermarkdowncustom()).
Regexp $-commands: each named capture.
mapsql(): each column, by its name.

::: seealso