NamedArgs Object

class NamedArgs extends Map

Carries the named arguments of one call. It is a case-insensitive Map whose keys are the parameter names, and it behaves like one in every respect but one: passed as the last argument of a call, it supplies that call's named arguments instead of being passed as a value.

Writing f(Alpha: 1) creates one automatically. The class itself is needed only to build a named call whose names are decided at run time, or to inspect the names a variadic function collected. It is exported by the KS module:

#Import "Ks" { NamedArgs }

Table of Contents

NamedArgs()

NamedArgsObj := NamedArgs(Name1, Value1, Name2, Value2, ...)

Takes the same alternating name/value pairs as Map(). An empty container is legal; it supplies no named arguments.

CaseSense is always Off and cannot be changed.

Why the position matters

Only the last argument of a call supplies named arguments. A NamedArgs anywhere else, including one a variadic call places before a later positional argument, is an ordinary value.

The consequence is that a NamedArgs cannot be passed to a function as data: it would name that function's parameters.

Type(na)        ; error: na's names are not parameters of Type
Type([na])      ; "Array" — the Array is the argument, so the container is data inside it

To pass one as a value, pass the Array or object which holds it.

Examples

A named call built at run time. The name is not known until the script runs, so it cannot be written as Name: value syntax.

#Import "Ks" { NamedArgs }

Setting := "Title"
MsgBox("Save changes?", NamedArgs(Setting, "Confirm"))

Forwarding, then adding a name. The wrapper's collected arguments already contain the caller's names; adding one of its own unions the two.

#Import "Ks" { NamedArgs }

Confirm(Params*) {
    MsgBox(Params*, Options: "YesNo")
}
Confirm("Save changes?", Title: "Confirm")   ; both Title and Options reach MsgBox

Inspecting what a variadic function collected.

#Import "Ks" { NamedArgs }

Peek(Params*) {
    if Params.Length && Params[Params.Length] is NamedArgs {
        for Name, Value in Params[Params.Length]
            MsgBox Name ": " Value
    }
}
Peek("Save changes?", Title: "Confirm", Options: "OK")

Named parameters, Map, Func.Params, #Warn NamedArg, KS module