Rules / Types, classes & roles / basic

Routine Reference

Code object with its own lexical scope and C<return> handling

What it is #

Position in the hierarchy #


Inherits from	—
Does	—
Inherited by	`Sub`, `Method`, `Submethod`, `Macro`

Routines #

Signatures are reproduced from the documentation, including their declared return types. A routine listed here is part of the type's published interface; whether Raku++ implements it is a separate question, answered by the examples below.

method `name` #

method name(Routine:D: --> Str:D)

Returns Str:D.

Returns the name of the sub or method.

method `package` #

method package(Routine:D:)

Returns the package in which the routine is defined.

method `multi` #

method multi(Routine:D: --> Bool:D)

Returns Bool:D.

Returns True if the routine is a multi sub or method. Note that the name of a multi sub refers to its proto and this method would return false if called on it. It needs to be called on the candidates themselves:

method `candidates` #

method candidates(Routine:D: --> Positional:D)

Returns Positional:D.

Returns a list of multi candidates, or a one-element list with itself if it's not a multi

method `cando` #

method cando(Capture $c)

Returns a possibly-empty list of candidates that can be called with the given Capture, ordered by narrowest candidate first. For methods, the first element of the Capture needs to be the invocant:

method `wrap` #

method wrap(Routine:D: &wrapper)

Wraps (i.e. in-place modifies) the routine. That means a call to this routine first calls &wrapper, which then can (but doesn't have to) call the original routine with the callsame, callwith, nextsame and nextwith dispatchers. The return value from the routine is also the return value from the wrapper. wrap returns an instance of a private class called

method `unwrap` #

method unwrap($wraphandle)

Restores the original routine after it has been wrapped with wrap. While the signature allows any type to be passed, only the Routine::WrapHandle type returned from wrap can usefully be.

method `is-wrapped` #

method is-wrapped()

Returns True or False, depending on the whether or not the Routine is wrapped.

method `yada` #

method yada(Routine:D: --> Bool:D)

Returns Bool:D.

Returns True if the routine is a stub

trait `is` #

multi trait_mod:<is>(Routine $r, :$cached!)

Causes the return value of a routine to be stored, so that when subsequent calls with the same list of arguments are made, the stored value can be returned immediately instead of re-running the routine.N<This is still in experimental stage. Please check the corresponding section in the experimental features document> Useful when storing and returning the computed value is much faster than

trait `is` #

multi trait_mod:<is>(Routine $r, :$pure!)

Marks a subroutine as pure, that is, it asserts that for the same input, it will always produce the same output without any additional side effects. The is pure trait is a promise by the programmer to the compiler that it can constant-fold calls to such functions when the arguments are known at compile time. You can mark function as pure even if they throw exceptions in edge cases or if they modify temporary objects; hence the is pure trait can cover

trait `is` #

multi trait_mod:<is>(Routine $r, :$rw!)

When a routine is modified with this trait, its return value will be writable. This is useful when returning variables or writable elements of hashes or arrays, for example: produces Note that return marks return values as read only; if you need an early exit from an is rw routine, you have to use return-rw instead.

trait `is` #

multi trait_mod:<is>(Routine $r, :$export!)

Marks a routine as exported to the rest of the world From inside another file you'd say use Foo; to load a module and import the exported functions. See Exporting and Selective Importing Modules for more details.

trait `is` #

multi trait_mod:<is>(Routine:D $r, :$DEPRECATED!)

Marks a Routine as deprecated; that is, it should no longer be used going forward, and will eventually be removed. An optional message specifying the replacement functionality can be specified By having both the original (deprecated) and new Routine available simultaneously, you can avoid a breaking change in a single release, by allowing users time and instructions on how to update their code. Remove the deprecated version only after at least

trait `is` #

multi trait_mod:<is>(Routine:D, :$hidden-from-backtrace!)

Hides a routine from showing up in a default backtrace. For example produces the error message and backtrace but if inner is marked with hidden-from-backtrace the error backtrace does not show it: TODO: explain export tags

trait `is` #

multi trait_mod:<is>(Routine:D $r, :$default!)

There is a special trait for Routines called is default. This trait is designed as a way to disambiguate multi calls that would normally throw an error because the compiler would not know which one to use. This means that given the following two Routines, the one with the is default trait will be called. The is default trait can become very useful for debugging and other uses but keep in mind that it will only resolve an ambiguous dispatch between two

trait `is` #

multi trait_mod:<is>(Routine:D $r, :$raw!)

Gives total access to the data structure returned by the routine.

trait `is` #

multi trait_mod:<is>(Routine:D, :$test-assertion!)

Declares that a routine generates test output (aka TAP). When failures are reported, the calling routine's location is used instead of this routine. For example:

Examples, run three ways #

Every example below comes from the official documentation, together with the output that documentation asserts. Each was then executed by Rakudo and by Raku++ when this page was built. Where the three agree, one result is shown; where they do not, all three are — because which of them is wrong is exactly the information worth having.

2 all-differ · 1 doc-drift · 19 no-output · 2 ok · 1 rakupp-differs

class Routine is Block { }

Not executed: the documentation states no expected output for this example.

class Foo {
submethod bar { &?ROUTINE.^name }
};
say Foo.bar; # OUTPUT: «Submethod␤»

Documentation

Submethod

Rakudo

Submethod

Raku++

Raku++ disagrees with both the documentation and Rakudo — a defect.

multi foo ($, $) {};
say &foo.multi;             # OUTPUT: «False␤»
say &foo.candidates».multi; # OUTPUT: «(True)␤»

Documentation

False
(True)

Rakudo

0
(True)

Raku++

True
(False)

All three differ. Needs a human.

Not yet examined. Which of these is correct has not been established — do not treat either engine as settled here.

.signature.say for "foo".^can("comb")[0].cando: \(Cool, "o");
# OUTPUT: «(Cool $: Str $matcher, $limit = Inf, *%_)␤»

Documentation

(Cool $: Str $matcher, $limit = Inf, *%_)

Rakudo

Raku++

Nil

All three differ. Needs a human.

Not yet examined. Which of these is correct has not been established — do not treat either engine as settled here.

say (sub f() { ... }).yada;      # OUTPUT: «True␤»
say (sub g() { 1;  }).yada;      # OUTPUT: «False␤»

Output

True
False

Documentation, Rakudo and Raku++ all agree.

say foo( [1, 2, 3] );   # runs foo
say foo( [1, 2, 3] );   # doesn't run foo, uses cached value

Not executed: the documentation states no expected output for this example.

use experimental :cached;

sub nth-prime(Int:D $x where * > 0) is cached {
say "Calculating {$x}th prime";
return (2..*).grep(*.is-prime)[$x - 1];
}

say nth-prime(43);
say nth-prime(43);
say nth-prime(43);

Not executed: the documentation states no expected output for this example.

Calculating 43th prime
191
191
191

Not executed: the documentation states no expected output for this example.

sub syllables() is pure {
    say "Generating syllables";
    my @vowels = <a e i o u>;
    return  @vowels.append: <k m n sh d r t y> X~ @vowels;
}

Not executed: the documentation states no expected output for this example.

=begin code :preamble<sub syllables {}>
BEGIN { say ‘Begin’ }
say ‘Start’;
say (^100).map: { syllables().pick(4).join("") };

Not executed: the documentation states no expected output for this example.

# Example output:
# Begin
# Generating syllables
# Start
# (matiroi yeterani shoriyuru...
=end code

Not executed: the documentation states no expected output for this example.

sub double($x) is pure { 2 * $x };
double(21);
say "anything";
# WARNING: «Useless use of "double(21)" in expression "double(21)" in sink context (line 2)»

Not executed: the documentation states no expected output for this example.

sub walk(\thing, *@keys) is rw {
my $current := thing;
for @keys -> $k {
    if $k ~~ Int {
        $current := $current[$k];
    }
    else {
        $current := $current{$k};
    }
}
$current;
}

my %hash;
walk(%hash, 'some', 'key', 1, 2) = 'autovivified';

say %hash<some><key>[1][2];

Not executed: the documentation states no expected output for this example.

autovivified

Not executed: the documentation states no expected output for this example.

module Foo {
sub double($x) is export {
    2 * $x
}
}

import Foo;         # makes sub double available
say double 21;      # 42

Not executed: the documentation states no expected output for this example.

sub f() is DEPRECATED('the literal 42') { 42 }
say f();

Not executed: the documentation states no expected output for this example.

42
Saw 1 occurrence of deprecated code.
Sub f (from GLOBAL) seen at:
  deprecated.raku, line 2
Please use the literal 42 instead.
--------------------------------------------------------------------------------
Please contact the author to have these occurrences of deprecated code
adapted, so that this message will disappear!

Not executed: the documentation states no expected output for this example.

sub inner { die "OH NOEZ" };
sub outer { inner() };
outer();

Not executed: the documentation states no expected output for this example.

OH NOEZ
  in sub inner at bt.raku:1
  in sub outer at bt.raku:2
  in block <unit> at bt.raku:3

Not executed: the documentation states no expected output for this example.

sub inner is hidden-from-backtrace { die "OH NOEZ" };
sub outer { inner() };
outer();

Not executed: the documentation states no expected output for this example.

OH NOEZ
  in sub outer at bt.raku:2
  in block <unit> at bt.raku:3

Not executed: the documentation states no expected output for this example.

multi f() is default { say "Hello there" }
multi f() { say "Hello friend" }
f();   # OUTPUT: «"Hello there"␤»

Documentation

"Hello there"

Rakudo

Hello there

Raku++

Hello there

Both engines agree; the documentation states something else. Trust the engines.

multi f() is default { say "Hello there" }
multi f(:$greet) { say "Hello " ~ $greet }
f();   # "Use of uninitialized value $greet..."

Not executed: the documentation states no expected output for this example.

my @zipi = <zape zapatilla>;
sub þor() is raw {
return @zipi
};
þor()[1] = 'pantuflo';
say @zipi;  # OUTPUT: «[zape pantuflo]␤»

Output

[zape pantuflo]

Documentation, Rakudo and Raku++ all agree.

use Test;
sub foo-test($value) is test-assertion {
is $value, 42, "is the value 42?";
}
foo-test(666);    # <-- error is reported on this line

Not executed: the documentation states no expected output for this example.

Routine Reference

What it is #

Position in the hierarchy #

Routines #

method name #

method package #

method multi #

method candidates #

method cando #

method wrap #

method unwrap #

method is-wrapped #

method yada #

trait is #

trait is #

trait is #

trait is #

trait is #

trait is #

trait is #

trait is #

trait is #

Examples, run three ways #

method `name` #

method `package` #

method `multi` #

method `candidates` #

method `cando` #

method `wrap` #

method `unwrap` #

method `is-wrapped` #

method `yada` #

trait `is` #

trait `is` #

trait `is` #

trait `is` #

trait `is` #

trait `is` #

trait `is` #

trait `is` #

trait `is` #