Represents a parameter, for purpose of introspection.
The usual way to obtain a Parameter object is to create a signature, and call .params on it to obtain a list of the parameters.
my = :(Str );my = .params[0];say .type; # OUTPUT: «Str()»See Signature for more information, and also for an explanation on what most of the concepts related to parameters mean.
Methods §
method name §
Defined as:
method name(Parameter: --> Str)Returns the parameter name, which includes all sigils and twigils. This name is used internally when applied to code, or in a declaration to determine the declared the name. This name is not necessarily usable by a caller – if it is, it will also appear as an alias. Often, the name will be chosen descriptively as a form of self-documentation.
If the parameter is anonymous, an empty string will be returned.
Note: Before Rakudo version 2020.08 the return value for an anonymous parameter was Nil.
my Signature = :(Str , Bool);say .params[0].name; # OUTPUT: «$x» say .params[1].name; # OUTPUT: «» method usage-name §
Defined as:
method usage-name(Parameter: --> Str)Returns the parameter name without any sigils and twigils.
If the parameter is anonymous, an empty string will be returned.
Note: Before Rakudo version 2020.08 the return value for an anonymous parameter was Nil.
my Signature = :(Str , Str , Bool);say .params[0].usage-name; # OUTPUT: «x» say .params[1].usage-name; # OUTPUT: «l» say .params[2].usage-name; # OUTPUT: «» method sigil §
Defined as:
method sigil(Parameter: --> Str)Returns a string containing the parameter's sigil, for a looser definition of "sigil" than what is considered part of the parameter's name. Still returns a sigil even if the parameter is anonymous.
This "sigil" is actually an introspection used to help determine the normal binding style of a parameter, if it has not been altered through a trait.
| Sigil | Will bind to | Default behavior |
|---|---|---|
| $ | Scalar | Generate new Scalar, use instead of Scalar in argument, if any |
| @ | Positional | Bind directly to the argument |
| @ | PositionalBindFailover | If binding failed, call argument's .cache method, bind to result |
| % | Associative | Bind directly to the argument |
| & | Callable | Bind directly to the argument |
| \ | (anything) | Bind directly to the argument, keep existing Scalar, if any |
Also, | will bind to all remaining arguments and make new Capture if needed.
method type §
Returns the nominal type constraint of the parameter.
method coerce_type §
Returns the coercion type of the parameter.
method constraints §
Returns additional constraints on the parameter (usually as an all-Junction).
method named §
Defined as:
method named(Parameter: --> Bool)Returns True if it's a named parameter.
my Signature = :(Str , Bool :);say .params[0].named; # OUTPUT: «False» say .params[1].named; # OUTPUT: «True»method named_names §
Defined as:
method named_names(Parameter: --> List)Returns the list of externally usable names/aliases for a named parameter.
method positional §
Defined as:
method positional(Parameter: --> Bool)Returns True if the parameter is positional.
my Signature = :(Str , Bool :);say .params[0].positional; # OUTPUT: «True» say .params[1].positional; # OUTPUT: «False»method slurpy §
Defined as:
method slurpy(Parameter: --> Bool)Returns True for slurpy parameters.
method twigil §
Defined as:
method twigil(Parameter: --> Str)Returns a string containing the twigil part of the parameter's name.
method optional §
Defined as:
method optional(Parameter: --> Bool)Returns True for optional parameters.
method raw §
Defined as:
method raw(Parameter: --> Bool)Returns True for raw parameters.
sub f(, is raw, \c) f(17, "4711", 42); # OUTPUT: «FalseTrueTrue»Raw parameters bind either a variable or a value passed to it, with no decontainerization taking place. That means that if a variable was passed to it, you can assign to the parameter. This is different from rw-parameter which can only bind to variables, never to values.
This is the normal behavior for parameters declared with a sigil of '\', which is not really a sigil insofar as it is only used on the parameter.
sub f(\x) f(my ); # works f(42); # dies CATCH ;# OUTPUT: «X::Assignment::RO: Cannot modify an immutable Int»Other parameters may become raw through use of the 'is raw' trait. These still use their sigil in code.
sub f( is raw) When used with slurpy list parameters, the is raw trait will cause the list of arguments given to be packed into a List instead of an Array, which prevents them from being containerized with Scalar. This is the default behavior when using + with a sigilless parameter:
my is List = Mu, Any;say -> * ()[0] =:= [0]; # OUTPUT: «False» say -> + ()[0] =:= [0]; # OUTPUT: «False» say -> +l ()[0] =:= [0]; # OUTPUT: «True» say -> * is raw ()[0] =:= [0]; # OUTPUT: «True»method capture §
Defined as:
method capture(Parameter: --> Bool)Returns True for parameters that capture the rest of the argument list into a single Capture object.
sub how_many_extra_positionals($!, |capture) how_many_extra_positionals(0, 1, 2, 3); # OUTPUT: «3» say .signature.params[1].capture; # OUTPUT: «True»Like raw parameters, Capture parameters do not force any context on the values bound to them, which is why their sigils are only used in declarations.
method rw §
Defined as:
method rw(Parameter: --> Bool)Returns True for is rw parameters.
my Signature = :(Str is rw, Bool :);say .params[0].rw; # OUTPUT: «True» say .params[1].rw; # OUTPUT: «False»method copy §
Defined as:
method copy(Parameter: --> Bool)Returns True for is copy parameters.
my Signature = :(Str , Bool : is copy);say .params[0].copy; # OUTPUT: «False» say .params[1].copy; # OUTPUT: «True»method readonly §
Defined as:
method readonly(Parameter: --> Bool)Returns True for read-only parameters (the default).
my Signature = :(Str is rw, Bool :);say .params[0].readonly; # OUTPUT: «False» say .params[1].readonly; # OUTPUT: «True»method invocant §
Defined as:
method invocant(Parameter: --> Bool)Returns True if the parameter is the invocant parameter.
my Signature = :( : Str is rw, Bool :);say .params[0].invocant; # OUTPUT: «True» say .params[1].invocant; # OUTPUT: «False»method default §
Defined as:
method default(Parameter: --> Code)Returns a closure that upon invocation returns the default value for this parameter, or Code if no default was provided.
Note: Before Rakudo version 2020.08 the return value for a parameter with no default value was Any.
my = :(, = 12);say .params[0].default; # OUTPUT: «(Code)» say .params[1].default.(); # OUTPUT: «12» method type_captures §
Defined as:
method type_captures(Parameter: --> List)Returns a list of variable names of type captures associated with this parameter. Type captures define a type name within the attached code, which is an alias to the type gleaned from the argument during a call.
sub a(::T ::U ) a(8); # OUTPUT: «(Int)» say .signature.params[0].type_captures; # OUTPUT: «(T U)» sub b() a(8); # OUTPUT: «Int»The type used may change from call to call. Once they are defined, type captures can be used wherever you would use a type, even later in the same signature:
sub c(::T , T , ) ;c(4, 5, 6); # OK try c(4, 5, "six");given $! ;# OUTPUT: «Type check failed in assignment to $zz; expected Int but got Str ("six")» try c("four", 5, "six");given $! ;# OUTPUT: «Type check failed in binding to parameter '$y'; expected Str but got Int (5)» Type captures may be used at the same time as type constraints.
sub d(::T Numeric , T ) ;d(4, 5); # OK d(4e0, 5e0); # OK try d(4e0, 5);given $! ;# OUTPUT: «Type check failed in binding to parameter '$y'; expected Num but got Int (5)» try d("four", "five");given $! ;# OUTPUT: «Type check failed in binding to parameter '$x'; expected Numeric but got Str ("four")» method sub_signature §
Defined as:
method sub_signature(Parameter: --> Signature)If the parameter has a sub-signature, returns a Signature object for it. Otherwise returns Signature.
Note: Before Rakudo version 2020.08 the return value for a parameter with no sub-signature was Any.
my Signature = :( (, *), );say .params[0].sub_signature; # OUTPUT:«($first, *@rest)» say .params[1].sub_signature; # OUTPUT:«(Signature)» method prefix §
Defined as:
method prefix(Parameter: --> Str)If the parameter is slurpy, returns the marker (e.g., *, **, or +) the parameter was declared with. Otherwise, returns an empty string.
my Signature = :(, *);say .params[0].prefix; # OUTPUT:«» say .params[1].prefix; # OUTPUT:«*» my Signature = :(, **);say .params[0].prefix; # OUTPUT:«» say .params[1].prefix; # OUTPUT:«**» my Signature = :(, +);say .params[0].prefix; # OUTPUT:«» say .params[1].prefix; # OUTPUT:«+»method suffix §
Defined as:
method suffix(Parameter: --> Str)Returns the ? or ! marker a parameter was declared with, if any. Otherwise, returns the empty string.
my Signature = :(, ?);say .params[0].suffix; # OUTPUT: «» say .params[1].suffix; # OUTPUT: «?» my Signature = :(:!, :);say .params[0].suffix; # OUTPUT: «!» say .params[1].suffix; # OUTPUT: «»Runtime creation of Parameter objects (6.d, 2019.03 and later) §
Parameter.new( ... )In some situations, specifically when working with the MetaObject Protocol, it makes sense to create Parameter objects programmatically. For this purpose, you can call the new method with the following named parameters:
name
Optional. The name of the parameter, if any. Can be specified in the same way as in a Signature. So it may contain specific additional information, such as a sigil ($, @, % or &), a : prefix to indicate a named parameter, a twigil (. or !) to indicate public / private attribute binding, a postfix ! or ? to indicate an optional / mandatory parameter, and the various combinations of +, *, ** prefixes to indicate slurpiness types and | to indicate a Capture.
type
Optional. The type of the parameter. Assumes Any if not specified.
default
Optional. The value of the parameter if the parameter is optional and no argument has been given for that parameter. Assumes not initialization if no argument has been given, which would fall back to the (implicit) type of the parameter.
where
Optional. Additional constraints to be applied to any argument to match with this parameter. Does not set any additional constraints by default.
is-copy
Optional. Allows one to set the "is copy" flag on the parameter. Does not set the flag by default.
is-raw
Optional. Allows one to set the "is raw" flag on the parameter. Does not set the flag by default.
is-rw
Optional. Allows one to set the "is rw" flag on the parameter. Does not set the flag by default.
named
Optional. Indicates whether the parameter is a named parameter or not. Should only be specified if the : prefix is not specified in the name and a named parameter is required.
optional
Optional. Indicates whether the parameter is optional or not. Should only be specified if the ? postfix is not specified in the name and an optional parameter is required.
mandatory
Optional. Indicates whether the parameter is mandatory or not. Should only be specified if the ! postfix is not specified in the name and a mandatory parameter is required.
multi-invocant
Optional. Indicates whether the parameter should be considered in multi-dispatch or not. Defaults to True, so one would need to do :!multi-invocant to make the parameter not be considered in multi-dispatch.
sub-signature
Optional. Specifies any Signature that should be applied to the parameter to deconstruct it. By default, no signature is to be applied.
Type Graph §
Parameter