class Parameter

Element of a Signature

class Parameter { }

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 $sig   = :(Str $x);
my $param = $sig.params[0];
say $param.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

Returns the variable name, which includes all sigils and twigils. This name is used internally when applied to code, or in a declaration determines the name declared. This name is not necessarily usable by a caller – if it is, it will also appear as an alias. Often, the name will chosen descriptively as a form of self-documentation.

If the parameter is anonymous, Nil will be returned.

method sigil

Defined as:

method sigil(Parameter:D: --> Str:D)

Returns a string containing the parameter's sigil, for a looser definition of "sigil" than what is considered part of the variable's name|method 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 constraints

Returns additional constraints on the parameter (usually as an all-Junction).

method named

Defined as:

method named(Parameter:D: --> Bool:D)

Returns True if it's a named parameter.

my Signature $sig = :(Str $xBool :$is-named);
say $sig.params[0].named;                          # OUTPUT: «False␤» 
say $sig.params[1].named;                          # OUTPUT: «True␤» 

method named_names

Defined as:

method named_names(Parameter:D: --> List:D)

Returns the list of externally usable names/aliases for a named parameter.

method positional

Defined as:

method positional(Parameter:D: --> Bool:D)

Returns True if the parameter is positional.

my Signature $sig = :(Str $xBool :$is-named);
say $sig.params[0].positional;                     # OUTPUT: «True␤» 
say $sig.params[1].positional;                     # OUTPUT: «False␤» 

method slurpy

Defined as:

method slurpy(Parameter:D: --> Bool:D)

Returns True for slurpy parameters.

method twigil

Defined as:

method twigil(Parameter:D: --> Str:D)

Returns a string containing the twigil part of the parameter's name.

method optional

Defined as:

method optional(Parameter:D: --> Bool:D)

Returns True for optional parameters.

method raw

Defined as:

method raw(Parameter:D: --> Bool:D)

Returns True for raw parameters.

sub f($a$b is raw, \c{
    my $sig = &?ROUTINE.signature;
    for ^$sig.params.elems {
        say $sig.params[$_].raw;
    }
}
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{
    x = 5;
}
f(my $x);   # works 
f(42);      # dies 
CATCH { default { put .^name''.Str } };
# 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($x is raw{
    $x = 5;
}

method capture

Defined as:

method capture(Parameter:D: --> Bool:D)

Returns True for parameters that capture the rest of the argument list into a single Capture object.

sub how_many_extra_positionals($!|capture{ capture.elems.say }
how_many_extra_positionals(0123);                        # RESULT: «3» 
say &how_many_extra_positionals.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:D: --> Bool:D)

Returns True for is rw parameters.

my Signature $sig = :(Str $x is rwBool :$is-named);
say $sig.params[0].rw;                             # OUTPUT: «True␤» 
say $sig.params[1].rw;                             # OUTPUT: «False␤» 

method copy

Defined as:

method copy(Parameter:D: --> Bool:D)

Returns True for is copy parameters.

my Signature $sig = :(Str $xBool :$is-named is copy);
say $sig.params[0].copy;                           # OUTPUT: «False␤» 
say $sig.params[1].copy;                           # OUTPUT: «True␤» 

method readonly

Defined as:

method readonly(Parameter:D: --> Bool:D)

Returns True for read-only parameters (the default).

my Signature $sig = :(Str $x is rwBool :$is-named);
say $sig.params[0].readonly;                       # OUTPUT: «False␤» 
say $sig.params[1].readonly;                       # OUTPUT: «True␤» 

method invocant

Defined as:

method invocant(Parameter:D: --> Bool:D)

Returns True if the parameter is the invocant parameter.

method default

Returns a closure that upon invocation returns the default value for this parameter, or Any if no default was provided.

method type_captures

Defined as:

method type_captures(Parameter:D: --> List:D)

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 $x{ T.say }
a(8);                                       # OUTPUT: «(Int)␤» 
say &a.signature.params[0].type_captures;   # OUTPUT: «(T U)␤» 
sub b($x{ $x.^name.say }
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 same the signature:

sub c(::T $xT $y$z{ my T $zz = $z };
c(456);          # OK 
c(45"six");      # Fails when assigning to $zz, wants Int not Str 
c("four"5"six"); # Fails when binding $y, wants Str, not Int 

Type captures may be used at the same time as type constraints.

sub d(::T Numeric $xT $y{};
d(45);            # OK 
d(4e05e0);        # OK 
d(4e05);          # Fails when binding $y 
d("four""five");  # Fails when binding $x 

method sub_signature

If the parameter has a sub-signature, returns a Signature object for it. Otherwise returns Any.

Type Graph

Type relations for Parameter
perl6-type-graph Parameter Parameter Any Any Parameter->Any Mu Mu Any->Mu

Expand above chart