class Macro is Routine { }

A macro is a Routine whose invocation typically happens during parsing. By returning an AST, a macro can inject code into the calling location.

Type Graph §

Type relations for Macro

Expand above chart

Routines supplied by class Routine §

Macro inherits from class Routine, which provides the following routines:

(Routine) method package §

method package(Routine:D:)

Returns the package in which the routine is defined.

(Routine) method multi §

method multi(Routine:D: --> 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:

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

(Routine) method candidates §

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

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

(Routine) 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:

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

(Routine) 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 Routine::WrapHandle, which you can pass to unwrap to restore the original routine.

(Routine) 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.

(Routine) method is-wrapped §

Defined as:

method is-wrapped()

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

(Routine) method yada §

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

Returns True if the routine is a stub

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

(Routine) trait is cached §

multi sub 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.[1]

Useful when storing and returning the computed value is much faster than re-computing it every time, and when the time saved trumps the cost of the use of more memory.

Even if the arguments passed to the routine are "reference types" (such as objects or arrays), then for the purpose of caching they will only be compared based on their contents. Thus the second invocation will hit the cache in this case:

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

Since it's still at the experimental stage, you will have to insert the use experimental :cached; statement in any module or script that uses it.

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);

produces this output:

Calculating 43th prime
191
191
191

(Routine) trait is pure §

multi sub 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.

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;
}

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 cases that the compiler cannot deduce on its own. On the other hand, you might not want to constant-fold functions that produce a large return value (such as the string or list repetition operators, infix x and xx) even if they are pure, to avoid large precompilation files.

To see it an action with a particular compiler you can try this example:

BEGIN { say ‘Begin’ }
say ‘Start’;
say (^100).map: { syllables().pick(4).join("") };
 
 
# Example output: 
# Begin 
# Generating syllables 
# Start 
# (matiroi yeterani shoriyuru...

Essentially this allows the compiler to perform some operations at compile time. The benefits of constant-folding may include better performance, especially in cases when the folded code is precompiled.

In addition, using a pure function or operator in sink context (that is, where the result is discarded) may lead to a warning. The code

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)»

If you want to apply this trait to a multi, you need to apply it to the proto; it will not work otherwise, at least in versions 2018.08 and below.

(Routine) trait is rw §

multi sub 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:

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.raku;

produces

("some" => {"key" => [Any, [Any, Any, "autovivified"]]}).hash

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.

(Routine) trait is export §

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

Marks a routine as exported to the rest of the world

module Foo {
    sub double($x) is export {
        2 * $x
    }
}
 
import Foo;         # makes sub double available 
say double 21;      # 42

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.

(Routine) trait is DEPRECATED §

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

Marks a routine as deprecated, optionally with a message what to use instead.

This code

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

produces this output:

42
Saw 1 occurrence of deprecated code.
================================================================================
Sub f (from GLOBAL) seen at:
  deprecated.p6, 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!

(Routine) trait is hidden-from-backtrace §

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

Hides a routine from showing up in a default backtrace. For example

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

produces the error message and backtrace

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

but if inner is marked with hidden-from-backtrace

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

the error backtrace does not show it:

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

(Routine) trait is default §

Defined as

multi sub 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.

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

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 Routines of the same precedence. If one of the Routines is narrower than another, then that one will be called. For example:

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

In this example, the multi without is default was called because it was actually narrower than the Sub with it.

(Routine) trait is raw §

Defined as:

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

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

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

Routines supplied by class Code §

Macro inherits from class Code, which provides the following routines:

(Code) method ACCEPTS §

multi method ACCEPTS(Code:D: Mu $topic)

Usually calls the code object and passes $topic as an argument. However, when called on a code object that takes no arguments, the code object is invoked with no arguments and $topic is dropped. The result of the call is returned.

(Code) method arity §

Defined as:

method arity(Code:D: --> Int:D)

Returns the minimum number of positional arguments that must be passed in order to call the code object. Any optional or slurpy parameters in the code object's Signature do not contribute, nor do named parameters.

sub argless() { }
sub args($a, $b?) { }
sub slurpy($a, $b, *@c) { }
say &argless.arity;             # OUTPUT: «0␤» 
say &args.arity;                # OUTPUT: «1␤» 
say &slurpy.arity;              # OUTPUT: «2␤»

(Code) method assuming §

method assuming(Callable:D $self: |primers)

Returns a Callable that implements the same behavior as the original, but has the values passed to .assuming already bound to the corresponding parameters.

my sub slow($n){ my $i = 0; $i++ while $i < $n; $i };
 
# takes only one parameter and as such wont forward $n 
sub bench(&c){ c, now - ENTER now };
 
say &slow.assuming(10000000).&bench; # OUTPUT: «(10000000 7.5508834)␤»

For a sub with arity greater than one, you can use Whatever * for all of the positional parameters that are not "assumed".

sub first-and-last ( $first, $last ) {
    say "Name is $first $last";
}
 
my &surname-smith = &first-and-last.assuming( *, 'Smith' );
 
&surname-smith.( 'Joe' ); # OUTPUT: «Name is Joe Smith␤»

You can handle any combination of assumed and not assumed positional parameters:

sub longer-names ( $first, $middle, $last, $suffix ) {
    say "Name is $first $middle $last $suffix";
}
 
my &surname-public = &longer-names.assuming( *, *, 'Public', * );
 
&surname-public.( 'Joe', 'Q.', 'Jr.'); # OUTPUT: «Name is Joe Q. Public Jr.␤»

Named parameters can be assumed as well:

sub foo { say "$^a $^b $:foo $:bar" }
&foo.assuming(13, :42foo)(24, :72bar); # OUTPUT: «13 24 42 72␤»

And you can use .assuming on all types of Callables, including Methods and Blocks:

# We use a Whatever star for the invocant: 
my &comber = Str.^lookup('comb').assuming: *, /P \w+/;
say comber 'Perl is awesome! Python is great! And PHP is OK too';
# OUTPUT: «(Perl Python PHP)␤» 
 
my &learner = {
    "It took me $:months months to learn $^lang"
}.assuming: 'Raku';
say learner :6months;  # OUTPUT: «It took me 6 months to learn Raku␤»

(Code) method count §

Defined as:

method count(Code:D: --> Real:D)

Returns the maximum number of positional arguments that may be passed when calling the code object. For code objects that can accept any number of positional arguments (that is, they have a slurpy parameter), count will return Inf. Named parameters do not contribute.

sub argless() { }
sub args($a, $b?) { }
sub slurpy($a, $b, *@c) { }
say &argless.count;             # OUTPUT: «0␤» 
say &args.count;                # OUTPUT: «2␤» 
say &slurpy.count;              # OUTPUT: «Inf␤»

(Code) method of §

Defined as:

method of(Code:D: --> Mu)

Returns the return type constraint of the Code:

say -> () --> Int {}.of; # OUTPUT: «(Int)␤»

(Code) method signature §

Defined as:

multi method signature(Code:D: --> Signature:D)

Returns the Signature object for this code object, which describes its parameters.

sub a(Int $one, Str $two) {};
say &a.signature; # OUTPUT: «(Int $one, Str $two)␤»

(Code) method cando §

method cando(Capture $c)

Returns a list of candidates that can be called with the given Capture. Since Code objects do not have any multiple dispatch, this either returns a list with the object, or an empty list.

my $single = \'a';         # a single argument Capture 
my $plural = \('a', 42);   # a two argument Capture 
my &block = { say $^a };   # a Block object, that is a subclass of Code, taking one argument 
say &block.cando($single); # OUTPUT: «(-> $a { #`(Block|94212856419136) ... })␤» 
say &block.cando($plural); # OUTPUT: «()␤»

(Code) method Str §

Defined as:

multi method Str(Code:D: --> Str:D)

Will output the method name, but also produce a warning. Use .raku or .gist instead.

sub marine() { }
say ~&marine;
# OUTPUT: «Sub object coerced to string (please use .gist or .raku to do that)␤marine␤» 
say &marine.Str;
# OUTPUT: «Sub object coerced to string (please use .gist or .raku to do that)␤marine␤» 
say &marine.raku; # OUTPUT: «sub marine { #`(Sub|94280758332168) ... }␤»

(Code) method file §

Defined as:

method file(Code:D: --> Str:D)

Returns the name of the file in which the code object was declared.

say &infix:<+>.file;   # OUTPUT: «SETTING::src/core.c/Numeric.pm6␤»

(Code) method line §

Defined as

method line(Code:D: --> Int:D)

Returns the line number in the source code at which the code object's declaration begins.

say &infix:<+>.line;   # OUTPUT: «208␤»

If the code object was generated automatically (and thus not declared in the source code), then line returns the line on which the enclosing scope's declaration begins. For example, when called on an automatically generated accessor method produced by the has $.name syntax, line returns the line on which the method's class's declaration begins.

For example, if you have the following source file:

class Food {                # Line 1 
    has $.ingredients;      # Line 2 
                            # Line 3 
    method eat {};          # Line 4 
}                           # Line 5

Then the line method would give you the following output:

say Food.^lookup('eat').line;          # OUTPUT: «4␤» 
say Food.^lookup('ingredients').line;  # OUTPUT: «1␤»

(Code) method is-implementation-detail §

method is-implementation-detail(--> False)

Note: this method has been available in Rakudo compiler starting from 2020.05 release.

Returns True if the code object was marked with is implementation-detail trait, False otherwise.

Routines supplied by role Callable §

Macro inherits from class Code, which does role Callable, which provides the following routines:

(Callable) method CALL-ME §

method CALL-ME(Callable:D $self: |arguments)

This method is required for the ( ) postcircumfix operator and the .( ) postcircumfix operator. It's what makes an object actually call-able and needs to be overloaded to let a given object act like a routine. If the object needs to be stored in a &-sigiled container, it has to implement Callable.

class A does Callable {
    submethod CALL-ME(|c){ 'called' }
}
my &a = A;
say a(); # OUTPUT: «called␤»

Applying the Callable role is not a requirement to make an object callable; if a class simply wants to add subroutine-like semantics in a regular scalar container, the submethod CALL-ME can be used for that.

class A {
    has @.values;
    submethod CALL-ME(Int $x where 0 <= * < @!values.elems) {
        @!values[$x]
    }
}
my $a = A.new: values => [4,5,6,7];
say $a(2); # OUTPUT: «6␤»

(Callable) method Capture §

Defined as:

method Capture()

Throws X::Cannot::Capture.