class Capture
Argument list suitable for passing to a Signature
A Capture
is a container for passing arguments to a code object. Captures are the flip-side of Signatures – Captures are the caller defined arguments, while Signatures are the callee defined parameters.
When you call print $a, $b
, the $a, $b
part is a Capture.
Captures contain a list-like part for positional arguments and a hash-like part for named arguments, thus behaving as Positional and Associative, although it does not actually mixes in those roles. For the named arguments, Captures use a slightly different syntax than a normal List. There are two easy ways to make a named argument: 1) use an unquoted key naming a parameter, followed by =>
, followed by the argument and 2) use a colon-pair literal named after the parameter:
say unique 1, -2, 2, 3, as => ; # OUTPUT: «(1 -2 3)»# ... is the same thing as:say unique 1, -2, 2, 3, :as(); # OUTPUT: «(1 -2 3)»# Be careful not to quote the name of a named parameter:say unique 1, -2, 2, 3, 'as' => ;# OUTPUT: «(1 -2 2 3 as => -> ;; $_? is raw { #`(Block|78857320) ... })»
A stand-alone Capture can also be made, stored, and used later. A literal Capture can be created by prefixing a term with a backslash \
. Commonly, this term will be a List of terms, from which any Pair literal will be placed in the named part, and all other terms will be placed in the positional part.
my = \(42); # Capture with one positional part= \(1, 2, a => 'b'); # Capture with two positional and one named parts
To use such a Capture, you may use '|'
before it in a function call, and it will be as if the values in the Capture were passed directly to the function as arguments – named arguments will be passed as named arguments and positional arguments will be passed as positional arguments. You may re-use the Capture as many times as you want, even with different functions.
my = \(4, 2, 3);reverse(|).say; # OUTPUT: «3 2 4»sort(5,|).say; # OUTPUT: «2 3 4 5»
Inside a Signature, a Capture may be created by prefixing a sigilless parameter with a vertical bar |
. This packs the remainder of the argument list into that parameter.
f(1, 2, 3, a => 4, b => 5);sub f(, |c)
Note that Captures are still Lists in that they may contain containers, not just values:
my = 1;my = \(4, 2, , 3);sort(|).say; # OUTPUT: «1 2 3 4»= 6;sort(|).say; # OUTPUT: «2 3 4 6»
Methods
method list
Defined as:
method list(Capture:)
Returns the positional part of the Capture.
my Capture = \(2, 3, 5, apples => (red => 2));say .list; # OUTPUT: «(2 3 5)»
method hash
Defined as:
method hash(Capture:)
Returns the named/hash part of the Capture.
my Capture = \(2, 3, 5, apples => (red => 2));say .hash; # OUTPUT: «Map.new((:apples(:red(2))))»
method elems
Defined as:
method elems(Capture: --> Int)
Returns the number of positional elements in the Capture.
my Capture = \(2, 3, 5, apples => (red => 2));say .elems; # OUTPUT: «3»
method keys
Defined as:
multi method keys(Capture: --> Seq)
Returns a Seq containing all positional keys followed by all named keys. For positional arguments the keys are the respective arguments ordinal position starting from zero.
my = \(2, 3, 5, apples => (red => 2));say .keys; # OUTPUT: «(0 1 2 apples)»
method values
Defined as:
multi method values(Capture: --> Seq)
Returns a Seq containing all positional values followed by all named argument values.
my = \(2, 3, 5, apples => (red => 2));say .values; # OUTPUT: «(2 3 5 red => 2)»
method kv
Defined as:
multi method kv(Capture: --> Seq)
Returns a Seq of alternating keys and values. The positional keys and values, if any, comes first followed by the named keys and values.
my = \(2, 3, apples => (red => 2));say .kv; # OUTPUT: «(0 2 1 3 apples red => 2)»
method pairs
Defined as:
multi method pairs(Capture: --> Seq)
Returns all arguments, the positional followed by the named, as a Seq of Pairs. Positional arguments have their respective ordinal value, starting at zero, as key while the named arguments have their names as key.
my Capture = \(2, 3, apples => (red => 2));say .pairs; # OUTPUT: «(0 => 2 1 => 3 apples => red => 2)»
method antipairs
Defined as:
multi method antipairs(Capture: --> Seq)
Returns all arguments, the positional followed by the named, as a Seq of pairs where the keys and values have been swapped, i.e. the value becomes the key and the key becomes the value. This behavior is the opposite of the pairs method.
my = \(2, 3, apples => (red => 2));say .antipairs; # OUTPUT: «(2 => 0 3 => 1 (red => 2) => apples)»
method Bool
Defined as:
method Bool(Capture: --> Bool)
Returns True
if the Capture contains at least one named or one positional argument.
say \(1,2,3, apples => 2).Bool; # OUTPUT: «True»say \().Bool; # OUTPUT: «False»
method Capture
Defined as:
method Capture(Capture: --> Capture)
Returns itself, i.e. the invocant.
say \(1,2,3, apples => 2).Capture; # OUTPUT: «\(1, 2, 3, :apples(2))»
method Numeric
Defined as:
method Numeric(Capture: --> Int)
Returns the number of positional elements in the Capture.
say \(1,2,3, apples => 2).Numeric; # OUTPUT: «3»