txt: ## signatures.md
  ## Chunk 2 of 2
  , "d", "e", "f", 2, 3]␤»
  a([1, 2]);                 # OUTPUT: «[1, 2]␤»
  a(1, [1, 2], ([3, 4], 5)); # OUTPUT: «[1, 1, 2, 3, 4, 5]␤»
  a(($_ for 1, 2, 3));       # OUTPUT: «[1, 2, 3]␤»
  
  ```
  
  A single asterisk slurpy flattens all given iterables, effectively hoisting any object created with commas up to the top level.
  
  ## [Unflattened slurpy](#Signature_literals "go to top of document")[§](#Unflattened_slurpy "direct link")
  
  Slurpy parameters declared with two stars do not flatten any [`Iterable`](/type/Iterable) arguments within the list, but keep the arguments more or less as-is:
  
  ```raku
  my @array = <a b c>;
  my $list := <d e f>;
  sub b(**@b) { @b.raku.say };
  b(@array);                 # OUTPUT: «[["a", "b", "c"],]␤»
  b(1, $list, [2, 3]);       # OUTPUT: «[1, ("d", "e", "f"), [2, 3]]␤»
  b([1, 2]);                 # OUTPUT: «[[1, 2],]␤»
  b(1, [1, 2], ([3, 4], 5)); # OUTPUT: «[1, [1, 2], ([3, 4], 5)]␤»
  b(($_ for 1, 2, 3));       # OUTPUT: «[(1, 2, 3),]␤»
  
  ```
  
  The double asterisk slurpy hides the nested comma objects and leaves them as-is in the slurpy array.
  
  ## [Single argument rule slurpy](#Signature_literals "go to top of document")[§](#Single_argument_rule_slurpy "direct link")
  
  A slurpy parameter created using a plus engages the *"single argument rule"*, which decides how to handle the slurpy argument based upon context. Basically, if only a single argument is passed and that argument is [`Iterable`](/type/Iterable), that argument is used to fill the slurpy parameter array. In any other case, `+@` works like `**@`.
  
  ```raku
  my @array = <a b c>;
  my $list := <d e f>;
  sub c(+@b) { @b.raku.say };
  c(@array);                 # OUTPUT: «["a", "b", "c"]␤»
  c(1, $list, [2, 3]);       # OUTPUT: «[1, ("d", "e", "f"), [2, 3]]␤»
  c([1, 2]);                 # OUTPUT: «[1, 2]␤»
  c(1, [1, 2], ([3, 4], 5)); # OUTPUT: «[1, [1, 2], ([3, 4], 5)]␤»
  c(($_ for 1, 2, 3));       # OUTPUT: «[1, 2, 3]␤»
  
  ```
  
  For additional discussion and examples, see [Slurpy Conventions for Functions](/language/functions#Slurpy_conventions).
  
  # [Type captures](#Signature_literals "go to top of document")[§](#Type_captures "direct link")
  
  Type captures allow deferring the specification of a type constraint to the time the function is called. They allow referring to a type both in the signature and the function body.
  
  ```raku
  sub f(::T $p1, T $p2, ::C){
      # $p1 and $p2 are of the same type T, that we don't know yet
      # C will hold a type we derive from a type object or value
      my C $division = $p1 / $p2;
      return sub (T $p1) {
          $division * $p1;
      }
  }
  
  # The first parameter is Int and so must be the 2nd.
  # We derive the 3rd type from calling the operator that is used in &f.
  my &s = f(10, 2, Int.new / Int.new);
  say s(2); # 10 / 2 * 2 == 10
  ```
  
  # [Positional vs. named arguments](#Signature_literals "go to top of document")[§](#Positional_vs._named_arguments "direct link")
  
  An argument can be *positional* or *named*. By default, arguments are positional, except slurpy hash and arguments marked with a leading colon `:`. The latter is called a [colon-pair](/type/Pair). Check the following signatures and what they denote:
  
  ```raku
  $sig1 = :($a);               # a positional argument
  $sig2 = :(:$a);              # a named argument of name 'a'
  $sig3 = :(*@a);              # a slurpy positional argument
  $sig4 = :(*%h);              # a slurpy named argument
  
  ```
  
  On the caller side, positional arguments are passed in the same order as the arguments are declared.
  
  ```raku
  sub pos($x, $y) { "x=$x y=$y" }
  pos(4, 5);                          # OUTPUT: «x=4 y=5»
  ```
  
  In the case of named arguments and parameters, only the name is used for mapping arguments to parameters. If a fat arrow is used to construct a [`Pair`](/type/Pair) only those with valid identifiers as keys are recognized as named arguments.
  
  ```raku
  sub named(:$x, :$y) { "x=$x y=$y" }
  named( y => 5, x => 4);             # OUTPUT: «x=4 y=5»
  
  ```
  
  You can invoke the routine using a variable with the same name as the named argument; in that case `:` will be used for the invocation so that the name of the variable is understood as the key of the argument.
  
  ```raku
  sub named-shortcut( :$shortcut ) {
      say "Looks like $shortcut"
  }
  named-shortcut( shortcut => "to here"); # OUTPUT: «Looks like to here␤»
  my $shortcut = "Þor is mighty";
  named-shortcut( :$shortcut );           # OUTPUT: «Looks like Þor is mighty␤»
  ```
  
  It is possible to have a different name for a named argument than the variable name:
  
  ```raku
  sub named(:official($private)) { "Official business!" if $private }
  named :official;
  ```
  
  # [Argument aliases](#Signature_literals "go to top of document")[§](#Argument_aliases "direct link")
  
  The [colon-pair](/type/Pair) syntax can be used to provide aliases for arguments:
  
  ```raku
  sub alias-named(:color(:$colour), :type(:class($kind))) {
      say $colour ~ " " ~ $kind
  }
  alias-named(color => "red", type => "A");    # both names can be used
  alias-named(colour => "green", type => "B"); # more than two names are ok
  alias-named(color => "white", class => "C"); # every alias is independent
  ```
  
  The presence of the colon `:` will decide whether we are creating a new named argument or not. `:$colour` will not only be the name of the aliased variable, but also a new named argument (used in the second invocation). However, `$kind` will just be the name of the aliased variable, that does not create a new named argument. More uses of aliases can be found in [sub MAIN](/language/create-cli#sub_MAIN).
  
  A function with named arguments can be called dynamically, dereferencing a [`Pair`](/type/Pair) with `|` to turn it into a named argument.
  
  ```raku
  multi f(:$named) { note &?ROUTINE.signature };
  multi f(:$also-named) { note &?ROUTINE.signature };
  for 'named', 'also-named' -> $n {
      f(|($n => rand))                # OUTPUT: «(:$named)␤(:$also-named)␤»
  }
  
  my $pair = :named(1);
  f |$pair;                           # OUTPUT: «(:$named)␤»
  ```
  
  The same can be used to convert a [`Hash`](/type/Hash) into named arguments.
  
  ```raku
  sub f(:$also-named) { note &?ROUTINE.signature };
  my %pairs = also-named => 4;
  f |%pairs;                              # OUTPUT: «(:$also-named)␤»
  ```
  
  A [`Hash`](/type/Hash) that contains a list may prove problematic when slipped into named arguments. To avoid the extra layer of containers coerce to [`Map`](/type/Map) before slipping.
  
  ```raku
  class C { has $.x; has $.y; has @.z };
  my %h = <x y z> Z=> (5, 20, [1,2]);
  say C.new(|%h.Map);
  # OUTPUT: «C.new(x => 5, y => 20, z => [1, 2])␤»
  ```
  
  You can create as many aliases to a named argument as you want:
  
  ```raku
  sub alias-named(:color(:$colour),
                  :variety(:style(:sort(:type(:class($kind)))))) {
      return $colour ~ " " ~ $kind
  }
  say alias-named(color => "red", style => "A");
  say alias-named(colour => "green", variety => "B");
  say alias-named(color => "white", class => "C");
  
  ```
  
  You can create named arguments that do not create any variables by making the argument an alias for an [anonymous argument](#index-entry-anonymous_arguments). This can be useful when using named arguments solely as a means of selecting a `multi` candidate, which is often the case with traits, for instance:
  
  ```raku
  # Timestamps calls to a routine.
  multi trait_mod:<is>(Routine:D $r is raw, :timestamped($)!) {
      $r does my role timestamped { has Instant:D @.timestamps };
      $r.wrap: -> | { ENTER $r.timestamps.push: now; callsame };
  }
  
  sub foo is timestamped { }
  foo;
  say +&foo.?timestamps; # OUTPUT: «1␤»
  
  ```
  
  # [Optional and mandatory arguments](#Signature_literals "go to top of document")[§](#Optional_and_mandatory_arguments "direct link")
  
  Positional parameters are mandatory by default, and can be made optional with a default value or a trailing question mark:
  
  ```raku
  $sig1 = :(Str $id);         # required parameter
  $sig2 = :($base = 10);      # optional parameter, default value 10
  $sig3 = :(Int $x?);         # optional parameter, default is the Int type object
  
  ```
  
  Named parameters are optional by default, and can be made mandatory with a trailing exclamation mark:
  
  ```raku
  $sig1 = :(:%config);        # optional parameter
  $sig2 = :(:$debug = False); # optional parameter, defaults to False
  $sig3 = :(:$name!);         # mandatory 'name' named parameter
  
  ```
  
  Default values can depend on previous parameters, and are (at least notionally) computed anew for each call
  
  ```raku
  $sig1 = :($goal, $accuracy = $goal / 100);
  $sig2 = :(:$excludes = ['.', '..']);        # a new Array for every call
  
  ```
  
  ## [Was an argument passed for a parameter?](#Signature_literals "go to top of document")[§](#Was_an_argument_passed_for_a_parameter? "direct link")
  
  Table showing checks of whether an argument was passed for a given parameter:
  
  | Parameter kind | Example | Comment | Check for no arg passed |
  | --- | --- | --- | --- |
  | Slurpy | \*@array | Don't check using .defined | if not @array |
  | Required | $foo | Can't be omitted | (not applicable) |
  | Optional | @bar = default | Pick a suitable default¹ | if @bar =:= default |
  
  ¹ A suitable default is an Object that has a distinct identity, as may be checked by the [`WHICH`](https://docs.raku.org/type/Mu#method_WHICH) method.
  
  A parameter with a default is always *optional*, so there is no need to mark it with a `?` or the `is optional` trait.
  
  Then you can use the `=:=` [container identity operator](https://docs.raku.org/language/operators#infix_=:=) in the body of the routine to check whether this exact default was bound to the parameter.
  
  Example with a positional parameter:
  
  ```raku
  my constant PositionalAt = Positional.new;
  
  sub a (@list = PositionalAt) { say @list =:= PositionalAt }
  a;              # OUTPUT: «True␤»
  a [1, 2, 3];    # OUTPUT: «False␤»
  
  ```
  
  Example with some scalar parameters:
  
  ```raku
  my constant AnyAt = Any.new;
  
  sub b ($x=AnyAt, :$y=AnyAt) { say $x =:= AnyAt; say $y =:= AnyAt }
  b 1;            # OUTPUT: «False␤True␤»
  b 1, :2y;       # OUTPUT: «False␤False␤»
  
  ```
  
  If your parameters are typed, then the [type smileys](https://docs.raku.org/language/glossary#Type_smiley) can be used with [`multi`](https://docs.raku.org/language/functions#Multi-dispatch)s like this:
  
  ```raku
  multi c (Int:U $z)  { say 'Undefined' }
  multi c (Int:D $z)  { say 'Defined'   }
  multi c (Int   $z?) { say 'Omitted'   }
  c;              #Omitted
  c (Int);        #Undefined
  c 42;           #Defined
  
  ```
  
  The examples use names like `PositionalAt` to reflect that the `.WHICH` test returns an object of type [`ObjAt`](/type/ObjAt), you are free to make up you own names.
  
  # [Dynamic variables](#Signature_literals "go to top of document")[§](#Dynamic_variables "direct link")
  
  [Dynamic variables](/language/variables#The_*_twigil) are allowed in signatures although they don't provide special behavior because argument binding does connect two scopes anyway.
  
  # [Destructuring arguments](#Signature_literals "go to top of document")[§](#Destructuring_arguments "direct link")
  
  Non-scalar parameters can be followed or substituted by a sub-signature in parentheses, which will destructure the argument given. The destructuring of a list is just its elements:
  
  ```raku
  sub first(@array ($first, *@rest)) { $first }
  ```
  
  or
  
  ```raku
  sub first([$f, *@]) { $f }
  ```
  
  While the destructuring of a hash is its pairs:
  
  ```raku
  sub all-dimensions(% (:length(:$x), :width(:$y), :depth(:$z))) {
      $x andthen $y andthen $z andthen True
  }
  ```
  
  Pointy loops can also destructure hashes, allowing assignment to variables:
  
  ```raku
  my %hhgttu = (:40life, :41universe, :42everything);
  for %hhgttu -> (:$key, :$value) {
    say "$key → $value";
  }
  # OUTPUT: «universe → 41␤life → 40␤everything → 42␤»
  ```
  
  In general, an object is destructured based on its attributes. A common idiom is to unpack a [`Pair`](/type/Pair)'s key and value in a for loop:
  
  ```raku
  for <Peter Paul Merry>.pairs -> (:key($index), :value($guest)) { }
  ```
  
  However, this unpacking of objects as their attributes is only the default behavior. To make an object get destructured differently, change its [`Capture`](/routine/Capture) method.
  
  # [Sub-signatures](#Signature_literals "go to top of document")[§](#Sub-signatures "direct link")
  
  To match against a compound parameter use a sub-signature following the argument name in parentheses.
  
  ```raku
  sub foo(|c(Int, Str)){
     put "called with {c.raku}"
  };
  foo(42, "answer");
  # OUTPUT: «called with \(42, "answer")␤»
  ```
  
  # [Long names](#Signature_literals "go to top of document")[§](#Long_names "direct link")
  
  To exclude certain parameters from being considered in multiple dispatch, separate them with a double semicolon.
  
  ```raku
  multi f(Int $i, Str $s;; :$b) { say "$i, $s, {$b.raku}" };
  f(10, 'answer');
  # OUTPUT: «10, answer, Any␤»
  ```
  
  # [Capture parameters](#Signature_literals "go to top of document")[§](#Capture_parameters "direct link")
  
  Prefixing a parameter with a vertical bar `|` makes the parameter a [`Capture`](/type/Capture), using up all the remaining positional and named arguments.
  
  This is often used in `proto` definitions (like `proto foo (|) {*}`) to indicate that the routine's [`multi` definitions](/syntax/multi) can have any [type constraints](#Type_constraints). See [proto](/language/functions#proto) for an example.
  
  If bound to a variable, arguments can be forwarded as a whole using the slip operator `|`.
  
  ```raku
  sub a(Int $i, Str $s) { say $i.^name ~ ' ' ~ $s.^name }
  sub b(|c) { say c.^name; a(|c) }
  b(42, "answer");
  # OUTPUT: «Capture␤Int Str␤»
  ```
  
  # [Parameter traits and modifiers](#Signature_literals "go to top of document")[§](#Parameter_traits_and_modifiers "direct link")
  
  By default, parameters are bound to their argument and marked as read-only. One can change that with traits on the parameter.
  
  The `is copy` trait causes the argument to be copied, and allows it to be modified inside the routine
  
  ```raku
  sub count-up($x is copy) {
      $x = ∞ if $x ~~ Whatever;
      .say for 1..$x;
  }
  ```
  
  The `is rw` trait, which stands for *is read-write*, makes the parameter bind to a variable (or other writable container). Assigning to the parameter changes the value of the variable at the caller side.
  
  ```raku
  sub swap($x is rw, $y is rw) {
      ($x, $y) = ($y, $x);
  }
  ```
  
  On slurpy parameters, `is rw` is reserved for future use by language designers.
  
  The [`is raw` trait](/type/Parameter#method_raw) is automatically applied to parameters declared with a [backslash](/language/variables#Sigilless_variables) or a [plus sign](#Single_argument_rule_slurpy) as a "sigil", and may also be used to make normally sigiled parameters behave like these do. In the special case of slurpies, which normally produce an [`Array`](/type/Array) full of [`Scalar`](/type/Scalar)s as described above, `is raw` will instead cause the parameter to produce a [`List`](/type/List). Each element of that list will be bound directly as raw parameter.
  
  To explicitly ask for a read-only parameter use the `is readonly` trait. Please note that this applies only to the container. The object inside can very well have mutator methods and Raku will not enforce immutability on the attributes of the object.
  
  Traits can be followed by the where clause:
  
  ```raku
  sub ip-expand-ipv6($ip is copy where m:i/^<[a..f\d\:]>**3..39$/) { }
  ```
  