Welcome to the official documentation of the Perl 6 programming language! Besides online browsing and searching, you can also view everything in one file or contribute by reporting mistakes or sending patches.
Language Reference & Tutorials
A collection of documents describing, in detail, the various conceptual parts of the language.
Type Reference
Index of built-in classes and roles.
Routine Reference
Index of built-in subroutines and methods.
Perl 6 Programs
A collection of documents describing how to run the Perl 6 executable program and other utilities, how to debug Perl 6 programs, and how to hack on Perl 6 source code.

The Perl 6 homepage offers a comprehensive list of Perl 6 resources, including tutorials, how-tos and FAQs (Frequently Asked Questions).

You may also be interested in the Perl 6 design documents, which are in some places more complete than this documentation, but targeted toward compiler writers rather than users of the language. Documentation for the different but related Perl 5 language can be found on the Perl 5 documentation website.

1 5to6-nutshell

Perl 5 to Perl 6, in a nutshell: How do I do what I used to do?

This page attempts to index the changes in syntax and semantics from Perl 5 to Perl 6. Whatever worked in Perl 5 and must be written differently in Perl 6, should be listed here (whereas many new Perl 6 features and idioms won't be).

Hence this should not be mistaken for a beginner tutorial or a promotional overview of Perl 6; it is intended as a technical reference for Perl 6 learners with a strong Perl 5 background and for anyone porting Perl 5 code to Perl 6 (though note that #Automated Translation might be more convenient).

A note on semantics; when we say "now" in this document, we mostly just mean "now that you are trying out Perl 6." We don't mean to imply that Perl 5 is now suddenly obsolete. Quite the contrary, most of us love Perl 5, and we expect Perl 5 to continue in use for a good many years. Indeed, one of our more important goals has been to make interaction between Perl 5 and Perl 6 run smoothly. However, we do also like the design decisions in Perl 6, which are certainly newer and arguably better integrated than many of the historical design decisions in Perl 5. So many of us do hope that over the next decade or two, Perl 6 will become the more dominant language. If you want to take "now" in that future sense, that's okay too. But we're not at all interested in the either/or thinking that leads to fights.

1.1 CPAN

See https://modules.perl6.org/ .

If the module that you were using has not been converted to Perl 6, and no alternative is listed in this document, then its use under Perl 6 may not have been addressed yet.

The Inline::Perl5 project makes it possible to use Perl 5 modules directly from Perl 6 code by using an embedded instance of the perl interpreter to run Perl 5 code.

1.2 Syntax

1.2.1 Identifiers

In identifiers, Perl 6 allows the use of dashes (-), underscores (_), apostrophes ('), and alphanumerics:

sub test-doesn't-hang { ... }
my $ความสงบ = 42;
my \Δ = 72; say 72 - Δ;

1.2.2 -> Method calls

If you've read any Perl 6 code at all, it's immediately obvious that method call syntax now uses a dot instead of an arrow:

$person->name  # Perl 5
$person.name   # Perl 6

The dot notation is both easier to type and more of an industry standard. But we also wanted to steal the arrow for something else. (Concatenation is now done with the ~ operator, if you were wondering.)

To call a method whose name is not known until runtime:

$object->$methodname(@args);  # Perl 5
$object."$methodname"(@args); # Perl 6

If you leave out the quotes, then Perl 6 expects $methodname to contain a Method object, rather than the simple string name of the method.

1.2.3 Whitespace

Perl 5 allows a surprising amount of flexibility in the use of whitespace, even with strict mode and warnings turned on:

# unidiomatic but valid Perl 5
say"Hello ".ucfirst  ($people
    [$ i]
    ->
    name)."!"if$greeted[$i]<1;

Perl 6 also endorses programmer freedom and creativity, but balanced syntactic flexibility against its design goal of having a consistent, deterministic, extensible grammar that supports single-pass parsing and helpful error messages, integrates features like custom operators cleanly, and doesn't lead programmers to accidentally misstate their intent. Also, the practice of "code golf" is slightly de-emphasized; Perl 6 is designed to be more concise in concepts than in keystrokes.

As a result, there are various places in the syntax where whitespace is optional in Perl 5, but is either mandatory or forbidden in Perl 6. Many of those restrictions are unlikely to concern much real-life Perl code (e.g., whitespace being disallowed between the sigil and name of a variable), but there are a few that will unfortunately conflict with some Perl hackers' habitual coding styles:

However, note that you can use unspace to add whitespace in Perl 6 code in places where it is otherwise not allowed:

# Perl 5
my @books = $xml->parse_file($file)          # some comment
                ->findnodes("/library/book");

# Perl 6
my @books = $xml.parse-file($file)\          # some comment
                .findnodes("/library/book");

See also S03#Minimal whitespace DWIMmery and S04#Statement parsing in the Perl 6 design docs.

1.2.4 Sigils

In Perl 5, arrays and hashes use changing sigils depending on how they are being accessed. In Perl 6 the sigils are invariant, no matter how the variable is being used - you can think of them as part of the variable's name.

(See also #Dereferencing).

1.2.4.1 $ Scalar

The $ sigil is now always used with "scalar" variables (e.g. $name), and no longer for array indexing and Hash indexing. That is, you can still use $x[1] and $x{"foo"}, but it will act on $x, with no effect on a similarly named @x or %x. Those would now be accessed with @x[1] and %x{"foo"}.

1.2.4.2 @ Array

The @ sigil is now always used with "array" variables (e.g. @months, @months[2], @months[2, 4]), and no longer for value-slicing hashes.

1.2.4.3 % Hash

The % sigil is now always used with "hash" variables (e.g. %calories, %calories<apple>, %calories<pear plum>), and no longer for key/value-slicing arrays.

1.2.4.4 & Sub

The & sigil is now used consistently (and without the help of a backslash) to refer to the function object of a named subroutine/operator without invoking it, i.e. to use the name as a "noun" instead of a "verb":

my $sub = \&foo; # Perl 5
my $sub = &foo;  # Perl 6

callback => sub { say @_ }  # Perl 5 - can't pass built-in sub directly
callback => &say            # Perl 6 - & gives "noun" form of any sub

Since Perl 6 does not allow adding/removing symbols in a lexical scope once it has finished compiling, there is no equivalent to Perl 5's undef &foo;, and the closest equivalent to Perl 5's defined &foo would be defined &::("foo") (which uses the "dynamic symbol lookup" syntax). However, you can declare a mutable named subroutine with my &foo; and then change its meaning at runtime by assigning to &foo.

In Perl 5, the ampersand sigil can additionally be used to call subroutines in special ways with subtly different behavior compared to normal sub calls. In Perl 6 those special forms are no longer available:

1.2.4.5 * Glob

TODO: Research what exact use-cases still need typeglobs in Perl 5 today, and refactor this section to list them (with translations).

In Perl 5, the * sigil referred to the GLOB structure that Perl uses to store non-lexical variables, file handles, subs, and formats.

(This should not be confused with the Perl 5 built-in glob() function, which reads filenames from a directory).

You are most likely to encounter a GLOB in code written on a early Perl version that does not support lexical filehandles, when a filehandle needed to be passed into a sub.

# Perl 5 - ancient method
sub read_2 {
    local (*H) = @_;
    return scalar(<H>), scalar(<H>);
}
open FILE, '<', $path or die;
my ($line1, $line2) = read_2(*FILE);

You should refactor your Perl 5 code to remove the need for the GLOB, before translating into Perl 6.

# Perl 5 - modern use of lexical filehandles
sub read_2 {
    my ($fh) = @_;
    return scalar(<$fh>), scalar(<$fh>);
}
open my $in_file, '<', $path or die;
my ($line1, $line2) = read_2($in_file);

And here's just one possible Perl 6 translation:

# Perl 6
sub read-n($fh, $n) {
    return $fh.get xx $n;
}
my $in-file = open $path or die;
my ($line1, $line2) = read-n($in-file, 2);

1.2.5 [] Array indexing/slicing

Index and slice operations on arrays no longer inflect the variable's sigil, and adverbs can be used to control the type of slice:

Also note that the subscripting brackets are now a normal postcircumfix operator rather than a special syntactic form, and thus checking for existence of elements and unsetting elements is done with adverbs.

1.2.6 {} Hash indexing/slicing

Index and slice operations on hashes no longer inflect the variable's sigil, and adverbs can be used to control the type of slice. Also, single-word subscripts are no longer magically autoquoted inside the curly braces; instead, the new angle-brackets version is available which always autoquotes its contents (using the same rules as the qw// quoting construct):

Also note that the subscripting curly braces are now a normal postcircumfix operator rather than a special syntactic form, and thus checking for existence of keys and removing keys is done with adverbs.

1.2.7 Reference creation

TODO: Rewrite this section to make it clear that the "referencing/ dereferencing" metaphor does not map cleanly to the actual Perl 6 container system, and focus more on how one would translate or replace actual code that uses references in Perl 5.

In Perl 5, references to anonymous arrays and hashes and subs are returned during their creation. References to existing named variables and subs were generated with the \ operator.

In Perl 6, anonymous arrays and hashes and subs still return their reference during creation. References to named subs are generated by preceding the sub name with a & sigil. References to existing named variables are generated by item context.

my $aref = [ 1, 2, 9 ];          # Both Perl 5&6
my $href = { A => 98, Q => 99 }; # Both Perl 5&6 [*See Note*]

my $aref =     \@aaa  ; # Perl 5
my $aref = item(@aaa) ; # Perl 6

my $href =     \%hhh  ; # Perl 5
my $href = item(%hhh) ; # Perl 6

my $sref =     \&foo  ; # Perl 5
my $sref =      &foo  ; # Perl 6

NOTE: If one or more values reference the topic variable, $_, the right-hand side of the assignment will be interpreted as a Block, not a Hash:

my @people = [
    { id => "1A", firstName => "Andy", lastName => "Adams" },
    { id => "2B", firstName => "Beth", lastName => "Burke" },
    # ...
];

sub lookup-user (Hash $h) { #`(Do something...) $h }

my @names = map {
    my $query = { name => "$_<firstName> $_<lastName>" };
    say $query.WHAT;       # (Block)
    say $query<name>;      # ERROR: Type Block does not support associative indexing

    lookup-user($query);   # Type check failed in binding $h; expected Hash but got Block
}, @people;

Instead, you should either:

See Hash assignment for more details.

1.2.8 Dereferencing

In Perl 5, the syntax for dereferencing an entire reference is the type-sigil and curly braces, with the reference inside the curly braces.

In Perl 6, the curly braces are changed to parentheses.

# Perl 5
    say      ${$scalar_ref};
    say      @{$arrayref  };
    say keys %{$hashref   };
    say      &{$subref    };

# Perl 6
    say      $($scalar_ref);
    say      @($arrayref  );
    say keys %($hashref   );
    say      &($subref    );

Note that in both Perl 5 and Perl 6, the surrounding curly braces or parentheses can often be omitted, though the omission can reduce readability.

In Perl 5, the arrow operator, -> , is used for single access to a composite's reference or to call a sub through its reference. In Perl 6, we now use the dot operator . for those tasks.

# Perl 5
    say $arrayref->[7];
    say $hashref->{'fire bad'};
    say $subref->($foo, $bar);

# Perl 6
    say $arrayref.[7];
    say $hashref.{'fire bad'};
    say $subref.($foo, $bar);

In recent versions of Perl 5 (5.20 and later), a new feature allows the use of the arrow op for dereferencing. See http://search.cpan.org/~shay/perl-5.20.1/pod/perl5200delta.pod#Experimental_Postfix_Dereferencing That new feature corresponds Perl 6 .list and .hash methods:

# Perl 5.20
    use experimental qw< postderef >;
    my @a = $arrayref->@*;
    my %h = $hashref->%*;
    my @slice = $arrayref->@[3..7];

# Perl 6
    my @a = $arrayref.list;         # or @($arrayref)
    my %h = $hashref.hash;          # or %($hashref)
    my @slice = $arrayref[3..7];

The "Zen" slice does the same thing:

# Perl 6
    my @a = $arrayref[];
    my %h = $hashref{};

See S32/Containers

1.3 Operators

See S03/Operators for full details on all operators.

Unchanged:

1.3.1 <=> cmp Three-way comparisons

In Perl 5, these operators returned -1, 0, or 1. In Perl 6, they return Order::Less, Order::Same, or Order::More.

cmp is now named leg; it forces string context for the comparison.

<=> still forces numeric context.

cmp in Perl 6 does either <=> or leg, depending on the existing type of its arguments.

1.3.2 ~~ Smart-match operator

While the operator has not changed, the rules for what exactly is matched depends on the types of both arguments, and those rules are far from identical in Perl 5 and Perl 6. See S03/Smart matching

1.3.3 & | ^ String Bitwise ops

1.3.4 & | ^ Numeric Bitwise ops

1.3.5 & | ^ Boolean ops

In Perl 5, & | ^ were invoked according to the contents of their arguments. For example, 31 | 33 returns a different result than "31" | "33".

In Perl 6, those single-character ops have been removed, and replaced by two-character ops which coerce their arguments to the needed context.

# Infix ops (two arguments; one on each side of the op)
+&  +|  +^  And Or Xor: Numeric
~&  ~|  ~^  And Or Xor: String
?&  ?|  ?^  And Or Xor: Boolean

# Prefix ops (one argument, after the op)
+^  Not: Numeric
~^  Not: String
?^  Not: Boolean (same as the ! op)

1.3.6 << >> Numeric shift left|right ops

Replaced by +< and +> .

say 42 << 3; # Perl 5
say 42 +< 3; # Perl 6

1.3.7 => Fat comma

In Perl 5, => acted just like a comma, but also quoted its left-hand side.

In Perl 6, => is the Pair operator, which is quite different in principle, but works the same in many situations.

If you were using => in hash initialization, or in passing arguments to a sub that expects a hashref, then the usage is likely identical.

# Works in Perl 5 and Perl 6
my %hash = ( AAA => 1, BBB => 2 );
get_the_loot( 'diamonds', { quiet_level => 'very', quantity => 9 }); # Note the curly braces

If you were using => as a convenient shortcut to not have to quote part of a list, or in passing arguments to a sub that expects a flat list of KEY, VALUE, KEY, VALUE, then continuing to use => may break your code. The easiest workaround is to change the fat comma to a regular comma, and manually add quotes to its left-hand side. Or, you can change the sub's API to slurp a hash. A better long-term solution is to change the sub's API to expect Pairs. However, this requires you to change all sub calls at once.

# Perl 5
sub get_the_loot {
    my $loot = shift;
    my %options = @_;
    # ...
}
# Note: no curly braces in this sub call
get_the_loot( 'diamonds', quiet_level => 'very', quantity => 9 );
# Perl 6, original API
sub get_the_loot( $loot, *%options ) { # The * means to slurp everything
    ...
}
get_the_loot( 'diamonds', quiet_level => 'very', quantity => 9 ); # Note: no curly braces in this API

# Perl 6, API changed to specify valid options
# The colon before the sigils means to expect a Pair,
# with the key having the same name as the variable.
sub get_the_loot( $loot, :$quiet_level?, :$quantity = 1 ) {
    # This version will check for unexpected arguments!
    ...
}
get_the_loot( 'diamonds', quietlevel => 'very' ); # Throws error for misspelled parameter name

1.3.8 ? : Ternary operator

Now spelled with two question marks instead of one question mark, and two exclamation points instead of one colon.

my $result = ( $score > 60 )  ? 'Pass'  : 'Fail'; # Perl 5
my $result = ( $score > 60 ) ?? 'Pass' !! 'Fail'; # Perl 6

1.3.9 . (Dot op) Concatenation

Replaced by the tilde.

Mnemonic: think of "stitching" together the two strings with needle and thread.

$food = 'grape' . 'fruit'; # Perl 5
$food = 'grape' ~ 'fruit'; # Perl 6

1.3.10 x List Repeat op or String Repeat op

In Perl 5, x was the Repetition operator.

In scalar context, x would repeat a string. In Perl 6, x repeats strings in any context.

In list context, x would repeat a list—but only if the left argument is parenthesized! In Perl 6, the new xx op repeats lists in any context.

Mnemonic: x is short and xx is long, so xx is the one used for lists.

# Perl 5
    print '-' x 80;             # Print row of dashes
    @ones = (1) x 80;           # A list of 80 1's
    @ones = (5) x @ones;        # Set all elements to 5
# Perl 6
    print '-' x 80;             # Unchanged
    @ones = 1 xx 80;            # Parentheses no longer needed
    @ones = 5 xx @ones;         # Parentheses no longer needed

1.3.11 .. ... Two Dots or Three Dots, Range op or Flipflop op

In Perl 5, .. was one of two completely different operators, depending on context.

In list context, .. is the familiar range operator. Range has many new wrinkles in Perl 6, but ranges from Perl 5 code should not require translation.

In scalar context, .. and ... were the little-known Flipflop operators. They have been replaced by ff and fff.

1.3.12 String interpolation

In Perl 5, "${foo}s" deliminates a variable name from regular text next to it. In Perl 6, simply extend the curly braces to include the sigil too: "{$foo}s"

1.4 Compound Statements

1.4.1 Conditionals

1.4.1.1 if elsif else unless

Mostly unchanged; parentheses around the conditions are now optional, but if used, must not immediately follow the keyword, or it will be taken as a function call instead. Binding the conditional expression to a variable is also a little different:

if (my $x = dostuff()) {...}  # Perl 5
if dostuff() -> $x {...}      # Perl 6

(You can still use the my form in Perl 6, but it will scope to the outer block, not the inner.)

The unless conditional only allows for a single block in Perl 6; it does not allow for an elsif or else clause.

1.4.1.2 given-when

The given-when construct is like a chain of if-elsif-else statements or like the switch-case construct in e.g. C. It has the general structure:

given EXPR {
    when EXPR { ... }
    when EXPR { ... }
    default { ... }
}

In its simplest form, the construct is as follows:

given $value {
    when "a match" {
        do-something();
    }
    when "another match" {
        do-something-else();
    }
    default {
        do-default-thing();
    }
}

This is simple in the sense that a scalar value is matched in the when statements. More generally, the matches are actually smart-matches on the input value such that lookups using more complex entities such as regexps can be used instead of scalar values.

See also the warnings on the smart-match op above.

1.4.2 Loops

1.4.2.1 while until

Mostly unchanged; parentheses around the conditions are now optional, but if used, must not immediately follow the keyword, or it will be taken as a function call instead. Binding the conditional expression to a variable is also a little different:

while (my $x = dostuff()) {...}  # Perl 5
while dostuff() -> $x {...}      # Perl 6

(You can still use the my form in Perl 6, but it will scope to the outer block, not the inner.)

Note that reading line-by-line from a filehandle has changed.

In Perl 5, it was done in a while loop using the diamond operator. Using for instead of while was a common bug, because the for causes the whole file to be sucked in at once, swamping the program's memory usage.

In Perl 6, for statement is lazy, so we read line-by-line in a for loop using the .lines method.

while (<IN_FH>)  { } # Perl 5
for $IN_FH.lines { } # Perl 6

1.4.2.2 do while/until

do {
    ...
} while $x < 10;

do {
    ...
} until $x >= 10;

The construct is still present, but do was renamed to repeat, to better represent what the construct does:

repeat {
    ...
} while $x < 10;

repeat {
    ...
} until $x >= 10;

1.4.2.3 for foreach

Note first this common misunderstanding about the for and foreach keywords. Many programmers think that they distinguish between the C-style three-expression form and the list-iterator form; they do not! In fact, the keywords are interchangeable; the Perl 5 compiler looks for the semi-colons within the parentheses to determine which type of loop to parse.

The C-style three-factor form now uses the loop keyword, and is otherwise unchanged. The parentheses *are* still required.

for  ( my $i = 1; $i <= 10; $i++ ) { ... } # Perl 5
loop ( my $i = 1; $i <= 10; $i++ ) { ... } # Perl 6

The loop-iterator form of for or foreach is named for in Perl 6. foreach is no longer a keyword. Parentheses are optional.

The iteration variable, if any, has been moved from before the list, to after the list and an added arrow operator.

The iteration variable is now always lexical; my is neither needed nor allowed.

In Perl 5, the iteration variable is a read-write alias to the current list element.

In Perl 6, that alias is read-only (for safety), unless you change -> to <->. When translating, inspect the use of the loop variable to decide if read-write is needed.

for my $car (@cars)  {...} # Perl 5; read-write
for @cars  -> $car   {...} # Perl 6; read-only
for @cars <-> $car   {...} # Perl 6; read-write

If the default topic $_ is being used, but needs to be read-write, then just use <-> and explicitly specify $_.

for (@cars)      {...} # Perl 5; default topic
for @cars        {...} # Perl 6; $_ is read-only
for @cars <-> $_ {...} # Perl 6; $_ is read-write

1.4.2.3.1 each

Here is the equivalent to Perl 5’s while…each(%hash) or while…each(@array) (= iterating over both the keys or indices and values of a data structure) in Perl 6:

while (my ($i, $v) = each(@array)) { ... } # Perl 5
for @array.kv -> $i, $v { ... } # Perl 6

while (my ($k, $v) = each(%hash)) { ... } # Perl 5
for %hash.kv -> $k, $v { ... } # Perl 6

1.4.3 Flow Control statements

Unchanged:

1.4.3.1 continue

There is no longer a continue block. Instead, use a NEXT block within the body of the loop.

# Perl 5
    my $str = '';
    for (1..5) {
        next if $_ % 2 == 1;
        $str .= $_;
    }
    continue {
        $str .= ':'
    }
# Perl 6
    my $str = '';
    for 1..5 {
        next if $_ % 2 == 1;
        $str ~= $_;
        NEXT {
            $str ~= ':'
        }
    }

1.5 Functions

NOTE FOR EDITORS: When adding functions, please place them in alphabetical order.

1.5.1 Built-ins with bare blocks

Builtins that previously accepted a bare block followed, without a comma, by the remainder of the arguments will now require a comma between the block and the arguments e.g. map, grep, etc.

my @results = grep { $_ eq "bars" } @foo; # Perl 5
my @results = grep { $_ eq "bars" }, @foo; # Perl 6

1.5.2 delete

Turned into an adverb of the {} hash subscripting and [] array subscripting operators.

my $deleted_value = delete $hash{$key};  # Perl 5
my $deleted_value = %hash{$key}:delete;  # Perl 6 - use :delete adverb

my $deleted_value = delete $array[$i];  # Perl 5
my $deleted_value = @array[$i]:delete;  # Perl 6 - use :delete adverb

1.5.3 exists

Turned into an adverb of the {} hash subscripting and [] array subscripting operators.

say "element exists" if exists $hash{$key};  # Perl 5
say "element exists" if %hash{$key}:exists;  # Perl 6 - use :exists adverb

say "element exists" if exists $array[$i];  # Perl 5
say "element exists" if @array[$i]:exists;  # Perl 6 - use :exists adverb

1.6 Regular Expressions ( Regex / Regexp )

1.6.1 Change =~ and !~ to ~~ and !~~ .

In Perl 5, matches and substitutions are done against a variable using the =~ regexp-binding op.

In Perl 6, the ~~ smartmatch op is used instead.

next if $line  =~ /static/  ; # Perl 5
next if $line  ~~ /static/  ; # Perl 6

next if $line  !~ /dynamic/ ; # Perl 5
next if $line !~~ /dynamic/ ; # Perl 6

$line =~ s/abc/123/;          # Perl 5
$line ~~ s/abc/123/;          # Perl 6

Alternately, the new .match and .subst methods can be used. Note that .subst is non-mutating. See S05/Substitution.

1.6.2 Captures start with 0, not 1

/(.+)/ and print $1; # Perl 5
/(.+)/ and print $0; # Perl 6

1.6.3 Move modifiers

Move any modifiers from the end of the regex to the beginning. This may require you to add the optional m on a plain match like /abc/.

next if $line =~    /static/i ; # Perl 5
next if $line ~~ m:i/static/  ; # Perl 6

1.6.4 Add :P5 or :Perl5 adverb

If the actual regex is complex, you may want to use it as-is, by adding the P5 modifier.

next if $line =~    m/[aeiou]/   ; # Perl 5
next if $line ~~ m:P5/[aeiou]/   ; # Perl 6, using P5 modifier
next if $line ~~ m/  <[aeiou]> / ; # Perl 6, native new syntax

1.6.5 Special matchers generally fall under the <> syntax

There are many cases of special matching syntax that Perl 5 regexes support. They won't all be listed here, but often instead of being surrounded by (), the assertions will be surrounded by <>.

For character classes, this means that:

For look-around assertions:

(Unrelated to <> syntax, the "lookaround" /foo\Kbar/ becomes /foo <( bar )> /

1.6.6 Longest token matching (LTM) displaces alternation

In Perl 6 regexes, | does LTM, which decides which alternation wins an ambiguous match based off of a set of rules, rather than about which was written first.

The simplest way to deal with this is just to change any | in your Perl 5 regex to a ||.

TODO more rules. Use translate_regex.pl from Blue Tiger in the meantime.

1.7 Pragmas

1.7.6.1 strict

Strict mode is now on by default.

1.7.6.2 warnings

Warnings are now on by default.

no warnings is currently NYI, but putting things in a quietly {} block will silence.

1.7.6.3 autodie

The functions which were altered by autodie to throw exceptions on error, now throw exceptions by default unless you test the return value explicitly.

# Perl 5
open my $i_fh, '<', $input_path;  # Fails silently on error
use autodie;
open my $o_fh, '>', $output_path; # Throws exception on error

# Perl 6
my $i_fh = open $input_path,  :r; # Throws exception on error
my $o_fh = open $output_path, :w; # Throws exception on error

1.7.6.4 base

1.7.6.5 parent

Both use base and use parent have been replaced in Perl 6 by the is keyword, in the class declaration.

# Perl 5
package Cat;
use base qw(Animal);

# Perl 6
class Cat is Animal;

1.7.6.6 bigint bignum bigrat

No longer relevant.

Int is now arbitrary precision, as is the numerator of Rat (the denominator is limited to 2**64, after which it will automatically upgrade to Num to preserve performance). If you want a Rat with an arbitrary-precision denominator, FatRat is available.

1.7.6.7 constant

In Perl 6, constant is a declarator for variables, just like my, except the variable is permanently locked to the result of its initialization expression (evaluated at compile time).

So, change the => to =.

use constant DEBUG => 0; # Perl 5
constant DEBUG = 0;      # Perl 6

use constant pi => 4 * atan2(1, 1); # Perl 5
# pi, e, i are built-in constants in  Perl 6

1.7.6.8 encoding

TODO Allows you to write your script in non-ascii or non-utf8

1.7.6.9 integer

Perl pragma to use integer arithmetic instead of floating point

1.7.6.10 lib

Manipulate @INC at compile time

1.7.6.11 mro

No longer relevant.

In Perl 6, method calls now always use the C3 method resolution order.

1.7.6.12 utf8

No longer relevant.

In Perl 6, source code is expected to be in utf8 encoding.

1.7.6.13 vars

Discouraged in Perl 5. See http://perldoc.perl.org/vars.html.

You should refactor your Perl 5 code to remove the need for use vars, before translating into Perl 6.

1.8 Command-line flags

See S19/commandline

Unchanged:

-c -e -h -I -n -p -S -T -v -V

1.8.6.1 -a

Unchanged in the Spec, but not yet implemented in Rakudo.

For now, change your code to use .split manually.

1.8.6.2 -F

Unchanged in the Spec, but not yet implemented in Rakudo.

For now, change your code to use .split manually.

1.8.6.3 -l

This is now the default behavior.

1.8.6.4 -M -m

Only -M remains. And, as you can no longer use the "no Module" syntax, the use of - with -M to "no" a module is no longer available.

1.8.6.5 -E

Since all features are already enabled, just use lowercase -e .

1.8.6.6 -d, -dt, -d:foo, -D, etc.

Replaced with the ++BUG metasyntactic option.

1.8.6.7 -s

Switch parsing is now done by the parameter list of the MAIN subroutine.

# Perl 5
    #!/usr/bin/perl -s
    if ($xyz) { print "$xyz\n" }
./example.pl -xyz=5
5

# Perl 6
    sub MAIN( Int :$xyz ) {
        say $xyz if $xyz.defined;
    }
perl6 example.p6 --xyz=5
5
perl6 example.p6 -xyz=5
5

Taint warnings are not yet specified.

Removed. See S19#Removed Syntactic Features.

This is now the default behavior.

1.9 File-related operations

1.9.1 Reading the lines of a text file into an array

In Perl 5, a common idiom for reading the lines of a text file goes something like this:

open my $fh, "<", "file" or die "$!";
my @lines = <$fh>;
close $fh;

In Perl 6, this has been simplified to

my @lines = "file".IO.lines;

Do not be tempted to try slurping in a file and splitting the resulting string on newlines as this will give an array with a trailing empty element, which is one more than you probably expect (it's also more complicated), e.g.:

# initialize the file to read
spurt "test-file", q:to/END/;
first line
second line
third line
END
# read the file
my @lines = "test-file".IO.slurp.split(/\n/);
say @lines.elems;    #-> 4

1.9.2 Trapping the standard output of executables.

Whereas in Perl 5 you would do:

my $arg = 'Hello';
my $captured = `echo \Q$arg\E`;
my $captured = qx(echo \Q$arg\E);

Or using String::ShellQuote (because \Q…\E is not completely right):

my $arg = shell_quote 'Hello';
my $captured = `echo $arg`;
my $captured = qx(echo $arg);

In Perl 6, you will probably want to run commands without using the shell:

my $arg = 'Hello';
my $captured = run('echo', $arg, :out).out.slurp-rest;
my $captured = run(«echo "$arg"», :out).out.slurp-rest;

You can also use the shell if you really want to:

my $arg = 'Hello';
my $captured = shell("echo $arg", :out).out.slurp-rest;
my $captured = qqx{echo $arg};

But beware that in this case there is no protection at all! run does not use the shell, so there is no need to escape the arguments (arguments are passed directly). If you are using shell or qqx, then everything ends up being one long string which is then passed to the shell. Unless you validate your arguments very carefully, there is a high chance to introduce shell injection vulnerabilities with such code.

1.10 Environment variables

1.10.1 Perl module library path

In Perl 5 one of the environment variables to specify extra search paths for Perl modules is PERL5LIB.

$ PERL5LIB="/some/module/lib" perl program.pl

In Perl 6 this is similar, one merely needs to change a number! As you probably guessed, you just need to use PERL6LIB :

$ PERL6LIB="/some/module/lib" perl6 program.p6

In Perl 5 one uses the ':' (colon) as a directory separator for PERL5LIB, but in Perl 6 one uses the ',' (comma). For example:

$ export PERL5LIB=/module/dir1:/module/dir2;

but

$ export PERL6LIB=/module/dir1,/module/dir2;

(Perl 6 does not recognize either the PERL5LIB or the older Perl environment variable PERLLIB.)

As with Perl 5, if you don't specify PERL6LIB, you need to specify the library path within the program via the use lib pragma:

use lib '/some/module/lib'

Note that PERL6LIB is more of a developer convenience in Perl 6 (as opposed to the equivalent usage of PERL5LIB in Perl5) and shouldn't be used by module consumers as it could be removed in the future. This is because Perl 6's module loading isn't directly compatible with operating system paths.

1.11 Misc.

1.11.1 '0' is True

Unlike Perl 5, a string containing nothing but zero ('0') is True. As Perl 6 has types in core, that makes more sense. This also means the common pattern:

... if defined $x and length $x; # or just length() in modern perls

In Perl 6 becomes a simple

... if $x;

1.11.2 dump

Gone.

The Perl 6 design allows for automatic transparent saving-and-loading of compiled bytecode.

Rakudo supports this only for modules so far.

1.11.3 Importing specific functions from a module

In Perl 5 it is possible to selectively import functions from a given module like so:

use ModuleName qw{foo bar baz};

In Perl 6 one specifies the functions which are to be exported by using the is export role on the relevant subs and all subs with this role are then exported. Hence, the following module Bar exports the subs foo and bar but not baz:

unit module Bar;

sub foo($a) is export { say "foo $a" }
sub bar($b) is export { say "bar $b" }
sub baz($z) { say "baz $z" }

To use this module, simply use Bar and the functions foo and bar will be available

use Bar;
foo(1);    #=> "foo 1"
bar(2);    #=> "bar 2"

If one tries to use baz an "Undeclared routine" error is raised at compile time.

So, how does one recreate the Perl 5 behaviour of being able to selectively import functions? For this one needs to define an EXPORT sub inside the module which specifies the functions to be exported and (in the current implementation of Rakudo (2015.03)) remove the module Bar statement. (Please note that not having the module statement isn't consistent with Synopsis 11, however it works.)

The module Bar now is merely a file called Bar.pm with the following contents:

use v6.c;

sub EXPORT(*@import-list) {
    my %exportable-subs =
        '&foo' => &foo,
        '&bar' => &bar,
        ;
    my %subs-to-export;
    for @import-list -> $import {
        if grep $sub-name, %exportable-subs.keys {
            %subs-to-export{$sub-name} = %exportable-subs{$sub-name};
        }
    }
    return %subs-to-export;
}

sub foo($a, $b, $c) { say "foo, $a, $b, $c" }
sub bar($a) { say "bar, $a" }
sub baz($z) { say "baz, $z" }

Note that the subs are no longer explicitly exported via the is export role. We are defining an EXPORT sub which specifies the subs in the module we want to be available for export and then we are populating a hash containing the subs which will actually be exported. The @import-list is set by the use statement in the calling code thus allowing us to selectively import the subs made available by the module.

So, to import only the foo routine, we do the following in the calling code:

use Bar <foo>;
foo(1);       #=> "foo 1"

Here we see that even though bar is able to be exported, if we don't explicitly import it, it's not available for use. Hence this causes an "Undeclared routine" error at compile time:

use Bar <foo>;
foo(1);
bar(5);       #!> "Undeclared routine: bar used at line 3"

however, this will work

use Bar <foo bar>;
foo(1);       #=> "foo 1"
bar(5);       #=> "bar 5"

Note also that baz remains unimportable even if specified in the use statement:

use Bar <foo bar baz>;
baz(3);       #!> "Undeclared routine: baz used at line 2"

In order to get this to work, one obviously has to jump through many hoops. In the standard use-case where one specifies the functions to be exported via the is export role, Perl 6 automatically creates the EXPORT sub in the correct manner for you, so one should consider very carefully whether or not writing one's own EXPORT routine is worthwhile.

1.12 Core modules

1.12.3.1 Data::Dumper

In Perl 5, the Data::Dumper module was used for serialization, and for debugging views of program data structures by the programmer.

In Perl 6, these tasks are accomplished with the .perl method, which every object has.

# Given:
    my @array_of_hashes = (
        { NAME => 'apple',   type => 'fruit' },
        { NAME => 'cabbage', type => 'no, please no' },
    );
# Perl 5
    use Data::Dumper;
    $Data::Dumper::Useqq = 1;
    print Dumper \@array_of_hashes; # Note the backslash.
# Perl 6
    say @array_of_hashes.perl; # .perl on the array, not on its reference.

In Perl 5, Data::Dumper has a more complex optional calling convention, which allows for naming the VARs.

In Perl 6, placing a colon in front of the variable's sigil turns it into a Pair, with a key of the var name, and a value of the var value.

# Given:
    my ( $foo, $bar ) = ( 42, 44 );
    my @baz = ( 16, 32, 64, 'Hike!' );
# Perl 5
    use Data::Dumper;
    print Data::Dumper->Dump(
        [     $foo, $bar, \@baz   ],
        [ qw(  foo   bar   *baz ) ],
    );
# Output
    $foo = 42;
    $bar = 44;
    @baz = (
             16,
             32,
             64,
             'Hike!'
           );
# Perl 6
    say [ :$foo, :$bar, :@baz ].perl;
# Output
    ["foo" => 42, "bar" => 44, "baz" => [16, 32, 64, "Hike!"]]

1.12.3.2 Getopt::Long

Switch parsing is now done by the parameter list of the MAIN subroutine.

# Perl 5
    use 5.010;
    use Getopt::Long;
    GetOptions(
        'length=i' => \( my $length = 24       ), # numeric
        'file=s'   => \( my $data = 'file.dat' ), # string
        'verbose'  => \( my $verbose           ), # flag
    ) or die;
    say $length;
    say $data;
    say 'Verbosity ', ($verbose ? 'on' : 'off') if defined $verbose;
perl example.pl
    24
    file.dat
perl example.pl --file=foo --length=42 --verbose
    42
    foo
    Verbosity on

perl example.pl --length=abc
    Value "abc" invalid for option length (number expected)
    Died at c.pl line 3.

# Perl 6
    sub MAIN( Int :$length = 24, :file($data) = 'file.dat', Bool :$verbose ) {
        say $length if $length.defined;
        say $data   if $data.defined;
        say 'Verbosity ', ($verbose ?? 'on' !! 'off');
    }
perl6 example.p6
    24
    file.dat
    Verbosity off
perl6 example.p6 --file=foo --length=42 --verbose
    42
    foo
    Verbosity on
perl6 example.p6 --length=abc
    Usage:
      c.p6 [--length=<Int>] [--file=<Any>] [--verbose]

Note that Perl 6 auto-generates a full usage message on error in command-line parsing.

1.13 Automated Translation

A quick way to find the Perl 6 version of a Perl 5 construct, is to run it through an automated translator.

NOTE: None of these translators are yet complete.

1.13.1 Blue Tiger

This project is dedicated to automated modernization of Perl code. It does not (yet) have a web front-end, and so must be locally installed to be useful. It also contains a separate program to translate Perl 5 regexes into Perl 6.

https://github.com/Util/Blue_Tiger/

1.13.2 Perlito

Online Translator!

This project is a suite of Perl cross-compilers, including Perl 5-to-6 translation. It has a web front-end, and so can be used without installation. It only supports a subset of Perl 5 syntax so far.

http://fglock.github.io/Perlito/perlito/perlito5.html

1.13.3 MAD

Larry Wall's own code for translating Perl 5 to Perl 6 has bit-rotted, and is not (currently) viable on recent releases of Perl 5.

MAD (Misc Attribute Definition) is a configuration option when building Perl from a source distribution. The `perl` executable analyses and translates your Perl sourcecode into an op-tree, and then executes the program by walking the op-tree. Normally, most of the details from the analysis are thrown away during this process. When MAD is enabled, the `perl` executable will save those details to an XML file, which can then be read and further processed into Perl 6 code by a MAD parser.

Please consult #perl6 to find out the best release of Perl 5 to use for your MAD science experiments.

1.13.4 Perl-ToPerl6

Jeff Goff's Perl::ToPerl6 module for Perl 5 is designed around Perl::Critic's framework. It aims to convert Perl5 to compilable (if not necessarily running) Perl 6 code with the bare minimum of changes. Code transformers are configurable and pluggable, so you can create and contribute your own transformers, and customize existing transformers to your own needs. You can install the latest release from CPAN, or follow the project live on GitHub. An online converter may become available at some point.

1.14 Other sources of translation knowledge

2 5to6-perlfunc

Perl 5 to Perl 6 guide - functions

2.1 DESCRIPTION

A (hopefully) comprehensive list of Perl 5 builtin functions with their Perl 6 equivalents with notes on variations between them where necessary.

2.2 NOTE

I will not be explaining the functions in detail. This document is an attempt to guide you from the functions in Perl 5's perlfunc document to their equivalents in Perl 6. For full documentation on the Perl 6 functions, please see the Perl 6 documentation.

One general comment: Perl 6 takes its objects a lot more seriously than Perl 5. In Perl 6, everything is an object, although the language is flexible enough to not force you to work in an object oriented manner if you do not wish to do so. What this does mean, however, is that a lot of things that are function calls of the form function(@args) are now also method calls of the form @args.function (In rare cases, there is only a method call). This should be obvious in the following text, but it probably behooves you to get into that frame of mind now.

Also, unless otherwise stated, the use of the term "function" here will mean a function in the style of func(@args), while "method" will refer to a function in the style of @args.func.

2.3 Alphabetical Listing of Perl Functions

2.3.1 Filetests

Perl 6 gives you a couple of options when it comes to file tests. You can do a smart match (~~) or you can call a method.

In Perl 6, you don't need to actually open a filehandle in the traditional way (although you can) to do a filetest. You can simply append .IO to the filename. For instance, here is how to check if a file is readable using smart match:

'/path/to/file'.IO ~~ :r

You can, of course, use an already opened filehandle. Here, using the file handle $fh, is an example, using the method syntax for the file test:

$fh.r

Most of the former filetests have colon equivalents for use with smart match:

:e Exists
:d Directory
:f File
:l Symbolic link
:r Readable
:w Writable
:x Executable
:s Size
:z Zero size

All of these tests can be used as methods (without the colon).

Three tests, however, only have method equivalents:

$fh.modified; # -M $fh
$fh.accessed; # -A $fh
$fh.changed;  # -C $fh

The remaining filetests in Perl 5 do not appear to be implemented in Perl 6.

The documentation for this can be found at File test operators.

There is more information on reading and writing files at io. Also, the section on open() below may be helpful.

2.3.2 abs

Works as a function (abs($x)), but also as a method. One gotcha, however - method calls bind more tightly than -, so, for example, -15.abs evaluates as -(15.abs) giving you -15. In this example, you would have to do something like (-15).abs.

abs also operates on $_ in the absence of a value, but not as a function, and as a method you need to call it as .abs rather than simply abs.

2.3.3 accept

accept is a method you can call on a server, e. g. $server.accept(). Instead of returning a packed address, it returns a socket, most likely an IO::Socket object of some sort.

2.3.4 alarm

[NEEDS FURTHER RESEARCH] alarm() is no more. It has been suggested that a replacement may be somewhere in the new Concurrency features, such as Promise.in, but some digging may be needed to find a true analog.

2.3.5 atan2

Available as a function as well as being able to be used as a method. For instance, these are equivalent:

atan2(100);
100.atan2;

2.3.6 bind

[NEEDS FURTHER RESEARCH] No sign of a socket-related bind() in Perl 6. At a guess, whatever socket binding is needed happens when you create a new socket object.

2.3.7 binmode

Instead of this, you would use :bin as the file mode when opening the socket. E. g. my $fh = open("path/to/file", :bin);

2.3.8 bless

With the changes in class creation in Perl 6, this may find less use than in Perl 5, and is a method as well as a function. The Perl 6 docs say "Creates a new object of the same type as the invocant, uses the named arguments to initialize attributes, and returns the created object." If you're porting a module from Perl 5 to Perl 6, it's quite possible you'll want to use new for creating objects rather than bless, although there may be some situations in which the latter may still be useful.

2.3.9 break

Not in Perl 6. For breaking out of given blocks, you should probably take a look at proceed and succeed here.

2.3.10 caller

There are a couple different ways to get at caller information in Perl 6. The basic functionality is provided through callframe now. However, Perl 6 constructs call frames for regular blocks, not just for subroutines, so there are more frames to look through. The following will retrieve the basic information that caller can return:

my $frame   = callframe(0); # OR just callframe()
my ($subroutine, $package);
if $frame.code ~~ Routine {
    $subroutine = $frame.code.name;
    $package    = $frame.code.package;
}
my $file    = $frame.file;
my $line    = $frame.line;

Many of the other details returned by caller are specific to Perl 5 and have no meaning in Perl 6.

You can also get some of the information for the current frame or routine frame by using the dynamic variables &?ROUTINE, &?BLOCK, $?PACKAGE, $?FILE, and $?LINE. For many purposes, Backtrace may provide an easier way to browse through the call stack.

2.3.11 chdir

Works as it does in Perl 5.

2.3.12 chmod

Functions as under Perl 5, with the difference that octal numbers are represented differently (0o755 rather than 0755). You may also use it as a method, e. g. $fh.chmod(0o755).

2.3.13 chomp

The behavior of chomp is different than in Perl 5. It leaves the target unaffected and returns a copy of the target with a final logical newline removed, e.g. $x = "howdy\n";$y = chomp($x); results in $x containing "howdy\n" and $y containing "howdy". Also works as a method, e.g. $y = $x.chomp. As with many other methods, also works with assignment to modify the target in place, e.g. $x.=chomp results in $x containing "howdy".

2.3.14 chop

As with chomp, in Perl 6, this returns the chopped string, rather than chopping in place. I. e. $x = "howdy";$y = chop($x); results in $x being "howdy" and $y being "howd". Also works as a method: $y = $x.chop

2.3.15 chown

chown is not in Perl 6.

2.3.16 chr

Similar to the Perl 5 version, coerces the target to an integer, and uses that as a Unicode code point to return the relevant character. Can be used as a function and a method:

chr(65); # "A"
65.chr;  # "A"

2.3.17 chroot

Apparently this is not in Perl 6.

2.3.18 close

As in Perl 5, closes a filehandle. Returns a boolean value. Both close $fh and $fh.close will work.

2.3.19 closedir

Currently, there is no closedir function. When it is implemented, it may well be a method in the IO::Dir class.

2.3.20 connect

Use connect from IO::Socket::Async for an asynchronous socket or create a IO::Socket::INET socket for a synchronous one.

2.3.21 continue

Instead of a continue block, you should use a NEXT block. The closest analog to a bare continue; in Perl 5 appears to be proceed/succeed.

2.3.22 cos

Works as in Perl 5, but can be also used as a method, i. e. (1/60000).cos.

2.3.23 crypt

This appears not to have made it into Perl 6.

2.3.24 dbm functions

These functions have largely been superseded in Perl 5, and are unlikely to ever turn up in Perl 6 (although any assumptions about the Perl 6 database implementation may be premature).

2.3.25 defined

Probably does what you expect, but technically it returns False on the type object, and True otherwise. This may make more sense when you realize that $num.perl is the type Any if you haven't assigned anything to it, and the assigned value if you have. Can, of course be used as a method: $num.defined

2.3.26 delete

Perl 6 replaces this with the new adverb syntax, specifically the :delete adverb. E. g. my $deleted_value = %hash{$key}:delete; and my $deleted_value = @array[$i]:delete;.

2.3.27 die

Works similarly to the Perl 5 version, but Perl 6's Exception mechanism may give you more power and flexibility than is available in Perl 5. See exceptions. To omit the stacktrace and location, like Perl 5's die "...\n", use:

note "...";
exit 1;

2.3.28 do

Similar to the Perl 5 version. Note that there must be a space between the do and the block.

Has been replaced in Perl 6 by EVALFILE.

2.3.29 dump

According to S29, dump has been... dumped.

2.3.30 each

There is no exact equivalent, but you can use %hash.kv which returns a list of keys and values. For example: for %hash.kv -> $k, $v { say "$k: $v" }

Incidentally, what we have there with the -> is called a pointy block and, though there are a number of examples in the documentation, there doesn't seem to be a really clear explanation of how they work. https://design.perl6.org/S04.html#The_for_statement may be of some help here, as well as the design document at https://design.perl6.org/S06.html#%22Pointy_blocks%22. There is also some information at https://en.wikibooks.org/wiki/Perl_6_Programming/Blocks_and_Closures#Pointy_Blocks

2.3.31 eof

In Perl 6, this is not usable as a function, but only as a method. I. e. $filehandle.eof. Returns True if at end of file.

2.3.32 eval

Replaced by EVAL. Note that EVAL does not do any exception handling!

2.3.33 evalbytes

No equivalent.

2.3.34 exec

Nothing in Perl 6 exactly replicates the Perl 5 exec. shell and run are similar to Perl 5's system, but exec's behavior of not returning after executing a system command would have to be emulated by something like shell($command);exit(); or possibly exit shell($command);.

Neither of these workarounds have the behavior (on Unix-like systems) of replacing your Perl program's process with the new program; notably, they will not work for the practice in some long-running daemons of periodically redoing exec on themselves to reset their state or force operating-system cleanup. Nor will they serve exec's function of returning stale resources to the operating system.

If you want exec for these behaviors, you can use an exec* function via the NativeCall interface. Consult your operating system manual pages for exec (or other similarly-named calls such as execl, execv, execvp, or execvpe). (Beware: these calls are not generally portable between Unix-like operating system families.)

2.3.35 exists

In Perl 6, this is not a function, but an adverb:

%hash{$key}:exists;
@array[$i]:exists;

2.3.36 exit

Appears to do the same thing as in Perl 5.

2.3.37 exp

Same as in Perl 5, but can also be used as a method: 5.exp;

2.3.38 fc

Looks like it does the same thing as in Perl 5.

2.3.39 fcntl

Appears not to be in Perl 6.

2.3.40 __FILE__

Replaced by $?FILE.

2.3.41 fileno

S32 indicates that this should be available as a method, but appears currently unimplemented.

2.3.42 flock

Currently unimplemented.

2.3.43 fork

Not implemented as a built in function, but available through the NativeCall interface. E. g. use NativeCall; sub fork returns int32 is native { * }; say fork;.

2.3.44 formats

Perl 6 does not have built-in formats.

2.3.45 getc

Reads a single character from the input stream as in Perl 5. May now also be used as a method: $filehandle.getc

2.3.46 getlogin

S29 lists it, but it does not seem to be implemented yet.

2.3.47 getpeername

S29 lists it, but the implementation does not seem clear or, for that matter, implemented.

2.3.48 getpgrp

Does not appear to be implemented.

2.3.49 getpriority

Does not appear to be implemented.

2.3.50 get and set functions

[NEEDS FURTHER RESEARCH] Apparently this range of functions are to be handled by roles like User, Group, etc.

2.3.51 getsock*

[NEEDS FURTHER RESEARCH] These are likely implemented by some kind of IO::Socket object, but details are unclear.

2.3.52 glob

Used in an example in S32, but apparently unimplemented.

2.3.53 gmtime

Like the various parts of localtime, gmtime's functionality appears to in the DateTime object. To get a UTC version of a DateTime object for the current time, for instance, use my $gmtime = DateTime.now.utc.

2.3.54 goto

[NEEDS FURTHER RESEARCH] Described in S04, but not yet fully documented.

2.3.55 grep

Still in Perl 6, with the caveat that the block form now requires a comma after the block. I.e. @foo = grep { $_ = "bars" }, @baz. Can also be used as a method: @foo = @bar.grep(/^f/)

2.3.56 hex

Replaced by the adverbial form :16. E. g. :16("aF") returns 175.

Alternately, the same result can be achieved by using the .base method: 0xaF.base(10)

It just so happens that .Str defaults to base 10, so if you just say 0xaF, that will also print 175, but that may not be immediately obvious, so may not be the best way to go for this.

2.3.57 import

Was never a builtin function in Perl 5 in the first place. In Perl 6, typically, one declares functions as exportable or not, and all the exportable ones are exported. Nevertheless, selective importing is possible, but beyond the scope of this document. For details, see this section.

2.3.58 index

Works as in Perl 5. Can also now be used as a method: "howdy!".index("how"); # 0

2.3.59 int

There is a truncate function in Perl 6 (also usable as a method) that does what Perl 5's int does. You may want to use that as a direct translation of Perl 5 code, but in Perl 6, you can just as easily call the .Int method on the number. 3.9.Int; # 3 and 3.9.truncate are equivalent.

2.3.60 ioctl

Currently unimplemented in Perl 6.

2.3.61 join

Works as in Perl 5, and also works as a method: @x.join(",")

2.3.62 keys

Works as in Perl 5, and can also be used as a method: %hash.keys

2.3.63 kill

No pre-defined core alternative exists. A non-portable method can be to use NativeCall:

use NativeCall;
sub kill(int32, int32) is native {*};
kill $*PID, 9; # OUTPUT: «Killed␤»

To kill processes that were started by creating a Proc::Async, use Proc::Async.kill method.

2.3.64 last

Same as in Perl 5.

2.3.65 lc

Works as in Perl 5, and also as a method: "UGH".lc

2.3.66 lcfirst

Does not exist in Perl 6.

2.3.67 length

Replaced by chars, typically used as a method ($string.chars), but also works as a function.

2.3.68 __LINE__

Replaced by $?LINE.

In Perl 6, part of the IO::Path class. The only difference between Perl 5 and Perl 6 is that the argument order has changed. It's now link($original, $linked_file).

2.3.70 listen

Not clearly documented, but it appears that listen will be a method you would call on some variety of IO::Socket object.

2.3.71 local

The Perl 6 equivalent is temp. Unlike local, however, the value of the given variable is not immediately unset: it retains its original value until assigned to.

2.3.72 localtime

Most of the functionality of localtime is found in DateTime. The specific parts of localtime can be found as follows:

my $d = DateTime.now; 
 $sec  = $d.second; # Potentially includes fractional seconds 
 $min  = $d.minute; 
 $hour = $d.hour; 
 $mday = $d.day-of-month; # or $d.day; 1..31 
 $mon  = $d.month; # 1..12 
 $year = $d.year; 
 $wday = $d.day-of-week; # 1 => Monday, 2 => Tuesday, etc. 
 $yday = $d.day-of-year; # 1..366 
 

Please note that ranges are not 0-based in Perl 6, as shown in the comments in the example.

There does not currently appear to be a way to get Perl 5's $isdst. Also, the result of scalar(localtime) that Perl 5 provides is not available. $d.Str will give something along the lines of "2015-06-29T12:49:31-04:00".

2.3.73 lock

In Perl 6, a method in the Lock class.

2.3.74 log

Available in Perl 6. Also works as a method. I. e. log(2) is equivalent to 2.log.

2.3.75 lstat

Likely implemented somewhere in one of the IO classes in Perl 6, but it is not clear where at this time.

2.3.76 m//

Regular expression syntax is somewhat different in Perl 6, but the match operator still exists. If you're trying to rewrite some Perl 5 code, the most important difference is that =~ is replaced by the smart match operator, ~~. Similarly, !~ is replaced by !~~. Options for regex operators are adverbs and are complicated. For details, see Adverbs

2.3.77 map

As a function, the only difference between Perl 5 and Perl 6 is that, if you're using a block, the block must be followed by a comma. Can also be used as a method: @new = @old.map: { $_ * 2 }

2.3.78 mkdir

Works as in Perl 5.

The zero argument (implicit $_) version is not permitted in Perl 6.

2.3.79 msg*

Not builtins in Perl 6. May appear in an external module at some point. Maybe.

2.3.80 my

Works as in Perl 5.

2.3.81 next

The same in Perl 6.

2.3.82 no

In Perl 6, this is usable for pragmas such as strict, but not for modules. It's unclear whether it can be used for versions, but since that's currently something of a moot point, I would guess not.

2.3.83 oct

Replaced by the adverbial form :8. E. g. :8("100") returns 64.

If you want to deal with strings that start in 0x, 0o, or 0b, you can just use the prefix:<+> operator.

2.3.84 open

The most obvious change from Perl 5 is the file mode syntax. To open a file for reading only, you would say open("file", :r). For write- only, read-write, and append, you would use :w, :rw, and :a respectively. There are also options for encoding and how the filehandle deals with newlines. Details here.

2.3.85 opendir

No replacement. See &dir / IO::Path.dir for alternatives.

2.3.86 ord

Same as in Perl 5. May be used as a method: "howdy!".ord; # 104

2.3.87 our

The same in Perl 6.

2.3.88 pack

Available in Perl 6. The template options are currently more restricted than they are in Perl 5. The current documented list can be found at unpack.

2.3.89 package

S10 indicates that package can be used in Perl 6, but only with a block. I. e. package Foo { ... } means that the code within the block would be in package Foo. There is a special case where a declaration of the form package Foo; as the first statement in a file indicates that the rest of the file is Perl 5 code, but the usefulness of this is unclear. In fact, as modules and classes are declared with distinct keywords (such as class), it's unlikely you will use package directly in Perl 6.

2.3.90 __PACKAGE__

Replaced by $?PACKAGE.

2.3.91 pipe

Depending on your needs, see Channel to shuttle data between threads (and Concurrency tutorial for other options), or see Proc type for piping to and from processes.

2.3.92 pop

Works in Perl 6, and can also be used as a method. I. e. my $x = pop @a; and my $x = @a.pop; are equivalent.

2.3.93 pos

Not available in Perl 6. The closest equivalent is the :c adverb, which defaults to $/.to if $/ is true, and 0 if it isn't. For information on :c, see Continue.

2.3.94 print

print can be used as a function in Perl 6, writing to standard out. To use print as a function with a filehandle instead of standard out, you can use a method call: $fh.print("howdy!")

2.3.95 printf

Perl 6 version is similar; see sprintf for details on acceptable format directives. To print to a filehandle other than STDOUT, use the .printf method on that filehandle.

2.3.96 prototype

Not available in Perl 6. The closest equivalent is .signature. E. g. say &sprintf.signature results in "(Cool $format, *@args)".

2.3.97 push

Works as in Perl 5, as well as being available as a method: @a.push("foo");. Note: the flattening behaviour is different in Perl 6: @b.push: @a will push @a into @b as a single element. See also the append method.

2.3.98 quoting

These survive the transition to Perl 6. Some notes:

q/.../ # is still equivalent to using single quotes.
qq/.../ # is still equivalent to using double quotes.
qw/.../ # is more commonly rendered as C<< <...> >> in Perl 6.

There are some added quoting constructs and equivalents, as explained at quoting.

Has been replaced by rx/.../.

No direct equivalent, i.e. nothing that just returns the string with all the ASCII non-word characters backslashed. In regexes, however, using $foo will treat $foo as a literal string, and using <$foo> will interpret the contents of $foo as regex code. Note that the angle brackets are doing something different here than they do outside a regex. For more information on this, see https://design.perl6.org/S05.html#Extensible_metasyntax_(%3C...%3E)

2.3.99 rand

rand by itself works as it does in Perl 5, but you can no longer give it an argument. You can, however, use it as a method on a number to get that behavior. I. e. the Perl 5 rand(100) is equivalent to 100.rand in Perl 6. Additionally, you can get a random integer by using something like (^100).pick. For why you are able to do that, see ^ operator and pick.

2.3.100 read

read is found in IO::Handle and IO::Socket in Perl 6. It reads the specified number of bytes (rather than characters) from the relevant handle or socket. The use of an offset available in Perl 5 is not documented to exist at this time.

2.3.101 readdir

Not a builtin function. To iterate through the contents of a directory, take a look at dir routine.

2.3.102 readline

Not available in Perl 6. You most likely want to use the .lines method in some way. For more detailed information on reading from files, see io.

Appears to be gone from Perl 6.

2.3.104 readpipe

Doesn't appear to be working in Perl 6, but qx// is functional, so it might be lurking around in some class that isn't obvious.

2.3.105 recv

Appears to be in IO::Socket. Not extensively documented at this time.

2.3.106 redo

Unchanged in Perl 6.

2.3.107 ref

Gone. To quote S29, "If you really want the type name, you can use $var.WHAT.perl. If you really want P5 ref semantics, use Perl5::p5ref." Except that Perl5::p5ref does not seem to currently exist...

2.3.108 rename

Still available in Perl 6.

2.3.109 requires

No equivalent.

2.3.110 reset

No equivalent.

2.3.111 return

Appears to be available in Perl 6, although not clearly documented.

2.3.112 reverse

In Perl 6, this only reverses the elements of a list. reverse(@a) or @a.reverse. To reverse the characters in a string, use the .flip method.

2.3.113 rewinddir

[NEEDS FURTHER RESEARCH] There does not appear to be an obvious direct equivalent. It is possible that some incantation in IO::Path may serve, but it's not clear what it would be.

2.3.114 rindex

Works as in Perl 5, and may also be used as a method. E. g. $x = "babaganush";say $x.rindex("a");say $x.rindex("a", 3); # 5, 3

2.3.115 rmdir

Works in Perl 6 and can also be used as a method. rmdir "Foo"; and "Foo".IO.rmdir; are equivalent.

2.3.116 s///

Regular expression syntax is somewhat different in Perl 6, but the substitution operator exists. If you're trying to rewrite some Perl 5 code, the most important difference is that =~ is replaced by the smart match operator, ~~. Similarly, !~ is !~~. Options for regex operators are adverbs and are complicated. For details, see Adverbs page

2.3.117 say

say can be used as a function, defaulting to standard out. To use say as a function with a filehandle instead of standard out, you need to put a colon after the filehandle. I. e. say $fh: "Howdy!". The use of the colon as an "invocant marker" here is discussed at https://design.perl6.org/S03.html#line_4019. Alternately, you can use a method call: $fh.say("howdy!")

2.3.118 scalar

Gone. Apparently "very" gone.

2.3.119 seek

Not documented in a any real way yet, but listed under the IO::Handle class.

2.3.120 seekdir

Not currently documented, but looks to be something that would be implemented in one of the IO classes, likely IO::Path.

2.3.121 select

"[S]elect as a global concept is dead." When I asked around about select, I was told that $*OUT and such are overridable in dynamic scope, and that IO::Capture::Simple (at https://github.com/sergot/IO-Capture-Simple) may be of use for something you might be doing with the value of select.

2.3.122 semctl

No longer in core.

2.3.123 semget

No longer in core.

2.3.124 semop

No longer in core.

2.3.125 send

Can be found in the IO::Socket class.

2.3.126 setpgrp

No longer in core. Will probably wind up in a POSIX module.

2.3.127 setpriority

No longer in core. Will probably wind up in a POSIX module.

2.3.128 setsockopt

Not documented, but probably hiding in an IO class somewhere.

2.3.129 shift

Works as a method as well as a function. shift @a and @a.shift are equivalent.

2.3.130 shm*

Gone from the core. May turn up in a module somewhere.

2.3.131 shutdown

Not documented, but likely moved into IO::Socket.

2.3.132 sin

Works as a function and also as a method. sin(2) and 2.sin are equivalent.

2.3.133 sleep

Still works as in Perl 5. As of this writing, works as a method, but that is deprecated and will be removed soon.

2.3.134 sockets

Not currently documented, but will likely wind up in IO::Socket.

2.3.135 sort

sort exists in Perl 6, but is somewhat different. $a and $b are no longer special (See 5to6-perlvar) and sort routines no longer return positive integers, negative integers, or 0, but rather Order::Less, Order::Same, or Order::More objects. See sort for details. May also be used as a method I. e. sort(@a) is equivalent to @a.sort.

2.3.136 splice

Available in Perl 6. Can also be used as a method. splice(@foo, 2, 3, <M N O P>); is equivalent to @foo.splice(2, 3, <M N O P>); .

2.3.137 split

Works mostly as in Perl 5. There are some exceptions, though. To get the special behavior of using the empty string, you must actually use the empty string - the special case of the empty pattern // being treated as the empty string does not apply. If you use a regex for the split, it will use the regex, while a literal string will be treated literally. If you wish to have the delimiters included in the resulting list, you need to use the named parameter :all, like this: split(';', "a;b;c", :all) # a ; b ; c Empty chunks are not removed from the result list as they are in Perl 5. For that behavior, see comb. Details on split are here. Unsurprisingly, split also now works as a method: "a;b;c".split(';')

The zero argument version must now be called with an explicit empty string, as described above.

2.3.138 sprintf

Works as in Perl 5. The formats currently available are:

% a literal percent sign
c a character with the given codepoint
s a string
d a signed integer, in decimal
u an unsigned integer, in decimal
o an unsigned integer, in octal
x an unsigned integer, in hexadecimal
e a floating-point number, in scientific notation
f a floating-point number, in fixed decimal notation
g a floating-point number, in %e or %f notation
X like x, but using uppercase letters
E like e, but using an uppercase "E"
G like g, but with an uppercase "E" (if applicable)

Compatibility:

i a synonym for %d
D a synonym for %ld
U a synonym for %lu
O a synonym for %lo
F a synonym for %f

Perl 5 (non-)compatibility:

n produces a runtime exception
p produces a runtime exception

There are modifiers for integers, but they're mainly no-ops, as the semantics aren't settled:

h interpret integer as native "short" (typically int16)
l interpret integer as native "long" (typically int32 or int64)
ll interpret integer as native "long long" (typically int64)
L interpret integer as native "long long" (typically uint64)
q interpret integer as native "quads" (typically int64 or larger)

2.3.139 sqrt

Works as a function and a method. sqrt(4) and 4.sqrt are equivalent.

2.3.140 srand

Available in Perl 6.

2.3.141 stat

Likely implemented somewhere in IO, but it is not clear where at this time.

2.3.142 state

Available in Perl 6, see state.

2.3.143 study

study is no more.

2.3.144 sub

Unsurprisingly, we still have subroutines! You can have a signature in your subroutine which allows you to specify arguments. Nevertheless, in the absence of a signature (and only in the absence of a signature), @_ still contains what is passed to the function. So, in theory, you don't need to change that aspect of a function if porting from Perl 5 to Perl 6 (although you should probably consider the option of using a signature). For all the gory details, see functions.

2.3.145 __SUB__

Replaced by &?ROUTINE.

2.3.146 substr

Can be used as a function or a method. substr("hola!", 1, 3) and "hola!".substr(1, 3) both return "ola".

Part of IO::Path in Perl 6. The only difference between Perl 5 and Perl 6 is that the argument order has changed. It's now link($original, $linked_file).

2.3.148 syscall

Not a builtin in Perl 6. Most likely out in a module somewhere, but it's currently unclear where.

2.3.149 sys*

As with the non-sys versions of these functions, are probably lurking in the IO classes somewhere.

2.3.150 system

For this, you probably want (run) or (shell routine).

2.3.151 syswrite

As with sysopen and friends, this has moved into the IO classes.

2.3.152 tell

In IO::Handle, but not yet documented, beyond a mention.

2.3.153 telldir

Possibly in IO::Path, but not yet documented.

2.3.154 tie

[NEEDS FURTHER RESEARCH] S29 indicates that variable tying has been replaced by container types. Unfortunately, what this means in practical terms has not been obviously specified.

2.3.155 time

"Returns an Int representing the current time." Although how it represents the current time isn't in the documentation currently, it appears to still be seconds since epoch, as in Perl 5.

2.3.156 times

Not available in Perl 6.

2.3.157 tr///

Works similarly to how it does in Perl 5. The one caveat is that ranges are specified differently. Instead of using a range "a-z", you would use "a..z", i. e. with Perl's range operator. In Perl 6, tr/// has a method version, which is better documented, called .trans. .trans uses a list of pairs, as follows: $x.trans(['a'..'c'] => ['A'..'C'], ['d'..'q'] => ['D'..'Q'], ['r'..'z'] => ['R'..'Z']); A much more extensive description of the uses of .trans can be found at https://design.perl6.org/S05.html#Transliteration. The y/// equivalent has been done away with.

2.3.158 truncate

Most likely somewhere in IO::Handle, but not currently documented.

2.3.159 uc

Works as a function and a method. uc("ha") and "ha".uc both return "HA".

2.3.160 ucfirst

Perl 6 has done away with ucfirst. The title case function tc probably does what you need.

2.3.161 undef

There is no undef in Perl 6. You can't undefine a function, and the closest equivalent value is probably Nil, but you'll likely have no use for that. If you were using something like (undef, $file, $line) = caller;, you would just get the filename and line number directly in Perl 6 instead of discarding the first result of caller. caller has been replaced by callframe in Perl 6, so the equivalent statement would be ($file, $line) = callframe.annotations<file line>;

Still available. Usable as a method: "filename".IO.unlink

The zero argument (implicit $_) version of unlink is not available in Perl 6.

2.3.163 unpack

Available in Perl 6. The template options are currently more restricted than they are in Perl 5. The current documented list can be found here.

2.3.164 unshift

Available in Perl 6. Can be used as a method. unshift(@a, "blah") is equivalent to @a.unshift("blah").

2.3.165 untie

[NEEDS FURTHER RESEARCH] Functions for tying variables seem to be replaced in Perl 6 by container types, as mentioned in S29. This has become no clearer since I wrote the entry for tie, above.

2.3.166 use

In Perl 5, this requires a minimum version of the perl executable in order to run. In Perl 6, this requires a version of the specification, (e.g. 6.c), which can be implemented by various perl6 executables.

2.3.167 utime

No equivalent.

2.3.168 values

Available in Perl 6. Can also be used as a method. values %hash is equivalent to %hash.values.

2.3.169 vec

S29 says "Should replace vec with declared buffer/array of bit, uint2, uint4, etc." It is unclear, however, that this has actually happened.

2.3.170 wait

[NEEDS FURTHER RESEARCH] Unclear where this has gone. There's a wait method in Supply, and an await method in both Channel and Promise. Which, if any or all, of these is a direct equivalent of Perl 5's wait is unclear.

2.3.171 waitpid

As with wait, the disposition of this is unclear.

2.3.172 wantarray

There is no wantarray in Perl 6, because reasons.

There are very easy ways to cover many of the use cases which wantarray filled.

First, since Perl 6 does not need special reference syntax to contain a List or Array in a Scalar, simply returning a list may be all that is needed:

sub listofstuff {
    return 1, 2, 3;
}
my $a = listofstuff();
print $a;                      # prints "123"
print join("<", listofstuff()) # prints "1<2<3"

One of the most common use cases is to provide either an array of lines or elements, or a prettier string than would be produced by simply printing the array. One can mix in a custom .Str method for this purpose:

sub prettylist(*@origlist) {
    @origlist but role {
        method Str { self.join("<") }
    }
}
print prettylist(1, 2, 3);  # prints "1<2<3"
print join(">", prettylist(3, 2, 1)); # prints "3>2>1"

In the above example, the returned list may be lazy, and the .Str method is not called until stringification happens, so no extra work is done to generate something which is not asked for.

Another use case is to create methods which are mutators when called in void context but produce copies during assignment. It is generally considered better form in Perl 6 not to do so, since users can quite easily turn any copy-producing method into a mutator using the .= operator:

my $a = "foo\n";
$a.ords.say; # says "(102 111 111 10)"
$a .= chomp;
$a.ords.say; # says "(102 111 111)"

However if you have your heart set on using the same function name for both operations, you can get most of the way there by mixing in a .sink method, which will be called when the result finds itself in void context. There are some caveats however, so again, this is not advised:

multi sub increment($b is rw) {
    ($b + 1) does role { method sink { $b++ } }
}
multi sub increment($b) {
    $b + 1
}
my $a = 1;
increment($a);
say $a;                 # says "2"
my $b = increment($a);
say $a, $b;             # says "2 3"
# ...users will just have to be aware that they should not accidentally
# sink a stored value later, though this requires some effort to
# actually do:
sub identity($c is rw) { $c };
$a = 1;
$b = increment($a);
identity($b);
$a.say;                  # says "2"

2.3.173 warn

warn throws an exception. To simply print a message to $*ERR, you would use the note function. For more on exceptions, see Exceptions.

2.3.174 write

Formats are gone from Perl 6, so this no longer works.

2.3.175 y///

This synonym for tr/// is gone. For functionality, see the entry for tr///.

3 5to6-perlop

Perl 5 to Perl 6 guide - operators

3.1 DESCRIPTION

A (hopefully) comprehensive list of Perl 5 operators with their Perl 6 equivalents with notes on variations between them where necessary.

3.2 NOTE

This document does not explain the operators in detail. This document is an attempt to guide you from the operators in Perl 5's perlop document to their equivalents in Perl 6. For full documentation on the Perl 6 equivalents, please see the Perl 6 documentation.

3.2.1 Operator Precedence and Associativity

The operator precedence table is somewhat different in Perl 6 than it is in Perl 5, so it will not be detail here. If you need to know the precedence and associativity of a given operator in Perl 6, refer to Operator Precedence.

3.2.2 Terms and List Operators

The things listed in Perl 5's perlop document as unary and list operators in this section tend to be things that can also be thought of as functions, such as print and chdir. As such, you can find information about them in 5to6-perlfunc.pod6. Parentheses are still used for grouping.

3.2.3 The Arrow Operator

As you typically will not be using references in Perl 6, the arrow is probably less useful as a dereferencing operator. If you do need to dereference something, however, the arrow is the dot. It is also the dot for method calls. So, Perl 5's $arrayref->[7] becomes $arrayref.[7] in Perl 6 and, similarly, $user->name becomes $user.name. The => arrow is used for constructing Pairs, see Pair term documentation.

3.2.4 Auto-increment and Auto-decrement

Work as in Perl 5. The one possible caveat is that they function by calling the succ method for ++ and the pred method for --. For builtin numeric types, this is unlikely to do something unusual, but custom types can define their own succ and pred methods, so in those cases, you should probably take note of what ++ and -- will actually do.

3.2.5 Exponentiation

Works as you would expect. The caveat in Perl 5's perlop about ** binding more tightly than unary minus (i. e. "-2**4" evaluates as "-(2**4)" rather than "(-2)**4)") is also true for Perl 6.

3.2.6 Symbolic Unary Operators

As in Perl 5, unary ! and - do logical and arithmetic negation, respectively. ?^ is used for bitwise logical negation, which the documentation indicates is equivalent to !. It may be relevant to note that these coerce their arguments to Bool and Numeric, respectively.

Unary ~ is the string context operator in Perl 6, so use prefix +^ for bitwise integer negation. Assumes two's complement.

+ does have an effect in Perl 6, coercing its argument to the Numeric type.

Unary <\> is no more. If you really want to take a reference to an existing named variable, you can use item context, like so: $aref = item(@array) You can get a reference to a named subroutine by using the & sigil: $sref = &foo Anonymous arrays, hashes, and subs return their references during creation right away.

3.2.7 Binding Operators

=~ and !~ have been replaced by ~~ and !~~, respectively. Those of you who consider smart matching broken in Perl 5 will be happy to hear that it works much better in Perl 6, as the stronger typing means less guesswork.

3.2.8 Multiplicative Operators

Binary *, /, and % do multiplication, division, and modulo, respectively, as in Perl 5.

Binary x is slightly different in Perl 6, and has a companion. print '-' x 80; gives you a string of 80 dashes, but for the Perl 5 behavior of @ones = (1) x 80; giving you a list of 80 "1"s, you would use @ones = 1 xx 80;.

3.2.9 Additive Operators

Binary + and - do addition and subtraction, respectively, as you would expect..

As . is the method call operator, so binary ~ acts as the concatenation operator in Perl 6.

3.2.10 Shift Operators

<< and >> have been replaced by +< and +> .

3.2.11 Named Unary Operators

As noted above, you'll find these in 5to6-perlfunc.pod6.

3.2.12 Relational Operators

These all work as in Perl 5.

3.2.13 Equality Operators

== and != both work as in Perl 5.

<=> and cmp have different behavior in Perl 6. <=> does a numeric comparison, but returns <Order::Less>, <Order::Same>, or <Order::More> instead of Perl 5's -1, 0, or 1. To get the Perl 5 behavior (with the change that it returns the Order objects, rather than integers) of cmp, you would use the leg operator.

cmp does either <=> or leg, depending on the existing type of its arguments.

~~ is the smart match operator as in Perl 5, but it's also just the match operator in Perl 6, as noted above. For how smart matching works in Perl 6, see https://design.perl6.org/S03.html#Smart_matching.

3.2.14 Smartmatch Operator

See the entry on ~~ directly above.

3.2.15 Bitwise And

Binary & is +& in Perl 6.

3.2.16 Bitwise Or and Exclusive Or

Bitwise OR has changed from | in Perl 5 to +| in Perl 6. Similarly, bitwise XOR ^ is +^

3.2.17 C-style Logical And

Unchanged.

3.2.18 C-style Logical Or

Unchanged.

3.2.19 Logical Defined-Or

Remains in Perl 6 as //. Returns the first defined operand, or else the last operand. Also, there is a low precedence version, called orelse.

3.2.20 Range Operators

In list context, .. operates as the range operator and should not need to be changed. That said, there are exclusionary range operators that may be useful. These are:

infix  ..^  Excludes endpoint. C<1..^5>; # 1 2 3 4 >
infix  ^..  Excludes starting point. C<1^..5>; # 2 3 4 5>
infix  ^..^ Excludes both starting and endpoint. C<1^..^5>; # 2 3 4>
prefix ^    From 0, excludes endpoint. C<^5>; # 0 1 2 3 4>

In scalar context, .. and ... work as flip-flop operators in Perl 5, but are little-known, and probably even less used. Those operations have been taken over by ff and fff in Perl 6, but are not clearly documented at this time.

3.2.21 Conditional Operator

?: has been replaced by ?? !!. I. e. where you would use $x = $ok ? $y : $z; in Perl 5, you would use $x = $ok ?? $y !! $z; in Perl 6.

3.2.22 Assignment Operators

Although not fully documented, S03 indicates that the mathematical and logical assignment operators should work as you would expect. The one noticeable change is that .= calls a mutating method on the object on the left, while ~= is the string concatenation assignment, as you might expect with the changes in . and ~. Also, the bitwise assignment operators are likely not separated into numeric and string versions (&=, etc., vs. &.=, etc.), as that feature is currently experimental in Perl 5 itself - although, again, this is not specifically documented.

3.2.23 Comma Operator

The comma operator works mostly as expected, but technically it creates Lists) or separates arguments in function calls. Also, there is a : variant that turns function calls into method calls - see this page.

The => operator works similarly to the Perl 5 "fat comma" behavior in that it allows an unquoted identifier on its left side, but in Perl 6 constructs Pair objects, rather than just functioning as a separator. If you are trying to just literally translate a line of Perl 5 code to Perl 6, it should behave as expected.

3.2.24 List Operators (Rightward)

Like the Named Unary Operators, you'll find these discussed in 5to6-perlfunc.pod.

3.2.25 Logical Not

The lower precedence version of !. As with !, coerces its argument to Bool.

3.2.26 Logical And

Lower precedence version of && as in Perl 5.

3.2.27 Logical or and Exclusive Or

or is the low precedence version of ||. The documentation lists an xor, but does not actually document it.

Additionally, there is a low precedence version of //, called orelse.

3.2.28 Quote and Quote-like Operators

For all the gory details on quoting constructs, see quoting.

There is a quoting operator that allows absolute literal strings: Q or 「…」, although the latter might be difficult to find on your keyboard, depending on your keyboard... Backslash escapes do not apply in Q quoted strings. E. g. Q{This is still a closing curly brace → \} renders "This is still a closing curly brace → \".

q does what you expect, allowing backslash escapes. E. g. q{This is not a closing curly brace → \}, but this is → } returning "This is not a closing curly brace → }, but this is →". As in Perl 5, you can get this behavior with single quotes.

qq allows interpolation of variables. However, by default, only scalar variables are interpolated. To get other variables to interpolate, you need to put square brackets after them. E. g. @a = <1 2 3>;say qq/@a[] example@example.com/; results in "1 2 3 example@example.com". Hashes interpolate in a possibly unexpected manner: %a = 1 => 2, 3 => 4;say "%a[]"; results in a space separating the pairs and tabs separating the key from the value in each pair (apparently). You can also interpolate Perl 6 code in strings using curly braces. For all the details, see Interpolation.

qw works as in Perl 5, and can also be rendered as <...> . E. g. qw/a b c/ is equivalent to <a b c> .

There is also a version of qw that interpolates, which is qqw. So my $a = 42;say qqw/$a b c/; gives you "42 b c".

Shell quoting is available through qx, but you should note that backticks do not do shell quoting as in Perl 5, and Perl variables are not interpolated in qx strings. If you need to interpolate Perl variables in a shell command string, you can use qqx instead.

The qr operator is gone from Perl 6.

tr/// works similarly to how it does in Perl 5. The one caveat is that ranges are specified differently. Instead of using a range "a-z", you would use "a..z", i. e. with Perl's range operator. tr/// has a method version, which is better documented, called .trans. .trans uses a list of pairs, as follows: $x.trans(['a'..'c'] => ['A'..'C'], ['d'..'q'] => ['D'..'Q'], ['r'..'z'] => ['R'..'Z']); A much more extensive description of the uses of .trans can be found at https://design.perl6.org/S05.html#Transliteration. The y/// equivalent has been done away with.

Heredocs are specified differently in Perl 6. You use :to with your quoting operator, e. g. q:to/END/; would start a heredoc ending with "END". Similarly, you get escaping and interpolation based on your quoting operator, i. e. literals with Q, backslash escapes with q, and interpolation with qq.

3.2.29 I/O Operators

The full details on Input/Output in Perl 6 can be found at io.

As <...> is the quote-words construct in Perl 6, <> is not used for reading lines from a file. You can do that by either making an IO object from a file name or using an open filehandle and then, in either case, calling .lines on it. I. e. either my @a = "filename".IO.lines; or my $fh = open "filename", :r;my @a = $fh.lines; (In the latter case, we are using :r to specifically open the file for reading). To do this in an iterative manner, you can use a for loop this way:

for 'huge-csv'.IO.lines -> $line { 
     # Do something with $line 
 } 
 

Note the use of -> there. That's part of the Block syntax, and in Perl 6 is needed for if, for, while, etc.

If you want to slurp the entire file into a scalar, you would - surprise! - use the .slurp method. For instance

my $x = "filename".IO.slurp; 
 # ... or ... 
 my $fh = open "filename", :r; 
 my $x = $fh.slurp; 

As noted in 5to6-perlvar.pod, the ARGV magic input filehandle has been replaced by $*ARGFILES, and the @ARGV array of command line arguments has been replaced by @*ARGS.

3.2.30 No-ops

Although it's not specifically documented, 1 while foo(); appears to work in this sense.

3.2.31 Bitwise String Operators

Documented individually above, but to summarize...

Bitwise integer negation is prefix +^. Bitwise boolean negation is ?^.

Bitwise and is +&.

Bitwise integer or is +|. Bitwise integer xor is infix +^. Bitwise boolean or is ?|.

Left shift and right shift are +< and +> .

4 5to6-perlsyn

Perl 5 to Perl 6 guide - syntax

perlsyn - Perl syntax

4.1 DESCRIPTION

A (hopefully) comprehensive description of the differences between Perl 5 and Perl 6 with regards to the syntax elements described in the perlsyn document.

4.2 NOTE

I will not be explaining Perl 6 syntax in detail. This document is an attempt to guide you from how things work in Perl 5 to the equivalents in Perl 6. For full documentation on the Perl 6 syntax, please see the Perl 6 documentation.

4.3 Free Form

Perl 6 is still largely free form. However, there are a few instances where the presence or lack of whitespace is now significant. For instance, in Perl 5, you can omit a space following a keyword (e. g. while($x < 5) or my($x, $y)). In Perl 6, that space is required, thus while ($x < 5) or my ($x, $y). In Perl 6, however, you can omit the parentheses altogether: while $x < 5 . This holds for if, for, etc.

Oddly, in Perl 5, you can leave spaces between an array or hash and its subscript, and before a postfix operator. So $seen {$_} ++ is valid. No more. That would now have to be %seen{$_}++.

If it makes you feel better, you can use backslashes to "unspace" whitespace, so you can use whitespace where it would otherwise be forbidden.

See Whitespace for details.

4.3.1 Declarations

As noted in 5to6-perlfunc.pod, there is no undef in Perl 6. A declared, but uninitialized scalar variable will evaluate to its type. In other words, my $x;say $x; will give you "(Any)". my Int $y;say $y; will give you "(Int)".

4.3.2 Comments

# starts a comment that runs to the end of the line as in Perl 5.

Embedded comments start with a hash character and a backtick (#`), followed by an opening bracketing character, and continue to the matching closing bracketing character. Like so:

if #`( why would I ever write an inline comment here? ) True { 
     say "something stupid"; 
 } 
 

As in Perl 5, you can use pod directives to create multiline comments, with =begin comment before and =end comment after the comment.

4.3.3 Truth and Falsehood

The one difference between Perl 5 truth and Perl 6 truth is that, unlike Perl 5, Perl 6 treats the string "0" as true. Numeric 0 is still false, and you can use prefix + to coerce string "0" to numeric to get it to be false. Perl 6, additionally has an actual Boolean type, so, in many cases, True and False may be available to you without having to worry about what values count as true and false.

4.3.4 Statement Modifiers

Mostly, statement modifiers still work, with a few exceptions.

First, for loops are exclusively what were known in Perl 5 as foreach loops and for is not used for C-style for loops in Perl 6. To get that behavior, you want loop. loop cannot be used as a statement modifier.

In Perl 6, you cannot use the form do {...} while $x. You will want to replace do in that form with repeat. Similarly for do {...} until $x.

4.3.5 Compound Statements

The big change from Perl 5 is that given is not experimental or disabled by default in Perl 6. For the details on given see this page.

4.3.6 Loop Control

next, last, and redo have not changed from Perl 5 to Perl 6.

continue, however, does not exist in Perl 6. You would use a NEXT block in the body of the loop.

# Perl 5 
 my $str = ''; 
 for (1..5) { 
     next if $_ % 2 == 1; 
     $str .= $_; 
 } 
 continue { 
     $str .= ':' 
 } 
 
 # Perl 6 
 my $str = ''; 
 for 1..5 { 
     next if $_ % 2 == 1; 
     $str ~= $_; 
     NEXT { 
         $str ~= ':' 
     } 
 } 
 

4.3.7 For Loops

As noted above, C-style for loops are not called for loops in Perl 6. They are just loop loops. To write an infinite loop, you do not need to use the C idiom of loop (;;) {...}, but may just omit the spec completely: loop {...}

4.3.8 Foreach Loops

In Perl 5, for, in addition to being used for C-style for loops, is a synonym for foreach. In Perl 6, for is just used for foreach style loops.

4.3.9 Switch Statements

Perl 6 has actual switch statements, provided by given with the individual cases handled by when and default. The basic syntax is:

given EXPR { 
     when EXPR { ... } 
     when EXPR { ... } 
     default { ... } 
 } 
 

The full details can be found here.

4.3.10 Goto

goto probably works similarly in Perl 6 to the way it does in Perl 5. However, as of this writing, it does not seem to be functional. For what is planned for goto, see https://design.perl6.org/S04.html#The_goto_statement.

4.3.11 The Ellipsis Statement

... (along with !!! and ???) are used to create stub declarations. This is a bit more complicated than the use of ... in Perl 5, so you'll probably want to look at https://design.perl6.org/S06.html#Stub_declarations for the gory details. That said, there doesn't seem to be an obvious reason why it shouldn't still fulfill the role it did in Perl 5, despite its role being expanded in Perl 6.

4.3.12 PODs: Embedded Documentation

Pod has changed between Perl 5 and Perl 6. Probably the biggest difference is that you need to enclose your pod between =begin pod and =end pod directives. There are a few tweaks here and there as well. For instance, as I have discovered while writing these documents, the vertical bar ("|") is significant in X<> codes, and it's not clear how to get a literal "|" into them. Your best bet may be to use the Perl 6 interpreter to check your pod. You can do this by using the --doc switch. E. g. perl6 --doc Whatever.pod. This will output any problems to standard error. (Depending on how/where you've installed perl6, you may need to specify the location of Pod::To::Text.) Details on Perl 6 style pod is at https://design.perl6.org/S26.html.

5 5to6-perlvar

Perl 5 to Perl 6 guide - special variables

5.1 DESCRIPTION

A (hopefully) comprehensive list of Perl 5 Special Variables with their Perl 6 equivalents with notes on variations between them where necessary.

5.2 NOTE

I will not be explaining the full use of the Perl 6 variables. This document is an attempt to guide you from the Special Variables in Perl 5 to their equivalents in Perl 6. For full documentation on the Perl 6 special variables, please see the Perl 6 documentation for those variables.

5.3 SPECIAL VARIABLES

5.3.1 General Variables

Thankfully, $_ is the general default variable as in Perl 5. The main difference in Perl 6 is that you can now call methods on it. For instance, Perl 5's say $_ can be rendered in Perl 6 as $_.say. Furthermore, as it is the default variable, you don't even need to use the variable name. The previous example can also be achieved by using .say.

As Perl 6 now has function signatures, your arguments can go there, rather than depending on @_ for them. In fact, if you use a function signature, use of @_ will spit at you telling it cannot override an existing signature.

If, however, you do not use a function signature, @_ will contain the arguments you pass to the function as it did in Perl 5. Again, as with $_, you can call methods on it. Unlike $_ you cannot assume @_ as the default variable for those methods to operate on. I. e. @_.shift works, .shift does not.

Currently, there is no equivalent of the List Separator variable in Perl 6. Design document S28 says there isn't one, so you probably don't want to hold your breath.

$$ is replaced in Perl 6 by $*PID

You can access the program name in Perl 6 via $*PROGRAM-NAME.

Note: $0 in Perl 6 is the variable holding the first captured value from a match (i. e. capture variables now start from $0 rather than $1).

The real group id is provided by $*GROUP.Numeric in Perl 6. $*GROUP.Str returns the group name, rather than its number.

The effective group id does not appear to be currently provided by Perl 6.

The real user id is provided by $*USER.Numeric in Perl 6. $*USER.Str returns the user name, rather than its number.

The effective user id does not appear to be currently provided by Perl 6.

The subscript separator variable is not included in Perl 6. Frankly, if your Perl 5 code is using this, it's almost certainly really, really old.

$a and $b have no special meaning in Perl 6. sort() does not use them for anything special. They're just regular old variables.

This feature has been extended by having blocks with placeholder parameters which are more versatile. Placeholder variables are created with the ^ twigil (e. g. $^z. They can be used in a bare block or in a subroutine without an explicit parameter list. The arguments to the block are assigned to the placeholder variables in their Unicode order. I. e. even if the variables appear in the block in the order ($^q, $^z, $^a), they will be assigned in the order ($^a, $^q, $^z). Ergo:

    sort { $^a cmp $^z }, 1, 5, 6, 4, 2, 3; 
     # (1 2 3 4 5 6) 
     sort { $^g cmp $^a }, 1, 5, 6, 4, 2, 3; 
     # (6 5 4 3 2 1) 
     for 1..9 { say $^c, $^a, $^b; last } 
     # 312 
 

For more on placeholder variables, see this page

%ENV has been replaced by %*ENV in Perl 6. Note that the keys of this hash may not be exactly the same between Perl 5 and Perl 6. For example, OLDPWD is missing from Perl 6's %ENV.

The version of perl is returned by $*PERL.version. For the beta this was "v6.b" with $*PERL containing "Perl 6 (6.b)".

Although the design documents (S28) indicate that this will likely become $*SYS_FD_MAX, this has not yet been implemented.

[NEEDS FURTHER RESEARCH] A bit confusing at this point. Design doc S28 indicates that @F in Perl 5 is replaced by @_ in Perl 6, but it's unclear just how that works. On the other hand, it's currently something of a moot point, as the Perl 5 to Perl 6 Translation doc indicates that the -a and -F command-line switches are not yet implemented in rakudo.

No longer exists in Perl 6. Please use "use lib" to manipulate the module repositories to be searched. The closest thing to @INC is really $*REPO. But that works completely differently from @INC mostly because of the precompilation capabilities of Perl 6.

# Print out a list of compunit repositories
.say for $*REPO.repo-chain;

No longer exists in Perl 6. Because each Repository is responsible for remembering which modules have been loaded already. You can get a list of all loaded modules (compilation units) like so:

use Test;
use MyModule;
say flat $*REPO.repo-chain.map(*.loaded); #-> (MyModule Test)

S28 suggests $*INPLACE_EDIT, but it does not yet exist.

S28 suggests $*EMERGENCY_MEMORY, but it does not yet exist.

This is somewhat unclear. It probably depends on what you mean by "the name of the operating system" as S28 has three different suggestions, all of which give different answers. On my OS X machine at this time...

say $*KERNEL; # gives "darwin (14.3.0)"
say $*DISTRO; # gives "macosx (10.10.3)"

Using .version on either of those will give you just the version number. .name gives the kernel or distro name. Those objects contain other information as well.

S28 also lists $*VM (which with my build of rakudo star currently gives "moar (2015.5.63.ge.7.a.473.c)"), but I'm unclear how the VM relates at all to the operating system.

[NEEDS FURTHER RESEARCH] No equivalent variable. S28 indicates that this functionality is dealt with in Perl 6 by event filters and exception translation.

Replaced in Perl 6 by $*INITTIME. Unlike in Perl 5, this is not in seconds since epoch, but an Instant object, which is measured in atomic seconds, with fractions.

As with $] this has been replaced with $*PERL.version.

There is no analog to this in Perl 6.

This has been replaced by $*EXECUTABLE-NAME. Note that this is an IO object in Perl 6, so use ~$*EXECUTABLE-NAME to get a Str to be closer to Perl 5.

5.3.2.1 Performance issues

As shown below, $`, $&, and $' are gone from Perl 6, primarily replaced by variations on $/ and, with their elimination, the associated performance issues in Perl 5 do not apply.

These existing variables do the same thing in Perl 6 as they do in Perl 5, except that they now start at $0 rather than $1. Furthermore, they are synonyms for indexed items in the match variable $/. I. e. $0 is equivalent to $/[0], $1 is equivalent to $/[1], etc.

$/ now contains the match object, so the Perl 5 behavior of $& can be obtained by stringifying it, i. e. ~$/. $/.Str also should work, but ~$/ is the currently more common idiom.

Since the former performance issues are done away with, this variable is not of use in Perl 6.

Replaced by $/.prematch.

Since the former performance issues are done away with, this variable is not of use in Perl 6.

Replaced by $/.postmatch.

Since the former performance issues are done away with, this variable is not of use in Perl 6.

Does not exist in Perl 6, but you can get the same information using $/[*- 1].Str ($/[*-1] would be the match object, not the actual string).

If you want to understand why that works, you can look at these documents:

...and possibly

...though the design documents are not always up to date.

S28 suggests $*MOST_RECENT_CAPTURED_MATCH, but there does not seem to be any implemented variable that matches $^N.

As with most regular expression related variables, this functionality is, at least in part, moved to the $/ variable in Perl 6. Or, in this case, the numbered variables that alias to the indexes of it. The offset is found by using the .to method. I. e. the first offset is $/[0].to, which is synonymous with $0.to. The value Perl 5 provides as $+[0] is provided by $/.to.

Once again, we move over to $/. The former $+{$match} is $/{$match}.

Similarly to @+ being replaced by using the .to method, @- is replaced by using the .from method on $/ and its variations. The first offset is $/[0].from or the equivalent $0.from. Perl 5's $- [0] is $/.from.

Much like %+, a use of %-{$match} would be replaced with $/{$match}.

No equivalent.

No equivalent.

No equivalent.

The name of the current file when reading lines can be obtained through $*ARGFILES.filename.

@*ARGS contains the command line arguments.

This has been replaced by $*ARGFILES.

As the -i command line switch has not yet been implemented, there is not yet an equivalent of ARGVOUT.

Currently no obvious equivalent.

The current line number is returned by the .ins method on the appropriate filehandle. E. g. $*IN.ins.

This is accessed through the .nl-in method on the filehandle. E. g. $*IN.nl-in.

This is accessed through the .nl-out method on the filehandle. E. g. $*OUT.nl-out.

Currently autoflush is not implemented in Perl 6.

Not implemented in Perl 6.

There are no built-in formats in Perl 6.

5.3.4 Error Variables

Because of how error variables have changed in Perl 6, I will not detail the changes individually.

To quote the Perl 6 docs, "$! is the error variable." That's it. All the error variables appear to have been eaten by $!. As with the rest of Perl 6, it's likely an object that will return various things depending on how you use it. Sadly, at the moment, the documentation for it is terribly sparse. It will probably do what you intend, but I'm not guaranteeing anything. Hopefully there will be more information in the near future.

Currently no equivalents for either of these variables.

Although deprecated in Perl 5, this may have some sort of equivalent in $?ENC, but this is far from clear.

No Perl 6 equivalent.

There may or may not be equivalents of these in Perl 6, but they're internal and you shouldn't be messing with them in the first place - certainly not if your understanding of Perl 6 requires you to read this document...

The chance of the Perl 6 debugger resembling the Perl 5 debugger is slim at best, and at this point there does not seem to be an equivalent of this variable.

S28 claims this variable is "pending". Not currently in Perl 6.

These Unicode-related variables do not appear to exist in Perl 6, but - maybe? - could have analogs in $?ENC somewhere. This, however, is totally unconfirmed.

5.3.6 Deprecated and removed variables

It should go without saying that, as these have been removed from Perl 5 already, there should be no need to tell you how to use them in Perl 6.

6 About the Docs

Meta-documentation

This document collection represents the on-going effort to document the Perl 6 programming language with the goals of being: comprehensive; easy to use; easy to navigate; and useful to both newcomers and experienced Perl 6 programmers.

An HTML version of the documentation is located online at https://docs.perl6.org.

The official source for this documentation is located at perl6/doc on GitHub.

This particular document is a quick overview of the process described in more detail in CONTRIBUTING on GitHub. This document also provides a short introduction to writing Perl 6 Pod files, which can be rendered into HTML and other formats.

6.1 Structure

All of the documentation is written in Perl 6 Pod and kept in the doc/ directory, and the doc/Language/ and doc/Type/ sub-directories. These files are processed as collections of definitions or "documentables", which are then post-processed and linked together.

6.2 Generating HTML from Pod

To generate HTML from the Pod files, you'll need:

To generate the documentation into the html/ folder, run:

perl6 htmlify.p6 

To host the documentation from a web server, have Perl 5 and Mojolicious::Lite installed, then run:

perl app.pl daemon 

6.3 Contributing

The documentation is written in Perl 6 Pod.

For a quick introduction to Perl 6 Pod, see Perl 6 Pod.

For full details about the Perl 6 Pod specification, see Synopsis 26, Documentation.

6.3.1 Adding definitions

Documentables can be defined using an =headN Pod directive, where N is greater than zero (e.g., =head1, =head2, …).

All of the paragraphs and blocks following that directive, up until the next directive of the same level, will be considered part of the documentable. So, in:

=head2  My Definition  
 
 Some paragraphs, followed by some code: 
 
     my Code $examples = "amazing"; 
 
 Mind === blown. 
 
 =head3 Minor details about  My Definition  
 
 It's fantastic. 
 
 =head2 And now, for something completely different 
 
 … 
 

The documentable My Definition extends down to the =head2 And now….

Documentables may contain other documentables. Class documentables, for example, often contain the methods the class implements.

Definitions must be in one of the following forms to be recognized as the start of a documentable named, say, Z. First the code in the document source:

=item X<C<How to use the Z infix> | infix,Z> (This a special case, which 
 is always considered a definition) 
 
 =item C<The Z Infix> 
 
 =item B<The C<Z> Infix> 
 
 =item C<Infix Z> 
 
 =item B<Infix C<Z>> 
 
 =item C<trait is cached> (A special case for the L<trait|/language/functions#Traits> documentables) 
 

Then the results on the rendered page:

These items should now be searchable by using the search field in the HTML docs.

You can add emphasis with bold ( B<> ) or italicized ( I<> ), with or without code formatting ( C<> ). Due to current parser limitations, special steps have to be taken to use X<> with other formatting codes; for example:

=item X<B<foo>|foo> a fancy subroutine 

renders like this

Notice that text after a pipe ('|') has no formatting. Also note that C<> preserves spaces and treats text as verbatim.

7 Classes and Objects

A tutorial for creating and using classes in Perl 6

More descriptive title?

Perl 6 has a rich built-in syntax for defining and using classes.

A default constructor allows the setting of attributes for the created object:

class Point { 
     has Int $.x; 
     has Int $.y; 
 } 
 
 class Rectangle { 
     has Point $.lower; 
     has Point $.upper; 
 
     method area() returns Int { 
         ($!upper.x - $!lower.x) * ( $!upper.y - $!lower.y); 
     } 
 } 
 
 # Create a new Rectangle from two Points 
 my $r = Rectangle.new(lower => Point.new(x => 0, y => 0), upper => Point.new(x => 10, y => 10)); 
 
 say $r.area(); # OUTPUT: «100␤» 

You can also provide your own construction and build implementation. The following, more elaborate example shows how a dependency handler might look in Perl 6. It showcases custom constructors, private and public attributes, methods and various aspects of signatures. It's not very much code, and yet the result is interesting and useful.

class Task { 
     has      &!callback; 
     has Task @!dependencies; 
     has Bool $.done; 
 
     # Normally doesn't need to be written 
     # BUILD is the equivalent of a constructor in other languages 
     method new(&callback, *@dependencies) { 
         return self.bless(:&callback, :@dependencies); 
     } 
 
     submethod BUILD(:&!callback, :@!dependencies) { } 
 
     method add-dependency(Task $dependency) { 
         push @!dependencies, $dependency; 
     } 
 
     method perform() { 
         unless $!done { 
             .perform() for @!dependencies; 
             &!callback(); 
             $!done = True; 
         } 
     } 
 } 
 
 my $eat = 
     Task.new({ say 'eating dinner. NOM!' }, 
         Task.new({ say 'making dinner' }, 
             Task.new({ say 'buying food' }, 
                 Task.new({ say 'making some money' }), 
                 Task.new({ say 'going to the store' }) 
             ), 
             Task.new({ say 'cleaning kitchen' }) 
         ) 
     ); 
 
 $eat.perform(); 

7.1 Starting with class

Perl 6, like many other languages, uses the class keyword to define a class. The block that follows may contain arbitrary code, just as with any other block, but classes commonly contain state and behavior declarations. The example code includes attributes (state), introduced through the has keyword, and behaviors, introduced through the method keyword.

Declaring a class creates a new type object which, by default, is installed into the current package (just like a variable declared with our scope). This type object is an "empty instance" of the class. For example, types such as Int and Str refer to the type object of one of the Perl 6 built-in classes. The example above uses the class name Task so that other code can refer to it later, such as to create class instances by calling the new method.

You can use .DEFINITE method to find out if what you have is an instance or a type object:

say Int.DEFINITE; # OUTPUT: «False␤» (type object)
say 426.DEFINITE; # OUTPUT: «True␤»  (instance)

class Foo {};
say Foo.DEFINITE;     # OUTPUT: «False␤» (type object)
say Foo.new.DEFINITE; # OUTPUT: «True␤»  (instance)

You can also use type smileys to only accept instances or type objects:

multi foo (Int:U) { "It's a type object!" }
multi foo (Int:D) { "It's an instance!"   }
say foo Int; # OUTPUT: «It's a type object!␤»
say foo 42;  # OUTPUT: «It's an instance!␤»

7.2 State

The first three lines inside the class block all declare attributes (called fields or instance storage in other languages). Just as a my variable cannot be accessed from outside its declared scope, attributes are not accessible outside of the class. This encapsulation is one of the key principles of object oriented design.

The first declaration specifies instance storage for a callback – a bit of code to invoke in order to perform the task that an object represents:

has &!callback; 

The & sigil indicates that this attribute represents something invocable. The ! character is a twigil, or secondary sigil. A twigil forms part of the name of the variable. In this case, the ! twigil emphasizes that this attribute is private to the class.

The second declaration also uses the private twigil:

has Task @!dependencies; 

However, this attribute represents an array of items, so it requires the @ sigil. These items each specify a task that must be completed before the present one can complete. Furthermore, the type declaration on this attribute indicates that the array may only hold instances of the Task class (or some subclass of it).

The third attribute represents the state of completion of a task:

has Bool $.done; 

This scalar attribute (with the $ sigil) has a type of Bool. Instead of the ! twigil, the . twigil is used. While Perl 6 does enforce encapsulation on attributes, it also saves you from writing accessor methods. Replacing the ! with a . both declares the attribute $!done and an accessor method named done. It's as if you had written:

has Bool $!done;
method done() { return $!done }

Note that this is not like declaring a public attribute, as some languages allow; you really get both a private attribute and a method, without having to write the method by hand. You are free instead to write your own accessor method, if at some future point you need to do something more complex than return the value.

Note that using the . twigil has created a method that will provide read-only access to the attribute. If instead the users of this object should be able to reset a task's completion state (perhaps to perform it again), you can change the attribute declaration:

has Bool $.done is rw;

The is rw trait causes the generated accessor method to return something external code can modify to change the value of the attribute.

You can also supply default values to attributes (which works equally for those with and without accessors):

has Bool $.done = False;

The assignment is carried out at object build time. The right-hand side is evaluated at that time, and can even reference earlier attributes:

has Task @!dependencies; 
 has $.ready = not @!dependencies; 

7.3 Static fields?

Perl 6 has no static keyword. Nevertheless, any class may declare anything that a module can, so making a scoped variable sounds like good idea.

class Singleton { 
     my Singleton $instance; 
     method new {!!!} 
     submethod instance { 
         $instance = Singleton.bless unless $instance; 
         $instance; 
     } 
 } 
 

Class attributes defined by my or our may also be initialized when being declared, however we are implementing the Singleton pattern here and the object must be created during its first use. It is not 100% possible to predict the moment when attribute initialization will be executed, because it can take place during compilation, runtime or both, especially when importing the class using the use keyword.

class HaveStaticAttr { 
       my Foo $.foo = some_complicated_subroutine; 
 } 

Class attributes may also be declared with a secondary sigil – in a similar manner to object attributes – that will generate read-only accessors if the attribute is to be public.

7.4 Methods

While attributes give objects state, methods give objects behaviors. Let's ignore the new method temporarily; it's a special type of method. Consider the second method, add-dependency, which adds a new task to a task's dependency list.

method add-dependency(Task $dependency) { 
     push @!dependencies, $dependency; 
 } 

In many ways, this looks a lot like a sub declaration. However, there are two important differences. First, declaring this routine as a method adds it to the list of methods for the current class. Thus any instance of the Task class can call this method with the . method call operator. Second, a method places its invocant into the special variable self.

The method itself takes the passed parameter – which must be an instance of the Task class – and pushes it onto the invocant's @!dependencies attribute.

The perform method contains the main logic of the dependency handler:

method perform() { 
     unless $!done { 
         .perform() for @!dependencies; 
         &!callback(); 
         $!done = True; 
     } 
 } 

It takes no parameters, working instead with the object's attributes. First, it checks if the task has already completed by checking the $!done attribute. If so, there's nothing to do.

Otherwise, the method performs all of the task's dependencies, using the for construct to iterate over all of the items in the @!dependencies attribute. This iteration places each item – each a Task object – into the topic variable, $_. Using the . method call operator without specifying an explicit invocant uses the current topic as the invocant. Thus the iteration construct calls the .perform() method on every Task object in the @!dependencies attribute of the current invocant.

After all of the dependencies have completed, it's time to perform the current Task's task by invoking the &!callback attribute directly; this is the purpose of the parentheses. Finally, the method sets the $!done attribute to True, so that subsequent invocations of perform on this object (if this Task is a dependency of another Task, for example) will not repeat the task.

7.4.1 Private Methods

Just like attributes, methods can also be private. Private methods are declared with a prefixed exclamation mark. They are called with self! followed by the method's name. To call a private method of another class the calling class has to be trusted by the called class. A trust relationship is declared with trusts and the class to be trusted must already be declared. Calling a private method of another class requires an instance of that class and the fully qualified name of the method. Trust also allows access to private attributes.

class B {...}

class C {
    trusts B;
    has $!hidden = 'invisible';
    method !not-yours () { say 'hidden' }
    method yours-to-use () {
        say $!hidden;
        self!not-yours();
    }
}

class B {
    method i-am-trusted () {
        my C $c.=new;
        $c!C::not-yours();
    }
}

C.new.yours-to-use(); # the context of this call is GLOBAL, and not trusted by C
B.new.i-am-trusted();

Trust relationships are not subject to inheritance. To trust the global namespace, the pseudo package GLOBAL can be used.

7.5 Constructors

Perl 6 is rather more liberal than many languages in the area of constructors. A constructor is anything that returns an instance of the class. Furthermore, constructors are ordinary methods. You inherit a default constructor named new from the base class Mu, but you are free to override new, as this example does:

method new(&callback, *@dependencies) {
    return self.bless(:&callback, :@dependencies);
}

The biggest difference between constructors in Perl 6 and constructors in languages such as C# and Java is that rather than setting up state on a somehow already magically created object, Perl 6 constructors create the object themselves. The easiest way to do this is by calling the bless method, also inherited from Mu. The bless method expects a set of named parameters to provide the initial values for each attribute.

The example's constructor turns positional arguments into named arguments, so that the class can provide a nice constructor for its users. The first parameter is the callback (the thing which will execute the task). The rest of the parameters are dependent Task instances. The constructor captures these into the @dependencies slurpy array and passes them as named parameters to bless (note that :&callback uses the name of the variable – minus the sigil – as the name of the parameter).

Private attributes really are private. This means that bless is not allowed to bind things to &!callback and @!dependencies directly. To do this, we override the BUILD submethod, which is called on the brand new object by bless:

submethod BUILD(:&!callback, :@!dependencies) { } 

Since BUILD runs in the context of the newly created Task object, it is allowed to manipulate those private attributes. The trick here is that the private attributes (&!callback and @!dependencies) are being used as the bind targets for BUILD's parameters. Zero-boilerplate initialization! See objects for more information.

The BUILD method is responsible for initializing all attributes and must also handle default values:

has &!callback; 
 has @!dependencies; 
 has Bool ($.done, $.ready); 
 submethod BUILD( 
         :&!callback, 
         :@!dependencies, 
         :$!done = False, 
         :$!ready = not @!dependencies 
     ) { } 

See Object Construction for more options to influence object construction and attribute initialization.

7.6 Consuming our class

After creating a class, you can create instances of the class. Declaring a custom constructor provides a simple way of declaring tasks along with their dependencies. To create a single task with no dependencies, write:

my $eat = Task.new({ say 'eating dinner. NOM!' }); 

An earlier section explained that declaring the class Task installed a type object in the namespace. This type object is a kind of "empty instance" of the class, specifically an instance without any state. You can call methods on that instance, as long as they do not try to access any state; new is an example, as it creates a new object rather than modifying or accessing an existing object.

Unfortunately, dinner never magically happens. It has dependent tasks:

my $eat = 
     Task.new({ say 'eating dinner. NOM!' }, 
         Task.new({ say 'making dinner' }, 
             Task.new({ say 'buying food' }, 
                 Task.new({ say 'making some money' }), 
                 Task.new({ say 'going to the store' }) 
             ), 
             Task.new({ say 'cleaning kitchen' }) 
         ) 
     ); 

Notice how the custom constructor and sensible use of whitespace makes task dependencies clear.

Finally, the perform method call recursively calls the perform method on the various other dependencies in order, giving the output:

making some money 
 going to the store 
 buying food 
 cleaning kitchen 
 making dinner 
 eating dinner. NOM! 

7.7 Inheritance

Object Oriented Programming provides the concept of inheritance as one of the mechanisms for code reuse. Perl 6 supports the ability for one class to inherit from one or more classes. When a class inherits from another class it informs the method dispatcher to follow the inheritance chain to look for a method to dispatch. This happens both for standard methods defined via the method keyword and for methods generated through other means, such as attribute accessors.

class Employee { 
     has $.salary; 
 
     method pay() { 
         say "Here is \$$.salary"; 
     } 
 } 
 
 class Programmer is Employee { 
     has @.known_languages is rw; 
     has $.favorite_editor; 
 
     method code_to_solve( $problem ) { 
         say "Solving $problem using $.favorite_editor in " 
         ~ $.known_languages[0] ~ '.'; 
     } 
 } 

Now, any object of type Programmer can make use of the methods and accessors defined in the Employee class as though they were from the Programmer class.

my $programmer = Programmer.new( 
     salary => 100_000, 
     known_languages => <Perl5 Perl6 Erlang C++>, 
     favorite_editor => 'vim' 
 ); 
 
 $programmer.code_to_solve('halting problem'); 
 $programmer.pay(); 

7.7.1 Overriding inherited methods

Of course, classes can override methods and attributes defined by parent classes by defining their own. The example below demonstrates the Baker class overriding the Cook's cook method.

class Cook is Employee { 
     has @.utensils  is rw; 
     has @.cookbooks is rw; 
 
     method cook( $food ) { 
         say "Cooking $food"; 
     } 
 
     method clean_utensils { 
         say "Cleaning $_" for @.utensils; 
     } 
 } 
 
 class Baker is Cook { 
     method cook( $confection ) { 
         say "Baking a tasty $confection"; 
     } 
 } 
 
 my $cook = Cook.new( 
     utensils => <spoon ladle knife pan>, 
     cookbooks => 'The Joy of Cooking', 
     salary => 40000); 
 
 $cook.cook( 'pizza' ); # OUTPUT: «Cooking pizza␤» 
 
 my $baker = Baker.new( 
     utensils => 'self cleaning oven', 
     cookbooks => "The Baker's Apprentice", 
     salary => 50000); 
 
 $baker.cook('brioche'); # OUTPUT: «Baking a tasty brioche␤» 

Because the dispatcher will see the cook method on Baker before it moves up to the parent class the Baker's cook method will be called.

To access methods in the inheritance chain use re-dispatch or the MOP.

7.7.2 Multiple inheritance

As mentioned before, a class can inherit from multiple classes. When a class inherits from multiple classes the dispatcher knows to look at both classes when looking up a method to search for. Perl 6 uses the C3 algorithm to linearize multiple inheritance hierarchies, which is a significant improvement over Perl 5's default approach (depth-first search) to handling multiple inheritance.

class GeekCook is Programmer is Cook { 
     method new( *%params ) { 
         push( %params<cookbooks>, "Cooking for Geeks" ); 
         return self.bless(|%params); 
     } 
 } 
 
 my $geek = GeekCook.new( 
     books           => 'Learning Perl 6', 
     utensils        => ('stainless steel pot', 'knife', 'calibrated oven'), 
     favorite_editor => 'MacVim', 
     known_languages => <Perl6> 
 ); 
 
 $geek.cook('pizza'); 
 $geek.code_to_solve('P =? NP'); 

Now all the methods made available to the Programmer and the Cook classes are available from the GeekCook class.

While multiple inheritance is a useful concept to know and occasionally use, it is important to understand that there are more useful OOP concepts. When reaching for multiple inheritance it is good practice to consider whether the design wouldn't be better realized by using roles, which are generally safer because they force the class author to explicitly resolve conflicting method names. For more information on roles see Roles.

7.7.3 The also declarator

Classes to be inherited from can be listed in the class declaration body by prefixing the is trait with also. This also works for the role composition trait does.

class GeekCook { 
     also is Programmer; 
     also is Cook; 
     # ... 
 } 
 
 role A {}; 
 role B {}; 
 class C { also does A; also does B } 

7.8 Introspection

Introspection is the process of gathering information about some objects in your program, not by reading the source code, but by querying the object (or a controlling object) for some properties, such as its type.

Given an object $o and the class definitions from the previous sections, we can ask it a few questions:

if $o ~~ Employee { say "It's an employee" }; 
 if $o ~~ GeekCook { say "It's a geeky cook" }; 
 say $o.WHAT; 
 say $o.perl; 
 say $o.^methods(:local)».name.join(', '); 
 say $o.^name; 

The output can look like this:

It's an employee 
 (Programmer) 
 Programmer.new(known_languages => ["Perl", "Python", "Pascal"], 
         favorite_editor => "gvim", salary => "too small") 
 code_to_solve, known_languages, favorite_editor 
 Programmer 

The first two tests each smart-match against a class name. If the object is of that class, or of an inheriting class, it returns true. So the object in question is of class Employee or one that inherits from it, but not GeekCook.

The .WHAT method returns the type object associated with the object $o, which tells us the exact type of $o: in this case Programmer.

$o.perl returns a string that can be executed as Perl code, and reproduces the original object $o. While this does not work perfectly in all cases, it is very useful for debugging simple objects.

For example closures cannot easily be reproduced this way; if you don't know what a closure is don't worry. Also current implementations have problems with dumping cyclic data structures this way, but they are expected to be handled correctly by .perl at some point.
$o.^methods(:local) produces a list of Methods that can be called on $o. The :local named argument limits the returned methods to those defined in the Programmer class and excludes the inherited methods.

The syntax of calling a method with .^ instead of a single dot means that it is actually a method call on its meta class, which is a class managing the properties of the Programmer class – or any other class you are interested in. This meta class enables other ways of introspection too:

say $o.^attributes.join(', '); 
 say $o.^parents.map({ $_.^name }).join(', '); 

Finally $o.^name calls the name method on the meta object, which unsurprisingly returns the class name.

Introspection is very useful for debugging and for learning the language and new libraries. When a function or method returns an object you don't know about, finding its type with .WHAT, seeing a construction recipe for it with .perl, and so on, you'll get a good idea of what its return value is. With .^methods you can learn what you can do with the class.

But there are other applications too: a routine that serializes objects to a bunch of bytes needs to know the attributes of that object, which it can find out via introspection.

8 Community

Information about the people working on and using Perl 6

8.1 Overview

"Perl 5 was my rewrite of Perl. I want Perl 6 to be the community's rewrite of Perl and of the community." - Larry Wall

8.2 IRC

There is a large presence on the #perl6 channel on freenode.net, who are happy to provide support and answer questions.

9 Concurrency

Concurrency and Asynchronous Programming

In common with most modern programming languages, Perl 6 is designed to support concurrency (allowing more than one thing to happen at the same time) and asynchronous programming (sometimes called event driven or reactive programming - that is an event or change in some part of a program may lead to an event or change in some other part of the program asynchronously to the program flow).

The aim of the Perl concurrency design is to provide a high-level, composable, consistent interface, regardless of how a virtual machine may implement it for a particular operating system, through layers of facilities as described below.

I'm not quite clear which specific features should be included below hyper-operators, autothreading junctions?

Additionally, certain Perl features may implicitly operate in an asynchronous fashion, so in order to ensure predictable interoperation with these features, user code should, where possible, avoid the lower level concurrency APIs (i.e. Thread and Scheduler ) and use the higher-level interfaces.

9.1 High-level APIs

9.1.1 Promises

A Promise (also called future in other programming environments) encapsulates the result of a computation that may not have completed or even started at the time the promise is obtained. A Promise starts from a Planned status and can result in either a Kept status, meaning the promise has been successfully completed, or a Broken status meaning that the promise has failed. Usually this is much of the functionality that user code needs to operate in a concurrent or asynchronous manner.

my $p1 = Promise.new; 
 say $p1.status;         # OUTPUT: «Planned␤» 
 $p1.keep('result'); 
 say $p1.status;         # OUTPUT: «Kept␤» 
 say $p1.result;         # OUTPUT: «result␤» 
                         # (since it has been kept, a result is available!) 
 
 my $p2 = Promise.new; 
 $p2.break('oh no'); 
 say $p2.status;         # OUTPUT: «Broken␤» 
 say $p2.result;         # dies, because the promise has been broken 
 CATCH { default { say .^name, ': ', .Str } }; 
 # OUTPUT: «X::AdHoc+{X::Promise::Broken}: oh no␤» 

Promises gain much of their power by being composable, for example by chaining, usually by the then method:

my $promise1 = Promise.new();
my $promise2 = $promise1.then(
    -> $v { say $v.result; "Second Result" }
);
$promise1.keep("First Result");
say $promise2.result;   # OUTPUT: «First Result␤Second Result␤»

Here the then method schedules code to be executed when the first Promise is kept or broken, itself returning a new Promise which will be kept with the result of the code when it is executed (or broken if the code fails.) keep changes the status of the promise to Kept setting the result to the positional argument. result blocks the current thread of execution until the promise is kept or broken, if it was kept then it will return the result (that is the value passed to keep, ) otherwise it will throw an exception based on the value passed to break. The latter behaviour is illustrated with:

my $promise1 = Promise.new();
my $promise2 = $promise1.then(-> $v { say "Handled but : "; say $v.result});
$promise1.break("First Result");
try $promise2.result;
say $promise2.cause;        # OUTPUT: «Handled but : ␤First Result␤»

Here the break will cause the code block of the then to throw an exception when it calls the result method on the original promise that was passed as an argument, which will subsequently cause the second promise to be broken, raising an exception in turn when its result is taken. The actual Exception object will then be available from cause. If the promise had not been broken cause would raise a X::Promise::CauseOnlyValidOnBroken exception.

A Promise can also be scheduled to be automatically kept at a future time:

my $promise1 = Promise.in(5);
my $promise2 = $promise1.then(-> $v { say $v.status; 'Second Result' });
say $promise2.result;

The method in creates a new promise and schedules a new task to call keep on it no earlier than the supplied number of seconds, returning the new Promise object.

A very frequent use of promises is to run a piece of code, and keep the promise once it returns successfully, or break it when the code dies. The start method provides a shortcut for that:

my $promise = Promise.start(
    { my $i = 0; for 1 .. 10 { $i += $_ }; $i}
);
say $promise.result;    # OUTPUT: «55␤»

Here the result of the promise returned is the value returned from the code. Similarly if the code fails (and the promise is thus broken), then cause will be the Exception object that was thrown:

my $promise = Promise.start({ die "Broken Promise" });
try $promise.result;
say $promise.cause;

This is considered to be such a commonly required pattern that it is also provided as subroutines:

my $promise = start {
    my $i = 0;
    for 1 .. 10 {
        $i += $_
    }
    $i
}
my $result = await $promise;
say $result;

await is almost equivalent to calling result on the promise object returned by start but it will also take a list of promises and return the result of each:

my $p1 = start {
    my $i = 0;
    for 1 .. 10 {
        $i += $_
    }
    $i
};
my $p2 = start {
    my $i = 0;
    for 1 .. 10 {
        $i -= $_
    }
    $i
};
my @result = await $p1, $p2;
say @result;            # OUTPUT: «[55 -55]␤»

In addition to await, two class methods combine several Promise objects into a new promise: allof returns a promise that is kept when all the original promises are kept or broken:

my $promise = Promise.allof(
    Promise.in(2),
    Promise.in(3)
);

await $promise;
say "All done"; # Should be not much more than three seconds later

And anyof returns a new promise that will be kept when any of the original promises is kept or broken:

my $promise = Promise.anyof(
    Promise.in(3),
    Promise.in(8600)
);

await $promise;
say "All done"; # Should be about 3 seconds later

Unlike await however the results of the original kept promises are not available without referring to the original, so these are more useful when the completion or otherwise of the tasks is more important to the consumer than the actual results, or when the results have been collected by other means. You may, for example, want to create a dependent Promise that will examine each of the original promises:

my @promises;
for 1..5 -> $t {
    push @promises, start {
        sleep $t;
        Bool.pick;
    };
}
say await Promise.allof(@promises).then({ so all(@promises>>.result) });

Which will give True if all of the promises were kept with True, False otherwise.

If you are creating a promise that you intend to keep or break yourself then you probably don't want any code that might receive the promise to inadvertently (or otherwise) keep or break the promise before you do. For this purpose there is the method vow, which returns a Vow object which becomes the only mechanism by which the promise can be kept or broken. If an attempt to keep or break the Promise is made directly then the exception X::Promise::Vowed will be thrown, as long as the vow object is kept private, the status of the promise is safe:

sub get_promise {
    my $promise = Promise.new;
    my $vow = $promise.vow;
    Promise.in(10).then({$vow.keep});
    $promise;
}

my $promise = get_promise();

# Will throw an exception
# "Access denied to keep/break this Promise; already vowed"
$promise.keep;
CATCH { default { say .^name, ': ', .Str } };
# OUTPUT: «X::Promise::Vowed: Access denied to keep/break this Promise; already vowed␤»

The methods that return a promise that will be kept or broken automatically such as in or start will do this, so it is not necessary to do it for these.

9.1.2 Supplies

A Supply is an asynchronous data streaming mechanism that can be consumed by one or more consumers simultaneously in a manner similar to "events" in other programming languages and can be seen as enabling "Event Driven" or reactive designs.

At its simplest, a Supply is a message stream that can have multiple subscribers created with the method tap on to which data items can be placed with emit.

The Supply can either be live or on-demand. A live supply is like a TV broadcast: those who tune in don't get previously emitted values. An on-demand broadcast is like Netflix: everyone who starts streaming a movie (taps a supply), always starts it from the beginning (gets all the values), regardless of how many people are watching it right now. Note that no history is kept for on-demand supplies, instead, the supply block is run for each tap of the supply.

A live Supply is created by the Supplier factory, each emitted value is passed to all the active tappers as they are added:

my $supplier = Supplier.new;
my $supply   = $supplier.Supply;

$supply.tap( -> $v { say $v });

for 1 .. 10 {
    $supplier.emit($_);
}

Note that the tap is called on a Supply object created by the Supplier and new values are emitted on the Supplier.

Or alternatively as an on-demand Supply created by the supply keyword:

my $supply = supply {
    for 1 .. 10 {
        emit($_);
    }
}
$supply.tap( -> $v { say $v });

In this case the code in the supply block is executed every time the Supply returned by supply is tapped, as demonstrated by:

my $supply = supply {
    for 1 .. 10 {
        emit($_);
    }
}
$supply.tap( -> $v { say "First : $v" });
$supply.tap( -> $v { say "Second : $v" });

The tap method returns a Tap object which can be used to obtain information about the tap and also to turn it off when we are no longer interested in the events:

my $supplier = Supplier.new;
my $supply   = $supplier.Supply;

my $tap = $supply.tap( -> $v { say $v });

$supplier.emit("OK");
$tap.close;
$supplier.emit("Won't trigger the tap");

Calling done on the supply object calls the done callback that may be specified for any taps, but does not prevent any further events being emitted to the stream, or taps receiving them.

The method interval returns a new on-demand supply which periodically emits a new event at the specified interval. The data that is emitted is an integer starting at 0 that is incremented for each event. The following code outputs 0 .. 5 :

my $supply = Supply.interval(2);
$supply.tap(-> $v { say $v });
sleep 10;

This could also be written using the react keyword:

react {
    whenever Supply.interval(2) -> $v {
        say $v;
        done() if $v == 4;
    }
}

Here the whenever keyword uses .act to create a tap on the Supply from the provided block. The react block is exited when done() is called in one of the taps.

A second argument can be supplied to interval which specifies a delay in seconds before the first event is fired. Each tap of a supply created by interval has its own sequence starting from 0, as illustrated by the following:

my $supply = Supply.interval(2);
$supply.tap(-> $v { say "First $v" });
sleep 6;
$supply.tap(-> $v { say "Second $v"});
sleep 10;

An on-demand Supply can also be created from a list of values that will be emitted in turn, thus the first on-demand example could be written as:

react {
    whenever Supply.from-list(1..10) -> $v {
        say $v;
    }
}

An existing supply object can be filtered or transformed, using the methods grep and map respectively, to create a new supply in a manner like the similarly named list methods: grep returns a supply such that only those events emitted on the source stream for which the grep condition is true is emitted on the second supply:

my $supplier = Supplier.new;
my $supply = $supplier.Supply;
$supply.tap(-> $v { say "Original : $v" });
my $odd_supply = $supply.grep({ $_ % 2 });
$odd_supply.tap(-> $v { say "Odd : $v" });
my $even_supply = $supply.grep({ not $_ % 2 });
$even_supply.tap(-> $v { say "Even : $v" });
for 0 .. 10 {
    $supplier.emit($_);
}

map returns a new supply such that for each item emitted to the original supply a new item which is the result of the expression passed to the map is emitted:

my $supplier = Supplier.new;
my $supply = $supplier.Supply;
$supply.tap(-> $v { say "Original : $v" });
my $half_supply = $supply.map({ $_ / 2 });
$half_supply.tap(-> $v { say "Half : $v" });
for 0 .. 10 {
    $supplier.emit($_);
}

If you need to have an action that runs when the supply finishes, you can do so by setting the done and quit options in the call to tap:

$supply.tap: { ... }, 
     done => { say 'Job is done.' }, 
     quit => { 
         when X::MyApp::Error { say "App Error: ", $_.message } 
     }; 

The quit block works very similar to a CATCH. If the exception is marked as seen by a when or default block, the exception is caught and handled. Otherwise, the exception continues to up the call tree (i.e., the same behavior as when quit is not set).

If you are using the react or supply block syntax with whenever, you can add phasers within your whenever blocks to handle the done and quit messages from the tapped supply:

react { 
     whenever $supply { 
         ...; # your usual supply tap code here 
         LAST { say 'Job is done.' } 
         QUIT { when X::MyApp::Error { say "App Error: ", $_.message } } 
     } 
 } 

The behavior here is the same as setting done and quit on tap.

9.1.3 Channels

A Channel is a thread-safe queue that can have multiple readers and writers that could be considered to be similar in operation to a "fifo" or named pipe except it does not enable inter-process communication. It should be noted that, being a true queue, each value sent to the Channel will only be available to a single reader on a first read, first served basis: if you want multiple readers to be able to receive every item sent you probably want to consider a Supply.

An item is queued onto the Channel with the method send, and the method receive removes an item from the queue and returns it, blocking until a new item is sent if the queue is empty:

my $channel = Channel.new;
$channel.send('Channel One');
say $channel.receive;  # OUTPUT: «Channel One␤»

If the channel has been closed with the method close then any send will cause the exception X::Channel::SendOnClosed to be thrown, and a receive will throw a X::Channel::ReceiveOnClosed if there are no more items on the queue.

The method list returns all the items on the Channel and will block until further items are queued unless the channel is closed:

my $channel = Channel.new;
await (^10).map: -> $r {
    start {
        sleep $r;
        $channel.send($r);
    }
}
$channel.close;
for $channel.list -> $r {
    say $r;
}

There is also the non-blocking method poll that returns an available item from the channel or Nil if there is no item or the channel is closed, this does of course mean that the channel must be checked to determine whether it is closed:

my $c = Channel.new;

# Start three Promises that sleep for 1..3 seconds, and then
# send a value to our Channel
^3 .map: -> $v {
    start {
        sleep 3 - $v;
        $c.send: "$v from thread {$*THREAD.id}";
    }
}

# Wait 3 seconds before closing the channel
Promise.in(3).then: { $c.close }

# Continuously loop and poll the channel, until it's closed
my $is-closed = $c.closed;
loop {
    if $c.poll -> $item {
        say "$item received after {now - INIT now} seconds";
    }
    elsif $is-closed {
        last;
    }

    say 'Doing some unrelated things...';
    sleep .6;
}

# Doing some unrelated things...
# Doing some unrelated things...
# 2 from thread 5 received after 1.2063182 seconds
# Doing some unrelated things...
# Doing some unrelated things...
# 1 from thread 4 received after 2.41117376 seconds
# Doing some unrelated things...
# 0 from thread 3 received after 3.01364461 seconds
# Doing some unrelated things...

The method closed returns a Promise that will be kept (and consequently will evaluate to True in a boolean context) when the channel is closed.

The .poll method can be used in combination with .receive method, as a caching mechanism where lack of value returned by `.poll` is a signal that more values need to be fetched and loaded into the channel:

sub get-value { 
     return $c.poll // do { start replenish-cache; $c.receive }; 
 } 
 
 sub replenish-cache { 
     for ^20 { 
         $c.send: $_ for slowly-fetch-a-thing(); 
     } 
 } 

Channels can be used in place of the Supply in the whenever of a react block described earlier:

my $channel = Channel.new; 
 my $p = start { 
     react { 
         whenever $channel { 
             say $_; 
         } 
     } 
 } 
 
 await (^10).map: -> $r { 
     start { 
         sleep $r; 
         $channel.send($r); 
     } 
 } 
 
 $channel.close; 
 await $p; 

It is also possible to obtain a Channel from a Supply using the Channel method which returns a Channel which is fed by a tap on the Supply:

my $supplier = Supplier.new;
my $supply   = $supplier.Supply;
my $channel = $supply.Channel;

my $p = start {
    react  {
        whenever $channel -> $item {
            say "via Channel: $item";
        }
    }
}

await (^10).map: -> $r {
    start {
        sleep $r;
        $supplier.emit($r);
    }
}

$supplier.done;
await $p;

Channel will return a different Channel fed with the same data each time it is called. This could be used, for instance, to fan-out a Supply to one or more Channels to provide for different interfaces in a program.

9.1.4 Proc::Async

Proc::Async builds on the facilities described to run and interact with an external program asynchronously:

my $proc = Proc::Async.new('echo', 'foo', 'bar');

$proc.stdout.tap(-> $v { print "Output: $v" });
$proc.stderr.tap(-> $v { print "Error:  $v" });

say "Starting...";
my $promise = $proc.start;

await $promise;
say "Done.";

# Output:
# Starting...
# Output: foo bar
# Done.

The path to the command as well as any arguments to the command are supplied to the constructor. The command will not be executed until start is called, which will return a Promise that will be kept when the program exits. The standard output and standard error of the program are available as Supply objects from the methods stdout and stderr respectively which can be tapped as required.

If you want to write to the standard input of the program you can supply the :w adverb to the constructor and use the methods write, print or say to write to the opened pipe once the program has been started:

my $proc = Proc::Async.new(:w, 'grep', 'foo');

$proc.stdout.tap(-> $v { print "Output: $v" });

say "Starting...";
my $promise = $proc.start;

$proc.say("this line has foo");
$proc.say("this one doesn't");

$proc.close-stdin;
await $promise;
say "Done.";

# Output:
# Starting...
# Output: this line has foo
# Done.

Some programs (such as grep without a file argument in this example, ) won't exit until their standard input is closed so close-stdin can be called when you are finished writing to allow the Promise returned by start to be kept.

9.2 Low-level APIs

9.2.1 Threads

The lowest level interface for concurrency is provided by Thread. A thread can be thought of as a piece of code that may eventually be run on a processor, the arrangement for which is made almost entirely by the virtual machine and/or operating system. Threads should be considered, for all intents, largely un-managed and their direct use should be avoided in user code.

A thread can either be created and then actually run later:

my $thread = Thread.new(code => { for  1 .. 10  -> $v { say $v }});
# ...
$thread.run;

Or can be created and run at a single invocation:

my $thread = Thread.start({ for  1 .. 10  -> $v { say $v }});

In both cases the completion of the code encapsulated by the Thread object can be waited on with the finish method which will block until the thread completes:

$thread.finish; 

Beyond that there are no further facilities for synchronization or resource sharing which is largely why it should be emphasized that threads are unlikely to be useful directly in user code.

9.2.2 Schedulers

The next level of the concurrency API is supplied by classes that implement the interface defined by the role Scheduler. The intent of the scheduler interface is to provide a mechanism to determine which resources to use to run a particular task and when to run it. The majority of the higher level concurrency APIs are built upon a scheduler and it may not be necessary for user code to use them at all, although some methods such as those found in Proc::Async, Promise and Supply allow you to explicitly supply a scheduler.

The current default global scheduler is available in the variable $*SCHEDULER.

The primary interface of a scheduler (indeed the only method required by the Scheduler interface) is the cue method:

method cue(:&code, Instant :$at, :$in, :$every, :$times = 1; :&catch)

This will schedule the Callable in &code to be executed in the manner determined by the adverbs (as documented in Scheduler) using the execution scheme as implemented by the scheduler. For example:

my $i = 0;
my $cancellation = $*SCHEDULER.cue({ say $i++}, every => 2 );
sleep 20;

Assuming that the $*SCHEDULER hasn't been changed from the default, will print the numbers 0 to 10 approximately (i.e with operating system scheduling tolerances) every two seconds. In this case the code will be scheduled to run until the program ends normally, however the method returns a Cancellation object which can be used to cancel the scheduled execution before normal completion:

my $i = 0;
my $cancellation = $*SCHEDULER.cue({ say $i++}, every => 2 );
sleep 10;
$cancellation.cancel;
sleep 10;

should only output 0 to 5,

Despite the apparent advantage the Scheduler interface provides over that of Thread all of functionality is available through higher level interfaces and it shouldn't be necessary to use a scheduler directly, except perhaps in the cases mentioned above where a scheduler can be supplied explicitly to certain methods.

A library may wish to provide an alternative scheduler implementation if it has special requirements, for instance a UI library may want all code to be run within a single UI thread, or some custom priority mechanism may be required, however the implementations provided as standard and described below should suffice for most user code.

9.2.2.1 ThreadPoolScheduler

The ThreadPoolScheduler is the default scheduler, it maintains a pool of threads that are allocated on demand, creating new ones as necessary up to maximum number given as a parameter when the scheduler object was created (the default is 16.) If the maximum is exceeded then cue may queue the code until such time as a thread becomes available.

Rakudo allows the maximum number of threads allowed in the default scheduler to be set by the environment variable RAKUDO_MAX_THREADS at the time the program is started.

9.2.2.2 CurrentThreadScheduler

The CurrentThreadScheduler is a very simple scheduler that will always schedule code to be run straight away on the current thread. The implication is that cue on this scheduler will block until the code finishes execution, limiting its utility to certain special cases such as testing.

9.2.3 Locks

The class Lock provides the low level mechanism that protects shared data in a concurrent environment and is thus key to supporting thread-safety in the high level API, this is sometimes known as a "Mutex" in other programming languages. Because the higher level classes (Promise, Supply and Channel) use a Lock where required it is unlikely that user code will need to use a Lock directly.

The primary interface to Lock is the method protect which ensures that a block of code (commonly called a "critical section") is only executed in one thread at a time:

my $lock = Lock.new;

my $a = 0;

await (^10).map: {
    start {
            $lock.protect({
                my $r = rand;
                sleep $r;
                $a++;
            });
    }
}

say $a; # OUTPUT: «10␤»

protect returns whatever the code block returns.

Because protect will block any threads that are waiting to execute the critical section the code should be as quick as possible.

9.3 Safety Concerns

Some shared data concurrency issues are less obvious than others. For a good general write-up on this subject see this blog post.

One particular issue of note is when container autovivification or extension takes place. When an Array or a Hash entry is initially assigned the underlying structure is altered and that operation is not async safe. For example, in this code:

my @array;
my $slot := @array[20];
$slot = 'foo';

The third line is the critical section as that is when the array is extended. The simplest fix is to use a Lock to protect the critical section . A possibly better fix would be to refactor the code so that sharing a container is not necessary.

10 Containers

A low-level explanation of Perl 6 containers

This article started as a conversation on IRC explaining the difference between the Array and the List type in Perl 6. It explains the levels of indirection involved in dealing with variables and container elements.

10.1 What is a variable?

Some people like to say "everything is an object", but in fact a variable is not a user-exposed object in Perl 6.

When the compiler encounters a variable declaration like my $x, it registers it in some internal symbol table. This internal symbol table is used to detect undeclared variables and to tie the code generation for the variable to the correct scope.

At run time, a variable appears as an entry in a lexical pad, or lexpad for short. This is a per-scope data structure that stores a pointer for each variable.

In the case of my $x, the lexpad entry for the variable $x is a pointer to an object of type Scalar, usually just called the container.

10.2 Scalar containers

Although objects of type Scalar are everywhere in Perl 6, you rarely see them directly as objects, because most operations decontainerize, which means they act on the Scalar container's contents instead of the container itself.

In code like

my $x = 42;
say $x;

the assignment $x = 42 stores a pointer to the Int object 42 in the scalar container to which the lexpad entry for $x points.

The assignment operator asks the container on the left to store the value on its right. What exactly that means is up to the container type. For Scalar it means "replace the previously stored value with the new one".

Note that subroutine signatures allow passing around of containers:

sub f($a is rw) {
    $a = 23;
}
my $x = 42;
f($x);
say $x;         # OUTPUT: «23␤»

Inside the subroutine, the lexpad entry for $a points to the same container that $x points to outside the subroutine. Which is why assignment to $a also modifies the contents of $x.

Likewise a routine can return a container if it is marked as is rw:

my $x = 23;
sub f() is rw { $x };
f() = 42;
say $x;         # OUTPUT: «42␤»

For explicit returns, return-rw instead of return must be used.

Returning a container is how is rw attribute accessors work. So

class A {
    has $.attr is rw;
}

is equivalent to

class A {
    has $!attr;
    method attr() is rw { $!attr }
}

Scalar containers are transparent to type checks and most kinds of read-only accesses. A .VAR makes them visible:

my $x = 42;
say $x.^name;       # OUTPUT: «Int␤»
say $x.VAR.^name;   # OUTPUT: «Scalar␤»

And is rw on a parameter requires the presence of a writable Scalar container:

sub f($x is rw) { say $x };
f 42;
CATCH { default { say .^name, ': ', .Str } };
# OUTPUT: «X::Parameter::RW: Parameter '$x' expected a writable container, but got Int value␤»

10.3 Binding

Next to assignment, Perl 6 also supports binding with the := operator. When binding a value or a container to a variable, the lexpad entry of the variable is modified (and not just the container it points to). If you write

my $x := 42;

then the lexpad entry for $x directly points to the Int 42. Which means that you cannot assign to it anymore:

my $x := 42;
$x = 23;
CATCH { default { say .^name, ': ', .Str } };
# OUTPUT: «X::AdHoc: Cannot assign to an immutable value␤»

You can also bind variables to other variables:

my $a = 0;
my $b = 0;
$a := $b;
$b = 42;
say $a;         # OUTPUT: «42␤»

Here, after the initial binding, the lexpad entries for $a and $b both point to the same scalar container, so assigning to one variable also changes the contents of the other.

You've seen this situation before: it is exactly what happened with the signature parameter marked as is rw.

Sigilless variables also bind by default and so do parameters with the trait is raw.

my $a = 42;
my \b = $a;
b++;
say $a;         # OUTPUT: «43␤»

sub f($c is raw) { $c++ }
f($a);
say $a;         # OUTPUT: «44␤»

10.4 Scalar containers and listy things

There are a number of positional container types with slightly different semantics in Perl 6. The most basic one is List It is created by the comma operator.

say (1, 2, 3).^name;    # OUTPUT: «List␤»

A list is immutable, which means you cannot change the number of elements in a list. But if one of the elements happens to be a scalar container, you can still assign to it:

my $x = 42;
($x, 1, 2)[0] = 23;
say $x;                 # OUTPUT: «23␤»
($x, 1, 2)[1] = 23;     # Cannot modify an immutable value
CATCH { default { say .^name, ': ', .Str } };
# OUTPUT: «X::Assignment::RO: Cannot modify an immutable Int␤»

So the list doesn't care about whether its elements are values or containers, they just store and retrieve whatever was given to them.

Lists can also be lazy, so elements at the end are generated on demand from an iterator.

An Array is just like a list, except that it forces all its elements to be containers, which means that you can always assign to elements:

my @a = 1, 2, 3;
@a[0] = 42;
say @a;         # OUTPUT: «[42 2 3]␤»

@a actually stores three scalar containers. @a[0] returns one of them, and the assignment operator replaces the integer value stored in that container with the new one, 42.

10.5 Assigning and binding to array variables

Assigning to a scalar variable and to an array variable both do basically the same thing: discard the old value(s), and enter some new value(s).

Nevertheless, it's easy to observe how different they are:

my $x = 42; say $x.^name;   # OUTPUT: «Int␤»
my @a = 42; say @a.^name;   # OUTPUT: «Array␤»

This is because the Scalar container type hides itself well, but Array makes no such effort. Also assignment to an array variable is coercive, so you can assign a non-array value to an array variable.

To place a non-Array into an array variable, binding works:

my @a := (1, 2, 3);
say @a.WHAT;                # OUTPUT: «(List)␤»

10.6 Binding to array elements

As a curious side note, Perl 6 supports binding to array elements:

my @a = (1, 2, 3);
@a[0] := my $x;
$x = 42;
say @a;                     # OUTPUT: «[42 2 3]␤»

If you've read and understood the previous explanations, it is now time to wonder how this can possibly work. After all, binding to a variable requires a lexpad entry for that variable, and while there is one for an array, there aren't lexpad entries for each array element (you cannot expand the lexpad at run time).

The answer is that binding to array elements is recognized at the syntax level and instead of emitting code for a normal binding operation, a special method (called BIND-KEY) is called on the array. This method handles binding to array elements.

Note that, while supported, one should generally avoid directly binding uncontainerized things into array elements. Doing so may produce counter-intuitive results when the array is used later.

my @a = (1, 2, 3);
@a[0] := 42;         # This is not recommended, use assignment instead.
my $b := 42;
@a[1] := $b;         # Nor is this.
@a[2] = $b;          # ...but this is fine.
@a[1, 2] := 1, 2;    # runtime error: X::Bind::Slice
CATCH { default { say .^name, ': ', .Str } };
# OUTPUT: «X::Bind::Slice: Cannot bind to Array slice␤»

Operations that mix Lists and Arrays generally protect against such a thing happening accidentally.

10.7 Flattening, items and containers

The % and @ sigils in Perl 6 generally indicate multiple values to an iteration construct, whereas the $ sigil indicates only one value.

my @a = 1, 2, 3;
for @a { };         # 3 iterations
my $a = (1, 2, 3);
for $a { };         # 1 iteration

@-sigiled variables do not flatten in list context:

my @a = 1, 2, 3;
my @b = @a, 4, 5;
say @b.elems;               # OUTPUT: «3␤»

There are operations that flatten out sublists that are not inside a scalar container: slurpy parameters (*@a) and explicit calls to flat:

my @a = 1, 2, 3;
say (flat @a, 4, 5).elems;  # OUTPUT: «5␤»

sub f(*@x) { @x.elems };
say f @a, 4, 5;             # OUTPUT: «5␤»

As hinted above, scalar containers prevent that flattening:

sub f(*@x) { @x.elems };
my @a = 1, 2, 3;
say f $@a, 4, 5;            # OUTPUT: «3␤»

The @ character can also be used as a prefix to remove a scalar container:

my $x = (1, 2, 3);
.say for @$x;               # 3 iterations

Methods generally don't care whether their invocant is in a scalar, so

my $x = (1, 2, 3);
$x.map(*.say);              # 3 iterations

maps over a list of three elements, not of one.

10.8 Self Reference

Complex containers, like Array or Hash and relatives, can contain a reference to itself, forming recursive data structures. Please note that very few builtin functions and methods will detect infinite loops. It is the responsibility of the user to handle timeouts.

my @a;
@a[0] = @a;
put @a.perl;
# OUTPUT: «((my @Array_75093712) = [@Array_75093712,])␤»

10.9 Type Constraints

Any container can have a type constraint in the form of a type object or a subset. Both can be placed between a declarator and the variable name or after the trait of. The constraint is a property of the container, not the variable. Any (re-)binding may change the type constraint or remove the constraint altogether if bound to a value instead of a container. Introspection of type constraints on containers is provided by .VAR.of.

EVAL ‚my Int $i = 42; $i := "forty plus two";‘;
CATCH { default { say .^name, ' ', .Str } }
# OUTPUT: «Type check failed in binding; expected Int but got Str ("forty plus two")␤…»

10.10 Custom containers

To provide custom containers Perl 6 provides the class Proxy. It takes two methods that are called when values are stored or fetched from the container. Type checks are not done by the container itself and other restrictions like readonlyness can be broken. The returned value must therefore be of the same type as the type of the variable it is bound to. We can use type captures to work with types in Perl 6.

sub lucky(::T $type) {
    my T $c-value; # closure variable
    return Proxy.new(
        FETCH => method () { $c-value },
        STORE => method (T $new-value) {
            X::OutOfRange.new(what => 'number', got => '13', range => '-∞..12, 14..∞').throw
                if $new-value == 13;
            $c-value = $new-value;
        }
    );
}

my Int $a := lucky(Int);
say $a = 12;    # OUTPUT: «12␤»
say $a = 'FOO'; # X::TypeCheck::Binding
say $a = 13;    # X::OutOfRange
CATCH { default { say .^name, ': ', .Str } };

11 Contributors

List of contributors to Perl 6 over the years

The following people contributed to the development of Perl 6, as could be determined from the logs of all the various projects that make up Perl 6. If you think you are missing from this list, or for any reason would not like to appear on this list, or need a correction, please submit a Pull Request with the required change(s).

11.1 A

  Gisle Aas 
   abcxyzp 
   Chuck Adams 
   Colin Paul Adams 
   Rod Adams 
   C.J. Adams-Collier 
   David H. Adler 
   Chirag Agrawal 
   Amir E. Aharoni 
   Bilal Akhtar 
   Julian Albo 
   Alekssasho 
   alexghacker 
   Paco Alguacil 
   Brandon S Allbery 
   Geir Amdal 
   Markus Amsler 
   Paul C. Anagnostopoulos 
   Nikolay Ananiev 
   anatolyv 
   andras 
   Saleem Ansari 
   Joji Antony 
   Tomoki Aonuma 
   Syed Uzair Aqeel 
   arathorn 
   Arcterus 
   Kodi Arfer 
   Daniel Arbelo Arrocha 
   ash 
   Ted Ashton 
   Arnaud Assad 
   atroxaper 
   Ori Avtalion אורי אבטליון 
   Auzon 

11.2 B

  Greg Bacon 
   Ivan Baidakou 
   Alex Balhatchet 
   Szabó 
   Balázs 
   Amir Livine Bar-On עמיר ליבנה בר-און 
   Luca Barbato 
   Mattia Barbon 
   Ann Barcomb 
   Christian Bartolomäus 
   Alex "Skud" Bayley 
   bcmb 
   Jody Belka 
   Shachaf Ben-Kiki 
   Andrei Benea 
   benedikth 
   Zev Benjamin 
   benmorrow 
   Kevan Benson 
   Martin Berends 
   Anton Berezin 
   Arthur Bergman 
   Anders Nor Berle 
   bestian 
   Peter Bevan 
   Mark Biggar 
   Carlin Bingham 
   Ævar Arnfjörð Bjarmason 
   J. David Blackstone 
   Ronald Blaschke 
   Ingo Blechschmidt 
   bloonix 
   blwood 
   Kristof Bogaerts 
   Dan Bolser 
   Конрад Боровски 
   Christopher Bottoms 
   Gonéri Le Bouder 
   Jos Boumans 
   Brad Bowman 
   Matt Boyle 
   bpetering 
   H.Merijn Brand 
   Terrence Brannon 
   Gwern Branwen 
   Stig Brautaset 
   Herbert "lichtkind" Breunung 
   bri 
   brian_d_foy 
   Fernando Brito 
   Geoffrey Broadwell 
   Leon Brocard 
   Benjamin Brodfuehrer 
   Samuel Bronson 
   Dan Brook 
   Nathan C. Brown 
   Roger Browne 
   Philippe Bruhat (BooK) 
   David Brunton 
   Corwin Brust 
   Klaus Brüssel 
   Lucas Buchala 
   buchetc 
   Christoph Buchetmann 
   Norbert Buchmuller 
   Buddha Buck 
   Alexandre Buisse 
   Tim Bunce 
   Bryan Burgers 
   Sean M. Burke 
   Matthew Byng-Maddick 
   András Bártházi 
   Jürgen Bömmels 

11.3 C

  Caelum 
   Aldo Calpini 
   Edward Cant 
   David Cantrell 
   Carlin 
   Michael Cartmell 
   Hezekiah Carty 
   Nuno 'smash' Carvalho 
   Marcelo Serra Castilhos 
   Piers Cawley 
   cdavaz 
   cdpruden 
   Gianni Ceccarelli 
   cfourier 
   Marc Chantreux 
   Mitchell N Charity 
   Oliver Charles 
   Vasily Chekalkin 
   Yuan-Chen Cheng 鄭原真 
   Daniel Chetlin 
   Hsin-Chan Chien 簡信昌 
   N. Hao Ching 
   Joshua Choi 
   Elizabeth Cholet 
   David Christensen 
   chuck 
   cjeris 
   Nicholas Clark 
   Steve Clark 
   Jeff Clites 
   cmarcelo 
   cmeyer 
   Paul Cochrane 
   Daniel Colascione 
   Jason Cole 
   Will "Coke" Coleda 
   Sylvain Colinet 
   cono 
   Tim Conrow 
   Géraud Continsouzas 
   Damian Conway 
   Neil Conway 
   Stuart Cook 
   David Corbin 
   Deven T. Corzine 
   cosmicnet 
   Timothy Covell 
   Beau E. Cox 
   Simon Cozens 
   Philip Crow 
   cspenser 
   Franck Cuny 
   Tyler Curtis 
   David Czech 

11.4 D

  Daenyth 
   Dagur 
   Ritz Daniel 
   darkwolf 
   Chris Davaz 
   David Warring 
   Justin DeVuyst 
   Daniel Dehennin 
   Akim Demaille 
   Detonite 
   Lars "daxim" Dieckow 迪拉斯 
   Matt Diephouse 
   Bob Diertens 
   Wendy "woolfy" van Dijk 
   Jeffrey Dik 
   John M. Dlugosz 
   dimid 
   diotalevi 
   Hans van Dok 
   Chris Dolan 
   Mark Dominus 
   Bryan Donlan 
   Andy Dougherty 
   Dave Doyle 
   drKreso 
   dr_df0 
   dudley 
   Jonathan Scott Duff 
   dug 
   Lee Duhem 
   Darren Duncan 

11.5 E

  Andrew Egeler 
   Havard Eidnes 
   Nelson Elhage 
   Ran Eliam 
   Fitz Elliott 
   Alex Elsayed 
   Jay Emerson 
   Aankhola Encorporated 
   ennio 
   Enveigler 
   Jon Ericson 
   Shae Matijs Erisson 
   Eryq 
   Mike Eve 
   Pat Eyler 

11.6 F

  Aaron Faanes 
   Kevin Falcone 
   David Farrell 
   Angel Faus 
   Jason Felds 
   Paul Fenwick 
   Jose Rodrigo Fernandez 
   Nelson Ferraz 
   Adriano Ferreira 
   João Fernando Ferreira 
   Chris Fields 
   Caio Marcelo de Oliveira Filho 
   Steve Fink 
   Shlomi "rindolf" Fish שלומי פיש 
   Mark Leighton Fisher 
   Scott Fitzenrider 
   Dudley Flanders 
   Richard Foley 
   Vincent Foley 
   Julian Fondren 
   Ruben Fonseca 
   David Formosa 
   Karl Forner 
   Solomon Foster 
   Chaddaï Fouché 
   Lloyd Fournier 
   Michael Fowler 
   Matt Fowles 
   franck 
   Austin Frank 
   Carl Franks 
   Kent Fredric 
   Chaim Frenkel 
   Piotr Fusik 

11.7 G

  gabriele 
   John Gabriele 
   Christoph Gärtner 
   Martin von Gagern 
   Felix Gallo 
   Salvador Ortiz Garcia 
   Rafaël Garcia-Suarez 
   Joshua Gatcomb 
   Jerry Gay 
   gcomnz 
   Jonathan Gentle 
   iVAN Georgiev 
   Brian Gernhardt 
   Bram Geron 
   Alessandro Ghedini 
   Imran Ghory 
   Peter Gibbs 
   Tanton Gibbs 
   Brad Gilbert (b2gills) 
   Karl Glazebrook 
   Nick Glencross 
   Mark Glines 
   Flávio S. Glock 
   Jason Gloudon 
   Simon Glover 
   gnuvince 
   Garrett Goebel 
   Jeffrey Goff 
   Mikhael Goikhman 
   Benjamin Goldberg 
   Arcady Goldmints-Orlov 
   Dimitry Golubovsky 
   Gerard Goossen 
   Goplat 
   Alex Gough 
   Léo Grange 
   Chad "Exodist" Granum 
   Kenneth A Graves 
   Bruce Gray 
   Nathan Gray 
   Mark Grimes 
   Lucien Grondin 
   Rolf Grossmann 
   David Grove 
   Marcel Grünauer 
   Daniel Grunblatt 
   Uri Guttman 
   gwern 

11.8 H

  Swaroop C H 
   Richard Hainsworth 
   Roger Hale 
   John "ab5tract" Haltiwanger 
   Nigel Hamilton 
   Eric Hanchrow 
   Sterling Hanenkamp 
   Ask Bjørn Hansen 
   Christian "chansen" Hansen 
   Eirik Berg Hanssen 
   Samuel Harrington 
   Trey Harris 
   John Harrison 
   Carsten Hartenfels 
   Richard Hartmann 
   Kyle Hasselbacher 
   Austin Hastings 
   Carl Hayter 
   Florian Helmberger 
   Gordon Henriksen 
   Felix Herrmann 
   Peter Heslin 
   Fred Heutte 
   Jarkko Hietaniemi 
   Michael H. Hind 
   Joshua Hoblitt 
   Zack Hobson 
   Eric Hodges 
   Rob Hoelz 
   Masahiro Honma 
   Lyle Hopkins 
   JD Horelick 
   Jeff Horwitz 
   Chris Hostetter 
   Laurens Van Houtven 
   Jeremy Howard 
   Yiyi Hu 鹄驿懿 
   Benedikt Huber 
   Brad Hughes 
   Sterling Hughes 
   Tom Hughes 
   Tristan Hume 
   Donald Hunter 
   Douglas Hunter 
   Juan Francisco Cantero Hurtado 
   Kay-Uwe 'kiwi' Hüll 

11.9 I

  Alin Iacob 
   Ibotty 
   ibrown 
   ihrd 
   Roland Illing 
   Jan Ingvoldstad 
   Joshua Isom 
   isop 
   Ivan_A_Frey 
   ivanoff 

11.10 J

  Akash Manohar J 
   jafelds 
   Robert G. Jakabosky 
   jamesrom 
   S. A. Janet 
   jani 
   Heiko Jansen 
   Stuart Jansen 
   Jarrod 
   Jedai 
   Chris Jepeway 
   Chris Jeris 
   Dagur Valberg Johannsson 
   Erik Johansen 
   Paul Johnson 
   johnspurr 
   Isaac Jones 
   Norman Nunley Jr 
   Yoshikuni Jujo 
   Brian S. Julin 
   Josh Juran 
   Michal Jurosz 

11.11 K

  David Koenig 
   Prakash Kailasa 
   Shoichi Kaji 
   Daniel Kang 
   Isis Kang 
   Chia-Liang Kao 高嘉良 
   Dmitry Karasik 
   Luben Karavelov 
   Amir Karger 
   Offer Kaye 
   Bruce Keeler 
   James E Keenan 
   Cole Keirsey 
   Adam Kennedy 
   Matt Kennedy 
   Shane Kerr 
   khairul 
   Mikhail Khorkov 
   Krzysztof Kielak 
   Andres Kievsky 
   Daehyub Kim 
   Rob Kinyon 
   Oleg Kiselyov 
   Oolley kj 
   Martin Kjeldsen 
   Thomas "domm" Klausner 
   Zohar "lumi" Kelrich זהר קלריך/卡卓哈 
   Damian Miles Knopp 
   Dan Kogai 小飼弾 
   Yuval "nothingmuch" Kogman יובל קוג'מן 
   Tomasz Konojacki 
   Vadim Konovalov 
   Nick Kostirya 
   Matt Kraai 
   Thomas Kratz 
   Adrian Kreher 
   John van Krieken 
   Matthias Krull 
   Bradley M. Kuhn 
   Bob Kuo 
   Colin Kuskie 
   Kamil Kułaga 

11.12 L

  Sage LaTorra 
   Brent Laabs 
   laben 
   Johannes Laire 
   Markus Laire 
   Fayland Lam 林道 
   Mike Lambert 
   lanny 
   Leo Lapworth 
   last.of.the.careless.men 
   Bart Lateur 
   Jia-Hong Lee 
   Lola Lee 
   Jonathan Leffler 
   Tobias Leich 
   lembark 
   Mark Lentczner 
   Moritz A Lenz 
   Jean-Louis Leroy 
   Andy Lester 
   Jonathan "Duke" Leto 
   Vladimir Lettiev 
   Mike Li 李曉光 
   Stefan Lidman 
   Yung-Chung Lin 林永忠 
   Glenn Linderman 
   Vladimir Lipsky 
   Zach Lipton 
   Stevan Little 
   Kang-Min Liu 劉康民 
   Skip Livingston 
   David M. Lloyd 
   Daniel Lo 
   Peter Lobsinger 
   Andres Löh 
   Nick Logan 
   Eric Lubow 
   Nolan Lum 
   Peter Lunicks 
   LylePerl 
   Ian Lynagh 
   lysdexsik 

11.13 M

  Kiran Kumar M. 
   Jerry MacClure 
   Noel Maddy 
   Christopher J. Madsen 
   Abhijit A. Mahabal 
   Max Maischein 
   Peter Makholm 
   Ujwal Reddy Malipeddi 
   malon 
   Christopher Malon 
   Dagfinn Ilmari Mannsåker 
   Michael Maraist 
   Roie Marianer רועי מריאנר 
   markmont 
   Simon Marlow 
   martin 
   Paolo Martini 
   Ilya Martynov 
   Jaume Martí 
   James Mastros 
   Michael J. Mathews 
   Vyacheslav Matjukhin 
   Tokuhiro Matsuno 
   mattc 
   Mike Mattie 
   Elizabeth "lizmat" Mattijsen 
   Вячеслав Матюхин 
   Markus Mayr 
   Josh McAdams 
   Martin McCarthy 
   Mark McConnell 
   Steven McDougall 
   John McNamara 
   Scott McWhirter 
   mdinger 
   Olivier "dolmen" Mengué 
   Kevin Metcalf 
   Patrick R. Michaud 
   mimir 
   mjreed 
   Tom Moertel 
   Michael Mol 
   Paolo Molaro 
   Shawn M Moore 
   Brandon Michael Moore 
   Alexander Moquin 
   Ion Alexandru Morega 
   Dino Morelli 
   Kolia Morev 
   Zach Morgan 
   mr_ank 
   Alex Munroe 
   muraiki 
   Paweł Murias 
   mvuets 
   Steve Mynott 
   mzedeler 
   Carl Mäsak 

11.14 N

  naesten 
   Tim Nelson 
   Ailin Nemui 
   Ingy döt Net 應吉大聶 
   David Nicol 
   Faye Niemeyer 
   Nigelsandever 
   Karl Rune Nilsen 
   Salve J. Nilsen 
   Per Christian Nodtvedt 
   Ben Noordhuis 
   Paweł Nowak 
   Norman Nunley 

11.15 O

  Tony O'Dell 
   יהושע "שי" אוחיון 
   Clayton O'Neill 
   Stefan O'Rear 
   Sean O'Rourke 
   Matt Oates 
   Tony Olekshy 
   Martin Olsen 
   Dmitriy Olshevskiy 
   Dave Olszewski 
   Nelo Onyiah 
   William Orr 
   Jon Orwant 
   Andrei Osipov 
   Christoph Otto 

11.16 P

  Pawel Pabian 
   Walter Pallestrong 
   Luke Palmer 
   Bartłomiej Palmowski 
   Pancake 
   Paolo 
   Marton Papp 
   Andrew Parker 
   Roman M. Parparov 
   Anthony Parsons 
   Mike Pastore 
   Nova Patch 
   Timo Paulssen 
   Tony Payne 
   Stéphane "cognominal" Payrard 
   Slava Pechenin 
   Gael Pegliasco 
   Stéphane Peiry 
   Felipe Pena 
   Nayden Pendov 
   Wenzel P. P. Peppmeyer 
   François Perrad 
   Markus Peter 
   Ben Petering 
   Steve Peters 
   Tim Peterson 
   Ronny Pfannschmidt 
   Clinton A. Pierce 
   Jerrad Pierce 
   Thilo Planz 
   plunix 
   pmakholm 
   Curtis 'Ovid' Poe 
   Gerd Pokorra 
   Peter Polacik 
   Flavio Poletti 
   Kevin Polulak 
   John Porter 
   Ryan W. Porter 
   Stephen P. Potter 
   Philip Potter 
   Adam Preble 
   premshree 
   Klāvs Priedītis 
   Adam Prime 
   Richard Proctor 
   Christopher Pruden 
   Kevin Puetz 
   Gregor N. Purdy 
   purl 

11.17 Q

  Hongwen Qiu 
   Jerome Quelin 
   quester 

11.18 R

  Gerhard R. 
   Peter Rabbitson 
   Florian Ragwitz 
   raiph 
   Matt Rajca 
   Marcus Ramberg 
   Claudio Ramirez 
   Prog Rammer 
   Allison Randal 
   David Ranvig 
   Lars Balker Rasmussen 
   Curtis Rawls 
   raydiak 
   Robin Redeker 
   Ted Reed 
   Jens Rehsack 
   Charles Reiss 
   Gabriele Renzi 
   Kenneth C. Rich 
   Jason Richmond 
   Ryan Richter 
   Sebastian Riedel 
   Dennis Rieks 
   Jens Rieks 
   Lanny Ripple 
   John Rizzo 
   rkhill 
   Andrew Robbins 
   Amos Robinson 
   Jonathan Rockway 
   Stefano Rodighiero 
   Andrew Rodland 
   Lindolfo Rodrigues 
   Bob Rogers 
   Dave Rolsky 
   David Romano 
   ron 
   Eric J. Roode 
   Garret Rooney 
   Garrett Rooney 
   David Ross 
   Andreas Rottmann 
   Brent Royal-Gordon 
   Shmarya Rubenstein 
   Sam Ruby 
   Simon Ruderich 
   Daniel Ruoso 
   Jake Russo 
   ruz 
   Joseph Ryan 
   Gilbert Röhrbein 

11.19 S

  Sam S 
   s1n 
   sahadev 
   Patrick Abi Salloum 
   salty_horse 
   Chip Salzenberg 
   Shrivatsan Sampathkumar 
   Igor Rafael Sanchez-Puls 
   Hugo van der Sanden 
   Thomas Sandlaß 
   Yun SangHo 
   sanug 
   Siddhant Saraf 
   Sasho 
   Andrew Savige 
   John Saylor 
   Matt Schallert 
   Bernhard Schmalhofer 
   Arthur Axel Schmidt 
   Ronald Schmidt 
   Michael Schroeder 
   Steven Schubiger 
   Steve "thundergnat" Schulze 
   Andreas Schwab 
   Randal L. Schwartz 
   Pepe Schwarz 
   Frederik Schwarzer 
   Calvin Schwenzfeier 
   Michael G. Schwern 
   Steffen Schwigon 
   Tom Scola 
   Ariel Scolnicov 
   Michael Scott 
   Peter Scott 
   Rick Scott 
   Stefan Seifert 
   Austin Seipp 
   Mark Senn 
   Filip Sergot 
   Seth Gold (Sgeo) 
   William Shallum 
   Kris Shannon 
   shenyute 
   Aaron Sherman 
   Mark Shoulson 
   Ryan Siemens 
   Ricardo Signes 
   Hinrik Örn Sigurðsson 
   Jonathan Sillito 
   Miroslav Silovic 
   Steve Simmons 
   Alberto Manuel Brandao Simoes 
   John Siracusa 
   Arne Skjærholt 
   Barrie Slaymaker 
   Radek Slupik 
   Mike Small 
   Benjamin Smith 
   Melvin Smith 
   Tim Smith 
   Adrian White aka 
   snarkyboojum 
   Richard Soderberg 
   SolidState 
   Vishal Soni 
   Syloke Soong 
   Shawn Sorichetti 
   Tadeusz Sośnierz 
   sue spence 
   Cory Spencer 
   Robert Spier 
   Michael Stapelberg 
   Edwin Steiner 
   stephenpollei 
   Michael Stevens 
   Don Stewart 
   Radu Stoica 
   Klaas-Jan Stol 
   Alek Storm 
   David Storrs 
   Mark Stosberg 
   Jonathan Stowe 
   Cosimo Streppone 
   Jonathan Strickland 
   Pascal Stumpf 
   Su-Shee 
   Sue 
   Laye Suen 
   Dan Sugalski 
   Mark Summerfield 
   Simon Sun 
   Cheng-Lung Sung 宋政隆 
   Sunnavy 
   Samuel Sutch 
   svatsan 
   svn 
   Andrew Sweger 
   sygi 
   Sebastian Sylvan 
   Gábor Szabó 
   Bálint Szilakszi 
   Marek Šuppa 

11.20 T

  TOGoS 
   Arvindh Rajesh Tamilmani 
   Audrey Tang 唐鳳 
   Bestian Tang 唐宗浩 
   Adrian Taylor 
   Jesse Taylor 
   Philip Taylor 
   Kevin Tew 
   the_dormant 
   Marcus Thiesen 
   Adam Thomason 
   Richard Tibbetts 
   Carey Tilden 
   Marcel Timmerman 
   Leon Timmermans 
   tkob 
   John Tobey 
   Frank Tobin 
   Bennett Todd 
   Graham Todd 
   Leopold Tötsch 
   Daniel Toma 
   Nathan Torkington 
   Timothy Totten 
   Itsuki Toyota 
   John J. Trammell 
   Matt S. Trout 
   Nat Tuck 
   Adam Turoff 
   Ben Tyler 

11.21 U

  ujwal 
   Bernd Ulmann 
   Reini Urban 
   parrot user 
   uzair 

11.22 V

  VZ 
   Ilmari Vacklin 
   vamped 
   Wim Vanderbauwhede 
   vendethiel 
   David Vergin 
   Ted Vessenes 
   Sam Vilain 
   Cédric Vincent 
   Jesse Vincent 
   Jos Visser 
   John van Vlaanderen 
   vmax 
   Jeremy Voorhis 
   Martin Vorländer 
   Johan Vromans 
   Maxim Vuets 

11.23 W

  Juerd Waalboer 
   Mariano Wahlmann 
   Kevin Walker 
   Gloria Wall 
   Larry Wall 
   Lewis Wall 
   Michal J Wallace 
   John Paul Wallington 
   walter 
   Matthew Walton 
   Ting Wang 
   Xinyuan Wang 
   Andy Wardley 
   Bryan C. Warnock 
   wayland 
   Stephen Weeks 
   Zhen-Bang Wei 
   Nick Wellnhofer 
   Shu-Chun Weng 
   Danny Werner 
   Brian Wheeler 
   David E. Wheeler 
   Dave Whipp 
   Adrian White 
   Andrew Whitworth 
   Bart Wiegmans 
   Nathan Wiger 
   Brock Wilcox 
   Edwin Wiles 
   Bob Wilkinson 
   Chris 'BinGOs' Williams 
   Greg Williams 
   Josh Wilmes 
   Matthew Wilson 
   Ashley Winters 
   Brian Wisti 
   Dave Woldrich 
   Helmut Wollmersdorfer 
   Kevin J. Woolley 
   Jonathan Worthington 
   Kuang-Che Wu 吳光哲 

11.24 X

  xenu 
   Liang-Qi Xie 謝良奇 
   Xtreak 

11.25 Y

  Gaal Yahas גל יחס 
   Thomas Yandell 
   Alvis Yardley 
   Thomas Yeh 葉志宏 
   Natan Yellin 
   yiyihu 
   Matt Youell 
   Tony Young 
   Shen Yu-Teh 

11.26 Z

  Ilya Zakharevich 
   Ruslan Zakirov 
   Ahmad M. Zawawi 
   Michael A. D. Zedeler 
   zengargoyle 
   zeriod 
   Agent Zhang 章亦春 
   Jimmy Zhuo 
   Ziggy6 
   Rob Zinkov 
   Zoffix Znet 

12 Control Flow

Statements used to control the flow of execution

12.1 statements

Perl 6 programs consists of one or more statements. Simple statements are separated by semicolons. The following program will say "Hello" and then say "World" on the next line.

say "Hello";
say "World";

In most places where spaces appear in a statement, and before the semicolon, it may be split up over many lines. Also, multiple statements may appear on the same line. It would be awkward, but the above could also be written as:

say
"Hello"; say "World";

12.2 blocks

Like many languages, Perl 6 uses blocks enclosed by { and } to turn multiple statements into a single statement. It is ok to skip the semicolon between the last statement in a block and the closing }.

{ say "Hello"; say "World" }

When a block stands alone as a statement, it will be entered immediately after the previous statement finishes, and the statements inside it will be executed.

say 1;                    # OUTPUT: «1␤»
{ say 2; say 3 };         # OUTPUT: «2␤3␤»
say 4;                    # OUTPUT: «4␤»

Unless it stands alone as a statement, a block simply creates a closure. The statements inside are not executed immediately. Closures are another topic and how they are used is explained elsewhere. For now it is just important to understand when blocks run and when they do not:

say "We get here"; { say "then here." }; { say "not here"; 0; } or die; 

In the above example, after running the first statement, the first block stands alone as a second statement, so we run the statement inside it. The second block does not stand alone as a statement, so instead, it makes an object of type Block but does not run it. Object instances are usually considered to be true, so the code does not die, even though that block would evaluate to 0, were it to be executed. The example does not say what to do with the Block object, so it just gets thrown away.

Most of the flow control constructs covered below are just ways to tell perl6 when, how, and how many times, to enter blocks like that second block.

Before we go into those, an important side-note on syntax: If there is nothing (or nothing but comments) on a line after a closing curly brace where you would normally put semicolon, then you do not need the semicolon:

# All three of these lines can appear as a group, as is, in a program
{ 42.say }                # OUTPUT: «42␤»
{ 43.say }                # OUTPUT: «43␤»
{ 42.say }; { 43.say }    # OUTPUT: «42␤43␤»

...but:

{ 42.say }  { 43.say }    # Syntax error 
 { 42.say; } { 43.say }    # Also a syntax error, of course 

So, be careful when you backspace in a line-wrapping editor:

{ "Without semicolons line-wrapping can be a bit treacherous.".say } \ 
 { 43.say } # Syntax error 

You have to watch out for this in most languages anyway to prevent things from getting accidentally commented out. Many of the examples below may have unnecessary semicolons for clarity.

12.3 do

The simplest way to run a block where it cannot be a stand-alone statement is by writing do before it:

# This dies half of the time 
 do { say "Heads I win, tails I die."; Bool.pick } or die; say "I win."; 

Note that you need a space between the do and the block.

The whole do {...} evaluates to the final value of the block. The block will be run when that value is needed in order to evaluate the rest of the expression. So:

False and do { 42.say };

...will not say 42. However, the block is only evaluated once each time the expression it is contained in is evaluated:

# This says "(..1 ..2 ..3)" not "(..1 ...2 ....3)"
my $f = "."; say do { $f ~= "." } X~ 1, 2, 3;

In other words, it follows the same reification rules as everything else.

Technically, do is a loop which runs exactly one iteration.

A do may also be used on a bare statement (without curly braces) but this is mainly just useful for avoiding the syntactical need to parenthesize a statement if it is the last thing in an expression:

3, do if 1 { 2 }  ; # OUTPUT: «(3, 2)␤» 
 3,   (if 1 { 2 }) ; # OUTPUT: «(3, 2)␤» 
 3,    if 1 { 2 }  ; # Syntax error 

...which brings us to if.

12.4 if

To conditionally run a block of code, use an if followed by a condition. The condition, an expression, will be evaluated immediately after the statement before the if finishes. The block attached to the condition will only be evaluated if the condition means True when coerced to Bool. Unlike some languages the condition does not have to be parenthesized, instead the { and } around the block are mandatory:

if 1 { "1 is true".say }  ; # says "1 is true" 
 if 1   "1 is true".say    ; # syntax error, missing block 
 if 0 { "0 is true".say }  ; # does not say anything, because 0 is false 
 if 42.say and 0 { 43.say }; # says "42" but does not say "43" 

There is also a form of if called a "statement modifier" form. In this case, the if and then the condition come after the code you want to run conditionally. Do note that the condition is still always evaluated first:

43.say if 42.say and 0;     # says "42" but does not say "43"
43.say if 42.say and 1;     # says "42" and then says "43"
say "It is easier to read code when 'if's are kept on left of screen"
    if True;                # says the above, because it is true
{ 43.say } if True;         # says "43" as well

The statement modifier form is probably best used sparingly.

The if statement itself will either slip us an empty list, if it does not run the block, or it will return the value which the block produces:

my $d = 0; say (1, (if 0 { $d += 42; 2; }), 3, $d); # says "(1 3 0)"
my $c = 0; say (1, (if 1 { $c += 42; 2; }), 3, $c); # says "(1 2 3 42)"
say (1, (if 1 { 2, 2 }), 3);         # does not slip, says "(1 (2 2) 3)"

For the statement modifier it is the same, except you have the value of the statement instead of a block:

say (1, (42 if True) , 2); # says "(1 42 2)"
say (1, (42 if False), 2); # says "(1 2)"
say (1,  42 if False , 2); # says "(1 42)" because "if False, 2" is true

The if does not change the topic ($_) by default. In order to access the value which the conditional expression produced, you have to ask for it more strongly:

$_ = 1; if 42 { $_.say }                ; # says "1"
$_ = 1; if 42 -> $_ { $_.say }          ; # says "42"
$_ = 1; if 42 -> $a { $_.say;  $a.say } ; # says "1" then says "42"
$_ = 1; if 42       { $_.say; $^a.say } ; # says "1" then says "42"

12.4.1 else/elsif

A compound conditional may be produced by following an if conditional with else to provide an alternative block to run when the conditional expression is false:

if 0 { say "no" } else { say "yes" }   ; # says "yes" 
 if 0 { say "no" } else{ say "yes" }    ; # syntax error, space is required 

The else cannot be separated from the conditional statement by a semicolon, but as a special case, it is OK to have a newline.

if 0 { say "no" }; else { say "yes" }  ; # syntax error 
 if 0 { say "no" } 
 else { say "yes" }                     ; # says "yes" 

Additional conditions may be sandwiched between the if and the else using elsif. An extra condition will only be evaluated if all the conditions before it were false, and only the block next to the first true condition will be run. You can end with an elsif instead of an else if you want.

if 0 { say "no" } elsif False { say "NO" } else { say "yes" } # says "yes"
if 0 { say "no" } elsif True { say "YES" } else { say "yes" } # says "YES"

if 0 { say "no" } elsif False { say "NO" } # does not say anything

sub right { "Right!".say; True }
sub wrong { "Wrong!".say; False }
if wrong() { say "no" } elsif right() { say "yes" } else { say "maybe" }
# The above says "Wrong!" then says "Right!" then says "yes"

You cannot use the statement modifier form with else or elsif:

42.say if 0 else { 43.say }            # syntax error 

All the same rules for semicolons and newlines apply, consistently

if 0 { say 0 }; elsif 1 { say 1 }  else { say "how?" } ; # syntax error 
 if 0 { say 0 }  elsif 1 { say 1 }; else { say "how?" } ; # syntax error 
 if 0 { say 0 }  elsif 1 { say 1 }  else { say "how?" } ; # says "1" 
if 0 { say 0 } elsif 1 { say 1 }
else { say "how?" }                                    ; # says "1"

if 0 { say 0 }
elsif 1 { say 1 } else { say "how?" }                  ; # says "1"

if        0 { say "no" }
elsif False { say "NO" }
else        { say "yes" }                              ; # says "yes"

The whole thing either slips us an empty list (if no blocks were run) or returns the value produced by the block that did run:

my $d = 0; say (1,
                (if 0 { $d += 42; "two"; } elsif False { $d += 43; 2; }),
                3, $d); # says "(1 3 0)"
my $c = 0; say (1,
                (if 0 { $c += 42; "two"; } else { $c += 43; 2; }),
                3, $c); # says "(1 2 3 43)"

It's possible to obtain the value of the previous expression inside an else, which could be from if or the last elsif if any are present:

$_ = 1; if 0     { } else -> $a { "$_ $a".say } ; # says "1 0"
$_ = 1; if False { } else -> $a { "$_ $a".say } ; # says "1 False"

if False { } elsif 0 { } else -> $a { $a.say }  ; # says "0"

12.4.2 unless

When you get sick of typing "if not (X)" you may use unless to invert the sense of a conditional statement. You cannot use else or elsif with unless because that ends up getting confusing. Other than those two differences unless works the same as #if:

unless 1 { "1 is false".say }  ; # does not say anything, since 1 is true 
 unless 1   "1 is false".say    ; # syntax error, missing block 
 unless 0 { "0 is false".say }  ; # says "0 is false" 
unless 42.say and 1 { 43.say } ; # says "42" but does not say "43"
43.say unless 42.say and 0;      # says "42" and then says "43"
43.say unless 42.say and 1;      # says "42" but does not say "43"

$_ = 1; unless 0 { $_.say }           ; # says "1"
$_ = 1; unless 0 -> $_ { $_.say }     ; # says "0"
$_ = 1; unless False -> $a { $a.say } ; # says "False"

my $c = 0; say (1, (unless 0 { $c += 42; 2; }), 3, $c); # says "(1 2 3 42)"
my $d = 0; say (1, (unless 1 { $d += 42; 2; }), 3, $d); # says "(1 3 0)"

12.4.3 with, orwith, without

The with statement is like if but tests for definedness rather than truth. In addition, it topicalizes on the condition, much like given:

with "abc".index("a") { .say }      # prints 0

Instead of elsif, orwith may be used to chain definedness tests:

# The below code says "Found a at 0"
my $s = "abc";
with   $s.index("a") { say "Found a at $_" }
orwith $s.index("b") { say "Found b at $_" }
orwith $s.index("c") { say "Found c at $_" }
else                 { say "Didn't find a, b or c" }

You may intermix if-based and with-based clauses.

# This says "Yes"
if 0 { say "No" } orwith Nil { say "No" } orwith 0 { say "Yes" };

As with unless, you may use without to check for undefinedness, but you may not add an else clause:

my $answer = Any;
without $answer { warn "Got: $_" }

There are also with and without statement modifiers:

my $answer = (Any, True).roll;
say 42 with $answer;
warn "undefined answer" without $answer;

12.5 when

The when block is similar to an if block and either or both can be used in an outer block, they also both have a "statement modifier" form. But there is a difference in how following code in the same, outer block is handled: When the when block is executed, control is passed to the enclosing block and following statements are ignored; but when the if block is executed, following statements are executed. (Note there are other ways to modify the default behavior of each which are discussed in other sections.) The following examples should illustrate the if or when block's default behavior assuming no special exit or other side effect statements are included in the if or when blocks:

{ 
     if X {...} # if X is true in boolean context, block is executed 
     # following statements are executed regardless 
 } 
 { 
     when X {...} # if X is true in boolean context, block is executed 
                  # and control passes to the outer block 
     # following statements are NOT executed 
 } 

Should the if and when blocks above appear at file scope, following statements would be executed in each case.

There is one other feature a when has that if doesn't: the when's boolean context test defaults to $_ ~~ while the if's does not. That has an effect on how one uses the X in the when block without a value for $_ (it's Any in that case and Any smart matches on True: Any ~~ True yields True). Consider the following:

{ 
     my $a = 1; 
     my $b = True; 
     when $a    { say 'a' }; # no output 
     when so $a { say 'a' }  # a (in "so $a" 'so' coerces $a to Boolean context True 
                             # which matches with Any) 
     when $b    { say 'b' }; # b (b is True as defined so matches with Any) 
 } 

Finally, when's statement modifier form does not effect execution of following statements either inside or outside of another block:

say "foo" when X; # if X is true statement is executed 
                   # following statements are not affected 

12.6 for

The for loop iterates over a list, running the statements inside a block once on each iteration. If the block takes parameters, the elements of the list are provided as arguments.

my @foo = 1..3;
for @foo { $_.print } # prints each value contained in @foo
for @foo { .print }   # same thing, because .print implies a $_ argument
for @foo { 42.print } # prints 42 as many times as @foo has elements

Pointy block syntax or a placeholder may be used to name the parameter, of course.

my @foo = 1..3;
for @foo -> $item { print $item }
for @foo { print $^item }            # same thing

Multiple parameters can be declared, in which case the iterator takes as many elements from the list as needed before running the block.

my @foo = 1..3;
for @foo.kv -> $idx, $val { say "$idx: $val" }
my %hash = <a b c> Z=> 1,2,3;
for %hash.kv -> $key, $val { say "$key => $val" }
for 1, 1.1, 2, 2.1 { say "$^x < $^y" }  # says "1 < 1.1" then says "2 < 2.1"

Parameters of a pointy block can have default values, allowing to handle lists with missing elements.

my @list = 1,2,3,4;
for @list -> $a, $b = 'N/A', $c = 'N/A' {
    say "$a $b $c"
}
# OUTPUT: «1 2 3␤4 N/A N/A␤»

If the postfix form of for is used a block is not required and the topic is set for the statement list.

say „I $_ butterflies!“ for <♥ ♥ ♥>;
# OUTPUT«I ♥ butterflies!␤I ♥ butterflies!␤I ♥ butterflies!␤»

A for may be used on lazy lists – it will only take elements from the list when they are needed, so to read a file line by line, you could use:

for $*IN.lines -> $line { .say } 

Iteration variables are always lexical, so you don't need to use my to give them the appropriate scope. Also, they are read-only aliases. If you need them to be read-write, use <-> instead of ->. If you need to make $_ read-write in a for loop, do so explicitly.

my @foo = 1..3;
for @foo <-> $_ { $_++ }

A for loop can produce a List of the values produced by each run of the attached block. To capture these values, put the for loop in parenthesis or assign them to an array:

(for 1, 2, 3 { $_ * 2 }).say;              # says "(2 4 6)"
my @a = do for 1, 2, 3 { $_ * 2 }; @a.say; # says "[2 4 6]"
my @b = (for 1, 2, 3 { $_ * 2 }); @a.say;  # same thing

12.7 gather/take

gather is a statement or block prefix that returns a sequence of values. The values come from calls to take in the dynamic scope of the gather block.

my $a = gather {
    take 1;
    take 5;
    take 42;
}
say join ', ', $a;          # OUTPUT: «1, 5, 42␤»

gather/take can generate values lazily, depending on context. If you want to force lazy evaluation use the lazy subroutine or method. Binding to a scalar or sigilless container will also force laziness.

For example

my @vals = lazy gather {
    take 1;
    say "Produced a value";
    take 2;
}
say @vals[0];
say 'between consumption of two values';
say @vals[1];

# OUTPUT:
# 1
# between consumption of two values
# Produced a value
# 2

gather/take is scoped dynamically, so you can call take from subs or methods that are called from within gather:

sub weird(@elems, :$direction = 'forward') {
    my %direction = (
        forward  => sub { take $_ for @elems },
        backward => sub { take $_ for @elems.reverse },
        random   => sub { take $_ for @elems.pick(*) },
    );
    return gather %direction{$direction}();
}

say weird(<a b c>, :direction<backward> );          # OUTPUT: «(c b a)␤»

If values need to be mutable on the caller side, use take-rw.

12.8 given

The given statement is Perl 6's topicalizing keyword in a similar way that switch topicalizes in languages such as C. In other words, given sets $_ inside the following block. The keywords for individual cases are when and default. The usual idiom looks like this:

my $var = (Any, 21, any <answer lie>).pick;
given $var {
    when 21 { say $_ * 2 }
    when 'lie' { .say }
    default { say 'default' }
}

The given statement is often used alone:

given 42 { .say; .Numeric; }

This is a lot more understandable than:

{ .say; .Numeric; }(42)

12.8.1 default and when

A block containing a default statement will be left immediately when the sub-block after the default statement is left. It is as though the rest of the statements in the block are skipped.

given 42 {
    "This says".say;
    $_ == 42 and ( default { "This says, too".say; 43; } );
    "This never says".say;
}
# The above block evaluates to 43

A when statement will also do this (but a when statement modifier will not.)

In addition, when statements smartmatch the topic ($_) against a supplied expression such that it is possible to check against values, regular expressions, and types when specifying a match.

for 42, 43, "foo", 44, "bar" {
    when Int { .say }
    when /:i ^Bar/ { .say }
    default  { say "Not an Int or a Bar" }
}
# OUTPUT: «42␤43␤Not an Int or a Bar␤44␤Bar␤»

In this form, the given/when construct acts much like a set of if/elsif/else statements. Be careful with the order of the when statements. The following code says "Int" not 42.

given 42 {
    when Int { say "Int" }
    when 42  { say 42 }
    default  { say "huh?" }
}
# OUTPUT: «Int␤»

When a when statement or default statement causes the outer block to return, nesting when or default blocks do not count as the outer block, so you can nest these statements and still be in the same "switch" just so long as you do not open a new block:

given 42 {
    when Int {
      when 42  { say 42 }
      say "Int"
    }
    default  { say "huh?" }
}
# OUTPUT: «42»

when statements can smart match against Signatures.

12.8.2 proceed

12.8.3 succeed

Both proceed and succeed are meant to be used only from inside when or default blocks.

The proceed statement will immediately leave the when or default block, skipping the rest of the statements, and resuming after the block. This prevents the when or default from exiting the outer block.

default { 
     proceed; 
     "This never says".say 
 } 
 "This says".say; 

This is most often used to enter multiple when blocks. proceed will resume matching after a successful match, like so:

given 42 {
    when Int   { say "Int"; proceed }
    when 42    { say 42 }
    when 40..* { say "greater than 40" }
    default    { say "huh?" }
}
# OUTPUT: «Int␤»
# OUTPUT: «42␤»

Note that the when 40..* match didn't occur. For this to match such cases as well, one would need a proceed in the when 42 block.

This is not like a C switch statement, because the proceed does not merely enter the directly following block, it attempts to match the given value once more, consider this code:

given 42 {
    when Int { "Int".say; proceed }
    when 43  { 43.say }
    when 42  { 42.say }
    default  { "got change for an existential answer?".say }
}
# OUTPUT: «Int␤»
# OUTPUT: «42␤»

...which matches the Int, skips 43 since the value doesn't match, matches 42 since this is the next positive match, but doesn't enter the default block since the when 42 block doesn't contain a proceed.

By contrast, the succeed keyword short-circuits execution and exits the entire given block at that point. It may also take an argument to specify a final value for the block.

given 42 {
    when Int {
        say "Int";
        succeed "Found";
        say "never this!";
    }
    when 42 { say 42 }
    default { say "dunno?" }
}
# OUTPUT: «Int␤»

If you are not inside a when or default block, it is an error to try to use proceed or succeed. Also remember, the when statement modifier form does not cause any blocks to be left, and any succeed or proceed in such a statement applies to the surrounding clause, if there is one:

given 42 {
    { say "This says" } when Int;
    "This says too".say;
    when * > 41 {
       { "And this says".say; proceed } when * > 41;
       "This never says".say;
    }
    "This also says".say;
}

12.8.4 given as a statement

given can follow a statement to set the topic in the statement it follows.

.say given "foo";
# OUTPUT: «foo␤»

printf "%s %02i.%02i.%i",
        <Mo Tu We Th Fr Sa Su>[.day-of-week - 1],
        .day,
        .month,
        .year
    given DateTime.now;
# OUTPUT: «Sa 03.06.2016»

12.9 loop

The loop statement takes three statements in parentheses separated by ; that take the role of initializer, conditional and incrementer. The initializer is execute once and any variable declaration will spill into the surrounding block. The conditional is executed once per iteration and coerced to Bool, if False the loop is stopped. The incrementer is executed once per iteration.

loop (my $i = 0; $i < 10; $i++) {
    say $i;
}

The infinite loop does not require parentheses.

loop { say 'forever' } 

The loop statement may be used to produce values from the result of each run of the attached block if it appears in lists:

(loop ( my $i = 0; $i++ < 3;) { $i * 2 }).say;               # OUTPUT: «(2 4 6)␤»
my @a = (loop ( my $j = 0; $j++ < 3;) { $j * 2 }); @a.say;   # OUTPUT: «[2 4 6]␤»
my @b = do loop ( my $k = 0; $k++ < 3;) { $k * 2 }; @b.say;  # same thing

Unlike a for loop, one should not rely on whether returned values are produced lazily, for now. It would probably be best to use eager to guarantee that a loop whose return value may be used actually runs:

sub heads-in-a-row {
    (eager loop (; 2.rand < 1;) { "heads".say })
}

12.10 while, until

The while statement executes the block as long as its condition is true. So

my $x = 1;
while $x < 4 {
    print $x++;
}
print "\n";

# OUTPUT: «123␤»

Similarly, the until statement executes the block as long as the expression is false.

my $x = 1;
until $x > 3 {
    print $x++;
}
print "\n";

# OUTPUT: «123␤»

The condition for while or until can be parenthesized, but there must be a space between the keyword and the opening parenthesis of the condition.

Both while and until can be used as statement modifiers. E. g.

my $x = 42;
$x-- while $x > 12

Also see repeat/while and repeat/until below.

All these forms may produce a return value the same way loop does.

12.11 repeat/while, repeat/until

Executes the block at least once and, if the condition allows, repeats that execution. This differs from while/until in that the condition is evaluated at the end of the loop, even if it appears at the front.

my $x = -42;
repeat {
    $x++;
} while $x < 5;
$x.say; # OUTPUT: «5␤»

repeat {
    $x++;
} while $x < 5;
$x.say; # OUTPUT: «6␤»

repeat while $x < 10 {
    $x++;
}
$x.say; # OUTPUT: «10␤»

repeat while $x < 10 {
    $x++;
}
$x.say; # OUTPUT: «11␤»

repeat {
    $x++;
} until $x >= 15;
$x.say; # OUTPUT: «15␤»

repeat {
    $x++;
} until $x >= 15;
$x.say; # OUTPUT: «16␤»

repeat until $x >= 20 {
    $x++;
}
$x.say; # OUTPUT: «20␤»

repeat until $x >= 20 {
    $x++;
}
$x.say; # OUTPUT: «21␤»

All these forms may produce a return value the same way loop does.

12.12 return

The sub return will stop execution of a subroutine or method, run all relevant phasers and provide the given return value to the caller. The default return value is Nil. If a return type constraint is provided it will be checked unless the return value is Nil. If the type check fails the exception X::TypeCheck::Return is thrown. If it passes a control exception is raised and can be caught with CONTROL.

Any return in a block is tied to the first Routine in the outer lexical scope of that block, no matter how deeply nested. Please note that a return in the root of a package will fail at runtime. A return in a block that is evaluated lazily (e.g. inside map) may find the outer lexical routine gone by the time the block is executed. In almost any case last is the better alternative.

TODO add link to section in /language/function that shows how return values are produces/handled

12.13 return-rw

The sub return will return values, not containers. Those are immutable and will lead to runtime errors when attempted to be mutated.

sub s(){ my $a = 41; return $a };
say ++s();
CATCH { default { say .^name, ': ', .Str } };
# OUTPUT: «X::Multi::NoMatch.new(dispatcher …

To return a mutable container, use return-rw.

sub s(){ my $a = 41; return-rw $a };
say ++s();
# OUTPUT: «42␤»

The same rules as for return regarding phasers and control exceptions apply.

12.14 fail

Leaves the current routine and returns the provided Exception or Str wrapped inside a Failure, after all relevant phasers are executed. If the caller activated fatal exceptions via the pragma use fatal;, the exception is thrown instead of being returned as a Failure.

sub f { fail "WELP!" };
say f;
CATCH { default { say .^name, ': ', .Str } }
# OUTPUT: «X::AdHoc: WELP!␤»

12.15 once

A block prefix with once will be executed exactly once, even if placed inside a loop or a recursive routine.

my $guard = 3;
loop {
    last if $guard-- <= 0;
    once { put 'once' };
    print 'many'
} # OUTPUT: «once␤manymanymany»

This works per "clone" of the containing code object, so:

({ once 42.say } xx 3).map: {$_(), $_()}; # says 42 thrice

Note that this is not a thread-safe construct when the same clone of the same block is run by multiple threads. Also remember that methods only have one clone per class, not per object.

12.16 quietly

A quietly block will suppress warnings.

quietly { warn 'kaput!' };
warn 'still kaput!';
# OUTPUT: «still kaput! [...]␤»

12.17 LABELs

while, until, and for loops can all take a label, which can be used to identify them for next, last, and redo. Nested loops are supported, for instance:

OUTAHERE: while True  {
    for 1,2,3 -> $n {
        last OUTAHERE if $n == 2;
    }
}

12.18 next

The next command starts the next iteration of the loop. So the code

my @x = 1, 2, 3, 4, 5; 
 for @x -> $x { 
     next if $x == 3; 
     print $x; 
 } 
 

prints "1245".

12.19 last

The last command immediately exits the loop in question.

my @x = 1, 2, 3, 4, 5; 
 for @x -> $x { 
     last if $x == 3; 
     print $x; 
 } 
 

prints "12".

12.20 redo

The redo command restarts the loop block without evaluating the conditional again.

{ 
     my $x = prompt("Enter a number"); 
     redo unless $x ~~ /\d+/ 
 } 

12.21 samewith

The samewith allows one to call a multisub of the same name as the current sub.

multi indent-say ( 'test' ) { 
     samewith 'ABCD'; 
 } 
 
 multi indent-say ( Str $string ) { 
     say "\t$string"; 
 } 
 

13 Exceptions

Using exceptions in Perl 6

Exceptions in Perl 6 are objects that record error information; for example: that unexpected data was received; that a network connection is no longer available; or that a needed file is missing.

All built-in exceptions inherit from Exception, which provides some basic behavior, including the storage of a backtrace and an interface for the backtrace printer.

13.1 Ad hoc exceptions

Ad hoc exceptions work just like in Perl 5, where die is called with a description of the error.

die "oops, something went wrong";

# RESULT: «oops, something went wrong in block <unit> at my-script.p6:1␤»

13.2 Typed exceptions

Typed exceptions provide more information about the error stored within an exception object.

For example, if while executing .zombie copy on an object, a needed path foo/bar becomes unavailable, then an X::IO::DoesNotExist exception can be raised:

die X::IO::DoesNotExist.new(:path("foo/bar"), :trying("zombie copy"))

# RESULT: «Failed to find 'foo/bar' while trying to do '.zombie copy'
#          in block <unit> at my-script.p6:1»

Note how the object has provided the backtrace with information about what went wrong. A user of the code can now more easily find and correct the problem.

13.3 Catching exceptions

It's possible to handle exceptional circumstances by supplying a CATCH block:

die X::IO::DoesNotExist.new(:path("foo/bar"), :trying("zombie copy"));

CATCH {
    when X::IO { say "some kind of IO exception was caught!" }
}

# RESULT: «some kind of IO exception was caught!»

Here, we are saying that if any exception of type X::IO occurs, then the message some kind of IO exception was caught! will be displayed.

A CATCH block uses smart matching similar to how given/when smart matches on options, thus it's possible to catch and handle various categories of exceptions inside a when block.

To handle all exceptions, use a default statement.

CATCH {
     default {
         say .WHAT.perl, do given .backtrace[0] { .file, .line, .subname }
     }
}

Note that the match target is a role. To allow user defined exceptions to match in the same manner, they must implement the given role. Just existing in the same namespace will look alike but won't match in a CATCH block.

13.3.1 Exception handlers and enclosing blocks.

After a CATCH has handled the exception, the block enclosing the CATCH is exited.

In other words, even when the exception is handled successfully, the rest of the code in the enclosing block will never be executed.

die "something went wrong ...";

CATCH {
    # will definitely catch all the exception
    default { .Str.say; }
}

say "This won't be said.";   # but this line will be never reached since
                             # the enclosing block will be exited immediately
# OUTPUT: «something went wrong ...␤»

Compare with this:

CATCH {

  CATCH {
      default { .Str.say; }
  }

  die "something went wrong ...";

}

say "Hi! I am at the outer block!"; # OUTPUT: «Hi! I am at the outer block!␤»

See "Resuming of Exceptions", for how to return control back to where the exception originated.

13.4 try blocks

To contain an exception, use a try block. Any exception that is thrown in such a block will be caught by the implicit CATCH block or a CATCH block provided by the user. In the latter case, any unhandled exception will be rethrown.

class E is Exception { method message() { "Just stop already!" } }

try {
    E.throw.new; # this will be local

    say "This won't be said.";
}

say "I'm alive!";

try {
    CATCH {
        when X::AdHoc { .Str.say; .resume }
    }

    die "No, I expect you to DIE Mr. Bond!";

    say "I'm immortal.";

    E.new.throw;

    say "No, you don't!";
}

Output:

I'm alive! 
 No, I expect you to DIE Mr. Bond! 
 I'm immortal. 
 Just stop already! 
   in block <unit> at exception.p6 line 21 

A try-block is a normal block and as such treats it's last statement as the return value of itself. We can therefore use it as a RHS.

say try { +"99999" } // "oh no"; 
 say try { +"hello" } // "oh no"; 
 
 # OUTPUT: «99999␤oh no␤» 

Try blocks support else blocks indirectly by returning the return value of the expression or Nil if an exception was thrown.

with try +"♥" {
    say "this is my number: $_"
} else {
    say "not my number!"
}
# OUTPUT: «not my number!␤»

13.5 Throwing exceptions

Exceptions can be thrown explicitly with the .throw method of an Exception object.

This example throws an AdHoc exception, catches it and allows the code to continue from the point of the exception by calling the .resume method.

{
    X::AdHoc.new(:payload<foo>).throw;
    "OHAI".say;
    CATCH {
        when X::AdHoc { .resume }
    }
}

"OBAI".say;

# OUTPUT: «OHAI␤OBAI␤»

If the CATCH block doesn't match the exception thrown, then the exception's payload is passed on to the backtrace printing mechanism.

{
    X::AdHoc.new(:payload<foo>).throw;
    "OHAI".say;
    CATCH {  }
}

"OBAI".say;

# RESULT: «foo
#          in block <unit> at my-script.p6:1»

This next example doesn't resume from the point of the exception. Instead, it continues after the enclosing block, since the exception is caught, and then control continues after the CATCH block.

{
    X::AdHoc.new(:payload<foo>).throw;
    "OHAI".say;
    CATCH {
        when X::AdHoc { }
    }
}

"OBAI".say;

# OUTPUT: «OBAI␤»

throw can be viewed as the method form of die, just that in this particular case, the sub and method forms of the routine have different names.

13.6 Resuming of Exceptions

Exceptions interrupt control flow and divert it away from the statement following the statement that threw it. Any exception handled by the user can be resumed and control flow will continue with the statement following the statement that threw the exception. To do so, call the method .resume on the exception object.

CATCH { when X::AdHoc { .resume } }         # this is step 2

die "We leave control after this.";         # this is step 1

say "We have continued with control flow."; # this is step 3

13.7 Uncaught Exceptions

If an exception is thrown and not caught, it causes the program to exit with a non-zero status code, and typically prints a message to the standard error stream of the program. This message is obtained by calling the gist method on the exception object. You can use this to suppress the default behavior of printing a backtrace along with the message:

class X::WithoutLineNumber is X::AdHoc {
    multi method gist(X::WithoutLineNumber:D:) {
            $.payload
    }
}
die X::WithoutLineNumber.new(payload => "message")

# prints "message\n" to $*ERR and exits, no backtrace

13.8 Control Exceptions

Control exceptions are thrown by certain keywords and are handled either automatically or by the appropriate phaser. Any unhandled control exception is converted to a normal exception.

{ return; CATCH { default { say .^name, ': ',.Str } } }

# OUTPUT: «X::ControlFlow::Return: Attempt to return outside of any Routine␤»
# was CX::Return

14 Experimental Features

New features for brave users

During Perl 6 development, new features are often made available for users to experimental with before their design is completed. Eventually these features may be made part of the Perl 6 specification. To use these features, one uses the experimental pragma in program source code, for example, like this:

use experimental :macros;

Following is a list of current experimental features and a short description of each feature's purpose or a link to more details about its use. (Note: Features marked "[TBD]" are to be defined later.)

The following should be a table but formatting in tables is not yet rendered properly.

14.1 Collation

Is available in release 2017.02. To use:

use experimental :collation;

Allows the use of the unicmp and coll operators. Also allows the use of the collate method. unicmp and coll are like cmp, except it implements the Unicode Collation Algorithm.

coll and the collate method are affected by the $*COLLATION variable, while unicmp is not. Unlike the cmp operator which sorts according to codepoint, unicmp and coll sort according to how most users would expect.

use experimental :collation;
say 'a' unicmp 'Z'; # Less
say 'a' cmp 'Z'; # More

coll and the collate method are both configurable by setting the $*COLLATION variable.

14.1.1 collate (method)

You can use the collate method similar to how one would use the sort method.

use experimental :collation;
say ('a', 'Z').sort; # (Z a)
say ('a', 'Z').collate; # (a Z)
say <ä a o ö>.collate; # (a ä o ö)
my %hash = 'aa' => 'value', 'Za' => 'second';
say %hash.collate; # (aa => value Za => second);

14.1.2 Collation Levels

There are four collation levels which are all configurable.

While the Primary, Secondary and Tertiary mean different things for different scripts, for the Latin script used in English they mostly correspond with Primary being Alphabetic, Secondary being Diacritics and Tertiary being Case.

In the below example you can see how when we disable tertiary collation which in Latin script generally is for case, and also disable quaternary which breaks any ties by checking the codepoint values of the strings, we get Same back for A and a:

use experimental :collation;
$*COLLATION.set(:quaternary(False), :tertiary(False));
say 'a' coll 'A'; # Same

Note the collation features, especially the $*COLLATION API could change at any time

15 FAQ

Frequently Asked Questions about Perl 6

15.1 General

15.1.1 What's the difference between Rakudo and Perl 6?

Properly speaking, Rakudo is an implementation of Perl 6. It's currently the most developed, but there have been other implementations in the past and there will likely be others in the future. Perl 6 is the definition of the language. Often, Rakudo and Perl 6 will be used interchangeably.

15.1.2 Is there a Perl 6 version 6.0.0?

No. The first stable language specification version is v6.c ("Christmas"). Future versions of the spec may have point releases (e.g. v6.c.2) or major releases (e.g., v6.d).

You can check if your Rakudo compiler is at least the current release version (note this may not be true of vendor binaries) with the following:

perl6 -e 'say q[too old] if $*PERL.version before Version.new(q[6.c])' 

It was first implemented by the Rakudo Perl 6 compiler version 2015.12 and is likely to be supported by subsequent releases by use of the 'use 6.c' pragma.

15.1.3 When is v6.d likely to be released?

Not for some time since a lot of work is needed.

15.1.4 As a Perl 6 beginner, what should I install?

Mac users can use the latest Rakudo Star DMG binary installer at http://rakudo.org/downloads/star

Windows users can use the Rakudo Star MSI binary installer. You will need Windows Git and Strawberry Perl 5 to use zef to install library modules.

Linux users probably want to download Rakudo Star and follow the compilation instructions at http://www.perl6.org/downloads/.

There should be Linux and Mac binaries available from vendors and third parties, although vendor versions may be outdated.

There's an official Rakudo Star docker image at https://hub.docker.com/_/rakudo-star/

15.1.5 As an intermediate to advanced user I want to track Rakudo development.

Install rakudobrew which resembles Perl 5's perlbrew and the equivalent Python and Ruby tools.

15.1.6 Where can I find good documentation on Perl 6?

The most reliable information is to be found either under the perl6.org domains or directly linked from it.

https://perl6.org/resources/ with https://docs.perl6.org/ as the canonical technical reference.

There's much good recent material online but be careful to check, if available, the dates on web pages since a lot of Perl 6 information online is often outdated.

If something was left unanswered by the materials linked above, feel free to join #perl6 channel on Freenode to ask your question. You could also try searching the channel log for similar questions via Google.

15.1.7 What is the Perl 6 specification?

The specification refers to the official test suite for Perl 6. It's called roast and is hosted on github. Any compiler that passes the tests is deemed to implement that version of the Perl 6 specification.

Roast's master branch corresponds to the latest development that isn't necessarily part of any specification yet. Other branches correspond to specific versions; for example, "6c.errata".

Yes, see glossary.

15.1.9 I'm a Perl 5 programmer. Where is a list of differences between Perl 5 and Perl 6?

See the '5to6-nutshell' pod under https://docs.perl6.org/language/5to6-nutshell and related pages.

15.1.10 I'm a Ruby programmer looking for quickstart type docs?

See the 'rb-nutshell' pod under https://docs.perl6.org/language/rb-nutshell

15.2 Modules

15.2.1 Is there a CPAN for Perl 6?

There isn't yet a module repository for Perl 6 as sophisticated as CPAN. Nonetheless, modules.perl6.org has a list of known Perl 6 modules called the "ecosystem" hosted on github, and zef can install those that work with rakudo.

Support for installing Perl 6 modules from the Perl 5 CPAN is on the way.

15.2.2 Can I use Perl 5 modules from Perl 6?

Yes, with Inline::Perl5, which works well with most Perl 5 modules. It can even run Perl 5 Catalyst and DBI.

15.2.3 Can I use C and C++ from Perl 6?

Nativecall makes this particularly easy.

15.2.4 Nativecall can't find libfoo.so and I only have libfoo.so.1.2!

This is commonly seen on Debian-like systems. You need to install "libfoo-dev" to set a sym link for the missing file.

15.2.5 Where have all the traditional UNIX library functions gone?

It's very easy to use Nativecall to access them.

An ecosystem module POSIX is also available.

15.2.6 Does Rakudo have a core standard library?

Rakudo is a compiler release with minimal batteries included (Test and Nativecall etc.), rather like the linux kernel itself.

Rakudo Star is a distribution of rakudo that ships with some useful modules and many more can be installed from the ecosystem.

15.2.7 Is there something like B::Deparse/How can I get hold of the AST?

Use perl6 --target=ast -e 'very-short-example()' to get hold of the AST of a compilation unit.

15.3 Language Features

15.3.1 How can I dump Perl 6 data structures (like Perl 5 Data::Dumper and similar)?

Examples:

my $foo="bar";
dd $foo;          # OUTPUT: «Str $foo = "bar"␤»
say :$foo.perl;   # OUTPUT: «:foo("bar")␤»
say :$foo.gist;   # OUTPUT: «foo => bar␤»

There are also modules in the ecosystem to do this, like Data::Dump, which colors the output.

15.3.2 How can I get command line history in the Perl 6 prompt (REPL)?

Install Linenoise from the ecosystem.

An alternative for UNIX-like systems is to install rlwrap. This can be done on Debian-ish systems with "apt-get install rlwrap".

15.3.3 Why is the Rakudo compiler so apologetic?

If SORRY! is present in the output the error is a compile time error otherwise it's runtime.

Example:

say 1/0;   # Attempt to divide 1 by zero using div 
 
 sub foo( Int $a, Int $b ) {...} 
 foo(1)     # ===SORRY!=== Error while compiling ... 

15.3.4 What is (Any)?

Any is a top level class used as a default superclass for new classes. It's often seen in a context where a variable has been defined but not assigned where it loosely resembles the undef or null values in other languages.

Example:

my $foo;
say $foo;         # OUTPUT: «(Any)␤» - note the parentheses indicate type object
say $foo.^name;   # OUTPUT: «Any␤»

(Any) shouldn't be used to check for definedness. In Perl 6, definedness is a property of an object. Usually, instances are defined and type objects are undefined.

say 1.defined;       # OUTPUT: «True␤»
say (Any).defined;   # OUTPUT: «False␤»

15.3.5 What is so?

so is a loose precedence operator that coerces to Bool.

It has the same semantics as the ? prefix operator, just like and is the low-precedence version of &&.

Example usage:

say so 1|2 == 2;    # OUTPUT: «True␤»

In this example, the result of the comparison (which is a Junction), is converted to Bool before being printed.

15.3.6 What are those :D and :U things in signatures?

In Perl 6, classes and other types are objects and pass type checks of their own type.

For example, if you declare a variable

my Int $x = 42;

then not only can you assign integers (that is, instances of class Int) to it, but the Int type object itself:

$x = Int 

If you want to exclude type objects, you can append the :D type smiley, which stands for "definite":

my Int:D $x = 42; 
 $x = Int;            # dies with: 
                      # Type check failed in assignment to $x; 
                      # expected Int:D but got Int 

Likewise, :U constrains to undefined values, that is, type objects.

To explicitly allow either type objects or instances, you can use :_.

15.3.7 What is the --> thing in the signature?

--> is a return constraint, either a type or a definite value.

Example of a type constraint:

sub divide-to-int( Int $a, Int $b --> Int ) { 
         return ($a / $b).narrow; 
 } 
 
 divide-to-int(3, 2) 
 # Type check failed for return value; expected Int but got Rat 

Example of a definite return value:

sub discard-random-number( --> 42 ) { rand }
say discard-random-number;
# OUTPUT: «42␤»

In this case, the final value is thrown away because the return value is already specified.

15.3.8 How can I extract the values from a Junction?

If you want to extract the values (eigenstates) from a Junction, you are probably doing something wrong and should be using a Set instead.

Junctions are meant as matchers, not for doing algebra with them.

If you want to do it anyway, you can abuse autothreading for that:

sub eigenstates(Mu $j) {
    my @states;
    -> Any $s { @states.push: $s }.($j);
    @states;
}

say eigenstates(1|2|3).join(', ');
# prints 1, 2, 3 or a permutation thereof

15.3.9 If Str is immutable, how does s/// work? if Int is immutable, how does $i++ work?

In Perl 6, values of many basic types are immutable, but the variables holding them are not. The s/// operator works on a variable, into which it puts a newly created string object. Likewise, $i++ works on the $i variable, not just on the value in it.

See the documentation on containers for more information.

15.3.10 What's up with array references and automatic dereferencing? Do I still need the @ sigil?

In Perl 6, nearly everything is a reference, so talking about taking references doesn't make much sense. Unlike Perl 5, scalar variables can also contain arrays directly:

my @a = 1, 2, 3;
say @a;                 # OUTPUT: «[1 2 3]␤»
say @a.WHAT;            # OUTPUT: «(Array)␤»

my $scalar = @a;
say $scalar;            # OUTPUT: «[1 2 3]␤»
say $scalar.WHAT;       # OUTPUT: «(Array)␤»

The big difference is that arrays inside a scalar act as one value in list context, whereas arrays will be happily iterated over.

my @a = 1, 2, 3; 
 my $s = @a; 
 
 for @a { ... }          # loop body executed 3 times 
 for $s { ... }          # loop body executed only once 
 
 my @flat = flat @a, @a; 
 say @flat.elems;            # OUTPUT: «6␤» 
 
 my @nested = flat $s, $s; 
 say @nested.elems;          # OUTPUT: «2␤» 

You can force flattening with @( ... ) or by calling the .list method on an expression, and item context (not flattening) with $( ... ) or by calling the .item method on an expression.

15.3.11 Why sigils? Couldn't you do without them?

There are several reasons:

15.3.12 "Type Str does not support associative indexing."

You likely tried to mix string interpolation and HTML.

my $foo = "abc"; 
 say "$foo<html-tag>"; 

Perl 6 thinks $foo to be a Hash and <html-tag> to be a string literal hash key. Use a closure to help it to understand you.

my $foo = "abc";
say "{$foo}<html-tag>";

15.3.13 Does Perl 6 have coroutines? What about yield?

Perl 6 has no yield statement like Python does, but it does offer similar functionality through lazy lists. There are two popular ways to write routines that return lazy lists:

# first method, gather/take 
 my @values = gather while have_data() { 
     # do some computations 
     take some_data(); 
     # do more computations 
 } 
 
 # second method, use .map or similar method 
 # on a lazy list 
 my @squares = (1..*).map(-> \x { x² }); 

15.3.14 Why can't I initialize private attributes from the new method, and how can I fix this?

Code like

class A {
    has $!x;
    method show-x {
        say $!x;
    }
}
A.new(x => 5).show-x;

does not print 5. Private attributes are private, which means invisible to the outside. If the default constructor could initialize them, they would leak into the public API.

If you still want it to work, you can add a submethod BUILD that initializes them:

class B {
    has $!x;
    submethod BUILD(:$!x) { }
    method show-x {
        say $!x;
    }
}
B.new(x => 5).show-x;

BUILD is called by the default constructor (indirectly, see Object Construction for more details) with all the named arguments that the user passes to the constructor. :$!x is a named parameter with name x, and when called with a named argument of name x, its value is bound to the attribute $!x.

But don't do that. If the name is public, there is no downside to declaring it that way with $.x since the external view is readonly by default, and you can still access it internally with $!x.

15.3.15 How and why do say, put and print differ?

The most obvious difference is that say and put append a newline at the end of the output, and print does not.

But there's another difference: print and put converts its arguments to a string by calling the Str method on each item passed to, say uses the gist method instead. The former is meant for computers, the latter for human interpretation.

Or phrased differently, $obj.Str gives a string representation, $obj.gist a short summary of that object suitable for fast recognition by the programmer, and $obj.perl gives a Perlish representation.

Example: type objects, also known as "undefined values", stringify to an empty string and warn, whereas the gist method returns the name of the type, followed by an empty pair of parenthesis (to indicate there's nothing in that value except the type).

my Date $x;     # $x now contains the Date type object
print $x;       # empty string plus warning
say $x;         # OUTPUT: «(Date)␤»

So, say is optimized for debugging; display is optimized for people; and print and put are most suitable for producing output for other programs to consume.

put is thus sort of a hybrid between print and say; like print, its output is suitable for other programs, and like say, it adds a newline at the end of the output.

15.3.16 What's the difference between token and rule ?

regex, token and rule introduce regexes, but with slightly different semantics.

token implies the :ratchet or :r modifier, which prevents the rule from backtracking.

rule implies both the :ratchet and :sigspace (short :s) modifier, which means a rule doesn't backtrace, and it treats whitespace in the text of the regex as <.ws> calls (i.e., matches whitespace, which is optional except between two word characters). Whitespace at the start of the regex and at the start of each branch of an alternation is ignored.

regex declares a plain regex without any implied modifiers.

15.3.17 What's the difference between die and fail?

die throws an exception.

fail returns a Failure object. (If the caller has declared use fatal; in the calling lexical scope, fail throws an exception instead of returning.)

A Failure is an "unthrown" or "lazy" exception. It's an object that contains the exception, and throws the exception if you try to use the Failure as an ordinary object, or ignore it in sink context.

A Failure returns False from a defined check, and you can extract the exception with the exception method.

15.3.18 Why is wantarray or want gone? Can I return different things in different contexts?

Perl 5 has the wantarray function that tells you whether it's called in void, scalar or list context. Perl 6 has no equivalent construct because context does not flow inwards; i.e., a routine would need time travel to know which context it's called in because context is lazy (known only when the results are used later).

For example, Perl 6 has multiple dispatch. So, in a code example like

multi w(Int $x) { say 'Int' } 
 multi w(Str $x) { say 'Str' } 
 w(f()); 

there's no way to determine if the caller of sub f wants a string or an integer, because it's not yet known what the caller is. In general this requires solving the halting problem, which even Perl 6 compiler writers have trouble with.

One way to achieve context sensitivity in Perl 6 is to return an object that knows how to respond to method calls that are typical for a context. In Perl 6, this is actually a lot easier than it may sound, and other features of the language either mitigate the need to do so in the first place or make it possible to cover most of the use cases of wantarray.

For example, regex matches return Match objects that know how to respond to list indexing, hash indexing, and that can turn into the matched string.

15.3.19 What's the difference between Pointer and OpaquePointer?

OpaquePointer is deprecated and has been replaced with Pointer.

15.4 Perl 6 Implementation

15.4.1 What Perl 6 Implementations are available?

Currently the best developed is Rakudo (using multiple Virtual Machine backends). Historic implementations include Niecza (.NET) and Pugs (Haskell). Others are listed at Perl 6 Compilers

15.4.2 What language is Rakudo written in?

A short answer is that Rakudo is written almost entirely in Perl 6. A more detailed answer is that Rakudo is written in a mixture of Perl 6 and NQP ("Not Quite Perl"). NQP is a lightweight Perl 6-like environment for virtual machines; it's designed to be a high-level way to create compilers and libraries for virtual machines (such as MoarVM and JVM) using Perl 6 syntax.

15.4.3 What language is NQP written in?

NQP is a mixture of (1) NQP code, (2) whatever language the underlying virtual machine is using, (3) some third-party C and Java libraries, and (4) some bootstrapping files created by earlier runs of the build process.

15.4.4 Is Perl 6 Lisp?

(not (not Nil))

15.5 Meta Questions and Advocacy

15.5.1 Why is Perl 6 called Perl?

… As opposed to some other name that didn't imply all the things that the higher number might indicate on other languages.

The short answer is that it was Larry's choice under Rule 1.

The community considers Perl 5 and Perl 6 sister languages - they have a lot in common, address many of the same problem spaces, but Perl 6 is not intended to replace Perl 5. In fact, both languages interoperate with each other.

15.5.2 When will Perl 6 be ready? Is it ready now?

Readiness of programming languages and their compilers is not a binary decision. As the language and the implementations evolve, they grow steadily more usable. Depending on your needs, Perl 6 and its compilers may or may not be ready for you.

That said, version 6.c (Christmas 2015) is the first official release of Perl 6 as a language, along with a validation suite and a compiler that passes it.

15.5.3 Why should I learn Perl 6? What's so great about it?

Perl 6 unifies many great ideas that aren't usually found in other programming languages. While several other languages offer some of these features, none of them offer all.

Please see the feature comparison matrix for an overview of implemented features.

15.5.4 Is Perl 6 fast enough for me?

That depends on what you are doing. Rakudo has been developed with the philosophy of "make it work right then make it work fast". It's fast for some things already but needs work for others. Since Perl 6 provides lots of clues to the JIT that other dynamic languages don't, we think we'll have a lot of headroom for performance improvements. Some things already run faster than Perl 5.

Perl 5 programmers should be aware that Perl 6 comes with more built-in functionality. Simple benchmarks will be misleading unless you include things like Moose, type checking modules etc. in your Perl 5 script.

The following crude benchmarks, with all the usual caveats about such things, show that Perl 6 can be faster than Perl 5 for similar tasks if the big weaponry is included; at the same time, Perl 5 can be faster if only the bare bones are included.

Try it on your system. You may be pleasantly surprised!

Examples:

# Perl 6 version 
 use v6.c; 
 
 class Foo { has $.i is rw }; 
 
 for 1..1_000_000 -> $i { 
     my $obj = Foo.new; 
     $obj.i = $i; 
 } 
 
 # Perl 5 version 
 package Foo; 
 use Moose; 
 
 has i => (is => 'rw'); 
 
 __PACKAGE__->meta->make_immutable; 
 
 for my $i (1..1_000_000) { 
     my $obj = Foo->new; 
     $obj->i($i); 
 } 
 
 1; 
 
 # Another Perl 5 version that offers bare-bones set of features 
 # compared to Moose/Perl 6's version but those are not needed in this 
 # specific, simple program anyway. 
 package Foo; 
 use Mojo::Base -base; 
 
 has 'i'; 
 
 for my $i (1..1_000_000) { 
     my $obj = Foo->new; 
     $obj->i($i); 
 } 
 
 1; 
 
 # A perl program which works under both perl5 (with perl -Mbigint) 
 # and perl6 
 
 my ($prev, $current) = (1, 0); 
 
 for (0..100_000) { 
     ($prev, $current) = ($current, $prev + $current); 
 } 
 print $current; 

16 Functions

Functions and Functional Programming in Perl 6

Routines are the smallest means of code reuse in Perl 6. They come in several forms, most notably methods, which belong in classes and roles and are associated with an object, and functions, also called subroutines or short subs, which can be called independently of objects.

Subroutines default to lexical (my) scoping, and calls to them are generally resolved at compile time.

Subroutines can have a signature, also called parameter list, which specifies which, if any, arguments the signature expects. It can specify (or leave open) both the number and types of arguments, and also the return value.

Introspection on subroutines is provided via Routine .

16.1 Defining/Creating/Using Functions

16.1.1 Subroutines

To create a function, often all that's needed is to define a subroutine using the sub declarator:

sub my-func { say "Look ma, no args!" }
my-func;

To have the subroutine take arguments, a signature goes between the subroutine's name and its body, in parentheses:

sub exclaim  ($phrase)  { 
     say $phrase  ~  "!!!!" 
 } 
 exclaim "Howdy, World"; 

By default, subroutines are lexically scoped. That is sub foo {...} is the same as my sub foo {...} and is only defined within the current scope.

sub escape($str) { 
     # Puts a slash before non-alphanumeric characters 
     S:g[<-alpha -digit>] = "\\$/" given $str 
 } 
 
 say escape 'foo#bar?'; # foo\#bar\? 
 
 { 
     sub escape($str) { 
         # Writes each non-alphanumeric character in its hexadecimal escape 
         S:g[<-alpha -digit>] = "\\x[{ $/.ord.base(16) }]" given $str 
     } 
 
     say escape 'foo#bar?' # foo\x[23]bar\x[3F] 
 } 
 
 # Back to original escape function 
 say escape 'foo#bar?'; # foo\#bar\? 

Subroutines don't have to be named; in this case they're called anonymous.

say sub ($a, $b) { $a ** 2 + $b ** 2 }(3, 4) # OUTPUT: «25␤»

But in this case, it's often desirable to use the more succinct block syntax. Subroutines and blocks can be called in place, as in the example above.

16.1.2 Blocks and Lambdas

Whenever you see something like { $_ + 42 }, -> $a, $b { $a ** $b }, or { $^text.indent($:spaces) }, that's Block syntax. It's used after every if, for, while, etc.

for 1, 2, 3, 4 -> $a, $b {
    say $a ~ $b;
}
# OUTPUT: «12␤34␤»

They can also be used on their own as anonymous blocks of code.

say { $^a ** 2 + $^b ** 2}(3, 4) # OUTPUT: «25␤»

For details about the syntax of blocks, see the documentation for the Block type.

16.1.3 Signatures

The parameters that a function accepts are described in its signature.

sub format (Str $s)  { ... } 
 ->  $a, $b  { ... } 

Details about the syntax and use of signatures can be found in the documentation on the Signature class.

16.1.3.1 Automatic Signatures

If no signature is provided but either of the two automatic variables @_ or %_ are used in the function body, a signature with *@_ or *%_ will be generated. Both automatic variables can be used that the same time.

sub s { dd @_, %_ };
dd &s.signature # OUTPUT: «:(*@_, *%_)␤»

16.1.4 Arguments

Arguments are supplied as a comma separated list. To disambiguate nested calls, use parentheses:

sub f(&c){ c() * 2 }; # call the function reference c with empty parameter list
sub g($p){ $p - 2 };
say(g(42), 45);       # pass only 42 to g()

When calling a function, positional arguments should be supplied in the same order as the function's signature. Named arguments may be supplied in any order, but it is considered good form to place named arguments after positional arguments. Inside the argument list of a function call, some special syntax is supported:

sub f(|c){};
f :named(35);     # A named argument (in "adverb" form.)
f named => 35;    # Also a named argument.
f :35named;       # A named argument using abbreviated adverb form
f 'named' => 35;  # Not a named argument, a Pair in a positional argument
my \c = <a b c>.Capture;
f |c;             # Merge the contents of Capture $c as if they were supplied

Arguments passed to a function are conceptually first collected in a Capture container. Details about the syntax and use of these containers can be found in the documentation on the Capture class.

When using named arguments, note that normal List "pair-chaining" allows one to skip commas between named arguments.

sub f(|c){};
f :dest</tmp/foo> :src</tmp/bar> :lines(512);
f :32x :50y :110z;   # This flavor of "adverb" works, too
f :a:b:c;            # The spaces are also optional.

16.1.5 Return values

Any Block or Routine will provide its last expression as a return value to the caller. If return or return-rw are called their parameter, if any, will become the return value. The default return value is Nil.

sub a { 42 };
sub b { say a };
b;
# OUTPUT: «42␤»

Multiple return values are returned as a list or by creating a Capture. Destructuring can be used to untangle multiple return values.

sub a { 42, 'answer' };
put a.perl;
# OUTPUT: «(42, "answer")␤»

my ($n, $s) = a;
put [$s, $n];
# OUTPUT: «answer 42␤»

sub b { <a b c>.Capture };
put b.perl;
# OUTPUT: «\("a", "b", "c")␤»

16.1.6 Return Type Constraints

Perl 6 has many ways to specify a function's return type:

sub foo(--> Int)      {}; say &foo.returns; # OUTPUT: «(Int)␤» 
 sub foo() returns Int {}; say &foo.returns; # OUTPUT: «(Int)␤» 
 sub foo() of Int      {}; say &foo.returns; # OUTPUT: «(Int)␤» 
 my Int sub foo()      {}; say &foo.returns; # OUTPUT: «(Int)␤» 

Attempting to return values of another type will cause a compilation error.

sub foo() returns Int { "a"; }; foo; # Type check fails 

Note that Nil and Failure are exempt from return type constraints and can be returned from any routine, regardless of its constraint:

sub foo() returns Int { fail   }; foo; # Failure returned 
 sub bar() returns Int { return }; bar; # Nil returned 

16.1.7 Multi-dispatch

Perl 6 allows you to write several routines with the same name, but different signatures. When the routine is called by name, the runtime environment decides which is the best match, and calls that candidate. You declare each candidate with the multi declarator.

multi congratulate($name) {
    say "Happy birthday, $name";
}
multi congratulate($name, $age) {
    say "Happy {$age}th birthday, $name";
}

congratulate 'Larry';       # OUTPUT: «Happy birthday, Larry␤»
congratulate 'Bob', 45;     # OUTPUT: «Happy 45th birthday, Bob␤»

Dispatch can happen on the number of arguments (the arity), but also on the type:

multi as-json(Bool $d) { $d ?? 'true' !! 'false'; }
multi as-json(Real $d) { ~$d }
multi as-json(@d)      { sprintf '[%s]', @d.map(&as-json).join(', ') }

say as-json([True, 42]);    # OUTPUT: «[true, 42]␤»

Named parameters participate in the dispatch even if they are not provided in the call. Therefore a multi candidate with named will be given precedence.

multi without any specific routine type always defaults to a sub, but you can use it on methods as well. The candidates are all the multi methods of the object:

class Congrats {
    multi method congratulate($reason, $name) {
        say "Hooray for your $reason, $name";
    }
}

role BirthdayCongrats {
    multi method congratulate('birthday', $name) {
        say "Happy birthday, $name";
    }
    multi method congratulate('birthday', $name, $age) {
        say "Happy {$age}th birthday, $name";
    }
}

my $congrats = Congrats.new does BirthdayCongrats;

$congrats.congratulate('promotion','Cindy'); # OUTPUT: «Hooray for your promotion, Cindy␤»
$congrats.congratulate('birthday','Bob');    # OUTPUT: «Happy birthday, Bob␤»

16.1.7.1 proto

proto is a way to formally declare commonalities between multi candidates. It acts as a wrapper that can validate but not modify arguments. Consider this basic example:

proto congratulate(Str $reason, Str $name, |) {*}
multi congratulate($reason, $name) {
   say "Hooray for your $reason, $name";
}
multi congratulate($reason, $name, Int $rank) {
   say "Hooray for your $reason, $name -- got rank $rank!";
}
congratulate('being a cool number', 'Fred');     # OK 
 congratulate('being a cool number', 'Fred', 42); # OK 
 congratulate('being a cool number', 42);         # Proto match error 

All multi congratulate will conform to the basic signature of two strings, optionally followed by further parameters. The | is an un-named Capture parameter, allowing a multi which takes additional arguments. The third call fails at compile time because the proto's signature becomes the common signature of all three, and 42 doesn't match Str.

say &congratulate.signature # OUTPUT: «(Str $reason, Str $name, | is raw)␤» 

You can give the proto a function body, and place the {*} where you want the dispatch to be done.

# attempts to notify someone -- False if unsuccessful
proto notify(Str $user,Str $msg) {
   my \hour = DateTime.now.hour;
   if hour > 8 or hour < 22 {
      return {*};
   } else {
      # we can't notify someone when they might be sleeping
      return False;
   }
}

{*} always dispatches to candidates with the parameters it's called with. Parameter defaults and type coercions will work but are not be passed on.

proto mistake-proto(Str() $str, Int $number = 42) {*} 
 multi mistake-proto($str, $number) { say $str.WHAT } 
 mistake-proto(7, 42);  # OUTPUT: «(Int)␤» -- not passed on 
 mistake-proto('test'); # fails -- not passed on 
only

16.2 Conventions and Idioms

While the dispatch system described above provides a lot of flexibility, there are some conventions that most internal functions, and those in many modules, will follow. These produce a consistent look and feel.

16.2.1 Slurpy Conventions

Perhaps the most important of these is the way slurpy list arguments are handled. Most of the time, functions will not automatically flatten slurpy lists. The rare exceptions are those functions that don't have a reasonable behavior on lists of lists, for example, chrs, or where there is a conflict with an established idiom, like pop being the inverse of push.

If you wish to match this look and feel, any Iterable argument must be broken out element-by-element using a **@ slurpy, with two nuances:

This can be achieved by using a slurpy with a + or +@ instead of **:

sub grab(+@a) { "grab $_".say for @a }

...which is shorthand for something very close to:

multi sub grab(**@a) { "grab $_".say for @a }
multi sub grab(\a) {
    a ~~ Iterable and a.VAR !~~ Scalar ?? nextwith(|a) !! nextwith(a,)
}

This results in the following behavior, which is known as the "single argument rule" and is important to understand when invoking slurpy functions:

grab(1, 2);      # OUTPUT: «grab 1␤grab 2␤» 
 grab((1, 2));    # OUTPUT: «grab 1␤grab 2␤» 
 grab($(1, 2));   # OUTPUT: «grab 1 2␤» 
 grab((1, 2), 3); # OUTPUT: «grab 1 2␤grab 3␤» 

This also makes user-requested flattening feel consistent whether there is one sublist, or many:

grab(flat (1, 2), (3, 4));   # OUTPUT: «grab 1␤grab 2␤grab 3␤grab 4␤» 
 grab(flat $(1, 2), $(3, 4)); # OUTPUT: «grab 1 2␤grab 3 4␤» 
 grab(flat (1, 2));           # OUTPUT: «grab 1␤grab 2␤» 
 grab(flat $(1, 2));          # OUTPUT: «grab 1 2␤» 

It is worth noting that mixing binding and sigilless variables in these cases requires a bit of finesse, because there is no Scalar intermediary used during binding.

my $a = (1, 2);  # Normal assignment, equivalent to $(1, 2) 
 grab($a);        # OUTPUT: «grab 1 2␤» 
 my $b := (1, 2); # Binding, $b links directly to a bare (1, 2) 
 grab($b);        # OUTPUT: «grab 1␤grab 2␤» 
 my \c = (1, 2);  # Sigilless variables always bind, even with '=' 
 grab(c);         # OUTPUT: «grab 1␤grab 2␤» 

16.3 Functions are First-Class Objects

Functions and other code objects can be passed around as values, just like any other object.

There are several ways to get hold of a code object. You can assign it to a variable at the point of declaration:

my $square = sub (Numeric $x) { $x * $x }
# and then use it:
say $square(6);    # OUTPUT: «36␤»

Or you can reference an existing named function by using the &-sigil in front of it.

sub square($x) { $x * $x };

# get hold of a reference to the function:
my $func = &square

This is very useful for higher order functions, that is, functions that take other functions as input. A simple one is map, which applies a function to each input element:

sub square($x) { $x * $x };
my @squared = map &square,  1..5;
say join ', ', @squared;        # OUTPUT: «1, 4, 9, 16, 25␤»

16.3.1 Infix Form

To call a subroutine with 2 arguments like a infix operator, use a subroutine reference surrounded by [ and ].

sub plus { $^a + $^b };
say 21 [&plus] 21;
# OUTPUT: «42␤»

16.3.2 Closures

All code objects in Perl 6 are closures, which means they can reference lexical variables from an outer scope.

sub generate-sub($x) {
    my $y = 2 * $x;
    return sub { say $y };
    #      ^^^^^^^^^^^^^^  inner sub, uses $y
}
my $generated = generate-sub(21);
$generated(); # OUTPUT: «42␤»

Here $y is a lexical variable inside generate-sub, and the inner subroutine that is returned uses it. By the time that the inner sub is called, generate-sub has already exited. Yet the inner sub can still use $y, because it closed over the variable.

A less obvious but useful example for closures is using map to multiply a list of numbers:

my $multiply-by = 5;
say join ', ', map { $_ * $multiply-by }, 1..5;     # OUTPUT: «5, 10, 15, 20, 25␤»

Here the block passed to map references the variable $multiply-by from the outer scope, making the block a closure.

Languages without closures cannot easily provide higher-order functions that are as easy to use and powerful as map.

16.3.3 Routines

Routines are code objects that conform to type Routine, most notably Sub, Method, Regex and Submethod.

They carry additional functionality in addition to what Block supplies: they can come as multis, you can wrap them, and exit early with return:

my $keywords = set <if for unless while>;

sub has-keyword(*@words) {
    for @words -> $word {
        return True if $word (elem) $keywords;
    }
    False;
}

say has-keyword 'not', 'one', 'here';       # OUTPUT: «False␤»
say has-keyword 'but', 'here', 'for';       # OUTPUT: «True␤»

Here return does not just leave the block inside which it was called, but the whole routine. In general, blocks are transparent to return, they attach to the outer routine.

Routines can be inlined and as such provide an obstacle for wrapping. Use the pragma use soft; to prevent inlining to allow wrapping at runtime.

sub testee(Int $i, Str $s){
    rand.Rat * $i ~ $s;
}

sub wrap-to-debug(&c){
    say "wrapping {&c.name} with arguments {&c.signature.perl}";
    &c.wrap: sub (|args){
        note "calling {&c.name} with {args.gist}";
        my \ret-val := callwith(|args);
        note "returned from {&c.name} with return value {ret-val.perl}";
        ret-val
    }
}

my $testee-handler = wrap-to-debug(&testee);
# OUTPUT: «wrapping testee with arguments :(Int $i, Str $s)»

say testee(10, "ten");
# OUTPUT: «calling testee with \(10, "ten")␤returned from testee with return value "6.151190ten"␤6.151190ten»
&testee.unwrap($testee-handler);
say testee(10, "ten");
# OUTPUT: «6.151190ten␤»
Important ones: candidates, wrap, unwrap, assuming, arity, count

16.4 Defining Operators

Operators are just subroutines with funny names. The funny names are composed of the category name (infix, prefix, postfix, circumfix, postcircumfix), followed by a colon, and a list of the operator name or names (two components in the case of circumfix and postcircumfix).

This works both for adding multi candidates to existing operators, and for defining new ones. In the latter case, the definition of the new subroutine automatically installs the new operator into the grammar, but only in the current lexical scope. Importing an operator via use or import also makes it available.

# adding a multi candidate to an existing operator: 
 multi infix:<+>(Int $x, "same") { 2 * $x }; 
 say 21 + "same";            # OUTPUT: «42␤» 
 
 # defining a new operator 
 sub postfix:<!>(Int $x where { $x >= 0 }) { [*] 1..$x }; 
 say 6!;                     # OUTPUT: «720␤» 

The operator declaration becomes available as soon as possible, so you can even recurse into a just-defined operator, if you really want to:

sub postfix:<!>(Int $x where { $x >= 0 }) { 
     $x == 0 ?? 1 !! $x * ($x - 1)! 
 } 
 say 6!;                     # OUTPUT: «720␤» 

Circumfix and postcircumfix operators are made of two delimiters, one opening and one closing.

sub circumfix:<START END>(*@elems) { 
     "start", @elems, "end" 
 } 
 
 say START 'a', 'b', 'c' END;        # OUTPUT: «start a b c end␤» 

Postcircumfixes also receive the term after which they are parsed as an argument:

sub postcircumfix:<!! !!>($left, $inside) { 
     "$left -> ( $inside )" 
 } 
 say 42!! 1 !!;      # OUTPUT: «42 -> ( 1 )␤» 

Blocks can be assigned directly to operator names. Use a variable declarator and prefix the operator name with a &-sigil.

my &infix:<ieq> = -> |l { [eq] l>>.fc };
say "abc" ieq "Abc";
# OUTPUT: «True␤»

16.4.1 Precedence

Operator precedence in Perl 6 is specified relatively to existing operators. The traits is tighter, is equiv and is looser can be provided with an operator, the new operators precedence is related to. More then one trait can be applied.

For example infix:<*> has a tighter precedence than infix:<+>, and squeezing one in between works like this:

sub infix:<!!>($a, $b) is tighter(&infix:<+>) { 
     2 * ($a + $b) 
 } 
 
 say 1 + 2 * 3 !! 4;     # OUTPUT: «21␤» 

Here the 1 + 2 * 3 !! 4 is parsed as 1 + ((2 * 3) !! 4), because the precedence of the new !! operator is between that of + and *.

The same effect could have been achieved with

sub infix:<!!>($a, $b) is looser(&infix:<*>) { ... }

To put a new operator on the same precedence level as an existing operator, use is equiv(&other-operator) instead.

16.4.2 Associativity

When the same operator appears several times in a row, there are multiple possible interpretations. For example

1 + 2 + 3

could be parsed as

(1 + 2) + 3         # left associative

or as

1 + (2 + 3)         # right associative

For addition of real numbers, the distinction is somewhat moot, because + is mathematically associative.

But for other operators it matters a great deal. For example for the exponentiation/power operator, infix:<**> :

say 2 ** (2 ** 3);      # OUTPUT: «256␤»
say (2 ** 2) ** 3;      # OUTPUT: «64␤»

Perl 6 has the following possible associativity configurations:

A Assoc Meaning of $a ! $b ! $c
L left ($a ! $b) ! $c
R right $a ! ($b ! $c)
N non ILLEGAL
C chain ($a ! $b) and ($b ! $c)
X list infix:<!>($a; $b; $c)

You can specify the associativity of an operator with the is assoc trait, where left is the default associativity.

sub infix:<§>(*@a) is assoc<list> { 
     '(' ~ @a.join('|') ~ ')'; 
 } 
 
 say 1 § 2 § 3;      # OUTPUT: «(1|2|3)␤» 

16.5 Traits

Traits are subroutines that are run at compile time to modify the behavior of a type, variable, routine, attribute, or other language object.

Examples of traits are:

class ChildClass is ParentClass { ... } 
 #                ^^ trait, with argument ParentClass 
 has $.attrib is rw; 
 #            ^^^^^  trait with name 'rw' 
 class SomeClass does AnotherRole { ... } 
 #               ^^^^ trait 
 has $!another-attribute handles <close>; 
 #                       ^^^^^^^ trait 

... and also is tighter, is looser, is equiv and is assoc from the previous section.

Traits are subs of the form trait_mod<VERB> , where VERB stands for the name like is, does or handles. It receives the modified thing as argument, and the name as a named argument. See Sub for details.

multi sub trait_mod:<is>(Routine $r, :$doubles!) { 
     $r.wrap({ 
         2 * callsame; 
     }); 
 } 
 
 sub square($x) is doubles { 
     $x * $x; 
 } 
 
 say square 3;       # OUTPUT: «18␤» 

See type Routine for the documentation of built-in routine traits.

16.6 Re-dispatching

There are cases in which a routine might want to call the next method from a chain. This chain could be a list of parent classes in a class hierarchy, or it could be less specific multi candidates from a multi dispatch, or it could be the inner routine from a wrap.

In all those cases, you can use callwith to call the next routine in the chain with arguments of your own choice.

For example

multi a(Any $x) {
    say "Any $x";
    return 5;
}
multi a(Int $x) {
    say "Int $x";
    my $res = callwith($x + 1);
    say "Back in Int with $res";
}

a 1;        # OUTPUT: «Int 1␤Any 2␤Back in Int with 5␤»

Here a 1 calls the most specific Int candidate first, and callwith re-dispatches to the less specific Any candidate.

Very often, a re-dispatch passes the same argument along that the caller received, so there is a special routine for that: callsame.

multi a(Any $x) {
    say "Any $x";
    return 5;
}
multi a(Int $x) {
    say "Int $x";
    my $res = callsame;
    say "Back in Int with $res";
}

a 1;        # OUTPUT: «Int 1␤Any 1␤Back in Int with 5␤»

Another common use case is to re-dispatch to the next routine in the chain, and not do anything else afterwards. That's why we have nextwith and nextsame, which call the next routine with arbitrary arguments (nextwith) or with the same argument as the caller received (nextsame), but never return to the caller. Or to phrase it differently, the nextsame and nextwith variants replace the current callframe with the next candidate.

multi a(Any $x) { 
     say "Any $x"; 
     return 5; 
 } 
 multi a(Int $x) { 
     say "Int $x"; 
     nextsame; 
     say "back in a";    # never executed, because 'nextsame' doesn't return 
 } 
 
 a 1;        # OUTPUT: «Int 1␤Any 1␤» 

As mentioned earlier, multi subs are not the only situation in which callwith , callsame , nextwith and nextsame can be helpful. One is for dispatching to wrapped routines:

# enable wrapping: 
 use soft; 
 
 # function to be wrapped: 
 sub square-root($x) { $x.sqrt } 
 
 &square-root.wrap(sub ($num) { 
    nextsame if $num >= 0; 
    1i * callwith(abs($num)); 
 }); 
 
 say square-root(4);     # OUTPUT: «2␤» 
 say square-root(-4);    # OUTPUT: «0+2i␤» 

The final use case is to re-dispatch to methods from parent classes.

class LoggedVersion is Version { 
     method new(|c) { 
         note "New version object created with arguments " ~ c.perl; 
         nextsame; 
     } 
 } 
 
 say LoggedVersion.new('1.0.2'); 

If you need to make multiple calls to the wrapped code or to gain a reference to it, such as performing introspection it, you can use nextcallee.

sub power-it($x) { $x * $x } 
 sub run-it-again-and-again($x) { 
     my &again = nextcallee; 
     again again $x; 
 } 
 
 &power-it.wrap(&run-it-again-and-again); 
 say power-it(5);    # OUTPUT: «625␤» 

Redispatch may be required to call a block that is not the current scope what provides nextsame and friends with the problem to referring to the wrong scope. Use nextcallee to capture the right candidate and call it at the desired time.

my \IOL = Lock.new;
&say.wrap( -> |c {
    my &wrappee = nextcallee;
    IOL.protect: { &wrappee(|c) }
});
for ^100 { say "oops" }

16.7 Coercion Types

Coercion types can help you to have a specific type inside a routine, but accept wider input. When the routine is called, the argument is automatically converted to the narrower type.

sub double(Int(Cool) $x) { 
     2 * $x 
 } 
 
 say double '21';    # OUTPUT: «42␤» 
 say double Any;     # Type check failed in binding $x; expected 'Cool' but got 'Any' 

Here the Int is the target type to which the argument will be coerced, and Cool is the type that the routine accepts as input.

If the accepted input type is Any, you can abbreviate Int(Any) to Int().

The coercion works simply by looking for a method with the same name as the target type. So you can define coercions for your own types like so:

class Bar {...} 
 
 class Foo { 
    has $.msg = "I'm a foo!"; 
 
    method Bar { 
        Bar.new(:msg($.msg ~ ' But I am now Bar.')); 
    } 
 } 
 
 class Bar { 
    has $.msg; 
 } 
 
 sub print-bar(Bar() $bar) { 
    say $bar.WHAT; # OUTPUT: «(Bar)␤» 
    say $bar.msg;  # OUTPUT: «I'm a foo! But I am now Bar.␤» 
 } 
 
 print-bar Foo.new; 

Coercion types are supposed to work wherever types work, but Rakudo currently (2015.02) only implements them for subroutine parameters.

16.8 sub MAIN

The sub with the special name MAIN is executed after all relevant phasers, and its signature is the means by which command line arguments can be parsed. Multi methods are supported and a usage method is automatically generated and displayed if no command line arguments are provided. All command line arguments are also available in @*ARGS , it can be mutated before being processed by MAIN.

The return value of MAIN is ignored. To provide an exitcode other then 0, call exit.

sub MAIN( Int :$length = 24,
           :file($data) where { .IO.f // die "file not found in $*CWD" } = 'file.dat',
           Bool :$verbose )
{
    say $length if $length.defined;
    say $data   if $data.defined;
    say 'Verbosity ', ($verbose ?? 'on' !! 'off');

    exit 1;
}

16.9 sub USAGE

If no multi candidate of MAIN is found for the given command line parameters, the sub USAGE is called. If no such method is found, output a generated usage message.

sub MAIN(Int $i){ say $i == 42 ?? 'answer' !! 'dunno' }

sub USAGE(){
print Q:c:to/EOH/;
Usage: {$*PROGRAM-NAME} [number]

Prints the answer or 'dunno'.
EOH
}

17 Glossary

Glossary of Perl 6 terminology

17.1 Abstract Class

The generic Computer Science term "abstract class" defines the interface or #API of a class. In Perl 6, this is implemented using roles with stubbed methods.

role Canine {
    method bark { ... }          # the ... indicates a stub
}

class Dog does Canine {
    method bark { say "woof" }   # *MUST* be implemented by class
}

17.2 Advent Calendar

In the context of Perl 6, a yearly set of blog posts for each day from the 1st until the 25th of December, to be found at https://perl6advent.wordpress.com.

17.3 Adverb

Generically, an adverb is a named argument to a function. There are also some specific syntax forms that allow adverbs to be tucked into some convenient places:

q:w"foo bar";   # ":w" is a Quotelike form modifier adverb
m:g/a|b|c/;     # ":g" is also
TODO: Add this back in when :rotate on infix operators is supported 4 +> 5 :rotate # ":rotate" is an operator adverb @h{3}:exists; # ":exists" is also, but is known as a subscript adverb

Adverbs are usually expressed with colon pair notation, and for this reason colon pair notation is also known as the adverbial pair form:

:a(4)          # Same as "a" => 4

Some other forms that use a colon in ways that have adverb-like semantics are called adverbial forms. One special form starts with an integer value, followed by a name (for the key):

:20seconds     # same as seconds => 20

Also see #Colon Pair and Colon List.

17.4 Adverbial Pair

A generalized form of pair notation. They all start with the colon, like:

adverbial pair pair notation
:foo<bar> foo => 'bar'
:foo(42) foo => 42
:42foo foo => 42
:$foo foo => $foo
:foo foo => True
:!foo foo => False

Also see #Adverb and #Colon Pair and Colon List.

17.5 Allomorph

A type that has two related values which may be used depending on the context. For example IntStr allomorph is both an Int and a Str, so it will be accepted by anything that expects an Int, a Str, or an IntStr. Keep in mind that certain constructs, such as sets, bags, and mixes care about object identity, and so will not accept an allomorph as equivalent of its components alone.

The allomorph types IntStr, NumStr, RatStr and ComplexStr may be created as a result of parsing a quoted string:

say <42>.WHAT;     # OUTPUT: «(IntStr)␤»
say <42.1e0>.WHAT; # OUTPUT: «(NumStr)␤»
say <42.1>.WHAT;   # OUTPUT: «(RatStr)␤»

Note: angle brackets can also be used to create literals for which you'd normally need to use some operator (e.g. / for Rat or + for Complex). This allows you to use such literals in places where expressions are not allowed, for example, as literals in signatures:

    # Wrong, can't use an operator there: 
     mult foo (1/3) { say "It's one third!" } 
     # Right, a Rat literal: 
     mult foo (<1/3>) { say "It's one third!" } 

If you do want an allomorph and not a literal Numeric, then include whitespace around angle brackets:

say <42/1>.WHAT;   # OUTPUT: «(Rat)␤»
say <42+0i>.WHAT;  # OUTPUT: «(Complex)␤»
say < 42+0i >.WHAT;# OUTPUT: «(ComplexStr)␤»
say < 42/1 >.WHAT; # OUTPUT: «(RatStr)␤»

17.6 Anonymous

A subroutine, method or submethod is called anonymous if it can't be called by name.

# named subroutine
sub double($x) { 2 * $x };

# anonymous subroutine, stored in a named scalar
my $double = sub ($x) { 2 * $x };

Note that it is still allowed to have a name, but you cannot call it by that name:

# anonymous, but knows its own name 
 my $s = anon sub triple($x) { 3 * $x } 
 say $s.name;        # OUTPUT: «triple␤» 
 say triple(42);     # OUTPUT: «Undeclared routine: triple␤» 

17.7 API

Application Programming Interface. Ideally, someone using your system or library should be able to do so with knowledge only of the API, but not necessarily knowing anything about the internals or implementation.

See also #Abstract Class.

17.8 Apocalypse

A document originally written by #TimToady, in which he processed the initial barrage of RFCs that came out of the Perl community. Now only kept as an historical document for reference. See also #Exegesis and #Synopsis.

17.9 Arity

The number of positional operands expected by an operator, subroutine, method or callable block.

sub infix:<+>(Foo $a, Foo $b) { $a.Int + $b.Int }  # arity of "+" is 2 
 sub frobnicate($x) { ... }                         # arity of 1 
 sub the-answer() { 42 }                            # arity of 0 
 -> $key, $value { ... }                            # arity of 2 

The arity of a Callable is one of the main selectors in multi-dispatch.

17.10 Autothreading

Autothreading is what happens if you pass a Junction to a subroutine that expects a parameter of type Any or a subtype thereof (such as anything Cool). The call is then executed for each value of the junction. The result of these calls is assembled in a new junction of the same type as the original junction.

sub f($x) { 2 * $x };
say f(1|2|3) == 4;    # OUTPUT: «any(False, True, False)␤»

Here f() is a sub with one parameter, and since it has no explicit type, it is implicitly typed as Any. The Junction argument causes the f(1|2|3) call to be internally executed as f(1)|f(2)|f(3), and the resulting junction is 2|4|6. These are then all compared to 4, resulting in a junction False|True|False. This process of separating junction arguments into multiple calls to a function is called autothreading.

If you use the resulting junction in a boolean context, such as with an if, it collapses into a single boolean which is True if any of the values in the junction are True.

    if f(1|2|3) == 4 {    # fires because f(2) == 4 is true 
         say 'success'; 
     } 

17.11 block

17.12 bytecode

17.13 Camelia

A butterfly image intended primarily to represent Perl 6, The Language.

17.14 Colon Pair and Colon List

A colon pair is a shorthand syntax used to create or visually present a Pair object. The two most common forms are:

:a(4)          # Same as "a" => 4,   same as Pair.new("a", 4)
:a<4>          # Same as "a" => "4", same as Pair.new("a", "4")

This is also known as the adverbial pair form. Note: when the part after the colon and before the brackets is not a legal identifier, other semantics apply, not all of which produce Pair objects.

Two other common forms are:

:a             # Same as :a(True)
:!a            # Same as :a(False)

A colon list just means that a list that contains only colon pairs, does not need commas, or even spaces:

:a(4):c:!d:c   # Same as a => 4, c => True, d => False, c => True

Finally, if there is a variable with the same name as an intended adverbial pair, you don't have to specify the name twice, but just specify the adverb with the appropriate sigil:

:$foo          # same as foo => $foo 
 :@bar          # same as bar => @bar 
 :%mapper       # same as mapper => %mapper 
 :&test         # same as test => &test 

See also #Adverb.

17.15 Damian Conway

Original author of the #Exegesis (among many other things). See also https://en.wikipedia.org/wiki/Damian_Conway.

17.16 diffy

See operator. It means the type of the operator result is sufficiently different from its arguments that op= makes little sense

17.17 Exegesis

A document originally written by #TheDamian, in which he tried to explain the Apocalypses to the common (wo)man. Now only kept as an historical document for reference. See also #Synopsis.

17.18 fiddly

Too complicated to apply a meta-op to. See operator.

17.19 iffy

Often used as a boolean value. See operator.

17.20 Instance

An instance of a class is also called an object in some other programming languages. It has storage for attributes and is often the return value of a call to a method called new, or a literal.

Instances of most types are defined to be True e.g., defined($instance) is True.

my Str $str = "hello";  ## this is with builtin types, e.g. Str
if defined($str) {
    say "Oh, yeah. I'm defined.";
}
else {
    say "No. Something off? ";
}

## if you wanted objects...
class A {
    # nothing here for now.
}

my $an_instance = A.new;
say $an_instance.defined.perl;# defined($an_instance) works too.

To put things another way, a class contains the blueprints of methods and attributes, and an instance carries it into the real world.

17.21 Interface

An interface is an abstract class.

17.22 IRC

Internet Relay Chat. Perl 6 developers and users usually hang out on the #perl6 channel of irc.freenode.org. Currently available bots are:

17.22.1 camelia

The #Bot on the #perl6 #IRC channel that evaluates code, e.g.:

[16:28:27]  <lizmat>  m: say "Hello world" 
 [16:28:28]  <+camelia>    rakudo-moar 812a48: OUTPUT«Hello world␤» 

This is a handy tool for showing people if the output is (un)expected.

17.22.2 dalek

The #Bot on the #perl6 #IRC channel that reports changes made to various Perl 6 related repositories.

[15:46:40] <+dalek> doc: 2819f25 | lizmat++ | doc/Language/glossary.pod: 
 [15:46:40] <+dalek> doc: Add stubs for stuff inside the glossary already 
 [15:46:40] <+dalek> doc: review: https://github.com/perl6/doc/commit/2819f250 

17.22.3 yoleaux

The #Bot on the #perl6 #IRC channel that provides various services to people logged in. Commands to yoleaux (a pun on YOLO) start with a period. Some often used commands are:

17.22.3.1 .tell

Leave a message to another user who is currently not logged in. The message will be relayed as soon as the user says anything on the channel.

.tell lizmat I've read the glossary 

17.22.3.2 .u

Look up unicode codepoint information from either a codepoint, or the name of a codepoint.

[16:35:44]  <lizmat>   .u empty set 
 [16:35:45]  <yoleaux>  U+2205 EMPTY SET [Sm] (∅) 
 [16:36:29]  <lizmat>   .u ∅ 
 [16:36:30]  <yoleaux>  U+2205 EMPTY SET [Sm] (∅) 

Some #IRC clients then easily allow you to copy/paste the codepoint in question, which can be sometimes be easier than other unicode codepoint input methods.

17.23 IRC Lingo

The following terms are often used on the Perl 6 related #IRC channels:

17.23.1 ALAP

As Late As Possible

17.23.2 autopun

A self-referencing pun, e.g. "Are you ignorant or apathetic?" - "I don't know, and I don't care."

17.23.3 backlog

That part of a discussion on an #IRC channel that you've missed. If it is not or no longer available in your IRC client, you can go to sites such as http://irc.perl6.org to see what has been logged for you.

17.23.4 Bot

A program that does automatic tasks on one or more #IRC channels by acting like a regular user (as far as the IRC server is concerned) and performing some tasks that may involve answering to users requests. Examples are #camelia, #dalek and #yoleaux.

17.23.5 DWIM

Do What I Mean. A programming language designer motto.

17.23.6 flap

Sometimes a test will fail under some conditions, but not others; when this test passes some test runs and fails others, it's called flapping.

17.23.7 fossil

Something in a generally current document that is no longer true but which has not yet been fixed by correcting or removing it.

17.23.8 FSVO

For Some Value Of...

17.23.9 FTFY

Fixed That For You

17.23.10 IWBN

It Would Be Nice

17.23.11 LHF

Low Hanging Fruit. Usually used in the context of a (relatively) simple task to be performed by a (relative) newbie.

17.23.12 LTA

Less Than Awesome. Usually used in the context of an error message that is rather non-descriptive or unrelated to the actual error.

17.23.13 NST

No Such Thing

17.23.14 Opt

Short for "optimization", usually in either the context of spesh or JIT.

17.23.15 PB

Short for "problem". As in "that's not the pb".

17.23.16 PBP

"Perl Best Practices". The book by Damian Conway outlining best practices when programming Perl 5.

17.23.17 PR

See #Pull Request.

17.23.18 P5

Perl 5

17.23.19 P6

Perl 6

17.23.20 RSN

Real Soon Now

17.23.21 RT

Request Tracker (http://rt.perl.org/). The place where all the bugs related to #Rakudo live.

17.23.22 TIMTOWTDI

An alternative form of #TMTOWTDI, explicitly including the "is" from the contraction "There's".

17.23.23 TMI

Too Much Information.

17.23.24 TMTOWTDI

"There's More Than One Way To Do It", the Perl motto.

17.23.25 UGT

"Universal Greeting Time" - i.e., it's always "morning".

17.23.26 WFM

Works For Me

17.23.27 WIP

Work In Progress

17.23.28 WP

Wikipedia

17.23.29 WW

Short for wrong window. When on #IRC, someone types something in a channel that was intended for another channel, or for a private message.

17.24 Larry Wall

Perl's benevolent dictator for life, among many other things. See also https://en.wikipedia.org/wiki/Larry_Wall.

17.25 Lexing

17.26 Literal

A literal is a piece of code that directly stands for an (often built-in) object and also refers to the object itself.

my $x = 2;      # the 2 is a literal
say $x;         # $x is not a literal, but a variable
my $s = "Foo";  # the "Foo" is a literal, the $s is a variable

17.27 lvalue

An lvalue, or a left value, is anything that can appear on the left hand side of the assignment operator =. It is anything you can assign to.

Typical lvalues are variables, private and is rw attributes, lists of variables and lvalue subroutines.

Examples of lvalues:

Declaration lvalue Comments
my $x; $x
my ($a, $b); ($a, $b)
has $!attribute; $!attribute Only inside classes
has $.attrib is rw; $.attrib
sub a is rw { $x }; a()

Examples of things that are not lvalues:

3 literals
constant x = 3; constants
has $.attrib; attributes; you can only assign to $!attrib
sub f { }; f(); "normal" subs are not writable
sub f($x) { $x = 3 }; error - parameters are read-only by default

These are typically called rvalues.

17.28 Mainline

The mainline is the program text that is not part of any kind of block.

use v6.c;     # mainline
sub f {
              # not in mainline, in sub f
}
f();          # in mainline again

You can also have the mainline of any package-like declarator, such as class, module, grammar, etc. These are typically run just after the class/module/grammar have been compiled (or when loaded from a pre-compiled file).

17.29 MoarVM

MoarVM is short for Metamodel On A Runtime Virtual Machine. It's a virtual machine designed specifically for #NQP and its MOP: #6model. A document about the purpose of MoarVM. MoarVM has some similarities with the Hotspot VM so you may peruse its glossary for entries missing from the present one.

17.30 Multi-Dispatch

The process of picking a candidate for calling of a set of methods or subs that come by the same name but with different arguments. The most narrow candidate wins. In case of an ambiguity, a routine with is default trait will be chosen if one exists, otherwise an exception is thrown.

17.31 multi-method

A method that has multiple candidates going by the same name and are subject to Multi-Dispatch.

17.32 Niecza

An implementation of Perl 6 targeting the .NET platform. No longer actively maintained.

17.33 Not Quite Perl

See #NQP.

17.34 NQP

NQP is a primitive language for writing subroutines and methods using a subset of the Perl 6 syntax. It's not intended to be a full-fledged programming language, nor does it provide a runtime environment beyond the basic VM primitives. Compilers (such as #Rakudo typically use NQP to compile action methods that convert a parse tree into its equivalent abstract syntax tree representation.

17.35 NYI

Not Yet Implemented

17.36 opcode

17.37 Operator

An expression is made of operators and operands. More precisely it is made of an operator and operands that can be subexpressions or #values. Operators are an alternative syntax for a #multi-method. With that syntax, what would be the arguments of the function are named operands instead. Operators are classified into categories of categories. A category has a precedence, an arity, and can be #fiddly, #iffy, #diffy. Perl 6 is very creative as to what is an operator, so there are many categories. Operators are made of many tokens, possibly with a subexpression. For example, @a[0] belongs to the postcircumfix category, is broken into the operand @a and the postcircumfix operator [0] where 0 is the postcircumfixed subexpression.

The <O(I<...>)> construction gives information about an operator that completes the information provided by its category. Below %conditional is the category, :reducecheck<ternary> , which specifies calling .ternary to post-process the parse subtree and :pasttype<if> specifies the NQP #opcode generated in the AST from the parse subtree.

<O('%conditional, :reducecheck<ternary>, :pasttype<if>')>

17.38 Parse Tree

17.39 Parameter

Parameter is a class to define parameters to subroutines, method and a callable blocks. As opposed to the arguments you specify when calling a subroutine/method/callable block.

sub foo($bar) { say $bar }     # $bar is a parameter
foo(42);                       # 42 is an argument

17.40 Parrot

A virtual machine designed to run Perl 6 and other dynamic languages. No longer actively maintained.

17.41 PAST

#Parrot AST.

17.42 perl

Name of the Perl 5 executor.

17.43 Perl

The Perl programming language in its many forms.

17.44 PERL

A way to describe Perl as a language, considered to be improper by many in the Perl Community.

17.45 POD

Plain Ol' Documentation, a documentation format understood by Perl 6. See S26 for details.

17.46 Pull Request

A feature of https://github.com that allows you to make patches to be easily applied using the Github user interface. It means you request someone to do a git pull from your repository to hers. In GitHub, it can be done automatically through the web interface. PR is its usual acronym.

17.47 pugs

pugs was one of the first interpreters/compilers written for Perl 6. It was written in Haskell by Audrey Tang.

17.48 QAST

Successor to #PAST ('Q' being the next letter after 'P').

17.49 Rakudo

Rakudo is the name of a Perl 6 implementation that runs on #MoarVM and the JVM. It is an abbreviation of Rakuda-do, which, when translated from Japanese, means "The Way of the Camel". Also, in Japanese, "Rakudo" means "Paradise."

17.50 Reify

In English language, reify means to "to convert into or regard as a concrete thing." Its meaning in Perl 6 is very similar, in that conceptual things, like "elements of an infinite list" get reified when you try to operate on some of them:

# A list containing infinite number of un-reified Fibonacci numbers:
my @fibonacci = 1, 1, * + * … ∞;

# We reify 10 of them, looking up the first 10 of them with array index:
say @fibonacci[^10]; # OUTPUT: «(1 1 2 3 5 8 13 21 34 55)␤»

# We reify 5 more: 10 we already reified on previous line, and we need to
# reify 5 more to get the 15th element at index 14. Even though we need only
# the 15th element, the original Seq still has to reify all previous elements:
say @fibonacci[14]; # OUTPUT: «987␤»

Above we were reifying a Seq we created with the sequence operator, but other things use the concept as well. For example, an un-reified Range is just the two end points. In some languages, calculating the sum of a huge range is a lengthy and memory-consuming process, but Perl 6 calculates it instantly:

say sum 1 ..9_999_999_999_999; # OUTPUT: «49999999999995000000000000␤»

Why? Because the sum can be calculated without reifying the Range; that is without figuring out all the elements it contains. This is why this feature exists. You can even make your own things you can reify-on-demand, using gather and take :

my $seq = gather {
    say "About to make 1st element"; take 1;
    say "About to make 2nd element"; take 2;
}
say "Let's reify an element!";
say $seq[0];
say "Let's reify more!";
say $seq[1];
say "Both are reified now!";
say $seq[^2];

# OUTPUT:
# Let's reify an element!
# About to make 1st element
# 1
# Let's reify more!
# About to make 2nd element
# 2
# Both are reified now!
# (1 2)

Following the output above, you can see the print statements inside the gather got printed only when we reified the individual elements while looking up an element. Also note, the elements got reified just once. When we printed the same elements again on the last line of the example, the messages inside gather we no longer printed. This is because the construct used already-reified elements from the Seq's cache.

Note that above we assigned the gather to a Scalar container (the $ sigil), not the Positional one (the @ sigil). The reason is that the @-sigiled variables are mostly lazy. What this means is they reify the stuff assigned to them right away most of the time. The only time they don't do it is when the items are known to be is-lazy , like our sequence generated with infinity as the end point. Were we to assign the gather to a @-variable, the say statements inside of it would've been printed right away.

Another way to fully-reify a list, is by calling .elems on it. This is the reason why checking whether a list contains any items is best done by using .Bool method (or just using if @array { … }), since you don't need to reify all the elements to find out if there are any of them.

There are times where you do want to fully-reify a list before doing something. For example, the IO::Handle.lines returns a Seq. The following code contains a bug; keeping reification in mind, try to spot it:

    my $fh = "/tmp/bar".IO.open; 
     my $lines = $fh.lines; 
     close $fh; 
     say $lines[0]; 

We open a file handle, then assign return of .lines to a Scalar variable, so the returned Seq does not get reified right away. We then close the file handle, and try to print an element from $lines.

The bug in the code is by the time we reify the $lines Seq on the last line, we've already closed the file handle. When the Seq's iterator tries to generate the item we've requested, it results in the error about attempting to read from a closed handle. So, to fix the bug we can either assign to a @-sigiled variable or call .elems on $lines before closing the handle:

    my $fh = "/tmp/bar".IO.open; 
     my @lines = $fh.lines; 
     close $fh; 
     say @lines[0]; # no problem! 

Also good:

    my $fh = "/tmp/bar".IO.open; 
     my $lines = $fh.lines; 
     say "Read $lines.elems() lines"; #reifying before closing handle 
     close $fh; 
     say $lines[0]; # no problem! 

17.51 Repository

A filesystem under control of a source control management application, usually git, that holds the sources for a project, library or application. This file, for instance, is in a GitHub repository. Repositories store not only files, but also history of changes and can be used by the developing or writing team for interaction through issues or comments to code.

17.52 roast

The Perl 6 specification tests, which live here: https://github.com/perl6/roast/. Originally developed for #pugs, it now serves all Perl 6 implementations. Why roast? It's the repository of all spec tests.

17.53 rule

(Used in regular expressions)

17.54 rvalue

A value that can be used on the right hand side of an assignment. See also #lvalue.

17.55 Sigil

In Perl, the sigil is the first character of a variable name. It must be either $, @, %, or & respectively for a scalar, array, hash, or code variable. See also Twigil and role. Also sigiled variables allow short conventions for variable interpolation in a double quoted string, or even postcircumfix expressions starting with such a variable.

17.56 Sigilless Variable

17.57 Spesh

A functionality of the #MoarVM platform that uses run-time gathered data to improve commonly used pieces of #bytecode. It is much like a JIT compiler, except that those usually output machine code rather than bytecode.

17.58 STD

STD.pm is the "standard" Perl 6 grammar definition, see https://github.com/perl6/std/ that was used to implement Perl 6. STD.pm is no longer really a "specification" in a proscriptive sense: it's more of a guideline or model for Perl 6 implementations to follow.

17.59 Stub

17.60 Symbol

Fancy alternative way to denote a name. Generally used in the context of modules linking, be it in the OS level, or at the Perl 6 #Virtual Machine level for modules generated from languages targeting these VMs. The set of imported or exported symbols is called the symbol table.

17.61 Synopsis

The current human-readable description of the Perl 6 language. Still in development. Much more a community effort than the Apocalypses and Exegeses were. The current state of the language is reflected by #roast, its #test suite, not the synopses where speculative material is not always so flagged or more recent additions have not been documented. This is even more true of material that has not been yet implemented.

17.62 Syntax Analysis

17.63 test suite

The Perl 6 test suite is #roast

17.64 Texas operator

The ASCII variant of a non-ASCII Unicode operator or symbol. So described because "Everything's bigger in Texas." For instance, (elem) corresponds to the ("Is this an element of that set?") operator that comes from set theory. Texas operators are a workaround to the problem that people don't know how to type Unicode yet. Culturally, while we encourage people to use the Unicode symbols in a vague sort of way, we do not disparage the use of the ASCII variants. Well, maybe just a little...

17.65 TheDamian

#IRC screen name for #Damian Conway, writer of the original Exegeses.

17.66 TimToady

#IRC screen name for #Larry Wall, creator of Perl. The name comes from the pronunciation of #TIMTOWTDI as a word.

17.67 Thunk

A piece of code that isn't immediately executed, but doesn't have an independent scope.

17.68 value

17.69 Value type

A type is known as a value type if it is immutable and any instance of that type is interchangeable with any other instance "of the same value"—that is, any instance constructed in the same way. An instance of a value type is often called a value (but should not be confused with #lvalues or #rvalues).

For example, numbers are value types, so a number constructed one place in your program with, for instance, the literal 3 can't be changed in any way—it simply is 3—and any later use of the literal 3 can safely be pointed at the same place in memory as the first with no ill consequences.

Classes doing the roles Numeric and Stringy are among a few examples of built-in value types.

A value type is created by ensuring that an instance of the value type is immutable (i.e., its attributes cannot be modified after construction) and that its WHICH method returns the same thing every time an instance with the same value is constructed (and conversely returns a different thing every time an instance with a different value is constructed).

The language is free to optimize based on the assumption that equivalent instances of value types are interchangeable, but you should not depend on any such optimization. For instance, if you want clone to return an instance of self, or you want instance construction to be memoized so that re-construction of a previously-constructed value always returns the same instance, you currently must override this behavior yourself.

(The same would hold true of object finalization, but if your instances need special destruction behavior, you almost certainly do not actually have a value type. Values should be thought of as "timeless" and existing in some ideal form outside of your program's memory, like natural values are.)

17.70 Variable

A variable is a name for a container.

17.71 Variable Interpolation

17.72 Virtual Machine

A virtual machine is the Perl compiler entity that executes the bytecode. It can optimize the bytecode or generate machine code Just in Time. Examples are #MoarVM, #Parrot (who are intended to run Perl 6) and more generic virtual machines such as JVM and Javascript.

17.73 whitespace

17.74 6model

18 Grammar Tutorial

Why Grammars?

Grammars parse strings and return data structures from those strings. Grammars can be used to prepare a program for execution, to determine if a program can run at all (if it's a valid program), to break down a web page into constituent parts, or to identify the different parts of a sentence, among other things.

When Would I Use Grammars?

If you have strings to tame or interpret, grammars provide the tools to do the job.

The string could be a file that you're looking to break into sections; perhaps a protocol, like SMTP, where you need to specify which "commands" come after what user-supplied data; maybe you're designing your own domain specific language. Grammars can help.

The Broad Concept of Perl Grammars

Regular expressions work well for finding patterns in strings. However, for some tasks -- like finding multiple patterns at once, or combining patterns, or testing for patterns that may surround strings -- regular expressions, alone, are not enough.

When working with HTML, you could define a grammar to recognize HTML tags, both the opening and closing elements, and the text in between. You could then organize these elements into data structures, such as arrays or hashes.

18.1 Getting More Technical

18.1.1 The conceptual overview

Grammars are a special kind of class. You declare and define a grammar exactly as you would any other class, except that you use the grammar keyword instead of class.

grammar My::Gram { ... } 

Grammars are made up of methods that define a regex, a token, or a rule. These are all varieties of different types of match methods. Once you have a grammar defined, you call it and pass in a string for parsing.

my $matchObject = My::Gram.parse($string); 

Now, you may be wondering, if I have all these regexes defined that just return their results, how does that help with parsing strings that may be ahead or backwards in a string, or things that need to be combined from many of those regexes... and that's where grammar actions come in.

For every "method" you match in your grammar, you get an action you can use to act on that match. You also get an over-arching action that you can use to tie together all your matches and to build a data structure. This over-arching method is called TOP by default.

18.1.2 The technical overview

As already mentioned, grammars are declared using the grammar keyword and its "methods" are declared with regex, or token, or rule.

When a method (regex, token or rule) matches in the grammar, that matched string is put into a match object and keyed with the same name as the method.

grammar My::Gram { 
     token TOP { <thingy> .* } 
     token thingy { 'clever_text_keyword' } 
 } 

If you were to use my $match = My::Gram.parse( $string ) and your string started with 'clever_text_keyword', you would get a match object back that contained 'clever_text_keyword' keyed by the name of 'thingy' in your match object.

The TOP method (whether regex, token, or rule) is the overarching pattern that must match everything (by default). If the parsed string doesn't match the TOP regex, your returned match object will be empty (Any).

As you can see above, in TOP, the "<thingy>" token is mentioned. The <thingy> is defined on the next line, "token thingy...". That means that 'clever_text_keyword' must be the first thing in the string or the grammar parse will fail and we'll get an empty match. This is great for recognizing a malformed string that should be discarded.

18.2 Learning By Example - a REST Contrivance

Let's suppose we'd like to parse a URI into the component parts that make up a RESTful request. We want the URIs to work like this:

So, if we have "/product/update/7/notify", we would want our grammar to give us a $match object that has a "subject" of "product", a "command" of "update", and "data" of "7/notify" (for now, anyway).

We'll start by defining a grammar class and some match methods for the subject, command, and data. We'll use the token declarator since we don't care about whitespace.

grammar REST { 
     token subject { \w+ } 
     token command { \w+ } 
     token data    { .* } 
 } 

So far, this REST grammar says we want a subject that will be just word characters, a command that will be just word characters, and data that will be everything else left in the string.

Next, we'll want to arrange these matching tokens within the larger context of the URI. That's what the TOP method allows us to do. We'll add the TOP method and place the names of our tokens within it, together with the rest of the patterns that makes up the overall pattern. Note how we're building a larger regex from our named regexes.

grammar REST { 
     token TOP     { '/' <subject> '/' <command> '/' <data> } 
     token subject { \w+ } 
     token command { \w+ } 
     token data    { .* } 
 } 

With this code, we can already get the three parts of our RESTful request:

my $match = REST.parse('/product/update/7/notify'); 
 say $match; 
 
 # OUTPUT: «「/product/update/7/notify」␤ 
 #          subject => 「product」 
 #          command => 「update」 
 #          data => 「7/notify」» 

The data can be accessed directly by using $match<subject> or $match<command> or $match<data> to return the values parsed. They each contain match objects that you can work further with, such as coercing into a string ( $match<command>.Str ).

18.2.1 Adding some flexibility

So far, the grammar will handle retrieves, deletes and updates. However, a create command doesn't have the third part (the data portion). This means the grammar will fail to match if we try to parse a create URI. To avoid this, we need to make that last data position match optional, along with the '/' preceding it. This is accomplished by adding a question mark to the grouped '/' and data components of the TOP token, to indicate their optional nature, just like a normal regex.

So, now we have:

grammar REST { 
     token TOP     { '/' <subject> '/' <command> [ '/' <data> ]? } 
     token subject { \w+ } 
     token command { \w+ } 
     token data    { .* } 
 } 
 
 my $m = REST.parse('/product/create'); 
 say $m<subject>, $m<command>; 
 
 # OUTPUT: «「product」「create」␤» 

Next, assume that the URIs will be entered manually by a user and that the user might accidentally put spaces between the '/'s. If we wanted to accommodate for this, we could replace the '/'s in TOP with a token that allowed for spaces.

grammar REST { 
     token TOP     { <slash><subject><slash><command>[<slash><data>]? } 
     token subject { \w+ } 
     token command { \w+ } 
     token data    { .* } 
 
     token slash   { \s* '/' \s* } 
 } 
 
 my $m = REST.parse('/ product / update /7 /notify'); 
 say $m; 
 
 # OUTPUT: «「/ product / update /7 /notify」␤ 
 #          slash => 「/ 」 
 #          subject => 「product」 
 #          slash => 「 / 」 
 #          command => 「update」 
 #          slash => 「 /」 
 #          data => 「7 /notify」» 

We're getting some extra junk in the match object now, with those slashes. There's techniques to clean that up that we'll get to later.

18.2.2 Adding some constraints

We want our RESTful grammar to allow for CRUD operations only. Anything else we want to fail to parse. That means our "command" above should have one of four values: create, retrieve, update or delete.

There are several ways to accomplish this. For example, you could change the command method:

token command { \w+ } 
 
 # …becomes… 
 
 token command { 'create'|'retrieve'|'update'|'delete' } 

For a URI to parse successfully, the second part of the string between '/'s must be one of those CRUD values, otherwise the parsing fails. Exactly what we want.

There's another technique that provides greater flexibility and improved readability when options grow large: proto-regexes.

To utilize these proto-regexes (multimethods, in fact) to limit ourselves to the valid CRUD options, we'll replace "token command" with the following:

proto token command {*} 
 token command:sym<create>   { <sym> } 
 token command:sym<retrieve> { <sym> } 
 token command:sym<update>   { <sym> } 
 token command:sym<delete>   { <sym> } 

The 'sym' keyword is used to create the various proto-regex options. Each option is named (e.g., sym<update>), and for that option's use, a special <sym> token is auto-generated with the same name.

The <sym> token, as well as other user-defined tokens, may be used in the proto- regex option block to define the specific 'match condition'. Regex tokens are compiled forms and, once defined, cannot subsequently be modified by adverb actions (e.g., :i). Therefore, as it's auto-generated, the special <sym> token is useful only where an exact match of the option name is required.

If, for one of the proto-regex options, a match condition occurs, then the whole proto's search terminates. The matching data, in the form of a match object, is assigned to the parent proto token. If the special <sym> token was employed and formed all or part of the actual match, then it's preserved as a sub-level in the match object, otherwise it's absent.

Using proto-regexes like this gives us a lot of flexibility. For example, instead of returning <sym>, which in this case is the entire string that was matched, we could instead enter our own string, or do other funny stuff. We could do the same with the "token subject" method and limit it also to only parsing correctly on valid subjects (like 'part' or 'people', etc.).

18.2.3 Putting our RESTful grammar together

This is what we have for processing our RESTful URIs, so far:

grammar REST 
 { 
     token TOP { <slash><subject><slash><command>[<slash><data>]? } 
 
     proto token command {*} 
     token command:sym<create>   { <sym> } 
     token command:sym<retrieve> { <sym> } 
     token command:sym<update>   { <sym> } 
     token command:sym<delete>   { <sym> } 
 
     token subject { \w+ } 
     token data    { .* } 
     token slash   { \s* '/' \s* } 
 } 

Let's look at various URIs and see how they work with our grammar.

my @uris = ['/product/update/7/notify', 
             '/product/create', 
             '/item/delete/4']; 
 
 for @uris -> $uri { 
     my $m = REST.parse($uri); 
     say "Sub: $m<subject> Cmd: $m<command> Dat: $m<data>"; 
 } 
 
 # OUTPUT: «Sub: product Cmd: update Dat: 7/notify␤ 
 #          Sub: product Cmd: create Dat: 
 #          Sub: item Cmd: delete Dat: 4» 

With just this part of a grammar, we're getting almost everything we're looking for. The URIs get parsed and we get a data structure with the data.

The data token returns the entire end of the URI as one string. The 4 is fine. However from the '7/notify', we only want the 7. To get just the 7, we'll use another feature of grammar classes: actions.

18.3 Grammar Actions

Grammar actions are used within grammar classes to do things with matches. Actions are defined in their own classes, distinct from grammar classes.

You can think of grammar actions as a kind of plug-in expansion module for grammars. A lot of the time you'll be happy using grammars all by their own. But when you need to further process some of those strings, you can plug in the Actions expansion module.

To work with actions, you use a named parameter called "actions" which should contain an instance of your actions class. With the code above, if our actions class called REST-actions, we would parse the URI string like this:

my $matchObject = REST.parse($uri, actions => REST-actions.new); 
 
 #   …or if you prefer… 
 
 my $matchObject = REST.parse($uri, :actions(REST-actions.new)); 

If you name your action methods with the same name as your grammar methods (tokens, regexes, rules), then when your grammar methods match, your action method with the same name will get called automatically. The method will also be passed the corresponding match object (represented by the $/ variable).

Let's turn to an example.

18.4 Grammars by Example with Actions

Here we are back to our grammar.

grammar REST 
 { 
     token TOP { <slash><subject><slash><command>[<slash><data>]? } 
 
     proto token command {*} 
     token command:sym<create>   { <sym> } 
     token command:sym<retrieve> { <sym> } 
     token command:sym<update>   { <sym> } 
     token command:sym<delete>   { <sym> } 
 
     token subject { \w+ } 
     token data    { .* } 
     token slash   { \s* '/' \s* } 
 } 

Recall that we want to further process the data token "7/notify", to get the 7. To do this, we'll create an action class that has a method with the same name as the named token. In this case, our token is named "data" so our method is also named "data".

class REST-actions 
 { 
     method data($/) { $/.split('/') } 
 } 

Now when we pass the URI string through the grammar, the "data" token match will be passed to the REST-actions' "data" method. The action method will split the string by the '/' character and the first element of the returned list will be the ID number (7 in the case of "7/notify").

But not really; there's a little more.

18.4.1 Keeping grammars with actions tidy with "make" and "made"

If the grammar calls the action above on data, the data method will be called, but nothing will show up in the big TOP grammar match result returned to our program. In order to make the action results show up, we need to call "make" on that result. The result can be many things, including strings, array or hash structures.

You can imagine that the "make" places the result in a special contained area for a grammar. Everything that we "make" can be accessed later by "made".

So instead of the REST-actions class above, we should write

class REST-actions 
 { 
     method data($/) { make $/.split('/') } 
 } 

When we add "make" to the match split (which returns a list), the action will return a data structure to the grammar that will be stored separately from the "data" token of the original grammar. This way, we can work with both if we need to.

If we want to access just the ID of 7 from that long URI, we access the first element of the list returned from the "data" action that we "made" with "make":

my $uri = '/product/update/7/notify'; 
 
 my $match = REST.parse($uri, actions => REST-actions.new); 
 
 say $match<data>.made[0];  # OUTPUT: «7␤» 
 say $match<command>.Str;   # OUTPUT: «update␤» 

Here we call "made" on data, because we want the result of the action that we "made" (with "make") to get the split array. That's lovely! But, wouldn't it be lovelier if we could "make" a friendlier data structure that contained all of the stuff we want, rather than having to coerce types and remember arrays?

Just like TOP, which over-arches and matches the entire string, actions have a TOP method as well. We can "make" all of the individual match components, like "data" or "subject" or "command", and then we can place them in a data structure that we will "make" in TOP. When we return the final match object, we can then access this data structure.

To do this, we add the method TOP to the action class and "make" whatever data structure we like from the component pieces.

So, our action class becomes:

class REST-actions 
 { 
     method TOP ($/) { 
         make { subject => $<subject>.Str, 
                command => $<command>.Str, 
                data    => $<data>.made } 
     } 
 
     method data($/) { make $/.split('/') } 
 } 

Here in the TOP method, the "subject" remains the same as the subject we matched in the grammar. Also, "command" returns the valid <sym> that was matched (create, update, retrieve, or delete). We coerce each into .Str, as well, since we don't need the full match object.

We want to make sure to use the "made" method on the $<data> object, since we want to access the split one that we "made" with "make" in our action, rather than the proper $<data> object.

After we "make" something in the TOP method of a grammar action, we can then access all the custom values by calling the "made" method on the grammar result object. The code now becomes

my $uri = '/product/update/7/notify'; 
 
 my $match = REST.parse($uri, actions => REST-actions.new); 
 
 my $rest = $match.made; 
 say $rest<data>[0];   # OUTPUT: «7␤» 
 say $rest<command>;   # OUTPUT: «update␤» 
 say $rest<subject>;   # OUTPUT: «product␤» 

If the complete return match object is not needed, you could return only the made data from your action's TOP.

my $uri = '/product/update/7/notify'; 
 
 my $rest = REST.parse($uri, actions => REST-actions.new).made; 
 
 say $rest<data>[0];   # OUTPUT: «7␤» 
 say $rest<command>;   # OUTPUT: «update␤» 
 say $rest<subject>;   # OUTPUT: «product␤» 

Oh, did we forget to get rid of that ugly array element number? Hmm. Let's make something new in the grammar's custom return in TOP... how about we call it "subject-id" and have it set to element 0 of <data>.

class REST-actions 
 { 
     method TOP ($/) { 
         make { subject    => $<subject>.Str, 
                command    => $<command>.Str, 
                data       => $<data>.made, 
                subject-id => $<data>.made[0] } 
     } 
 
     method data($/) { make $/.split('/') } 
 } 

Now we can do this instead

my $uri = '/product/update/7/notify'; 
 
 my $rest = REST.parse($uri, actions => REST-actions.new).made; 
 
 say $rest<command>;    # OUTPUT: «update␤» 
 say $rest<subject>;    # OUTPUT: «product␤» 
 say $rest<subject-id>; # OUTPUT: «7␤» 

Here's the final code:

grammar REST 
 { 
     token TOP { <slash><subject><slash><command>[<slash><data>]? } 
 
     proto token command {*} 
     token command:sym<create>   { <sym> } 
     token command:sym<retrieve> { <sym> } 
     token command:sym<update>   { <sym> } 
     token command:sym<delete>   { <sym> } 
 
     token subject { \w+ } 
     token data    { .* } 
     token slash   { \s* '/' \s* } 
 } 
 
 
 class REST-actions 
 { 
     method TOP ($/) { 
         make { subject    => $<subject>.Str, 
                command    => $<command>.Str, 
                data       => $<data>.made, 
                subject-id => $<data>.made[0] } 
     } 
 
     method data($/) { make $/.split('/') } 
 } 

Hopefully this has helped introduce you to the grammars in Perl 6 and shown you how grammars and grammar action classes work together. For more information, check out the more advanced Perl Grammar Guide.

For more grammar debugging, see Grammar::Debugger. This provides breakpoints and color-coded MATCH and FAIL output for each of your grammar tokens.

19 Grammars

Parsing and interpreting text

Grammars are a powerful tool used to destructure text and often to return data structures that have been created by interpreting that text.

For example, Perl 6 is parsed and executed using a Perl 6-style grammar.

An example that's more practical to the common Perl 6 user is the JSON::Tiny module, which can deserialize any valid JSON file, however the deserializing code is written in less than 100 lines of simple, extensible code.

If you didn't like grammar in school, don't let that scare you off grammars. Grammars allow you to group regexes, just as classes allow you to group methods of regular code.

19.1 Named Regexes

The main ingredient of grammars is named regexes. While the syntax of Perl 6 Regexes is outside the scope of this document, named regexes have a special syntax, similar to subroutine definitions:

In fact, named regexes can even take extra arguments, using the same syntax as subroutine parameter lists

my  regex number {  \d+ [ \. \d+ ]?  }  

In this case, we have to specify that the regex is lexically scoped using the my keyword, because named regexes are normally used within grammars.

Being named gives us the advantage of being able to easily reuse the regex elsewhere:

say so "32.51" ~~  &number ;                                    # OUTPUT: «True␤» 
 say so "15 + 4.5" ~~ /  <number>  \s* '+' \s*  <number>  / # OUTPUT: «True␤» 

regex isn't the only declarator for named regexes – in fact, it's the least common. Most of the time, the token or rule declarators are used. These are both ratcheting, which means that the match engine won't back up and try again if it fails to match something. This will usually do what you want, but isn't appropriate for all cases:

my regex works-but-slow { .+ q } 
 my token fails-but-fast { .+ q } 
 my $s = 'Tokens won\'t backtrack, which makes them fail quicker!'; 
 say so $s ~~ &works-but-slow; # OUTPUT: «True␤» 
 say so $s ~~ &fails-but-fast; # OUTPUT: «False␤», the entire string get taken by the .+ 

The only difference between the token and rule declarators is that the rule declarator causes :sigspace to go into effect for the Regex:

my token non-space-y { 'once' 'upon' 'a' 'time' } 
 my rule space-y { 'once' 'upon' 'a' 'time' } 
 say so 'onceuponatime'    ~~ &non-space-y; # OUTPUT: «True␤» 
 say so 'once upon a time' ~~ &non-space-y; # OUTPUT: «False␤» 
 say so 'onceuponatime'    ~~ &space-y;     # OUTPUT: «False␤» 
 say so 'once upon a time' ~~ &space-y;     # OUTPUT: «True␤» 

19.2 Creating Grammars

Group of named regexes that form a formal grammar

Grammar is the superclass that classes automatically get when they are declared with the grammar keyword instead of class. Grammars should only be used to parse text; if you wish to extract complex data, an action object is recommended to be used in conjunction with the grammar.

19.2.1 Protoregexes

If you have a lot of alternations, it may become difficult to produce readable code or subclass your grammar. In the Actions class below, the ternary in method TOP is less than ideal and it becomes even worse the more operations we add:

grammar Calculator {
    token TOP { [ <add> | <sub> ] }
    rule  add { <num> '+' <num> }
    rule  sub { <num> '-' <num> }
    token num { \d+ }
}

class Calculations {
    method TOP ($/) { make $<add> ?? $<add>.made !! $<sub>.made; }
    method add ($/) { make [+] $<num>; }
    method sub ($/) { make [-] $<num>; }
}

say Calculator.parse('2 + 3', actions => Calculations).made;

# OUTPUT: «5␤»

To make things better, we can use protoregexes that look like `:sym<...> adverbs on tokens:

grammar Calculator {
    token TOP { <calc-op> }

    proto rule calc-op          {*}
          rule calc-op:sym<add> { <num> '+' <num> }
          rule calc-op:sym<sub> { <num> '-' <num> }

    token num { \d+ }
}

class Calculations {
    method TOP              ($/) { make $<calc-op>.made; }
    method calc-op:sym<add> ($/) { make [+] $<num>; }
    method calc-op:sym<sub> ($/) { make [-] $<num>; }
}

say Calculator.parse('2 + 3', actions => Calculations).made;

# OUTPUT: «5␤»

In the grammar, the alternation has now been replaced with <calc-op> , which is essentially the name of a group of values we'll create. We do so by defining a rule prototype with proto rule calc-op. Each of our previous alternations have been replaced by a new rule calc-op definition and the name of the alternation is attached with :sym<> adverb.

In the actions class, we now got rid of the ternary operator and simply take the .made value from the $<calc-op> match object. And the actions for individual alternations now follow the same naming pattern as in the grammar: method calc-op:sym<add> and method calc-op:sym<sub> .

The real beauty of this method can be seen when you subclass that grammar and actions class. Let's say we want to add a multiplication feature to the calculator:

grammar BetterCalculator is Calculator { 
     rule calc-op:sym<mult> { <num> '*' <num> } 
 } 
 
 class BetterCalculations is Calculations { 
     method calc-op:sym<mult> ($/) { make [*] $<num> } 
 } 
 
 say BetterCalculator.parse('2 * 3', actions => BetterCalculations).made; 
 
 # OUTPUT: «6␤» 

All we had to add are additional rule and action to the calc-op group and the thing works—all thanks to protoregexes.

19.2.2 Special Tokens

19.2.2.1 TOP

grammar Foo {
    token TOP { \d+ }
}

The TOP token is the default first token attempted to match when parsing with a grammar—the root of the tree. Note that if you're parsing with .parse method, token TOP is automatically anchored to the start and end of the string (see also: .subparse ).

Using rule TOP or regex TOP are also acceptable.

A different token can be chosen to be matched first using the :rule named argument to .parse, .subparse, or .parsefile Grammar methods.

19.2.2.2 ws

When rule instead of token is used, any whitespace after an atom is turned into a non-capturing call to ws. That is:

rule entry { <key> ’=’ <value> }

Is the same as:

token entry { <key> <.ws> ’=’ <.ws> <value> <.ws> } # . = non-capturing

The default ws matches one or more whitespace characters (\s) or a word boundary (<|w>):

# First <.ws> matches word boundary at the start of the line
# and second <.ws> matches the whitespace between 'b' and 'c'
say 'ab   c' ~~ /<.ws> ab <.ws> c /; # OUTPUT: «「ab   c」␤»

# Failed match: there is neither any whitespace nor a word
# boundary between 'a' and 'b'
say 'ab' ~~ /. <.ws> b/;             # OUTPUT: «Nil␤»

# Successful match: there is a word boundary between ')' and 'b'
say ')b' ~~ /. <.ws> b/;             # OUTPUT: «「)b」␤»

You can also redefine the default ws token:

grammar Foo {
    rule TOP { \d \d }
}.parse: "4   \n\n 5"; # Succeeds

grammar Bar {
    rule TOP { \d \d }
    token ws { \h*   }
}.parse: "4   \n\n 5"; # Fails

19.2.2.3 Always Succeed Assertion

The <?> is the always succeed assertion. When used as a grammar token, it can be used to trigger an Action class method. In the following grammar we look for Arabic digits and define a succ token with the always succeed assertion.

In the action class, we use calls to the succ method to do set up (in this case, we prepare a new element in @!numbers). In the digit method, we convert an Arabic digit into a Devanagari digit and add it to the last element of @!numbers. Thanks to succ, the last element will always be the number for the currently parsed digit digits.

grammar Digifier {
    rule TOP {
        [ <.succ> <digit>+ ]+
    }
    token succ   { <?> }
    token digit { <[0..9]> }
}

class Devanagari {
    has @!numbers;
    method digit ($/) { @!numbers[*-1] ~= $/.ord.&[+](2358).chr }
    method succ  ($)  { @!numbers.push: ''     }
    method TOP   ($/) { make @!numbers[^(*-1)] }
}

say Digifier.parse('255 435 777', actions => Devanagari.new).made;
# OUTPUT: «(२५५ ४३५ ७७७)␤»

19.2.3 Methods in Grammar

It's fine to use methods instead of rules or tokens in a grammar, as long as they return a /type/Cursor:

grammar DigitMatcher {
    method TOP (:$full-unicode) {
        $full-unicode ?? self.num-full !! self.num-basic;
    }
    token num-full  { \d+ }
    token num-basic { <[0..9]>+ }
}

The grammar above will attempt different matches depending on the arguments provided by parse methods:

say +DigitMatcher.subparse: '12७१७९०९', args => \(:full-unicode); 
 # OUTPUT: «12717909␤» 
 
 say +DigitMatcher.subparse: '12७१७९०९', args => \(:!full-unicode); 
 # OUTPUT: «12␤» 

19.3 Action Objects

A successful grammar match gives you a parse tree of Match objects, and the deeper that match tree gets, and the more branches in the grammar are, the harder it becomes to navigate the match tree to get the information you are actually interested in.

To avoid the need for diving deep into a match tree, you can supply an actions object. After each successful parse of a named rule in your grammar, it tries to call a method of the same name as the grammar rule, giving it the newly created Match object as a positional argument. If no such method exists, it is skipped.

Here is a contrived example of a grammar and actions in action:

use v6.c; 
 
 grammar TestGrammar { 
     token TOP { \d+ } 
 } 
 
 class TestActions { 
     method TOP($/) { 
         $/.make(2 + $/); 
     } 
 } 
 
 my $actions = TestActions.new; 
 my $match = TestGrammar.parse('40', :$actions); 
 say $match;         # OUTPUT: «「40」␤» 
 say $match.made;    # OUTPUT: «42␤» 

An instance of TestActions is passed as named argument actions to the parse call, and when token TOP has matched successfully, it automatically calls method TOP, passing the match object as an argument.

To make it clear that the argument is a match object, the example uses $/ as a parameter name to the action method, though that's just a handy convention, nothing intrinsic. $match would have worked too. (Though using $/ does give the advantage of providing $<capture> as a shortcut for $/<capture> ).

A slightly more involved example follows:

use v6.c; 
 
 grammar KeyValuePairs { 
     token TOP { 
         [<pair> \n+]* 
     } 
     token ws { \h* } 
 
     rule pair { 
         <key=.identifier> '=' <value=.identifier> 
     } 
     token identifier { 
         \w+ 
     } 
 } 
 
 class KeyValuePairsActions { 
     method identifier($/) { $/.make: ~$/                          } 
     method pair      ($/) { $/.make: $<key>.made => $<value>.made } 
     method TOP       ($/) { $/.make: $<pair>».made                } 
 } 
 
 my  $res = KeyValuePairs.parse(q:to/EOI/, :actions(KeyValuePairsActions)).made; 
     second=b 
     hits=42 
     perl=6 
     EOI 
 
 for @$res -> $p { 
     say "Key: $p.key()\tValue: $p.value()"; 
 } 

This produces the following output:

Key: second     Value: b 
 Key: hits       Value: 42 
 Key: perl       Value: 6 

Rule pair, which parsed a pair separated by an equals sign, aliases the two calls to token identifier to separate capture names to make them available more easily and intuitively. The corresponding action method constructs a Pair object, and uses the .made property of the sub match objects. So it (like the action method TOP too) exploits the fact that action methods for submatches are called before those of the calling/outer regex. So action methods are called in post-order.

The action method TOP simply collects all the objects that were .made by the multiple matches of the pair rule, and returns them in a list.

Also note that KeyValuePairsActions was passed as a type object to method parse, which was possible because none of the action methods use attributes (which would only be available in an instance).

In other cases, action methods might want to keep state in attributes. Then of course you must pass an instance to method parse.

Note that token ws is special: when :sigspace is enabled (and it is when we are using rule), it replaces certain whitespace sequences. This is why the spaces around the equals sign in rule pair work just fine and why the whitespace before closing } does not gobble up the newlines looked for in token TOP.

20 Perl 6 from Haskell - Nutshell

Learning Perl 6 from Haskell, in a nutshell: What do I already know?

Haskell and Perl 6 are very different languages. This is obvious. However, that does not mean there are not similarities or shared ideas! This page attempts to get a Haskell user up and running with Perl 6. The Haskell user may find that they need not abandon all of their Haskelly thoughts while scripting in Perl 6.

Note that this should not be mistaken for a beginner tutorial or overview of Perl 6; it is intended as a technical reference for Perl 6 learners with a strong Haskell background.

20.1 Types

20.1.1 Types vs Values

In Haskell, you have type level programming and then value level programming.

plusTwo :: Integer -> Integer   -- Types 
 plusTwo x = x + 2               -- Values 

You do not mix types and values in Haskell like the below

plusTwo 2          -- This is valid 
 plusTwo Integer    -- This is not valid 

In Perl 6, types (AKA type objects) live on the same level as values

sub plus-two(Int $x --> Int) { $x + 2 } 
 
 plus-two(2);    # This is valid 
 plus-two(Int);  # This is valid 

I will illustrate this unique aspect of Perl 6 with one more example:

multi sub is-string(Str $ --> True) {} 
 multi sub is-string(Any $ --> False) {} 
 
 is-string('hello');    #True 
 is-string(4);          #False 

20.1.2 Maybe

In Haskell, you have a Maybe type that allows you to forgo the worry of null types. Let's say you have a hypothetical function that parses a String to an Integer:

parseInt :: String -> Maybe Integer 
 
 case parseInt myString of 
   Just x  -> x 
   Nothing -> 0 

In Perl 6, since type objects coexist with regular objects, we have the concept of Defined and Undefined objects. Plain type objects are undefined while instantiated objects are defined.

sub parse-int(Str $s --> Int) { ... } 
 
 my $string = {...}; 
 given parse-int($string) { 
   when Int:D { $_ } 
   when Int:U { 0 } 
 } 

So in Perl 6 we have type constraints that indicate the definedness of a type. These are

Int:D; # This is a defined Int. 
 Int:U; # This is an undefined Int, AKA a type object 
 Int:_; # This is either defined or undefined. 

If we wanted to be explicit in the above example (probably a good idea), we could add the :_ constraint on the return type. This would let the user know that they should account for both defined and undefined return values. We could also use other methods and constructs that specifically test for definedness.

sub parse-int(Str $s --> Int:_) { ... } 
 
 # One way to do it 
 my $string = {...}; 
 given parse-int($string) { 
   when Int:D { $_ } 
   when Int:U { 0 } 
 } 
 
 # Another way to do it 
 my Int $number = parse-int($string); 
 if $number.defined { $number } else { 0 } 
 
 
 # A better way 
 with parse-int($string) { $_ } else { 0 } 
 
 # With the defined-or operator 
 parse-int($string) // 0 

The with operator that you see above is like if, except it explicitly tests for definedness and then passes the result to the following block. Similarly, without tests that the object is undefined and also passes the result to the following block.

For more natural control flow with undefined and defined types, Perl 6 introduces andthen and orelse.

sub parse-int(Str $s --> Int:_) { ... } 
 
 my $string = {...}; 
 my $result = parse-int($string) orelse 0; 
 
 sub hello() { say 'hi' } 
 hello() andthen say 'bye'; 

TODO: include a better example for andthen that makes sense. Maybe using promise objects?

So in practice, Perl 6 does not have the concept of a null type, but rather of defined or undefined types.

20.1.3 Data Definitions

Perl 6 is fundamentally an Object Oriented language. However, it also gives you the freedom to write in virtually any paradigm you wish. If you only want to pure functions that take an object and return a new object, you can certainly do so.

Here is a Haskell code example:

data Point = Point x y 
 
 moveUp :: Point -> Point 
 moveUp (Point x y) = Point x (y + 1) 

And an equivalent Perl 6 example:

class Point { has $.x; has $.y; } 
 
 sub move-up(Point $p --> Point) { 
   Point.new(x => $p.x, y => $p.y + 1) 
 } 

The code I illustrated above is an example of a Product Type. If instead you'd like to write a Sum Type, there is not an exact equivalent in Perl 6. The closest thing would be an Enum.

data Animal = Dog | Cat | Bird | Horse 
 
 testAnimal :: Animal -> String 
 testAnimal Dog   = "Woof" 
 testAnimal Horse = "Neigh" 

A Perl 6 Enum does not fit the same exact use cases, but it can be used in putting constraints on types.

enum Animal < Dog Cat Bird Horse >; 
 
 proto sub test-animal( Animal        ) {*} 
 multi sub test-animal( Dog           ) { 'Woof' } 
 multi sub test-animal( Animal::Horse ) { 'Neigh'  }   # more explicit 
 
 say test-animal Animal::Dog; # more explicit 
 say test-animal Horse; 

20.1.4 Type Aliases and Subsets

In Haskell, you can alias an existing type to simply increase clarity of intent and re-use existing types.

type Name = String 
 
 fullName :: Name -> Name -> Name 
 fullName first last = first ++ last 

The equivalent in Perl 6 is the following.

my constant Name = Str; 
 
 sub full-name ( Name \first, Name \last --> Name ) { first ~ last } 

It should be noted that in Perl 6, one can also create a subset of an existing type.

subset Name of Str where *.chars < 20; 
 
 sub full-name(Name $first, Name $last) { 
   $first ~ $last 
 } 
 
 full-name("12345678901234567890111", "Smith") # This does not compile, as the first parameter 
                                               # doesn't fit the Name type 

20.1.5 Typeclasses

TODO

explain how Perl 6 roles compare to Haskell typeclasses

20.2 Functions

20.2.1 Definitions and Signatures

Matching

Haskell makes heavy use of pattern matching in function definitions.

greeting :: String -> String 
 greeting  ""   = "Hello, World!" 
 greeting "bub" = "Hey bub." 
 greeting  name = "Hello, " ++ name ++ "!" 

Perl 6 does this as well! You just use the multi keyword to signify that it is a multiple dispatch function.

proto greeting ( Str   --> Str ) {*} 
 multi greeting ( ""    --> "Hello, World!" ) {} 
 multi greeting ( "bub" --> "Hey bub." ) {} 
 multi greeting ( \name ) { "Hello, " ~ name ~ "!" } 

The proto declarator is not necessary, but can sometimes aid in making sure that all multis follow your business rules. Using a variable name in the signature of the proto would provide more information in error messages, and for introspection.

proto greeting ( Str \name --> Str ) {*} 
 
 say &greeting.signature;                  # (Str \name --> Str) 

An interesting thing to note in the Perl 6 code above is that passing values like 'bub' as a function parameter is just syntax sugar for a where guard.

Using the example from the "Pattern Matching" section of this page, you can see the guards that are used behind the scenes to constrain our function arguments.

multi greeting ( ""    --> "Hello, World!" ) {} 
 multi greeting ( "bub" --> "Hey bub." ) {} 
 
 # The above is the same as the below 
 
 multi greeting(Str \name where ''    ) {'Hello, World!'} 
 multi greeting(Str \name where 'bub' ) {'Hey bub.'} 
 
 # The above is the same as the below, again. 
 
 multi greeting(Str \name where $_ ~~ ''   ) {'Hello, World!'} 
 multi greeting(Str \name where $_ ~~ 'bub') {'Hey bub.'} 

$_ is known as the topic variable. It assumes the form of whatever is appropriate. The smart match operator ~~ figures out the best way to determine if the left matches the right, be it number ranges, strings, etc. Our three examples above go from most sugared (top), to least sugared (bottom).

The bottom examples above could be wrapped in curly braces, making it more obvious that it is a code block. Note that a where clause may also take an explicit Callable.

multi greeting(Str \name where { $_ ~~ '' } ) {'Hello, World!'} 
 
 multi greeting(Str \name where -> $thing { $thing ~~ '' } ) {'Hello, World!'} 
 
 multi greeting ( Str \name where { Bool.pick } --> 'True' ){} 
 
 multi greeting ( Str \name where &some-subroutine ){…} 

If you read the section in this page on subsets, you'll notice that "where" is used in the making of subsets as well as here. The usage of "where" in both areas is exactly the same.

When using where, note that the order of definition is important, just like in Haskell.

multi greeting ( Str \name where '' --> 'Hello, World!' ){} 
 multi greeting ( Str \name where { Bool.pick } --> 'True' ){} 
 multi greeting ( Str \name where 'bub' --> 'Hey, bub.' ){} 
 
 say greeting ''   ; # will never say True 
 say greeting 'bub'; # about 50% of the time it will say True 

Deconstruction

TODO

20.2.2 Currying

TODO

.assuming vs currying

method chaining vs currying

20.2.3 Composing

TODO

show function composition operator. Maybe explain a more perl6ish way to do this though.

20.3 Case / Matching

Haskell makes heavy use of case matching like the below:

case number of 
   2 -> "two" 
   4 -> "four" 
   8 -> "eight" 
   _ -> "don't care" 

In Perl 6 you can achieve this same thing with the given/when structure:

my $number = {...}; 
 given $number { 
   when 2  { "two" } 
   when 4  { "four" } 
   when 8  { "eight" } 
   default { "don't care" } 
 } 

Note that the order of the when's is also significant, just like with the where's in the guard section of this page.

20.4 Lists

TODO

explain difference between perl6 Array, Sequence, List. Explain data shapes in regards to the @ sigil. Explain how you can convert an Array to a flattened list of objects with |@

data shapes become quite intuitive, but it takes a bit of practice.

20.4.1 List Comprehensions

There are no explicit list comprehensions in Perl6. But rather, you can achieve list comprehensions a couple of different ways.

Here is a trivial example in Haskell:

evens = [ x | x <- [0..100], even x ] 

And now in Perl6 :

# using `if` and `for` 
 my @evens = ($_ if $_ %% 2 for 0..100); 
 
 # using gather/take to build a Seq 
 my $evens = gather for 0..100 { take $_ if $_ %% 2 }; 
 
 # using gather/take to build an Array 
 my @evens = gather for 0..100 { take $_ if $_ %% 2 }; 

Since for is always eager it is generally better to use map or grep which will inherit the laziness or eagerness of its list argument.

my @evens = map { $_ if $_ %% 2 }, 0..100; 
 
 my @evens = grep { $_ %% 2 }, 0..100; 
 
 # using a Whatever lambda 
 my @evens = grep  * %% 2,  0..100; 

Here is the creation of tuples in Haskell:

tuples = [(i,j) | i <- [1,2], 
                   j <- [1..4] ] 
 -- [(1,1),(1,2),(1,3),(1,4),(2,1),(2,2),(2,3),(2,4)] 

And in Perl6:

my @tuples = 1,2  X  1..4; 
 # [(1,1), (1,2), (1,3), (1,4), (2,1), (2,2), (2,3), (2,4)] 

See this design document for more information on what kinds of list comprehensions are possible in Perl6: http://design.perl6.org/S04.html#The_do-once_loop

As you can see, when you get into some more advanced Haskell list comprehensions, Perl6 does not translate exactly the same, but it's possible to do the same things, nonetheless.

20.4.2 Fold

Fold in Haskell is called Reduce in Perl 6.

mySum = foldl `+` 0 numList 
my @numbers = {...}; 
 reduce { $^a + $^b }, 0, |@numbers; 
 @numbers.reduce({$^a + $^b}, with => 0) 

However, in Perl 6, if you want to use an infix operator (+ - / % etc) there is a nice little helper called the Reduction Metaoperator.

my @numbers = {...}; 
 [+] @numbers    # This is the same 
 [+] 0, @numbers # as this 

It inserts the operator in between all values in the list and produces a result, just like Fold.

In Haskell you, you have foldl and foldr. In Perl 6, this difference is determined by the associativity attached to the operator/subroutine.

sub two-elem-list ( \a, \b ) { ( a, b ) } 
 
 # you can use a subroutine as an infix operator 
 say 'a' [&two-elem-list] 'b'; # (a b) 
 
 # as the reduction prefix meta operator takes an infix operator, it will work there too; 
 [[&two-elem-list]] 1..5;           # ((((1 2) 3) 4) 5) 
 say (1..5).reduce: &two-elem-list; # ((((1 2) 3) 4) 5) 
 
 # right associative 
 sub right-two-elem-list( \a, \b ) is assoc<right> { ( a, b ) } 
 say (1..5).reduce: &right-two-elem-list; # (1 (2 (3 (4 5)))) 
 
 # XXX there is possibly a bug here as this currently doesn't look at 
 # XXX the associativity of &right-two-elem-list and just always does left assoc 
 say [[&right-two-elem-list]] 1..5; 
 
 # chaining 
 say [<] 1..5;            # True 
 say (1..5).reduce: &[<]; # True 

20.4.3 Map

TODO

20.4.4 Ranges

Haskell and Perl 6 both allow you to specify ranges of values.

myRange1 = 10..100 
 myRange2 = 1..        -- Infinite 
 myRange3 = 'a'..'h'   -- Letters work too 
my $range1 = 10..100; 
 my $range2 = 1..*;      # Infinite 
 my $range3 = 'a'..'h';  # Letters work too 

20.4.5 Laziness vs Eagerness

In the examples above, you have the concept of laziness displayed very plainly. Perl 6 has laziness only where it makes the most sense. For example, in the range 10..100, this is eager because it has a definite end. If a list does not have a definite end, then the list should clearly be lazy.

(1 .. 100).is-lazy; # False 
 (1 .. Inf).is-lazy; # True 

These are the "sane defaults" that Perl 6 takes pride in. But they are still defaults and can be changed into one or the other.

(1 .. 100).lazy.is-lazy;       # True 
 (1 .. 100).lazy.eager.is-lazy; # False 

20.5 Contexts (let-in / where)

TODO

explain how given/when and with/without and for loops open lexical scopes with the argument as the context.

compare it to let/in and where constructs maybe?

20.6 Parsers

20.6.1 Parser Combinators vs Grammars

TODO

21 Input/Output The Definitive Guide

Correctly use Perl 6 IO

21.1 The Basics

The vast majority of common IO work is done by the IO::Path type. If you want to read from or write to a file in some form or shape, this is the class you want. It abstracts away the details of file handles (or "file descriptors") and so you mostly don't even have to think about them.

Behind the scenes, IO::Path works with IO::Handle; a class which you can use directly if you need a bit more control than what IO::Path provides. When working with other processes, e.g. via Proc or Proc::Async types, you'll also be dealing with a subclass of IO::Handle: the IO::Pipe.

Lastly, you have the IO::CatHandle, as well as IO::Spec and its subclasses, that you'll rarely, if ever, use directly. These classes give you advanced features, such as operating on multiple files as one handle, or low-level path manipulations.

Along with all these classes, Perl 6 provides several subroutines that provide let you indirectly work with these classes. These come in handy if you like functional programming style or in Perl 6 one liners.

While IO::Socket and its subclasses also have to do with Input and Output, this guide does not cover them.

21.2 Navigating Paths

21.2.1 What's an IO::Path Anyway?

To represent paths to either files or directories, use IO::Path type. The simplest way to obtain an object of that type is to coerce a Str by calling .IO method on it:

say 'my-file.txt'.IO; # OUTPUT: «"my-file.txt".IO␤»

It may seem like something is missing here—there is no volume or absolute path involved—but that information is actually present in the object. You can see it by using .perl method:

say 'my-file.txt'.IO.perl;
# OUTPUT: «IO::Path.new("my-file.txt", :SPEC(IO::Spec::Unix), :CWD("/home/camelia"))␤»

The two extra attributes—SPEC and CWD—specify what type of operating system semantics the path should use as well as the "current working directory" for the path, i.e. if it's a relative path, then it's relative to that directory.

This means that regardless of how you made one, an IO::Path object technically always refers to an absolute path. This is why its .absolute and .relative methods return Str objects and they are the correct way to stringify a path.

However, don't be in a rush to stringify anything. Pass paths around as IO::Path objects. All the routines that operate on paths can handle them, so there's no need to convert them.

21.2.2 Working with Files

21.2.2.1 Writing into files

21.2.2.1.1 Writing new content

Let's make some files and write and read data from them! The spurt and slurp routines write and read the data in one chunk. Unless you're working with very large files that are difficult to store entirely in memory all at the same time, these two routines are for you.

    "my-file.txt".IO.spurt: "I ♥ Perl!"; 

The code above creates a file named my-file.txt in the current directory and then writes text I ♥ Perl! into it. If Perl 6 is your first language, celebrate your accomplishment! Try to open the file you created with some other program to verify what you wrote with your program. If you already know some other language, you may be wondering if this guide missed anything like handling encoding or error conditions.

However, that is all the code you need. The string will be encoded in utf-8 encoding by default and the errors are handled via the Failure mechanism: these are exceptions you can handle using regular conditionals. In this case, we're letting all potential Failures get sunk after the call and so any Exceptions they contain will be thrown.

21.2.2.1.2 Appending content

If you wanted to add more content to the file we made in previous section, you could note the spurt documentation mentions :append argument. However, for finer control, let's get ourselves an IO::Handle to work with:

my $fh = 'my-file.txt'.IO.open: :a;
$fh.print: "I count: ";
$fh.print: "$_ " for ^10;
$fh.close;

The .open method call opens our IO::Path and returns an IO::Handle. We passed :a as argument, to indicate we want to open the file for writing in append mode.

On the next couple of lines, we use the usual .print method on that IO::Handle to print ten lines of text. Note that, once again, Failure mechanism takes care of all the error checking for us. If the .open fails, it returns a Failure, which will throw when we attempt to call method .print on it.

Finally, we close the IO::Handle by calling .close documentation method on it. It is important that you do it, especially in large programs or ones that deal with a lot of files, as many systems have limits to how many files a program can have open at the same time. If you don't close your handles, eventually you'll reach that limit and the .open call will fail. Note that unlike some other languages, Perl 6 does not use reference counting, so the file handles are NOT closed when the scope they're defined in is left. They will be closed only when they're garbage collected and failing to close the handles may cause your program to reach the file limit before the open handles get a chance to get garbage collected.

21.2.2.2 Reading from files

21.3 The Wrong Way To Do Things

This section describes how NOT to do Perl 6 IO.

21.3.1 Leave $*SPEC Alone

You may have heard of $*SPEC and seen some code or books show its usage for splitting and joining path fragments. Some of the routine names it provides may even look familiar to what you've used in other languages.

However, unless you're writing your own IO framework, you almost ever need to use $*SPEC directly. $*SPEC provides low-level stuff and its use will not only make your code tough to read, you'll likely introduce security issues (e.g. null characters)!

The IO::Path type is the workhorse of Perl 6 world. It caters to all the path manipulation needs as well as provides shortcut routines that let you avoid dealing with file handles. Use that instead of the $*SPEC stuff.

Tip: you can join path parts with / and feed them to IO::Path 's routines; they'll still do The Right Thing™ with them, regardless of the operating system.

# WRONG!! TOO MUCH WORK! 
 my $fh = open $*SPEC.catpath: '', 'foo/bar', $file; 
 my $data = $fh.slurp; 
 $fh.close; 

# RIGHT! Use IO::Path to do all the dirty work my $data = 'foo/bar'.IO.add($file).slurp;

21.3.2 Stringifying IO::Path

Don't use .Str method to stringify IO::Path objects, unless you just want to display them somewhere for information purposes or something. The .Str method returns whatever the basic path string the IO::Path was instantiated with. It doesn't consider the value of $.CWD attribute. For example, this code is broken:

# WRONG!! .Str DOES NOT USE $.CWD! 
 my $path = 'foo'.IO; 
 chdir 'bar'; 
 run <tar -cvvf archive.tar>, ~$path; 

The chdir call changed the value of the current directory, but the $path we created is relative to the directory before that change.

However, the IO::Path object does know what directory it's relative to. We just need to use .absolute or .relative to stringify the object. Both routines return a Str object; they only differ in whether the result is an absolute or relative path. So, we can fix our code like this:

# RIGHT!! .absolute does consider the value of $.CWD! 
 my $path = 'foo'.IO; 
 chdir 'bar'; 
 run <tar -cvvf archive.tar>, $path.absolute; 
 # Also good: 
 run <tar -cvvf archive.tar>, $path.relative; 

21.3.3 Be mindful of $*CWD

While usually out of view, every IO::Path object, by default, uses the current value of $*CWD to set its $.CWD attribute. This means there are two things to pay attention to.

21.3.3.1 temp the $*CWD

This code is a mistake:

# WRONG!! 
 my $*CWD = "foo".IO; 

The my $*CWD made $*CWD undefined. The .IO coercer then goes ahead and sets the $.CWD attribute of the path its creating to the stringified version of the undefined $*CWD; an empty string.

The correct way to perform this operation is use temp instead of my. It'll localize the effect of changes to $*CWD , just like my would, but it won't make it undefined, so the .IO coercer will still get the correct old value:

temp $*CWD = "foo".IO; 

Better yet, if you want to perform some code in localized $*CWD , use the indir routine for that purpose.

22 Input/Output

File-related operations

Here we present a quick overview of the file-related input/output operations. Details can be found in the documentation for the IO role, as well as the IO::Handle and IO::Path types.

22.1 Reading from files

One way to read the contents of a file is to open the file via the open function with the :r (read) file mode option and slurp in the contents:

my $fh = open "testfile", :r; 
 my $contents = $fh.slurp-rest; 
 $fh.close; 

Here we explicitly close the file handle using the close method on the IO::Handle object. This is a very traditional way of reading the contents of a file. However, the same can be done more easily and clearly like so:

my $contents = "testfile".IO.slurp; 
 # or in procedural form: 
 $contents = slurp "testfile" 

By adding the IO role to the file name string, we are effectively able to refer to the string as the file object itself and thus slurp in its contents directly. Note that the slurp takes care of opening and closing the file for you.

22.1.1 Line by line

Of course, we also have the option to read a file line-by-line. The new line separator (i.e., $*IN.nl-in) will be excluded.

for 'huge-csv'.IO.lines -> $line { 
     # Do something with $line 
 } 
 
 # or if you'll be processing later 
 my @lines = 'huge-csv'.IO.lines; 

22.2 Writing to files

To write data to a file, again we have the choice of the traditional method of calling the open function – this time with the :w (write) option -- and printing the data to the file:

my $fh = open "testfile", :w; 
 $fh.print("data and stuff\n"); 
 $fh.close; 

Or equivalently with say, thus the explicit newline is no longer necessary:

my $fh = open "testfile", :w; 
 $fh.say("data and stuff"); 
 $fh.close; 

We can simplify this by using spurt to open the file in write mode, writing the data to the file and closing it again for us:

spurt "testfile", "data and stuff\n"; 

By default all (text) files are written as UTF-8, however if necessary, an explicit encoding can be specified via the :enc option:

spurt "testfile", "latin1 text: äöüß", enc => "latin1"; 

Writing formatted strings to a file is not directly supported at the moment because function 'printf' is not yet a method of IO::Handle. However, as a work-around, one can use function 'sprintf' to assign a formatted string to a Str object that can then be used with methods '.say' or '.print' as desired.

To append to a file, specify the :a option when opening the file handle explicitly,

my $fh = open "testfile", :a; 
 $fh.print("more data\n"); 
 $fh.close; 

or equivalently with say, thus the explicit newline is no longer necessary,

my $fh = open "testfile", :a; 
 $fh.say("more data"); 
 $fh.close; 

or even simpler with the :append option in the call to spurt:

spurt "testfile", "more data\n", :append; 

To explicitly write binary data to a file, open it with the :bin option. The input/output operations then will take place using the Buf type instead of the Str type.

22.3 Copying and renaming files

Routines copy, rename, and move are available to avoid low-level system commands. See details at copy, rename, and move. Some examples:

my $filea = 'foo'; 
 my $fileb = 'foo.bak'; 
 my $filec = '/disk1/foo';  # note 'diskN' is assumed to be a physical storage device 
 
 copy $filea, $fileb;              # overwrites $fileb if it exists 
 copy $filea, $fileb, :createonly; # fails if $fileb exists 
 
 rename $filea, 'new-foo';              # overwrites 'new-foo' if it exists 
 rename $filea, 'new-foo', :createonly; # fails if 'new-foo' exists 
 
 # use move when a system-level rename may not work 
 move $fileb, '/disk2/foo';              # overwrites '/disk2/foo' if it exists 
 move $fileb, '/disk2/foo', :createonly; # fails if '/disk2/foo' exists 

22.4 Checking files and directories

Use the e method on an IO::Handle object to test whether the file or directory exists.

if "nonexistent_file".IO.e { 
     say "file exists"; 
 } 
 else { 
     say "file doesn't exist"; 
 } 

It is also possible to use the colon pair syntax to achieve the same thing:

if "path/to/file".IO ~~ :e { 
     say 'file exists'; 
 } 
my $file = "path/to/file";
if $file.IO ~~ :e {
    say 'file exists';
}

Similarly to the file existence check, one can also check to see if a path is a directory. For instance, assuming that the file testfile and the directory lib exist, we would obtain from the existence test method e the same result, namely that both exist:

say "testfile".IO.e;  # OUTPUT: «True␤» 
 say "lib".IO.e;       # OUTPUT: «True␤» 

However, since only one of them is a directory, the directory test method d will give a different result:

say "testfile".IO.d;  # OUTPUT: «False␤» 
 say "lib".IO.d;       # OUTPUT: «True␤» 

Naturally the tables are turned if we check to see if the path is a file via the file test method f:

say "testfile".IO.f;  # OUTPUT: «True␤» 
 say "lib".IO.f;       # OUTPUT: «False␤» 

There are other methods that can be used to query a file or directory, some useful ones are:

my $f = "file"; 
 
 say $f.IO.modified; # return time of last file (or directory) change 
 say $f.IO.accessed; # return last time file (or directory) was read 
 say $f.IO.s;        # return size of file (or directory inode) in bytes 

See more methods and details at IO::Path.

22.5 Getting a directory listing

To list the contents of the current directory, use the dir function. It returns a list of IO::Path objects.

say dir;          # OUTPUT: «"/path/to/testfile".IO "/path/to/lib".IO␤»

To list the files and directories in a given directory, simply pass a path as an argument to dir:

say dir "/etc/";  # OUTPUT: «"/etc/ld.so.conf".IO "/etc/shadow".IO ....␤»

22.6 Creating and removing directories

To create a new directory, simply call the mkdir function with the directory name as its argument:

mkdir "newdir"; 

The function returns the name of the created directory on success and Nil on failure. Thus the standard Perl idiom works as expected:

mkdir "newdir" or die "$!"; 

Use rmdir to remove empty directories:

rmdir "newdir" or die "$!"; 

23 Inter-Process Communication

Programs running other programs and communicating with them

23.1 running

Many programs need to be able to run other programs. Running a program in Perl 6 is as easy as:

run 'git', 'status';

This line runs the program named "git" and passes "git" and "status" to its command-line. It will find the program using the %*ENV<PATH> setting.

If you would like to run a program by sending a command-line to the shell, there's a tool for that as well. All shell meta characters are interpreted by the shell, including pipes, redirects, environment variable substitutions and so on.

shell 'ls -lR | gzip -9 > ls-lR.gz';

Caution should be taken when using shell with user input.

23.2 proc

Both run and shell return a Proc object, which can be used to communicate with the process in more detail. Please note that unless you close all output pipes, the program will usually not terminate.

my $git = run 'git', 'log', '--oneline', :out;
for $git.out.lines -> $line {
    my ($sha, $subject) = $line.split: ' ', 2;
    say "$subject [$sha]";
}
$git.out.close();

If the program fails (exits with a non-zero exit code), it will throw an exception when the returned Proc object is sunk. You can save it into a variable, even anonymous one, to prevent the sinking:

$ = run '/bin/false'; # does not sink the Proc and so does not throw

You can tell the Proc object to capture output as a file handle by passing the :out and :err flags. You may also pass input via the :in flag.

my $echo = run 'echo', 'Hello, world', :out;
my $cat  = run 'cat', '-n', :in($echo.out), :out;
say $cat.out.get;
$cat.out.close();

You may also use Proc to capture the PID, send signals to the application, and check the exitcode.

my $crontab = run 'crontab', '-l';
if $crontab.exitcode == 0 {
    say 'crontab -l ran ok';
}
else {
    say 'something went wrong';
}

23.3 async

When you need more control over the communication with and from another process, you will want to make use of Proc::Async. This class provides support for asynchronous communication with a program, as well as the ability to send signals to that program.

# Get ready to run the program 
 my $log = Proc::Async.new('tail', '-f',  '/var/log/system.log'); 
 $log.stdout.tap(-> $buf { print $buf }); 
 $log.stderr.tap(-> $buf { $*ERR.print($buf) }); 
 
 # Start the program 
 my $done = $log.start; 
 sleep 10; 
 
 # Tell the program to stop 
 $log.kill('QUIT'); 
 
 # Wait for the program to finish 
 await $done; 

Here is a small program that uses the "tail" program to print out the contents of the log named system.log for 10 seconds and then tells the program to stop with a QUIT signal.

Whereas Proc provides access to output using IO::Handles, Proc::Async provides access using asynchronous supplies (see Supply).

If you want to run a program and do some work while you wait for the original program to finish, the start routine returns a Promise, which is kept when the program quits.

Use the write method to pass data into the program.

24 Lists, Sequences, and Arrays

Positional data constructs

Lists have been a central part of computing since before there were computers, during which time many devils have taken up residence in their details. They were actually one of the hardest parts of Perl 6 to design, but through persistence and patience, Perl 6 has arrived with an elegant system for handling them.

24.1 Literal Lists

Literal List s are created with commas and semicolons not with parentheses, so:

1, 2;        # This is two-element list
(1, 2);      # This is also a List, in parentheses
(1; 2);      # same List (see below)
(1);         # This is not a List, just a 1 in parentheses
(1,);        # This is a one-element List

There is one exception, empty lists are created with just parenthesis:

    ();          # This is an empty List 
     (,);         # This is a syntax error 

Note that hanging commas are just fine as long as the beginning and end of a list are clear, so feel free to use them for easy code editing.

Parentheses can be used to mark the beginning and end of a List, so:

(1, 2), (1, 2); # This is a list of two lists.

Lists of Lists can also be created by combining comma and semicolon. This is also called multi-dimensional syntax, because it is most often used to index multidimensional arrays.

say so (1,2; 3,4) eqv ((1,2), (3,4));
# OUTPUT: «True␤»
say so (1,2; 3,4;) eqv ((1,2), (3,4));
# OUTPUT: «True␤»
say so ("foo";) eqv ("foo") eqv (("foo")); # not a list
# OUTPUT: «True␤»

Unlike a comma, a hanging semicolon does not create a multidimensional list in a literal. However, be aware that this behavior changes in most argument lists, where the exact behavior depends on the function... but will usually be:

say('foo';);   # a list with one element and the empty list
# OUTPUT: «(foo)()␤»
say(('foo';)); # no list, just the string "foo"
# OUTPUT: «foo␤»

Because the semicolon doubles as a statement terminator it will end a literal list when used at the top level, instead creating a statement list. If you want to create a statement list inside parenthesis, use a sigil before the parenthesis:

say so (42) eqv $(my $a = 42; $a;);
# OUTPUT: «True␤»
say so (42,42) eqv (my $a = 42; $a;);
# OUTPUT: «True␤»

Individual elements can be pulled out of a list using a subscript. The first element of a list is at index number zero:

say (1, 2)[0];  # says 1 
 say (1, 2)[1];  # says 2 
 say (1, 2)[2];  # says Nil 
 say (1, 2)[-1]; # Error 
 say ((<a b>,<c d>),(<e f>,<g h>))[1;0;1]; # says "f" 

24.2 The @ sigil

Variables in Perl 6 whose names bear the @ sigil are expected to contain some sort of list-like object. Of course, other variables may also contain these objects, but @-sigiled variables always do, and are expected to act the part.

By default, when you assign a List to an @-sigiled variable, you create an Array. Those are described below. If, instead you want to put an actual List into an @-sigiled variable, you can use binding with := instead.

my @a := 1, 2, 3;

One of the ways @-sigiled variables act like lists is by always supporting positional subscripting. Anything bound to a @-sigiled value must support the Positional role which guarantees this:

my @a := 1; # Type check failed in binding; expected Positional but got Int 

24.3 Reset a List Container

To remove all elements from a Positional container assign Empty , the empty list () or a Slip of the empty list to the container.

my @a = 1, 2, 3;
@a = ();
@a = Empty;
@a = |();

24.4 Iteration

All lists may be iterated, which means taking each element from the list in order and stopping after the last element:

for 1, 2, 3 { .say }  # OUTPUT: «1␤2␤3␤»

24.5 Testing for Elements

To test for elements convert the List or Array to a Set or use a Set operator.

my @a = <foo bar buzz>;
say @a.Set<bar buzz>; # OUTPUT: «(True True)␤»
say so 'bar' ∈ @a;    # OUTPUT: «True␤»

24.5.1 Sequences

Not all lists are born full of elements. Some only create as many elements as they are asked for. These are called sequences, which are of type Seq. As it so happens, loops return Seqs.

(loop { 42.say })[2]  # OUTPUT: «42␤42␤42␤»

So, it is fine to have infinite lists in Perl 6, just so long as you never ask them for all their elements. In some cases, you may want to avoid asking them how long they are too – Perl 6 will try to return Inf if it knows a sequence is infinite, but it cannot always know.

TODO link or describe C<...>

Although the Seq class does provide some positional subscripting, it does not provide the full interface of Positional, so an @-sigiled variable may not be bound to a Seq.

my @s := Seq.new(<a b c>); CATCH { default { say .^name, ' ', .Str } }
# OUTPUT«Type check failed in binding to $iter; expected Iterator but got List ($("a", "b", "c"))␤  in block <unit> at <tmp> line 1␤␤»

This is because the Seq does not keep values around after you have used them. This is useful behavior if you have a very long sequence, as you may want to throw values away after using them, so that your program does not fill up memory. For example, when processing a file of a million lines:

for 'filename'.IO.lines -> $line { 
     do-something-with($line); 
 } 

You can be confident that the entire content of the file will not stay around in memory, unless you are explicitly storing the lines somewhere.

On the other hand, you may want to keep old values around in some cases. It is possible to hide a Seq inside a List, which will still be lazy, but will remember old values. This is done by calling the .list method. Since this List fully supports Positional, you may bind it directly to an @-sigiled variable.

my @s := (loop { 42.say }).list;
@s[2]; # says 42 three times
@s[1]; # does not say anything
@s[4]; # says 42 two more times

You may also use the .cache method instead of .list, depending on how you want the references handled. See the page on Seq for details.

TODO document .iterator

24.5.2 Slips

Sometimes you want to insert the elements of a list into another list. This can be done with a special type of list called a Slip.

say (1, (2, 3), 4) eqv (1, 2, 3, 4);         # OUTPUT: «False␤»
say (1, Slip.new(2, 3), 4) eqv (1, 2, 3, 4); # OUTPUT: «True␤»
say (1, slip(2, 3), 4) eqv (1, 2, 3, 4);     # OUTPUT: «True␤»

Another way to make a Slip is with the | prefix operator. Note that this has a tighter precedence than the comma, so it only affects a single value, but unlike the above options, it will break Scalars.

say (1, |(2, 3), 4) eqv (1, 2, 3, 4);        # OUTPUT: «True␤»
say (1, |$(2, 3), 4) eqv (1, 2, 3, 4);       # OUTPUT: «True␤»
say (1, slip($(2, 3)), 4) eqv (1, 2, 3, 4);  # OUTPUT: «False␤»

24.6 Lazy Lists

Lists can be lazy, what means that their values are computed on demand and stored for later use. To create a lazy list use gather/take or the sequence operator. You can also write a class that implements the role Iterable and returns True on a call to is-lazy. Please note that some methods like elems may cause the entire list to be computed what will fail if the list is also infinite.

my @l = 1,2,4,8...Inf;
say @l[0..16];
# OUTPUT: «(1 2 4 8 16 32 64 128 256 512 1024 2048 4096 8192 16384 32768 65536)␤»

24.7 Immutability

The lists we have talked about so far (List, Seq and Slip) are all immutable. This means you cannot remove elements from them, or re-bind existing elements:

(1, 2, 3)[0]:delete; # Error Can not remove elements from a List 
 (1, 2, 3)[0] := 0;   # Error Cannot use bind operator with this left-hand side 
 (1, 2, 3)[0] = 0;    # Error Cannot modify an immutable Int 

However, if any of the elements is wrapped in a Scalar you can still change the value which that Scalar points to:

my $a = 2;
(1, $a, 3)[1] = 42;
$a.say;            # OUTPUT: «42␤»

...that is, it is only the list structure itself – how many elements there are and each element's identity – that is immutable. The immutability is not contagious past the identity of the element.

24.8 List Contexts

So far we have mostly dealt with lists in neutral contexts. Lists are actually very context sensitive on a syntactical level.

24.8.1 List Assignment Context

When a list appears on the right hand side of an assignment into a @-sigiled variable, it is "eagerly" evaluated. This means that a Seq will be iterated until it can produce no more elements. This is one of the places you do not want to put an infinite list, lest your program hang and, eventually, run out of memory:

my $i = 3;
my @a = (loop { $i.say; last unless --$i }); # OUTPUT: «3␤2␤1␤»
say "take off!";

24.8.2 Flattening "Context"

When you have a list that contains sub-lists, but you only want one flat list, you may flatten the list to produce a sequence of values as if all parentheses were removed. This works no matter how many levels deep the parentheses are nested.

say (1, (2, (3, 4)), 5).flat eqv (1, 2, 3, 4, 5) # OUTPUT: «True␤»

This is not really a syntactical "context" as much as it is a process of iteration, but it has the appearance of a context.

Note that Scalar s around a list will make it immune to flattening:

for (1, (2, $(3, 4)), 5).flat { .say } # OUTPUT: «1␤2␤(3 4)␤5␤»

...but an @-sigiled variable will spill its elements.

my @l := 2, (3, 4);
for (1, @l, 5).flat { .say };      # OUTPUT: «1␤2␤3␤4␤5␤»
my @a = 2, (3, 4);                 # Arrays are special, see below
for (1, @a, 5).flat { .say };      # OUTPUT: «1␤2␤(3 4)␤5␤»

24.8.3 Argument List (Capture) Context

When a list appears as arguments to a function or method call, special syntax rules are at play: the list is immediately converted into a Capture. A Capture itself has a List (.list) and a Hash (.hash). Any Pair literals whose keys are not quoted, or which are not parenthesized, never make it into .list. Instead, they are considered to be named arguments and squashed into .hash. See the page on Capture for the details of this processing.

Consider the following ways to make a new Array from a List. These ways place the List in an argument list context and because of that, the Array only contains 1 and 2 but not the Pair :c(3), which is ignored.

Array.new(1, 2, :c(3));
Array.new: 1, 2, :c(3);
new Array: 1, 2, :c(3);

In contrast, these ways do not place the List in argument list context, so all the elements, even the Pair :c(3), are placed in the Array.

Array.new((1, 2, :c(3)));
(1, 2, :c(3)).Array;
my @a = 1, 2, :c(3); Array.new(@a);
my @a = 1, 2, :c(3); Array.new: @a;
my @a = 1, 2, :c(3); new Array: @a;

In argument list context the | prefix operator applied to a Positional will always slip list elements as positional arguments to the Capture, while a | prefix operator applied to an Associative will slip pairs in as named parameters:

my @a := 2, "c" => 3;
Array.new(1, |@a, 4);    # Array contains 1, 2, :c(3), 4
my %a = "c" => 3;
Array.new(1, |%a, 4);    # Array contains 1, 4

24.8.4 Slice Indexing Context

From the perspective of the List inside a slice subscript, is only remarkable in that it is unremarkable: because adverbs to a slice are attached after the ], the inside of a slice is not an argument list, and no special processing of pair forms happens.

Most Positional types will enforce an integer coercion on each element of a slice index, so pairs appearing there will generate an error, anyway:

(1, 2, 3)[1, 2, :c(3)] # OUTPUT: «Method 'Int' not found for invocant of class 'Pair'␤» 

...however this is entirely up to the type – if it defines an order for pairs, it could consider :c(3) a valid index.

Indices inside a slice are usually not automatically flattened, but neither are sublists usually coerced to Int. Instead, the list structure is kept intact, causing a nested slice operation that replicates the structure in the result:

say ("a", "b", "c")[(1, 2), (0, 1)] eqv (("b", "c"), ("a", "b")) # OUTPUT: «True␤»

24.8.5 Range as Slice

A Range is a container for a lower and a upper boundary. Generating a slice with a Range will include any index between those bounds, including the bounds. For infinite upper boundaries we agree with mathematicians that Inf equals Inf-1.

my @a = 1..5;
say @a[0..2];     # OUTPUT: «(1 2 3)␤»
say @a[0..^2];    # OUTPUT: «(1 2)␤»
say @a[0..*];     # OUTPUT: «(1 2 3 4 5)␤»
say @a[0..^*];    # OUTPUT: «(1 2 3 4 5)␤»
say @a[0..Inf-1]; # OUTPUT: «(1 2 3 4 5)␤»

24.8.6 Array Constructor Context

Inside an Array Literal, the list of initialization values is not in capture context and is just a normal list. It is, however, eagerly evaluated just as in assignment.

[ 1, 2, :c(3) ] eqv Array.new((1, 2, :c(3))); # OUTPUT: «True␤»
[while $++ < 2 { 42.say; 43 }].map: *.say;    # OUTPUT: «42␤42␤43␤43␤»
(while $++ < 2 { 42.say; 43 }).map: *.say;    # OUTPUT: «42␤43␤42␤43␤»

Which brings us to Arrays...

24.9 Arrays

Arrays differ from lists in three major ways: Their elements may be typed, they automatically itemize their elements, and they are mutable. Otherwise they are Lists and are accepted wherever lists are.

say Array ~~ List     # OUTPUT: «True␤»

A fourth, more subtle, way they differ is that when working with Arrays, it can sometimes be harder to maintain laziness or work with infinite sequences.

24.9.1 Typing

Arrays may be typed such that their slots perform a typecheck whenever they are assigned to. An Array that only allows Int values to be assigned is of type Array[Int] and one can create one with Array[Int].new. If you intend to use an @-sigiled variable only for this purpose, you may change its type by specifying the type of the elements when declaring it:

my Int @a = 1, 2, 3;              # An Array that contains only Ints 
 my @b := Array[Int].new(1, 2, 3); # Same thing, but the variable is not typed 
 say @b eqv @a;                    # says True. 
 my @c = 1, 2, 3;                  # An Array that can contain anything 
 say @b eqv @c;                    # says False because types do not match 
 say @c eqv (1, 2, 3);             # says False because one is a List 
 say @b eq @c;                     # says True, because eq only checks values 
 say @b eq (1, 2, 3);              # says True, because eq only checks values 
 
 @a[0] = 42;                       # fine 
 @a[0] = "foo";                    # error: Type check failed in assignment 

In the above example we bound a typed Array object to a @-sigil variable for which no type had been specified. The other way around does not work – you may not bind an Array that has the wrong type to a typed @-sigiled variable:

my @a := Array[Int].new(1, 2, 3);     # fine 
 @a := Array[Str].new("a", "b");       # fine, can be re-bound 
 my Int @b := Array[Int].new(1, 2, 3); # fine 
 @b := Array.new(1, 2, 3);             # error: Type check failed in binding 

When working with typed arrays, it is important to remember that they are nominally typed. This means the declared type of an array is what matters. Given the following sub declaration:

sub mean(Int @a) {
    @a.sum / @a.elems
}

Calls that pass an Array[Int] will be successful:

my Int @b = 1, 3, 5; 
 say mean(@b);                       # @b is Array[Int] 
 say mean(Array[Int].new(1, 3, 5));  # Anonymous Array[Int] 
 say mean(my Int @ = 1, 3, 5);       # Another anonymous Array[Int] 

However, the following calls will all fail, due to passing an untyped array, even if the array just happens to contain Int values at the point it is passed:

my @c = 1, 3, 5; 
 say mean(@c);                       # Fails, passing untyped Array 
 say mean([1, 3, 5]);                # Same 
 say mean(Array.new(1, 3, 5));       # Same again 

Note that in any given compiler, there may be fancy, under-the-hood, ways to bypass the type check on arrays, so when handling untrusted input, it can be good practice to perform additional type checks, where it matters:

for @a -> Int $i { $_++.say }; 

However, as long as you stick to normal assignment operations inside a trusted area of code, this will not be a problem, and typecheck errors will happen promptly during assignment to the array, if they cannot be caught at compile time. None of the core functions provided in Perl 6 for operating on lists should ever produce a wonky typed Array.

Nonexistent elements (when indexed), or elements to which Nil has been assigned, will assume a default value. This default may be adjusted on a variable-by-variable basis with the is default trait. Note that an untyped @-sigiled variable has an element type of Mu, however its default value is an undefined Any:

my @a;
@a.of.perl.say;                 # OUTPUT: «Mu␤»
@a.default.perl.say;            # OUTPUT: «Any␤»
@a[0].say;                      # OUTPUT: «(Any)␤»
my Numeric @n is default(Real);
@n.of.perl.say;                 # OUTPUT: «Numeric␤»
@n.default.perl.say;            # OUTPUT: «Real␤»
@n[0].say;                      # OUTPUT: «(Real)␤»

24.9.2 Fixed Size Arrays

To limit the dimensions of an Array provide the dimensions separated by , or ; in brackets after the name of the array container. The values of such an Arrays will default to Any. The shape can be accessed at runtime via the shape method.

my @a[2,2];
dd @a;
# OUTPUT: «Array.new(:shape(2, 2), [Any, Any], [Any, Any])␤»
say @a.shape;
# OUTPUT: «(2 2)␤»

Assignment to a fixed size Array will promote a List of Lists to an Array of Arrays.

my @a[2;2] = (1,2; 3,4);
@a[1;1] = 42;
dd @a;
# OUTPUT: «Array.new(:shape(2, 2), [1, 2], [3, 42])␤»

24.9.3 Itemization

For most uses, Arrays consist of a number of slots each containing a Scalar of the correct type. Each such Scalar, in turn, contains a value of that type. Perl 6 will automatically type-check values and create Scalars to contain them when Arrays are initialized, assigned to, or constructed.

This is actually one of the trickiest parts of Perl 6 list handling to get a firm understanding of.

First, be aware that because itemization in Arrays is assumed, it essentially means that $(…)s are being put around everything that you assign to an array, if you do not put them there yourself. On the other side, Array.perl does not put $ to explicitly show scalars, unlike List.perl:

((1, 2), $(3, 4)).perl.say; # says "((1, 2), $(3, 4))"
[(1, 2), $(3, 4)].perl.say; # says "[(1, 2), (3, 4)]"
                            # ...but actually means: "[$(1, 2), $(3, 4)]"

It was decided all those extra dollar signs and parentheses were more of an eye sore than a benefit to the user. Basically, when you see a square bracket, remember the invisible dollar signs.

Second, remember that these invisible dollar signs also protect against flattening, so you cannot really flatten the elements inside of an Array with a normal call to flat or .flat.

((1, 2), $(3, 4)).flat.perl.say; # OUTPUT: «(1, 2, $(3, 4)).Seq␤»
[(1, 2), $(3, 4)].flat.perl.say; # OUTPUT: «($(1, 2), $(3, 4)).Seq␤»

Since the square brackets do not themselves protect against flattening, you can still spill the elements out of an Array into a surrounding list using flat.

(0, [(1, 2), $(3, 4)], 5).flat.perl.say; # OUTPUT: «(0, $(1, 2), $(3, 4), 5).Seq␤»

...the elements themselves, however, stay in one piece.

This can irk users of data you provide if you have deeply nested Arrays where they want flat data. Currently they have to deeply map the structure by hand to undo the nesting:

say gather [0, [(1, 2), [3, 4]], $(5, 6)].deepmap: *.take; # OUTPUT: «(1 2 3 4 5 6)␤»

...future versions of Perl 6 might find a way to make this easier. However, not returning Arrays or itemized lists from functions, when non-itemized lists are sufficient, is something that one should consider as a courtesy to their users:

The fact that all elements of an array are itemized (in Scalar containers) is more a gentleman's agreement than a universally enforced rule, and it is less well enforced that typechecks in typed arrays. See the section below on binding to Array slots.

24.9.4 Literal Arrays

Literal Arrays are constructed with a List inside square brackets. The List is eagerly iterated (at compile time if possible) and values in the list are each type-checked and itemized. The square brackets themselves will spill elements into surrounding lists when flattened, but the elements themselves will not spill due to the itemization.

24.9.5 Mutability

Unlike lists, Arrays are mutable. Elements may deleted, added, or changed.

my @a = "a", "b", "c";
@a.say;                  # OUTPUT: «[a b c]␤»
@a.pop.say;              # OUTPUT: «c␤»
@a.say;                  # OUTPUT: «[a b]␤»
@a.push("d");
@a.say;                  # OUTPUT: «[a b d]␤»
@a[1, 3] = "c", "c";
@a.say;                  # OUTPUT: «[a c d c]␤»

24.9.5.1 Assigning

Assignment of a list to an Array is eager. The list will be entirely evaluated, and should not be infinite or the program may hang. Assignment to a slice of an Array is, likewise, eager, but only up to the requested number of elements, which may be finite:

my @a;
@a[0, 1, 2] = (loop { 42 });
@a.say;                     # OUTPUT: «[42 42 42]␤»

During assignment, each value will be typechecked to ensure it is a permitted type for the Array. Any Scalar will be stripped from each value and a new Scalar will be wrapped around it.

24.9.5.2 Binding

Individual Array slots may be bound the same way $-sigiled variables are:

my $b = "foo";
my @a = 1, 2, 3;
@a[2] := $b;
@a.say;          # OUTPUT: «[1 2 "foo"]␤»
$b = "bar";
@a.say;          # OUTPUT: «[1 2 "bar"]␤»

...but binding Array slots directly to values is strongly discouraged. If you do, expect surprises with built-in functions. The only time this would be done is if a mutable container that knows the difference between values and Scalar-wrapped values is needed, or for very large Arrays where a native-typed array cannot be used. Such a creature should never be passed back to unsuspecting users.

25 Core Modules

Core modules that may be useful to module authors

The Perl core has a few modules you may want to use. Following is a list of them along with a link to their source code.

26 Module Development Utilities

What can help you write/test/improve your module(s)

Here is a list of modules that you can find in the Perl 6 ecosystem which aim to make the experience of developing Perl 6 modules more fun.

26.1 Module builder and Authoring tools

Some modules and tools to help you with generating files that are part of a module distribution.

26.2 Tests

Some tests of module quality.

26.3 NativeCall

Here some modules to help you work with NativeCall.

26.4 Sample modules

Modules that exist only as minimalist examples, tests for installers, or skeletons.

27 Modules

How to create, use and distribute Perl 6 modules

27.1 Creating and Using Modules

A module is usually a source file or set of source files

Technically a module is a set of compunits which are usually files but could come from anywhere as long as there is a compunit repository that can provide it. See S11 .
that expose Perl 6 constructs. These are typically packages (classes, roles, grammars), subroutines, and sometimes variables. In Perl 6 module can also refer to a type of package declared with the module keyword (see example below) but here we mostly mean "module" as a set of source files in a namespace.

27.1.1 Basic Structure

Module distributions (in the set of related source files sense) in Perl 6 have the same structure as any distribution in the Perl family of languages: there is a main project directory containing a README and a LICENSE file, a lib directory for the source files, which may be individually referred to as modules and/or may themselves define modules with the module keyword

As synopsis S11 says: Confusing? Yes it is.
, a t directory for tests, and possibly a bin directory for executable programs and scripts.

Source files generally use the standard .pm extension, and scripts or executables use .pl. However, if you wish to highlight that the file is written in Perl 6 you can use the .pm6 extension for modules, and .p6 or .pl6 extension for scripts. Test files still use the normal .t extension. For windows compatibility, .p6 is the preferred extension for cross-platform scripts.

27.1.2 Loading and Basic Importing

Loading a module makes the packages in the same namespace declared within available in the file scope of the loader. Importing from a module makes the symbols exported available in the lexical scope of the importing statement.

27.1.2.1 need

need loads a compunit at compile time.

need MyModule;

Any packages in the namespace defined within will also be available.

# MyModule.pm
unit module MyModule;

class MyModule::Class { ... }

MyModule::Class will be defined when MyModule is loaded.

class Class { ... } won't get exported automatically on loading...not sure if bug or..

27.1.2.2 use

use loads and then imports from a compunit at compile time.

use MyModule;

It is equivalent to:

 need  MyModule; 
 import MyModule; 

See also Selective Importing to restrict what you import.

27.1.2.3 require

require loads a compunit and imports definite symbols at runtime.

say "loading MyModule";
require MyModule;

The compunit name can be in a runtime variable if you put it inside an indirect lookup.

my $name = 'MyModule';
require ::($name);

The symbols provided by the loaded module will not be imported into the current scope. You may use dynamic lookup or dynamic subsets to use them by providing the fully qualified name of a symbol.

To import symbols you must define them at compile time. NOTE: require is lexically scoped:

sub do-something {
   require MyModule <&something>;
   say ::('MyModule'); # MyModule symbol exists here
   something() # &something will be defined here
}
say ::('MyModule'); # This will NOT contain the MyModule symbol
do-something();
# &something will not be defined here

If MyModule doesn't export &something then require will fail.

A require with compile-time symbol will install a placeholder package that will be updated to the loaded module, class, or package. Note that the placeholder will be kept, even if require failed to load the module. This means that checking if a module loaded like this is wrong:

# *** WRONG: ***
try require Foo;
if ::('Foo') ~~ Failure { say "Failed to load Foo!"; }
# *** WRONG: ***

As the compile-time installed package causes ::('Foo') to never be a Failure. The correct way is:

# Use return value to test whether loading succeeded:
(try require Foo) === Nil and say "Failed to load Foo!";

# Or use a run-time symbol lookup with require, to avoid compile-time
# package installation:
try require ::('Foo');
if ::('Foo') ~~ Failure {
    say "Failed to load Foo!";
}

27.1.3 Exporting and Selective Importing

27.1.3.1 is export

Packages, subroutines, variables, constants and enums are exported by marking them with the is export trait (also note the tags available for indicating authors and versions).

unit module MyModule:ver<1.0.3>:auth<John Hancock (jhancock@example.com)>; 
 our $var is export = 3; 
 sub foo is export { ... }; 
 constant FOO is export = "foobar"; 
 enum FooBar is export <one two three>; 
 
 # Packages like classes can be exported too 
 class MyClass is export {}; 
 
 # If a subpackage is in the namespace of the current package 
 # it doesn't need to be explicitly exported 
 class MyModule::MyClass {}; 

As with all traits, if applied to a routine, "is export" should appear after any argument list.

sub foo(Str $string) is export { ... } 

You can pass named parameters to is export to group symbols for exporting so that the importer can pick and choose. There are three predefined tags: ALL, DEFAULT and MANDATORY.

# lib/MyModule.pm 
 unit module MyModule; 
 sub bag        is export             { ... } 
 sub pants      is export(:MANDATORY) { ... } # objects with tag ':MANDATORY' are always exported 
 sub sunglasses is export(:day)       { ... } 
 sub torch      is export(:night)     { ... } 
 sub underpants is export(:ALL)       { ... } 
# main.pl 
 use lib 'lib'; 
 use MyModule;          # bag, pants 
 use MyModule :DEFAULT; # the same 
 use MyModule :day;     # pants, sunglasses 
 use MyModule :night;   # pants, torch 
 use MyModule :ALL;     # bag, pants, sunglasses, torch, underpants 

Note there currently is no way for the user to import a single object if the module author hasn't made provision for that, and it is not an easy task at the moment (see RT #127305). One way the author can provide such access is to give each export trait its own unique tag. (And the tag can be the object name!) Then the user can either (1) import all objects:

use Foo :ALL; 

or (2) import one or more objects selectively:

use Foo :bar, :s5; 

Notes:

1. The :MANDATORY tag on an exported sub ensures it will be exported no matter whether the using program adds any tag or not.

2. All exported subs without an explicit tag are implicitly :DEFAULT.

3. The space after the module name and before the tag is mandatory.

4. Multiple import tags may be used (separated by commas). For example:

# main.pl 
 use lib 'lib'; 
 use MyModule :day, :night; # pants, sunglasses, torch 

5. Multiple tags may be used in the export trait, but they must all be separated by either commas, or whitespace, but not both.

sub foo() is export(:foo :s2 :net) {} 
 sub bar() is export(:bar, :s3, :some) {} 

27.1.3.2 UNIT::EXPORT::*

Beneath the surface, is export is adding the symbols to a UNIT scoped package in the EXPORT namespace. For example, is export(:FOO) will add the target to the UNIT::EXPORT::FOO package. This is what Perl 6 is really using to decide what to import.

unit module MyModule; 
 
 sub foo is export { ... } 
 sub bar is export(:other) { ... } 

Is the same as:

unit module MyModule; 
 
 my package EXPORT::DEFAULT { 
     our sub foo { ... } 
 } 
 
 my package EXPORT::other { 
     our sub bar { ... } 
 } 

For most purposes is export is sufficient but the EXPORT packages are useful when you want to produce the exported symbols dynamically. For example:

# lib/MyModule.pm 
 unit module MyModule; 
 
 my package EXPORT::DEFAULT { 
    for <zero one two three four>.kv -> $number, $name { 
       for <sqrt log> -> $func { 
          OUR::{'&' ~ $func ~ '-of-' ~ $name } := sub { $number."$func"() }; 
       } 
    } 
 } 
 
# main.pl 
 use MyModule; 
 say sqrt-of-four; # OUTPUT: «2␤» 
 say log-of-zero;  # OUTPUT: «-Inf␤» 

27.1.3.3 EXPORT

You can export arbitrary symbols with an EXPORT sub. EXPORT must return a Map, where the keys are the symbol names and the values are the desired values. The names should include the sigil (if any) for the associated type.

# lib/MyModule.pm 
 
 class MyModule::Class { ... } 
 
 sub EXPORT { 
     { 
      '$var'   => 'one', 
      '@array' => <one two three>, 
      '%hash'  => { one => 'two', three => 'four' }, 
      '&doit'   => sub { ... }, 
      'ShortName' => MyModule::Class 
     } 
 } 
# main.pl 
 use lib 'lib'; 
 use MyModule; 
 say $var; 
 say @array; 
 say %hash; 
 doit(); 
 say ShortName.new; # OUTPUT: «MyModule::Class.new␤» 

Note, EXPORT can't be declared inside a package because presently Rakudo (2015.09) treats EXPORT as part of the compunit rather than the package.

Whereas UNIT::EXPORT packages deal with the named parameters passed to use, the EXPORT sub handles positional parameters. If you pass positional parameters to use they will be passed to EXPORT. If a positional is passed the module no longer exports default symbols. You may still import them explicitly by passing :DEFAULT to use along with your positional parameters.

# lib/MyModule 
 
 class MyModule::Class {} 
 
 sub EXPORT($short_name?) { 
     { 
       do $short_name => MyModule::Class if $short_name 
     } 
 } 
 
 sub always is export(:MANDATORY) { say "works" } 
 
 #import with :ALL or :DEFAULT to get 
 sub shy is export { say "you found me!" } 
# main.pl 
 use lib 'lib'; 
 use MyModule 'foo'; 
 say foo.new(); # MyModule::Class.new 
 always();      # OK   - is imported 
 shy();         # FAIL - won't be imported 

You can combine `EXPORT` with type captures for interesting effect. This example creates a `?` postfix which will only work on Cools.

# lib/MakeQuestionable.pm 
 sub EXPORT(::Questionable) { 
     my multi postfix:<?>(Questionable $_) { .so }; 
     { 
       '&postfix:<?>' => &postfix:<?>, 
     } 
 } 
use MakeQuestionable Cool; 
 say 0?, 1?, {}?, { a => "b" }?; # OUTPUT: «False True False True␤» 

27.1.4 Introspection

To list exported symbols of a module first query the export tags supported by the module.

use URI::Escape;
dd URI::Escape::EXPORT::.keys;
# OUTPUT: «("DEFAULT", "ALL").Seq»

Then use the tag you like and pick the symbol by its name.

dd URI::Escape::EXPORT::DEFAULT::.keys;
# OUTPUT: «("\&uri-escape", "\&uri_escape", "\&uri-unescape", "\&uri_unescape").Seq»
my &escape-uri = URI::Escape::EXPORT::DEFAULT::<&uri_escape>;

27.1.5 Finding Modules

A user may have a collection of modules not found in the normal ecosystem, maintained by a module or package manager, but needed regularly. Instead of using the use lib pragma one can use the PERL6LIB environment variable to point to module locations. For example:

export PERL6LIB=/path/to/my-modules,/path/to/more/modules

Note that the comma (',') is used as the directory separator (instead of the colon (':') as with Perl 5 for PERL5LIB or PERLLIB).

The include path will be searched recursively for any modules when Rakudo is started. Directories that start with a dot are ignored and symlinks are followed.

27.2 Distributing Modules

If you've written a Perl 6 module and would like to share it with the community, we'd be delighted to have it listed in the Perl 6 modules directory. :)

For now, the process requires that you use git for your module's version control.

The instructions herein assume that you have a GitHub account so that your module can be shared from its GitHub repository, however another provider such as GitLab should work as long as it works in a similar way.

To share your module, do the following:

That's it! Thanks for contributing to the Perl 6 community!

If you'd like to try out installing your module, use the zef module installer tool which is included with Rakudo Star Perl 6:

zef install Vortex::TotalPerspective 

This will download your module to its own working directory (~/.zef), build it there, and install the module into your local Perl 6 installation directory.

To use Vortex::TotalPerspective from your scripts, just write use Vortex::TotalPerspective, and your Perl 6 implementation will know where to look for the module file(s).

27.3 Modules and Tools Related to Module Authoring

You can find a list of modules and tools that aim to improve the experience of writing/test modules at Modules Extra

27.4 The Future of the Ecosystem

https://modules.perl6.org and github-based infrastructure is temporary. The plan is to establish something similar to Perl 5's PAUSE/CPAN/MetaCPAN infrastructure. Volunteers needed!

The rough plan is:

1. fix EVAL precomp bug (nine)
2. get Repository API straight
3. get zef up to speed
4. continue with the metacpan fork for perl6 (jdv79)

The repository with jdv's fork can be found at https://github.com/jdv/metacpan-web

You can also already upload your Perl 6 modules to Perl 5's PAUSE, selecting `Perl6` directory during the upload. That will ensure your module is indexed in Perl 6's space and not Perl 5's.

27.4.1 Contact Information

To discuss module development in general, or if your module would fill a need in the ecosystem, naming, etc., you can use the #perl6 on irc.freenode.net IRC channel.

To discuss toolchain specific questions, you can use the #perl6-toolchain on irc.freenode.net IRC channel. A repository to discuss tooling issues is also available at https://github.com/perl6/toolchain-bikeshed.

28 Meta-Object Protocol

Introspection and the Perl 6 Object System

Perl 6 is built on a meta object layer. That means that there are objects (the meta objects) that control how various object-oriented constructs (such as classes, roles, methods, attributes, enums, ...) behave.

To get a feeling for the meta object for class, here is the same example twice: once as normal declarations in Perl 6, and once expressed through the meta model:

class A {
    method x() { say 42 }
}

A.x();

corresponds to:

constant A := Metamodel::ClassHOW.new_type( name => 'A' );  # class A {
A.^add_method('x', my method x(A:) { say 42 });             # method x() .. .
A.^compose;                                                 # }

A.x();

(except that the declarative form runs at compile time, and the latter form does not).

The meta object behind an object can be obtained with $obj.HOW, where HOW stands for Higher Order Workings (or, HOW the *%@$ does this work?).

Here, the calls with .^ are calls to the meta object, so A.^compose is a shortcut for A.HOW.compose(A). The invocant is passed in the parameter list as well, to make it possible to support prototype-style type systems, where there is just one meta object (and not one meta object per type, as standard Perl 6 does it).

As the example above demonstrates, all object oriented features are available to the user, not just to the compiler. In fact the compiler just uses such calls to meta objects.

28.1 Metamethods

These are introspective macros that resemble method calls.

Metamethods are generally named with ALLCAPS, and it is considered good style to avoid creating your own methods with ALLCAPS names. This will avoid conflicts with any metamethods that may appear in future versions of the language.

28.1.1 WHAT

The type object of the type. This is a pseudo-method that can be overloaded without producing error or warning, but will be ignored.

For example 42.WHAT returns the Int type object.

28.1.2 WHICH

The object's identity value. This can be used for hashing and identity comparison, and is how the === infix operator is implemented.

28.1.3 WHO

The package supporting the object.

28.1.4 WHERE

The memory address of the object. Note that this is not stable in implementations with moving/compacting garbage collectors. Use WHICH for a stable identity indicator.

28.1.5 HOW

The metaclass object: "Higher Order Workings".

28.1.6 WHY

The attached Pod value.

28.1.7 DEFINITE

The object has a valid concrete representation. This is a pseudo-method that can be overloaded without producing error or warning, but will be ignored.

Returns True for instances and False for type objects.

28.1.8 VAR

Returns the underlying Scalar object, if there is one.

The presence of a Scalar object indicates that the object is "itemized".

.say for (1, 2, 3);           # OUTPUT: «1␤2␤3␤», not itemized
.say for $(1, 2, 3);          # OUTPUT: «(1 2 3)␤», itemized
say (1, 2, 3).VAR ~~ Scalar;  # OUTPUT: «False␤»
say $(1, 2, 3).VAR ~~ Scalar; # OUTPUT: «True␤»

28.2 Structure of the meta object system

Note: this documentation largely reflects the meta object system as implemented by the Rakudo Perl 6 compiler, since the design documents are very light on details.

For each type declarator keyword, such as class, role, enum, module, package, grammar or subset, there is a separate meta class in the Metamodel:: namespace. (Rakudo implements them in the Perl6::Metamodel:: namespace, and then maps Perl6::Metamodel to Metamodel).

Many of the these meta classes share common functionality. For example roles, grammars and classes can all contain methods and attributes, as well as being able to do roles. This shared functionality is implemented in roles which are composed into the appropriate meta classes. For example role Metamodel::RoleContainer implements the functionality that a type can hold roles and Metamodel::ClassHOW, which is the meta class behind the class keyword, does this role.

Most meta classes have a compose method that you must call when you're done creating or modifying a meta object. It creates method caches, validates things and so on, and weird behavior ensues if you forget to call it, so don't :-).

28.2.1 Bootstrapping concerns

You might wonder how Metamodel::ClassHOW can be a class, when being a class is defined in terms of Metamodel::ClassHOW, or how the roles responsible for role handling can be roles. The answer is by magic.

Just kidding. Bootstrapping is implementation specific. Rakudo does it by using the object system of the language in which itself is implemented, which happens to be (nearly) a subset of Perl 6: NQP, Not Quite Perl. NQP has a primitive, class-like kind called knowhow, which is used to bootstrap its own classes and roles implementation. knowhow is built on primitives that the virtual machine under NQP provides.

Since the object model is bootstrapped in terms of lower-level types, introspection can sometimes return low-level types instead of the ones you expect, like an NQP-level routine instead of a normal Routine object, or a bootstrap-attribute instead of Attribute.

28.2.2 Composition time and static reasoning

In Perl 6, a type is constructed as it is parsed, so in the beginning, it must be mutable. However if all types were always mutable, all reasoning about them would get invalidated at any modification of a type. For example the list of parent types and thus the result of type checking can change during that time.

So to get the best of both worlds, there is a time when a type transitions from mutable to immutable. This is called composition, and for syntactically declared types, it happens when the type declaration is fully parsed (so usually when the closing curly brace is parsed).

If you create types through the meta-object system directly, you must call .^compose on them before they become fully functional.

Most meta classes also use composition time to calculate some properties like the method resolution order, publish a method cache, and other house-keeping tasks. Meddling with types after they have been composed is sometimes possible, but usually a recipe for disaster. Don't do it.

28.2.3 Power and Responsibility

The meta object protocol offers much power that regular Perl 6 code intentionally limits, such as calling private methods on classes that don't trust you, peeking into private attributes, and other things that usually simply aren't done.

Regular Perl 6 code has many safety checks in place; not so the meta model. It is close to the underlying virtual machine, and violating the contracts with the VM can lead to all sorts of strange behaviors that, in normal code, would obviously be bugs.

So be extra careful and thoughtful when writing meta types.

28.2.4 Power, Convenience and Pitfalls

The meta object protocol is designed to be powerful enough to implement the Perl 6 object system. This power occasionally comes at the cost of convenience.

For example, when you write my $x = 42 and then proceed to call methods on $x, most of these methods end up acting on the integer 42, not on the scalar container in which it is stored. This is a piece of convenience found in ordinary Perl 6. Many parts of the meta object protocol cannot afford to offer the convenience of automatically ignoring scalar containers, because they are used to implement those scalar containers as well. So if you write my $t = MyType; ... ; $t.^compose you are composing the Scalar that the $-sigiled variable implies, not MyType.

The consequence is that you need to have a rather detailed understanding of the subtleties of Perl 6 in order to avoid pitfalls when working with the MOP, and can't expect the same "do what I mean" convenience that ordinary Perl 6 code offers.

29 Native Calling Interface

Call into dynamic libraries that follow the C calling convention

29.1 Getting Started

The simplest imaginable use of NativeCall would look something like this:

use NativeCall;
sub some_argless_function() is native('something') { * }
some_argless_function();

The first line imports various traits and types. The next line looks like a relatively ordinary Perl 6 sub declaration - with a twist. We use the "native" trait in order to specify that the sub is actually defined in a native library. The platform-specific extension (e.g., '.so' or '.dll'), as well as any customary prefixes (e.g., 'lib') will be added for you.

The first time you call "some_argless_function", the "libsomething" will be loaded and the "some_argless_function" will be located in it. A call will then be made. Subsequent calls will be faster, since the symbol handle is retained.

Of course, most functions take arguments or return values - but everything else that you can do is just adding to this simple pattern of declaring a Perl 6 sub, naming it after the symbol you want to call and marking it with the "native" trait.

29.2 Changing names

Sometimes you want the name of your Perl subroutine to be different from the name used in the library you're loading. Maybe the name is long or has different casing or is otherwise cumbersome within the context of the module you are trying to create.

NativeCall provides a "symbol" trait for you to specify the name of the native routine in your library that may be different from your Perl subroutine name.

unit module Foo;
use NativeCall;
our sub init() is native('foo') is symbol('FOO_INIT') { * }

Inside of "libfoo" there is a routine called "FOO_INIT" but, since we're creating a module called Foo and we'd rather call the routine as Foo::init, we use the "symbol" trait to specify the name of the symbol in "libfoo" and call the subroutine whatever we want ("init" in this case).

29.3 Passing and Returning Values

Normal Perl 6 signatures and the returns trait are used in order to convey the type of arguments a native function expects and what it returns. Here is an example.

sub add(int32, int32) returns int32 is native("calculator") { * }

Here, we have declared that the function takes two 32-bit integers and returns a 32-bit integer. Here are some of the other types that you may pass (this will likely grow with time).

int8           (int8_t in C, also used for char)
int16          (int16_t in C, also used for short)
int32          (int32_t in C, also used for int)
int64          (int64_t in C)
uint8          (uint8_t in C, also used for unsigned char)
uint16         (uint16_t in C, also used for unsigned short)
uint32         (uint32_t in C, also used for unsigned int)
uint64         (uint64_t in C)
long           (long in C)
longlong       (long long in C, at least 64-bit)
num32          (float in C)
num64          (double in C)
Str            (C string)
CArray[int32]  (int* in C, an array of ints)
Pointer[void]  (void* in C, can point to all other types)
bool           (bool from C99)
size_t         (size_t in C)

Don't use Perl 6 native types like int or num, as they don't have to correspond to the local C equivalent (e.g., Perl 6's int can be 8 bytes but C's int is only 4 bytes).

Note that the lack of a returns trait is used to indicate void return type. Do not use the 'void' type anywhere except in the Pointer parameterization.

For strings, there is an additional "encoded" trait to give some extra hints on how to do the marshaling.

sub message_box(Str is encoded('utf8')) is native('gui') { * }

To specify how to marshal string return types, just apply this trait to the routine itself.

sub input_box() returns Str is encoded('utf8') is native('gui') { * }

Note that a null string can be passed by passing the Str type object; a null return will also be represented by the type object.

If the C function requires the lifetime of a string to exceed the function call, the argument must be manually encoded and passed as CArray[uint8]:

# C prototype is void set_foo(const char *)
sub set_foo(CArray[uint8]) is native('foo') { * }
# C prototype is void use_foo(void)
sub use_foo() is native('foo') { * } # will use pointer stored by set_foo()

my $string = "FOO";
# The lifetime of this variable must be equal to the required lifetime of
# the data passed to the C function.
my $array = CArray[uint8].new($string.encode.list);

set_foo($array);
# ...
use_foo();
# It's fine if $array goes out of scope starting from here.

29.4 Basic use of Pointers

When the signature of your native function needs a pointer to some native type (int32, uint32, etc.) all you need to do is declare the argument is rw :

# C prototype is void my_version(int *major, int *minor)
sub my_version(int32 is rw, int32 is rw) is native('foo') { * }
my_version(my int32 $major, my int32 $minor); # Pass a pointer to

Sometimes you need to get a pointer (for example, a library handle) back from a C library. You don't care about what it points to - you just need to keep hold of it. The Pointer type provides for this.

sub Foo_init() returns Pointer is native("foo") { * }
sub Foo_free(Pointer) is native("foo") { * }

This works out OK, but you may fancy working with a type named something better than Pointer. It turns out that any class with the representation "CPointer" can serve this role. This means you can expose libraries that work on handles by writing a class like this:

class FooHandle is repr('CPointer') {
    # Here are the actual NativeCall functions.
    sub Foo_init() returns FooHandle is native("foo") { * }
    sub Foo_free(FooHandle) is native("foo") { * }
    sub Foo_query(FooHandle, Str) returns int8 is native("foo") { * }
    sub Foo_close(FooHandle) returns int8 is native("foo") { * }

    # Here are the methods we use to expose it to the outside world.
    method new {
        Foo_init();
    }

    method query(Str $stmt) {
        Foo_query(self, $stmt);
    }

    method close {
        Foo_close(self);
    }

    # Free data when the object is garbage collected.
    submethod DESTROY {
        Foo_free(self);
    }
}

Note that the CPointer representation can do nothing more than hold a C pointer. This means that your class cannot have extra attributes. However, for simple libraries this may be a neat way to expose an object oriented interface to it.

Of course, you can always have an empty class:

class DoorHandle is repr('CPointer') { }

And just use the class as you would use Pointer, but with potential for better type safety and more readable code.

Once again, type objects are used to represent nulls.

29.5 Function Pointers

C libraries can expose pointers to C functions as return values of functions and as members of Structures like, e.g., structs and unions.

Example of invoking a function pointer "$fptr" returned by a function "f", using a signature defining the desired function parameters and return value:

sub f() returns Pointer is native('mylib') { * }

my $fptr    = f();
my &newfunc = nativecast(:(Str, size_t --> int32), $fptr);

say newfunc("test", 4);

29.6 Arrays

NativeCall has some support for arrays. It is constrained to work with machine-size integers, doubles and strings, sized numeric types, arrays of pointers, arrays of structs, and arrays of arrays.

Perl 6 arrays, which support amongst other things laziness, are laid out in memory in a radically different way to C arrays. Therefore, the NativeCall library offers a much more primitive CArray type, which you must use if working with C arrays.

Here is an example of passing a C array.

sub RenderBarChart(Str, int32, CArray[Str], CArray[num64]) is native("chart") { * }
my @titles := CArray[Str].new;
@titles[0]  = 'Me';
@titles[1]  = 'You';
@titles[2]  = 'Hagrid';
my @values := CArray[num64].new;
@values[0]  = 59.5e0;
@values[1]  = 61.2e0;
@values[2]  = 180.7e0;
RenderBarChart('Weights (kg)', 3, @titles, @values);

Note that binding was used to @titles, not assignment! If you assign, you are putting the values into a Perl 6 array, and it will not work out. If this all freaks you out, forget you ever knew anything about the @ sigil and just use $ all the way when using NativeCall. :-)

my $titles = CArray[Str].new;
$titles[0] = 'Me';
$titles[1] = 'You';
$titles[2] = 'Hagrid';

Getting return values for arrays works out just the same.

Some library APIs may take an array as a buffer that will be populated by the C function and, for instance, return the actual number of items populated:

sub get_n_ints(CArray[int32], int32) returns int32 is native('ints') { * }

In these cases it is important that the CArray has at least the number of elements that are going to be populated before passing it to the native subroutine, otherwise the C function may stomp all over Perl's memory leading to possibly unpredictable behaviour:

my $ints = CArray[int32].new;
my $number_of_ints = 10;
$ints[$number_of_ints - 1] = 0; # extend the array to 10 items

my $n = get_n_ints($ints, $number_of_ints);

The memory management of arrays is important to understand. When you create an array yourself, then you can add elements to it as you wish and it will be expanded for you as required. However, this may result in it being moved in memory (assignments to existing elements will never cause this, however). This means you'd best know what you're doing if you twiddle with an array after passing it to a C library.

By contrast, when a C library returns an array to you, then the memory can not be managed by NativeCall, and it doesn't know where the array ends. Presumably, something in the library API tells you this (for example, you know that when you see a null element, you should read no further). Note that NativeCall can offer you no protection whatsoever here - do the wrong thing, and you will get a segfault or cause memory corruption. This isn't a shortcoming of NativeCall, it's the way the big bad native world works. Scared? Here, have a hug. Good luck! :-)

29.7 Structs

Thanks to representation polymorphism, it's possible to declare a normal looking Perl 6 class that, under the hood, stores its attributes in the same way a C compiler would lay them out in a similar struct definition. All it takes is a quick use of the "repr" trait:

class Point is repr('CStruct') {
    has num64 $.x;
    has num64 $.y;
}

The attributes can only be of the types that NativeCall knows how to marshal into struct fields. Currently, structs can contain machine-sized integers, doubles, strings, and other NativeCall objects (CArrays, and those using the CPointer and CStruct reprs). Other than that, you can do the usual set of things you would with a class; you could even have some of the attributes come from roles or have them inherited from another class. Of course, methods are completely fine too. Go wild!

CStruct objects are passed to native functions by reference and native functions must also return CStruct objects by reference. The memory management rules for these references are very much like the rules for arrays, though simpler since a struct is never resized. When you create a struct, the memory is managed for you and when the variable(s) pointing to the instance of a CStruct go away, the memory will be freed when the GC gets to it. When a CStruct-based type is used as the return type of a native function, the memory is not managed for you by the GC.

NativeCall currently doesn't put object members in containers, so assigning new values to them (with =) doesn't work. Instead, you have to bind new values to the private members:

class MyStruct is repr('CStruct') {
    has CArray[num64] $!arr;
    has Str $!str;
    has Point $!point; # Point is a user-defined class

    submethod TWEAK {
        my $arr := CArray[num64].new;
        $arr[0] = 0.9e0;
        $arr[1] = 0.2e0;
        $!arr := $arr;
        $!str := 'Perl 6 is fun';
        $!point := Point.new;
    }
}

As you may have predicted by now, a null is represented by the type object of the struct type.

29.7.1 CUnions

Likewise, it is possible to declare a Perl 6 class that stores its attributes the same way a C compiler would lay them out in a similar union definition; using the CUnion representation:

class MyUnion is repr('CUnion') {
    has int32 $.flags32;
    has int64 $.flags64;
}

say nativesizeof(MyUnion.new);  # 8, ie. max(sizeof(MyUnion.flags32), sizeof(MyUnion.flags64))

29.7.2 Embedding CStructs and CUnions

CStructs and CUnions can be in turn referenced by – or embedded into -- a surrounding CStruct and CUnion. To say the former we use has as usual, and to do the latter we use the HAS declarator instead:

class MyStruct is repr('CStruct') {
    has Point $.point;  # referenced
    has int32 $.flags;
}

say nativesizeof(MyStruct.new);  # 16, ie. sizeof(struct Point *) + sizeof(int32_t)

class MyStruct2 is repr('CStruct') {
    HAS Point $.point;  # embedded
    has int32 $.flags;
}

say nativesizeof(MyStruct2.new);  # 24, ie. sizeof(struct Point) + sizeof(int32_t)

29.8 Typed Pointers

TODO

TBD more

You can type your Pointer by passing the type as a parameter. It works with the native type but also with CArray and CStruct defined types. NativeCall will not implicitly allocate the memory for it even when calling new on them. It's mostly useful in the case of a C routine returning a pointer, or if it's a pointer embedded in a CStruct.

You have to call .deref on it to access the embedded type.

my Pointer[int32] $p; #For a pointer on int32;
my Pointer[MyCstruct] $p2 = some_c_routine();
my MyCstruct $mc = $p2.deref;
say $mc.field1;

29.9 Buffers and Blobs

TODO

TBD

29.10 Function arguments

NativeCall also supports native functions that take functions as arguments. One example of this is using function pointers as callbacks in an event-driven system. When binding these functions via NativeCall, one need only provide the equivalent signature as a constraint on the code parameter:

# void SetCallback(int (*callback)(const char *))
my sub SetCallback(&callback (Str --> int32)) is native('mylib') { * }

Note: the native code is responsible for memory management of values passed to Perl 6 callbacks this way. In other words, NativeCall will not free() strings passed to callbacks.

29.11 Library Paths and Names

TODO

TBD more

The native trait accepts the library name or the full path.

constant LIBMYSQL = 'mysqlclient';
constant LIBFOO = '/usr/lib/libfoo.so.1';
# and later
sub mysql_affected_rows( .. ) returns int32 is native(LIBMYSQL);
sub bar is native(LIBFOO);

You can also put an incomplete path like './foo' and NativeCall will automatically put the right extension according to the platform specification.

BE CAREFUL: the native trait and constant are evaluated at compile time. Don't write a constant that depends on a dynamic variable like:

constant LIBMYSQL = %*ENV<P6LIB_MYSQLCLIENT> || 'mysqlclient';

This will keep the value given at compile time. A module will be precompiled and LIBMYSQL will keep the value it acquires when the module gets precompiled.

29.11.1 ABI/API Version

If you write native('foo') NativeCall will search libfoo.so under Unix like system (libfoo.dynlib on OS X, foo.dll on win32). In most modern system it will require you or the user of your module to install the development package because it's recommended to always provide an API/ABI version to a shared library, so libfoo.so ends often being a symbolic link provided only by a development package.

To avoid that, the native trait allows you to specify the API/ABI version. It can be a full version or just a part of it. (Try to stick to Major version, some BSD code does not care for Minor.)

sub foo is native('foo', v1); # Will try to load libfoo.so.1
sub foo is native('foo', v1.2.3); # Will try to load libfoo.so.1.2.3

my List $lib = ('foo', 'v1');
sub foo is native($lib);

29.11.2 Routine

The native trait also accepts a Callable as argument, allowing you to provide your own way to handle the way it will find the library file to load.

sub foo is native(sub {'libfoo.so.42'});

It will only be called at the first invocation of the sub.

29.11.3 Calling into the standard library

If you want to call a C function that's already loaded, either from the standard library or from your own program, you can pass the Str type object as the argument to is native, so is native(Str).

For example on a UNIX-like operating system, you could use the following code to print the home directory of the current user:

use NativeCall;
my class PwStruct is repr('CStruct') {
    has Str $.pw_name;
    has Str $.pw_passwd;
    has uint32 $.pw_uid;
    has uint32 $.pw_gid;
    has Str $.pw_gecos;
    has Str $.pw_dir;
    has Str $.pw_shell;
}
sub getuid()              returns uint32   is native(Str) { * };
sub getpwuid(uint32 $uid) returns PwStruct is native(Str) { * };

say getpwuid(getuid()).pw_dir;

Though of course $*HOME is a much easier way :-)

29.12 Exported variables

Variables exported by a library – also named "global" or "extern" variables – can be accessed using cglobal. For example:

my $var := cglobal('libc.so.6', 'errno', int32)

This code binds to $var a new Proxy object that redirects all its accesses to the integer variable named "errno" as exported by the "libc.so.6" library.

29.13 C++ Support

NativeCall offers support to use classes and methods from C++ as shown in https://github.com/rakudo/rakudo/blob/nom/t/04-nativecall/13-cpp-mangling.t (and its associated C++ file). Note that at the moment it's not as tested and developed as C support.

29.14 Helper Functions

The NativeCall library exports several subroutines to help you work with data from native libraries.

29.14.1 sub nativecast

sub nativecast($target-type, $source) is export(:DEFAULT)

This will cast the Pointer $source to an object of $target-type. The source pointer will typically have been obtained from a call to a native subroutine that returns a pointer or as a member of a struct, this may be specified as void * in the C library definition for instance, but you may also cast from a pointer to a less specific type to a more specific one.

As a special case, if a Signature is supplied as $target-type then a subroutine will be returned which will call the native function pointed to by $source in the same way as a subroutine declared with the native trait. This is described in Function Pointers.

29.14.2 sub cglobal

sub cglobal($libname, $symbol, $target-type) is export is rw

This returns a Proxy object that provides access to the extern named $symbol that is exposed by the specified library. The library can be specified in the same ways that they can be to the native trait.

29.14.3 sub nativesizeof

sub nativesizeof($obj) is export(:DEFAULT)

This returns the size in bytes of the supplied object, it can be thought of as being equivalent to sizeof in C. The object can be a builtin native type such as int64 or num64, a CArray or a class with the repr CStruct, CUnion or CPointer.

29.15 Examples

Some examples can be found in the DBIsh repository.

29.15.1 MySQL

You'll need to install MySQL server locally; on Debian-esque systems it can be installed with something like:

sudo apt-get install mysql-server

Prepare your system along these lines before trying out the examples:

$ mysql -u root -p
UPDATE mysql.user SET password=password('sa') WHERE user = 'root';
CREATE DATABASE test;

29.15.2 Microsoft Windows

The win32-api-call.p6 script shows an example Windows API call done from Perl 6. See https://github.com/jnthn/zavolaj/tree/master/examples

30 Object Orientation

Object Orientation in Perl 6

Perl 6 provides strong support for object oriented programming. Although Perl 6 allows programmers to program in multiple paradigms, object oriented programming is at the heart of the language.

Perl 6 comes with a wealth of predefined types, which can be classified in two categories: normal and native types.

Native types are used for low-level types (like uint64). They do not have the same capabilities as objects, though if you call methods on them, they are boxed into normal objects.

Everything that you can store in a variable is either a native value or an object. That includes literals, types (type objects), code and containers.

30.1 Using Objects

To call a method on an object, add a dot, followed by the method name:

 say  "abc" . uc  ; 
 # OUTPUT: «ABC␤» 

This calls the uc method on "abc", which is an object of type Str . To supply arguments to the method, add arguments inside parentheses after the method.

my $formatted-text = "Fourscore and seven years ago...". indent  (8) ; 

$formatted-text now contains the above text, but indented 8 spaces.

Multiple arguments are separated by commas:

my @words = "Abe", "Lincoln"; 
 @words. push ("said" ,  $formatted-text. comb ( /\w+/ )); 

Multiple arguments can be specified by separating the argument list with a colon:

say @words. join : '--'; 
 # OUTPUT: «Abe--Lincoln--said--Fourscore--and--seven--years--ago␤» 

Since you have to put a : after the method if you want to pass arguments without parentheses, a method call without a colon or parentheses is unambiguously a method call without an argument list:

say 4.log:   ; # OUTPUT: «1.38629436111989␤» ( natural logarithm of 4 )
say 4.log: +2; # OUTPUT: «2␤» ( base-2 logarithm of 4 )
say 4.log  +2; # OUTPUT: «3.38629436111989␤» ( natural logarithm of 4, plus 2 )

Many operations that don't look like method calls (for example, smart matching, or interpolating an object into a string) result in method calls under the hood.

Methods can return mutable containers, in which case you can assign to the return value of a method call. This is how read-writable attributes to objects are used:

$*IN. nl-in  = "\r\n"; 

Here, we call method nl-in on the $*IN object, without arguments, and assign to the container it returned with the = operator.

All objects support methods from class Mu, which is the type hierarchy root. All objects derive from Mu.

30.1.1 Type Objects

Types themselves are objects and you can get the type object by writing its name:

my $int-type-obj = Int;

You can ask any object for its type object by calling the WHAT method (which is actually a macro in method form):

my $int-type-obj = 1.WHAT;

Type objects (other than Mu) can be compared for equality with the === identity operator:

sub f(Int $x) { 
     if $x.WHAT   ===   Int { 
         say 'you passed an Int'; 
     } 
     else { 
         say 'you passed a subtype of Int'; 
     } 
 } 

Although, in most cases, the .isa method will suffice:

sub f($x) { 
     if $x . isa  (Int) { 
         ... 
     } 
     ... 
 } 
 

Subtype checking is done by smart-matching:

if $type   ~~    Real  { 
     say '$type contains Real or a subtype thereof'; 
 } 

30.2 Classes

Classes are declared using the class keyword, typically followed by a name.

class Journey {
}

This declaration results in a type object being created and installed in the current package and current lexical scope under the name Journey. You can also declare classes lexically:

my class Journey {
}

This restricts their visibility to the current lexical scope, which can be useful if the class is an implementation detail nested inside a module or another class.

30.2.1 Attributes

Attributes are variables that exist per instance of a class. They are where the state of an object is stored. In Perl 6, all attributes are private. They are typically declared using the has declarator and the ! twigil.

class Journey {
    has $!origin;
    has $!destination;
    has @!travelers;
    has $!notes;
}

While there is no such thing as a public (or even protected) attribute, there is a way to have accessor methods generated automatically: replace the ! twigil with the . twigil (the . should remind you of a method call).

class Journey {
    has $.origin;
    has $.destination;
    has @!travelers;
    has $.notes;
}

This defaults to providing a read-only accessor. In order to allow changes to the attribute, add the is rw trait:

class Journey {
    has $.origin;
    has $.destination;
    has @!travelers;
    has $.notes is rw;
}

Now, after a Journey object is created, its .origin, .destination, and .notes will all be accessible from outside the class, but only .notes can be modified.

If an object is instantiated without certain attributes, such as origin or destination, we may not get the desired result . To prevent this, provide default values or make sure that an attribute is set on object creation by marking an attribute with an is required trait.

class Journey {
    # error if origin is not provided
    has $.origin is required;
    # set the destination to Orlando as default (unless that is the origin!)
    has $.destination = self.origin eq 'Orlando' ?? 'Kampala' !! 'Orlando';
    has @!travelers;
    has $.notes is rw;
}

Since classes inherit a default constructor from Mu and we have requested that some accessor methods are generated for us, our class is already somewhat functional.

# Create a new instance of the class. 
 my $vacation = Journey.new( 
     origin       =>  'Sweden', 
     destination => 'Switzerland', 
     notes       => 'Pack hiking gear!' 
 ); 
 
 # Use an accessor; this outputs Sweden. 
 say $vacation.origin; 
 
 # Use an rw accessor to change the value. 
 $vacation.notes = 'Pack hiking gear and sunglasses!'; 

Note that the default constructor will only set attributes that have an accessor method, but it can initialize read-only attributes.

30.2.2 Methods

Methods are declared with the method keyword inside a class body.

class Journey { 
     has $.origin; 
     has $.destination; 
     has @!travelers; 
     has $.notes is rw; 
 
      method  add_traveler($name) { 
         if $name  ne   any (@!travelers) { 
              push  @!travelers, $name; 
         } 
         else { 
              warn  "$name is already going on the journey!"; 
         } 
     } 
 
      method  describe() { 
         "From $!origin to $!destination" 
     } 
 } 

A method can have a signature, just like a subroutine. Attributes can be used in methods and can always be used with the ! twigil, even if they are declared with the . twigil. This is because the . twigil declares a ! twigil and generates an accessor method.

Looking at the code above, there is a subtle but important difference between using $!origin and $.origin in the method describe. The first is always a lookup of the attribute. The first is an inexpensive and obvious lookup of the attribute. $.origin is a method call and thus may be overridden in a subclass. Only use $.origin if you want to allow overriding.

Unlike Subroutines, additional named arguments will not produce compile time or runtime errors. That allows chaining of methods via Re-dispatching

Method names can be resolved at runtime with the ."" operator.

class A { has $.b };
my $name = 'b';
A.new."$name"().say;
# OUTPUT: «(Any)␤»

30.2.3 self

Inside a method, the term self is available, which is bound to the invocant (the object the method was called on). self can be used to call further methods on the invocant. Within methods, $.origin works the same as self.origin, however the colon-syntax for method arguments is only supported for method calls using self, not the shortcut.

Note that if the relevant methods bless, CREATE, BUILDALL of Mu are not overloaded, self will point to the type object in those methods.

Since user defined constructors are called on type objects, self will point to the type object in constructors and the submethod BUILD. Initializers are also called before object construction time. This can be used to access class attributes in initializers.

class C {
    my $.local = 42;
    has $.x = self.local
};
say C.new.x
# OUTPUT: «42␤»

30.2.4 Private Methods

Methods with an exclamation mark ! before the method name are not callable from anywhere outside the defining class; such methods are private in the sense that they are not visible from outside the class that declares them. Private methods are invoked with an exclamation mark instead of a dot:

method !do-something-private($x) {
    ...
}
method public($x) {
    if self.precondition {
        self!do-something-private(2 * $x)
    }
}

Private methods are not inherited by subclasses.

30.2.5 Submethods

Submethods are public methods that are not inherited by subclasses. The name stems from the fact that they are semantically similar to subroutines.

Submethods are useful for object construction and destruction tasks, as well as for tasks that are so specific to a certain type that subtypes must certainly override them.

For example, the default method new calls submethod BUILD on each class in an inheritance chain:

class Point2D { 
     has $.x; 
     has $.y; 
 
     submethod BUILD(:$!x, :$!y) { 
         say "Initializing Point2D"; 
     } 
 } 
 
 class InvertiblePoint2D is Point2D { 
     submethod BUILD() { 
         say "Initializing InvertiblePoint2D"; 
     } 
     method invert { 
         self.new(x => - $.x, y => - $.y); 
     } 
 } 
 
 say InvertiblePoint2D.new(x => 1, y => 2); 

This produces the following output:

Initializing Point2D 
 Initializing InvertiblePoint2D 
 InvertiblePoint2D.new(x => 1, y => 2) 

See also: #Object Construction.

30.2.6 Inheritance

Classes can have parent classes.

class Child   is  Parent1 is Parent2  { } 

If a method is called on the child class, and the child class does not provide that method, the method of that name in one of the parent classes is invoked instead, if it exists. The order in which parent classes are consulted is called the method resolution order (MRO). Perl 6 uses the C3 method resolution order. You can ask a type for its MRO through a call to its meta class:

say List .^ mro  ;      # List() Cool() Any() Mu() 

If a class does not specify a parent class, Any is assumed by default. All classes directly or indirectly derive from Mu, the root of the type hierarchy.

All calls to public methods are "virtual" in the C++ sense, which means that the actual type of an object determines which method to call, not the declared type:

class Parent { 
     method frob { 
         say "the parent class frobs" 
     } 
 } 
 
 class Child is Parent { 
     method frob { 
         say "the child's somewhat more fancy frob is called" 
     } 
 } 
 
 my Parent $test; 
 $test = Child.new; 
 $test.frob;          # calls the frob method of Child rather than Parent 

This produces the output:

the child's somewhat more fancy frob is called 

30.2.7 Object Construction

Objects are generally created through method calls, either on the type object or on another object of the same type.

Class Mu provides a constructor method called new, which takes named arguments and uses them to initialize public attributes.

class Point { 
     has $.x; 
     has $.y = 2 * $!x; 
 } 
 my $p = Point . new  ( x  =>  5, y => 2); 
 #             ^^^ inherited from class Mu 
 say "x: ", $p.x; 
 say "y: ", $p.y; 

This outputs:

x: 5 
 y: 2 
my $p2 = Point .new ( x => 5 ); 
 # the given value for x is used to calculate the right 
 # value for y. 
 say "x: ", $p.x; 
 say "y: ", $p.y; 

This outputs:

x: 5 
 y: 10 

Mu.new calls method bless on its invocant, passing all the named arguments. bless creates the new object and then calls method BUILDALL on it. BUILDALL walks all subclasses in reverse method resolution order (i.e. from Mu to most derived classes) and in each class checks for the existence of a method named BUILD. If the method exists, the method is called with all the named arguments from the new method. If not, the public attributes from this class are initialized from named arguments of the same name. In either case, if neither BUILD nor the default mechanism has initialized the attribute, default values are applied (the 2 * $!x in the example above).

TWEAK After the BUILD methods have been called, methods named TWEAK are called, if they exist, again with all the named arguments that were passed to new.

Due to the default behavior of BUILDALL and BUILD submethods, named arguments to the constructor new derived from Mu can correspond directly to public attributes of any of the classes in the method resolution order, or to any named parameter of any BUILD submethod.

This object construction scheme has several implications for customized constructors. First, custom BUILD methods should always be submethods, otherwise they break attribute initialization in subclasses. Second, BUILD submethods can be used to run custom code at object construction time. They can also be used for creating aliases for attribute initialization:

class EncodedBuffer { 
     has $.enc; 
     has $.data; 
 
     submethod  BUILD (:encoding(:$enc), :$data) { 
         $!enc   :=   $enc; 
         $!data := $data; 
     } 
 } 
 my $b1 = EncodedBuffer.new( encoding => 'UTF-8', data => [64, 65] ); 
 my $b2 = EncodedBuffer.new( enc      => 'UTF-8', data => [64, 65] ); 
 #  both enc and encoding are allowed now 

Since passing arguments to a routine binds the arguments to the parameters, a separate binding step is unnecessary if the attribute is used as a parameter. Hence the example above could also have been written as:

submethod BUILD(:encoding(:$ ! enc), :$ ! data) { 
     # nothing to do here anymore, the signature binding 
     # does all the work for us. 
 } 

However, be careful when using this auto-binding of attributes when the attribute may have special type requirements, such as an :$!id that must be a positive integer. Remember, default values will be assigned unless you specifically take care of this attribute, and that default value will be Any, which would cause a type error.

The third implication is that if you want a constructor that accepts positional arguments, you must write your own new method:

class Point { 
     has $.x; 
     has $.y; 
     method new($x, $y) { 
         self. bless (:$x, :$y); 
     } 
 } 

However this is considered poor practice, because it makes correct initialization of objects from subclasses harder.

Another thing to note is that the name new is not special in Perl 6. It is merely a common convention. You can call bless from any method at all, or use CREATE to fiddle around with low-level workings.

Another pattern of hooking into object creation is by writing your own method BUILDALL. To make sure that initialization of superclasses works fine, you need to callsame to invoke the parent classes BUILDALL.

class MyClass { 
     method BUILDALL(|) { 
         # initial things here 
 
         callsame;   # call the parent classes (or default) BUILDALL 
 
         # you can do final checks here. 
 
         self # return the fully built object 
     } 
 } 

The TWEAK method allows you to check things or modify attributes after object construction:

class RectangleWithCachedArea { 
     has ($.x1, $.x2, $.y1, $.y2); 
     has $.area; 
     submethod TWEAK() { 
         $!area = abs( ($!x2 - $!x1) * ( $!y2 - $!y1) ); 
     } 
 } 
 
 say RectangleWithCachedArea.new( x2 => 5, x1 => 1, y2 => 1, y1 => 0).area; 

30.2.8 Object Cloning

The Mu parent class, from which all classes inherit, supplies a method named clone, which is somewhat magical in that it can copy values from an object's private attributes to create a new object. This cloning is shallow since it only binds attributes to the same values contained in the original object; it does not make copies of those values.

As with new, public attributes can be set to initial values. These override values received from the original object. (See the documentation for Mu's clone for an example.)

Note that since clone is not a submethod, a class which provides its own clone method will replace the Mu method. There is no automatic mechanism like BUILDALL for cloning. For example, if one wished to make clone deeper for a particular class, one would will probably want to use callwith or nextwith to push the deeper copies to superclasses:

class A {
    has $.a;
    #...
    method clone {
        nextwith(:a($.a.clone))
    }
}

This works well for simple classes, but in some cases one might need to follow BUILDALL's lead and work in reverse method resolution order:

class B is A { 
     has $.b; 
     #... 
     method clone { 
         my $obj = callsame; 
         $obj.b = $!b.clone(:seed($obj.a.generate_seed)); 
         $obj 
     } 
 } 

30.3 Roles

Roles are in some ways similar to classes, in that they are a collection of attributes and methods. They differ in that roles are also meant for describing only parts of an object's behavior and in how roles are applied to classes. Or to phrase it differently, classes are meant for managing objects and roles are meant for managing behavior and code reuse.

use MONKEY-SEE-NO-EVAL; 
 role Serializable { 
     method serialize() { 
         self. perl ; # very primitive serialization 
     } 
     method deserialize($buf) { 
          EVAL  $buf; # reverse operation to .perl 
     } 
 } 
 
 class Point  does  Serializable { 
     has $.x; 
     has $.y; 
 } 
 my $p = Point.new(:x(1), :y(2)); 
 my $serialized = $p.serialize;      # method provided by the role 
 my $clone-of-p = Point.deserialize($serialized); 
 say $clone-of-p.x;      # OUTPUT: «1␤» 

Roles are immutable as soon as the compiler parses the closing curly brace of the role declaration.

30.3.1 Role Application

Role application differs significantly from class inheritance. When a role is applied to a class, the methods of that role are copied into the class. If multiple roles are applied to the same class, conflicts (e.g. attributes or non-multi methods of the same name) cause a compile-time error, which can be solved by providing a method of the same name in the class.

This is much safer than multiple inheritance, where conflicts are never detected by the compiler, but are instead resolved to the superclass that appears earlier in the method resolution order, which might not be what the programmer wanted.

For example, if you've discovered an efficient method to ride cows, and are trying to market it as a new form of popular transportation, you might have a class Bull, for all the bulls you keep around the house, and a class Automobile, for things that you can drive.

class Bull {
    has Bool $.castrated = False;
    method steer {
        # Turn your bull into a steer
        $!castrated = True;
        return self;
    }
}
class Automobile {
    has $.direction;
    method steer($!direction) { }
}
class Taurus is Bull is Automobile { }

my $t = Taurus.new;
$t.steer; # OUTPUT: «Castrates $t␤»

With this setup, your poor customers will find themselves unable to turn their Taurus and you won't be able to make more of your product! In this case, it may have been better to use roles:

role Bull-Like { 
     has Bool $.castrated = False; 
     method steer { 
         # Turn your bull into a steer 
         $!castrated = True; 
         return self; 
     } 
 } 
 role Steerable { 
     has Real $.direction; 
     method steer(Real $d = 0) { 
         $!direction += $d; 
     } 
 } 
 class Taurus does Bull-Like does Steerable { } 

This code will die with something like:

===SORRY!=== 
 Method 'steer' must be resolved by class Taurus because it exists in 
 multiple roles (Steerable, Bull-Like) 

This check will save you a lot of headaches:

class Taurus does Bull-Like does Steerable { 
     method steer($direction?) { 
         self.Steerable::steer($direction?) 
     } 
 } 

When a role is applied to a second role, the actual application is delayed until the second role is applied to a class, at which point both roles are applied to the class. Thus

role R1 {
    # methods here
}
role R2 does R1 {
    # methods here
}
class C does R2 { }

produces the same class C as

role R1 {
    # methods here
}
role R2 {
    # methods here
}
class C does R1 does R2 { }

30.3.2 Stubs

When a role contains a stubbed method, a non-stubbed version of a method of the same name must be supplied at the time the role is applied to a class. This allows you to create roles that act as abstract interfaces.

role AbstractSerializable { 
     method serialize() {   ...   }  # literal ... here marks the 
                                       # method as a stub 
 } 
 
 # the following is a compile time error, for example 
 #        Method 'serialize' must be implemented by Point because 
 #        it's required by a role 
 class APoint does AbstractSerializable { 
     has $.x; 
     has $.y; 
 } 
 
 # this works: 
 class SPoint does AbstractSerializable { 
     has $.x; 
     has $.y; 
     method serialize() { "p($.x, $.y)" } 
 } 

The implementation of the stubbed method may also be provided by another role.

30.3.3 Inheritance

Roles cannot inherit from classes, but they may cause any class which does that role to inherit from another class. So if you write:

role A is Exception { } 
 class X::Ouch does A { } 
 X::Ouch.^parents.say # OUTPUT: «((Exception))␤» 

...then X::Ouch will inherit directly from Exception, as we can see above by listing its parents.

30.3.4 Pecking order

A method defined directly in a class will always override definitions from applied roles or from inherited classes. If no such definition exists, methods from roles override methods inherited from classes. This happens both when said class was brought in by a role, and also when said class was inherited directly.

Note that each candidate for a multi-method is its own method... in this case, the above only applies if two such candidates have the same signature. Otherwise, there is no conflict, and the candidate is just added to the multi-method.

30.3.5 Automatic Role Punning

Any attempt to directly instantiate a role, as well as many other operations on it, will automatically create an instance of a class with the same name as the role, making it possible to transparently use a role as if it were a class.

role Point { 
     has $.x; 
     has $.y; 
     method abs { sqrt($.x * $.x + $.y * $.y) } 
 } 
 say Point.new(x => 6, y => 8).abs; 

We call this automatic creation of classes punning, and the generated class a pun.

30.3.6 Parameterized Roles

Roles can be parameterized, by giving them a signature in square brackets:

role BinaryTree[::Type] { 
     has BinaryTree[Type] $.left; 
     has BinaryTree[Type] $.right; 
     has Type $.node; 
 
     method visit-preorder(&cb) { 
         cb $.node; 
         for $.left, $.right -> $branch { 
             $branch.visit-preorder(&cb) if defined $branch; 
         } 
     } 
     method visit-postorder(&cb) { 
         for $.left, $.right -> $branch { 
             $branch.visit-postorder(&cb) if defined $branch; 
         } 
         cb $.node; 
     } 
     method new-from-list(::?CLASS:U: *@el) { 
         my $middle-index = @el.elems div 2; 
         my @left         = @el[0 .. $middle-index - 1]; 
         my $middle       = @el[$middle-index]; 
         my @right        = @el[$middle-index + 1 .. *]; 
         self.new( 
             node    => $middle, 
             left    => @left  ?? self.new-from-list(@left)  !! self, 
             right   => @right ?? self.new-from-list(@right) !! self, 
         ); 
     } 
 } 
 
 my $t = BinaryTree[Int].new-from-list(4, 5, 6); 
 $t.visit-preorder(&say);    # OUTPUT: «5␤4␤6␤» 
 $t.visit-postorder(&say);   # OUTPUT: «4␤6␤5␤» 

Here the signature consists only of a type capture, but any signature will do:

use v6.c; 
 
 enum Severity <debug info warn error critical>; 
 
 role Logging[$filehandle = $*ERR] { 
     method log(Severity $sev, $message) { 
         $filehandle.print("[{uc $sev}] $message\n"); 
     } 
 } 
 
 Logging[$*OUT].log(debug, 'here we go');        # OUTPUT: «[DEBUG] here we go␤» 

You can have multiple roles of the same name, but with different signatures; the normal rules of multi dispatch apply for choosing multi candidates.

30.3.7 Mixins of Roles

Roles can be mixed into objects. A role's given attributes and methods will be added to the methods and attributes the object already has. Multiple mixins and anonymous roles are supported.

role R { method Str() {'hidden!'} };
my $i = 2 but R;
sub f(\bound){ put bound };
f($i); # OUTPUT: «hidden!␤»

Note that the object got the role mixed in, not the object's class or the container. Thus, @-sigiled containers will require binding to make the role stick. Some operators will return a new value, which effectively strips the mixin from the result.

Mixins can be used at any point in your object's life.

# A counter for Table of Contents
role TOC-Counter {
    has Int @!counters is default(0);
    method Str() { @!counters.join: '.' }
    method inc($level) {
        @!counters[$level - 1]++;
        @!counters.splice($level);
        self
    }
}

my Num $toc-counter = NaN;     # don't do math with Not A Number
say $toc-counter;              # OUTPUT: «NaN␤»
$toc-counter does TOC-Counter; # now we mix the role in
$toc-counter.inc(1).inc(2).inc(2).inc(1).inc(2).inc(2).inc(3).inc(3);
put $toc-counter / 1;          # OUTPUT: «NaN␤» (because that's numerical context)
put $toc-counter;              # OUTPUT: «2.2.2␤» (put will call TOC-Counter::Str)

Roles can be anonymous.

my %seen of Int is default(0 but role :: { method Str() {'NULL'} });
say %seen<not-there>;          # OUTPUT: «NULL␤»
say %seen<not-there>.defined;  # OUTPUT: «True␤» (0 may be False but is well defined)
say Int.new(%seen<not-there>); # OUTPUT: «0␤»

30.4 Meta-Object Programming and Introspection

Perl 6 has a meta object system, which means that the behavior of objects, classes, roles, grammars, enums, etc. are themselves controlled by other objects; those objects are called meta objects. Meta objects are, like ordinary objects, instances of classes, in this case we call them meta classes.

For each object or class you can get the meta object by calling .HOW on it. Note that although this looks like a method call, it works more like a macro.

So, what can you do with the meta object? For one you can check if two objects have the same meta class by comparing them for equality:

say 1.HOW ===   2.HOW;      # OUTPUT: «True␤»
say 1.HOW === Int.HOW;      # OUTPUT: «True␤»
say 1.HOW === Num.HOW;      # OUTPUT: «False␤»

Perl 6 uses the word HOW, Higher Order Workings, to refer to the meta object system. Thus it should be no surprise that in Rakudo, the class name of the meta class that controls class behavior is called Perl6::Metamodel::ClassHOW. For each class there is one instance of Perl6::Metamodel::ClassHOW.

But of course the meta model does much more for you. For example, it allows you to introspect objects and classes. The calling convention for methods on meta objects is to call the method on the meta object and pass in the object of interest as first argument to the object. So to get the name of the class of an object, you could write:

my $object = 1;
my $metaobject = 1.HOW;
say $metaobject.name($object);      # OUTPUT: «Int␤»

# or shorter:
say 1.HOW.name(1);                  # OUTPUT: «Int␤»

(The motivation is that Perl 6 also wants to allow a more prototype-based object system, where it's not necessary to create a new meta object for every type).

There's a shortcut to keep from using the same object twice:

say 1.^name;                        # OUTPUT: «Int␤»
# same as
say 1.HOW.name(1);                  # OUTPUT: «Int␤»

See Metamodel::ClassHOW for documentation on the meta class of class and also the general documentation on the meta object protocol.

31 Operators

Common Perl 6 infixes, prefixes, postfixes, and more!

See Sub on how to define operators.

31.1 Operator Precedence

In an expression like 1 + 2 * 3, the 2 * 3 is evaluated first because the infix * has tighter precedence than the +.

The following table summarizes the precedence levels in Perl 6, from tightest to loosest:

A Level Examples
N Terms 42 3.14 "eek" qq["foo"] $x :!verbose @$array
L Method postfix .meth .+ .? .* .() .[] .{} .<> .«» .:: .= .^ .:
N Autoincrement ++ --
R Exponentiation **
L Symbolic unary ! + - ~ ? | || +^ ~^ ?^ ^
L Dotty infix .= .
L Multiplicative * / % %% +& +< +> ~& ~< ~> ?& div mod gcd lcm
L Additive + - +| +^ ~| ~^ ?| ?^
L Replication x xx
X Concatenation ~
X Junctive and &
X Junctive or | ^
L Named unary temp let
N Structural infix but does <=> leg cmp .. ..^ ^.. ^..^
C Chaining infix != == < <= > >= eq ne lt le gt ge ~~ === eqv !eqv =~=
X Tight and &&
X Tight or || ^^ // min max
R Conditional ?? !! ff fff
R Item assignment = => += -= **= xx=
L Loose unary so not
X Comma operator , :
X List infix Z minmax X X~ X* Xeqv ...
R List prefix print push say die map substr ... [+] [*] any Z=
X Loose and and andthen
X Loose or or xor orelse
X Sequencer <==, ==>, <<==, ==>>
N Terminator ; {...}, unless, extra ), ], }

Using two ! symbols below generically to represent any pair of operators that have the same precedence, the associativities specified above for binary operators are interpreted as follows:

A Assoc Meaning of $a ! $b ! $c
L left ($a ! $b) ! $c
R right $a ! ($b ! $c)
N non ILLEGAL
C chain ($a ! $b) and ($b ! $c)
X list infix:<!>($a; $b; $c)

For unary operators this is interpreted as:

A Assoc Meaning of !$a!
L left (!$a)!
R right !($a!)
N non ILLEGAL

In the operator descriptions below, a default associativity of left is assumed.

31.2 Operator classification

Operators can occur in several positions relative to a term:

+term prefix
term1 + term2 infix
term++ postfix
(term) circumfix
term1[term2] postcircumfix

Each operator is also available as a subroutine. The name of the routine is formed of the operator category, then a colon, and a list quote construct with the symbol(s) that make up the operator:

infix:<+>(1, 2);                # same as 1 + 2
circumfix:«[ ]»(<a b c>);       # same as [<a b c>]

As a special case, a listop (list operator) can stand either as a term or as a prefix. Subroutine calls are the most common listops. Other cases include meta-reduced infix operators ([+] 1, 2, 3) and the #prefix ... etc. stub operators.

Defining custom operators is covered in Defining Operators functions.

31.3 Meta Operators

Meta operators can be parameterized with other operators or subroutines in the same way as functions can take functions as parameters. To use a subroutine as a parameter, prefix its name with a &. Perl 6 will generate the actual combined operator in the background, allowing the mechanism to be applied to user defined operators. To disambiguate chained meta operators enclose the inner operator in square brackets. There are quite a few Meta operators with different semantics as explained, next.

31.4 Substitution Operators

31.4.1 s/// in-place substitution

my $str = 'old string';
$str ~~ s/o .+ d/new/;
say $str; # OUTPUT: «new string␤»

Operates on $_ topical variable, changing it in place. Uses the given Regex to find portions to replace and changes them to the provided replacement string. Sets $/ to the Match object or, if multiple matches were made, a List of Match objects. Returns $/.

It's common to use this operator with the ~~ smartmatch operator, as it aliases left hand side to $_, which s/// uses.

Regex captures can be referenced in the replacement part. Takes the same adverbs as the .subst method, which go between the s and the opening /, separated with optional whitespace:

my $str = 'foo muCKed into the lEn';

# replace second 'o' with 'x'
$str ~~ s:2nd/o/x/;

# replace 'M' or 'L' followed by non-whitespace stuff with 'd'
# and lower-cased version of that stuff:
$str ~~ s :g :i/<[ML]> (\S+)/d{lc $0}/;

say $str; # OUTPUT: «fox ducked into the den␤»

You can also use a different delimiter:

my $str = 'foober';
$str ~~ s!foo!fox!;
$str ~~ s{b(.)r} = " d$0n";
say $str; # OUTPUT: «fox den␤»

Non-paired characters can simply replace the original slashes. Paired characters, like braces, are used only on the match portion, with the substitution given by assignment (of anything: a string, a routine call, etc.).

31.4.2 S/// non-destructive substitution

say S/o .+ d/new/ with 'old string';      # OUTPUT: «new string␤»
S:g/« (.)/$0.uc()/.say for <foo bar ber>; # OUTPUT: «Foo␤Bar␤Ber␤»

Same semantics as the s/// operator, except leaves the original string intact and returns the resultant string instead of $/ ($/ still being set to the same values as with s///).

Note: since the result is obtained as a return value, using this operator with the ~~ smartmatch operator is a mistake and will issue a warning. To execute the substitution on a variable that isn't the $_ this operator uses, alias it to $_ with given, with, or any other way. Alternatively, use the .subst method.

31.5 Assignment Operators

Infix operators can be combined with the assignment operator to modify a value and apply the result to a container in one go. Containers will be autovivified if possible. Some examples:

my $a = 32;
$a += 10;     # 42
$a -= 2;      # 40

$a = 3;
$a min= 5;    # still 3
$a min= 2;    # 2

my $s = 'a';
$s ~= 'b';    # 'ab'

This behavior is automatically extended to include custom-defined infix operators.

sub infix:<space-concat> ($a, $b) { $a ~ " " ~ $b };
my $a = 'word1';
$a space-concat= 'word2';     # RESULT: «'word1 word2'»

Although not strictly operators, methods can be used in the same fashion.

my Real $a = 1/2;
$a = 3.14;
$a .= round;      # RESULT: «3»

31.6 Negated Relational Operators

The result of a relational operator returning Bool can be negated by prefixing with !. To avoid visual confusion with the !! operator, you may not modify any operator already beginning with !.

There are shortcuts for !== and !eq, namely != and ne.

my $a = True;
say so $a != True;    # OUTPUT: «False␤»
my $i = 10;

my $release = Date.new(:2015year, :12month, :24day);
my $today = Date.today;
say so $release !before $today;     # OUTPUT: «False␤»

31.7 Reversed Operators

Any infix operator may be called with its two arguments reversed by prefixing with R. Associativity of operands is reversed as well.

say 4 R/ 12;        # OUTPUT: «3␤»
say [R/] 2, 4, 16;  # OUTPUT: «2␤»

31.8 Hyper Operators

Hyper operators apply a given operator enclosed by « and » to one or two lists, returning the resulting list. The pointy part of « or » has to point to the shorter list. A list with just one element is fine too. If one of the lists is shorter then the other, the operator will cycle over the shorter list until all elements of the longer list are processed.

say (1, 2, 3) »*» 2;          # OUTPUT: «(2 4 6)␤»
say (1, 2, 3, 4) »~» <a b>;   # OUTPUT: «(1a 2b 3a 4b)␤»
say (1, 2, 3) »+« (4, 5, 6);  # OUTPUT: «(5 7 9)␤»

Assignment meta operators can be hyped.

my @a = 1, 2, 3;
say @a »+=» 1;    # OUTPUT: «[2 3 4]␤»

Hyper forms of unary operators have the pointy bit point to the operator and the blunt end at the list to be operated on.

my @wisdom = True, False, True;
say !« @wisdom;     # OUTPUT: «[False True False]␤»

my @a = 1, 2, 3;
@a»++;              # OUTPUT: «(2, 3, 4)␤»

Hyper operators are defined recursively on nested arrays.

say -« [[1, 2], 3]; # OUTPUT: «[[-1 -2] -3]␤»

Also, methods can be called in an out of order, concurrent fashion. The resulting list is in order. Note that all hyper operators are candidates for autothreading and will cause tears if the methods have side effects. The optimizer has full reign over hyper operators, which is the reason that they cannot be defined by the user.

class CarefulClass { method take-care {} }
my CarefulClass @objs;
my @results = @objs».take-care();

my @slops;        # May Contain Nuts
@slops».?this-method-may-not-exist();

Hyper operators can work with hashes. The pointy direction indicates if missing keys are to be ignored in the resulting hash. The enclosed operator operates on all values that have keys in both hashes.

%foo «+» %bar; intersection of keys
%foo »+« %bar; union of keys
%outer »+» %inner; only keys of %inner that exist in %outer will occur in the result
my %outer = 1, 2, 3 Z=> <a b c>;
my %inner = 1, 2 Z=> <x z>;
say %outer «~» %inner;          # OUTPUT: «{"1" => "ax", "2" => "bz"}␤»

Hyper operators can take user defined operators as its operator argument.

sub pretty-file-site (Int $size --> Str) {
    # rounding version of infix:</>(Int, Int)
    sub infix:<r/>(Int \i1, Int \i2) {
        round(i1 / i2, 0.1)
    }

    # we build a vector of fractions of $size and zip that with the fitting prefix
    for $size «[r/]« (2**60, 2**50, 2**40, 2**30, 2**20, 2**10)
              Z      <EB     PB     TB     GB     MB     KB> -> [\v,\suffix] {
        # starting with the biggest suffix, we take the first that is 0.5 of that suffix or bigger
        return v ~ ' ' ~ suffix if v > 0.4
    }
    # this be smaller or equal then 0.4 KB
    return $size.Str;
}

for 60, 50, 40, 30, 20, 10 -> $test {
    my &a = { (2 ** $test) * (1/4, 1/2, 1, 10, 100).pick * (1..10).pick };
    print pretty-file-site(a.Int) xx 2, ' ';
}

# OUTPUT: «10 EB 4 EB 2 PB 5 PB 0.5 PB 4 TB 300 GB 4.5 GB 50 MB 200 MB 9 KB 0.6 MB␤»

Whether hyperoperators descend into child lists depends on the nodality of the inner operator of a chain. For the hyper method call operator (».) the nodality of the target method is significant.

say (<a b>, <c d e>)».elems;        # OUTPUT: «(2 3)␤»
say (<a b>, <c d e>)».&{ .elems };  # OUTPUT: «((1 1) (1 1 1))␤»

You can chain hyper operators to destructure a List of Lists.

my $neighbors = ((-1, 0), (0, -1), (0, 1), (1, 0));
my $p = (2, 3);
say $neighbors »>>+<<» ($p, *);   # OUTPUT: «((1 3) (2 2) (2 4) (3 3))␤»

31.9 Reduction Operators

The reduction metaoperator, [ ], reduces a list with the given infix operator. It gives the same result as the reduce routine - see there for details.

# These two are equivalent:
say [+] 1, 2, 3;                # OUTPUT: «6␤»
say reduce &infix:<+>, 1, 2, 3; # OUTPUT: «6␤»

No whitespace is allowed between the brackets and the operator. To wrap a function instead of an operator, provide an additional layer of brackets:

sub plus { $^a + $^b };
say [[&plus]] 1, 2, 3;          # OUTPUT: «6␤»

The argument list is iterated without flattening. This means that you can pass a nested list to the reducing form of a list infix operator:

say [X~] (1, 2), <a b>;         # OUTPUT: «1, 2 X~ <a b>␤»

By default, only the final result of the reduction is returned. Prefix the wrapped operator with a \, to return a lazy list of all intermediate values instead. This is called a "triangular reduce". If the non-meta part contains a \ already, quote it with [] (e.g. [\[\x]]).

my @n = [\~] 1..*;
say @n[^5];         # OUTPUT: «(1 12 123 1234 12345)␤»

31.10 Cross Operators

The cross metaoperator, X, will apply a given infix operator in order of cross product to all lists, such that the rightmost operator varies most quickly.

1..3 X~ <a b> # RESULT: «<1a, 1b, 2a, 2b, 3a, 3b>␤»

31.11 Zip Operators

The zip metaoperator, (which is not the same thing as Z), will apply a given infix operator to pairs taken one left, one right, from its arguments. The resulting list is returned.

my @l = <a b c> Z~ 1, 2, 3;     # RESULT: «[a1 b2 c3]␤»

If one of the operands runs out of elements prematurely, the zip operator will stop. An infinite list can be used to repeat elements. A list with a final element of * will repeat its 2nd last element indefinitely.

my @l = <a b c d> Z~ ':' xx *;  # RESULT: «<a: b: c: d:>»
   @l = <a b c d> Z~ 1, 2, *;   # RESULT: «<a1 b2 c2 d2>»

If infix operator is not given, , (comma operator) will be used by default:

my @l = 1 Z 2;  # RESULT: «[(1 2)]»

31.12 Sequential Operators

The sequential metaoperator, S, will suppress any concurrency or reordering done by the optimizer. Most simple infix operators are supported.

say so 1 S& 2 S& 3;  # OUTPUT: «True␤»

31.13 Nesting of Meta Operators

To avoid ambiguity when chaining meta operators, use square brackets to help the compiler understand you.

my @a = 1, 2, 3;
my @b = 5, 6, 7;
@a X[+=] @b;
say @a;         # OUTPUT: «[19 20 21]␤»

31.14 Term Precedence

31.14.1 term < >

The quote-words construct breaks up the contents on whitespace and returns a List of the words. If a word looks like a number literal or a Pair literal, it's converted to the appropriate number.

say <a b c>[1];   # OUTPUT: «b␤»

31.14.2 term ( )

The grouping operator.

An empty group () creates an empty list. Parentheses around non-empty expressions simply structure the expression, but do not have additional semantics.

In an argument list, putting parenthesis around an argument prevents it from being interpreted as a named argument.

multi sub p(:$a!) { say 'named'      }
multi sub p($a)   { say 'positional' }
p a => 1;           # OUTPUT: «named␤»
p (a => 1);         # OUTPUT: «positional␤»

31.14.3 term { }

Block or Hash constructor.

If the content looks like a list of pairs and does not use $_ or other placeholder parameters, the constructor returns an itemized Hash.

Otherwise it constructs a Block.

Note that this construct does not re-parse the contents; rather, the contents are always parsed as a statement list (i.e. like a block), and if the later analysis shows that it needs to be interpreted as a hash, the block is executed and coerced to Hash.

31.14.4 circumfix [ ]

The Array constructor returns an itemized Array which does not flatten in list context.

31.15 Method Postfix Precedence

31.15.1 postcircumfix [ ]

sub postcircumfix:<[ ]>(@container, **@index, 
                         :$k, :$v, :$kv, :$p, :$exists, :$delete) 

Universal interface for positional access to zero or more elements of a @container, a.k.a. "array indexing operator".

my @alphabet = 'a' .. 'z';
say @alphabet[0];                   # OUTPUT: «a␤»
say @alphabet[1];                   # OUTPUT: «b␤»
say @alphabet[*-1];                 # OUTPUT: «z␤»
say @alphabet[100]:exists;          # OUTPUT: «False␤»
say @alphabet[15, 4, 17, 11].join;  # OUTPUT: «perl␤»
say @alphabet[23 .. *].perl;        # OUTPUT: «("x", "y", "z")␤»

@alphabet[1, 2] = "B", "C";
say @alphabet[0..3].perl            # OUTPUT: «("a", "B", "C", "d")␤»

See Subscripts, for a more detailed explanation of this operator's behavior, and how to implement support for it in custom types.

31.15.2 postcircumfix { }

sub postcircumfix:<{ }>(%container, **@key, 
                         :$k, :$v, :$kv, :$p, :$exists, :$delete) 

Universal interface for associative access to zero or more elements of a %container, a.k.a. "hash indexing operator".

my %color = kiwi => "green", banana => "yellow", cherry => "red";
say %color{"banana"};                 # OUTPUT: «yellow␤»
say %color{"cherry", "kiwi"}.perl;    # OUTPUT: «("red", "green")␤»
say %color{"strawberry"}:exists;      # OUTPUT: «False␤»

%color{"banana", "lime"} = "yellowish", "green";
%color{"cherry"}:delete;
say %color;             # OUTPUT: «banana => yellowish, kiwi => green, lime => green␤»

See postcircumfix < > and postcircumfix « » for convenient shortcuts, and Subscripts for a more detailed explanation of this operator's behavior, and how to implement support for it in custom types.

31.15.3 postcircumfix < >

Shortcut for postcircumfix { } that quotes its argument using the same rules as the quote-words operator of the same name.

my %color = kiwi => "green", banana => "yellow", cherry => "red";
say %color<banana>;               # OUTPUT: «yellow␤»
say %color<cherry kiwi>.perl;     # OUTPUT: «("red", "green")␤»
say %color<strawberry>:exists;    # OUTPUT: «False␤»

This is not a real operator, just syntactic sugar that is turned into the { } postcircumfix operator at compile-time.

31.15.4 postcircumfix « »

Shortcut for postcircumfix { } that quotes its argument using the same rules as the interpolating quote-words operator of the same name.

my %color = kiwi => "green", banana => "yellow", cherry => "red";
my $fruit = "kiwi";
say %color«cherry $fruit».perl;   # OUTPUT: «("red", "green")␤»

This is not a real operator, just syntactic sugar that is turned into the { } postcircumfix operator at compile-time.

31.15.5 postcircumfix ( )

The call operator treats the invocant as a Callable and invokes it, using the expression between the parentheses as arguments.

Note that an identifier followed by a pair of parentheses is always parsed as a subroutine call.

If you want your objects to respond to the call operator, you need to implement a method CALL-ME.

31.15.6 postfix .

The operator for calling one method, $invocant.method.

Technically this is not an operator, but syntax special-cased in the compiler.

31.15.7 postfix .&

The operator to call a subroutine (with at least one positional argument) like a method. The invocant will be bound to the first positional argument.

Technically this is not an operator, but syntax special-cased in the compiler.

my sub f($invocant){ dd $invocant; }
my $i = 42;
42.&f;
# OUTPUT: «Int $invocant = 42␤»
42.&(-> $invocant { dd $invocant });
# OUTPUT: «Int $invocant = 42␤»

31.15.8 postfix .=

A mutating method call. $invocant.=method desugars to $invocant = $invocant.method, similar to = .

Technically this is not an operator, but syntax special-cased in the compiler.

31.15.9 postfix .^

A meta-method call. $invocant.^method calls method on $invocant's metaclass. It desugars to $invocant.HOW.method($invocant, ...). See HOW for more information.

Technically this is not an operator, but syntax special-cased in the compiler.

31.15.10 postfix .?

Safe call operator. $invocant.?method calls method method on $invocant if it has a method of such name. Otherwise it returns Nil.

Technically this is not an operator, but syntax special-cased in the compiler.

31.15.11 postfix .+

$invocant.+method calls all methods called method from $invocant, and returns a List of the results. Dies if no such method was found.

Technically this is not an operator, but syntax special-cased in the compiler.

31.15.12 postfix .*

$invocant.*method calls all methods called method from $invocant, and returns a List of the results. If no such method was found, an empty List is returned.

Technically this is not an operator, but syntax special-cased in the compiler.

31.15.13 postfix ». / postfix >>.

Hyper method call operator. Will call a method on all elements of a List out of order and return the list of return values in order.

my @a = <a b c>;
my @b = @a».ord;                  # OUTPUT: «[97, 98, 99]␤»
sub foo(Str:D $c){ $c.ord * 2 };  # The first parameter of a method is the invocant.
say @a».&foo;                     # So we can pretend to have a method call with a sub that got a good first positional argument.
say @a».&{ .ord};                 # Blocks have an implicit positional arguments that lands in $_. The latter can be omitted for method calls.

Take care to avoid a common mistake of expecting side-effects to occur in order. The following say is not guaranteed to produce the output in order:

@a».say;  # WRONG! Could produce a␤b␤c␤ or c␤b␤a␤ or any other order 

31.15.14 postfix .postfix / .postcircumfix

In most cases, a dot may be placed before a postfix or postcircumfix:

my @a;
@a[1, 2, 3];
@a.[1, 2, 3]; # Same

This can be useful for visual clarity or brevity. For example, if an object's attribute is a function, putting a pair of parentheses after the attribute name will become part of the method call. So either two pairs of parentheses must be used, or a dot has to come before the parentheses to separate it from the method call.

class Operation {
    has $.symbol;
    has &.function;
}
my $addition = Operation.new(:symbol<+>, :function{ $^a + $^b });
say $addition.function()(1, 2);   # OUTPUT: «3␤»
# OR
say $addition.function.(1, 2);    # OUTPUT: «3␤»

If the postfix is an identifier, however, it will be interpreted as a normal method call.

1.i # No such method 'i' for invocant of type 'Int' 

Technically this is not an operator, but syntax special-cased in the compiler.

31.15.15 postfix .:<prefix>

A prefix can be called like a method using colonpair notation. For example:

my $a = 1;
say ++$a;       # OUTPUT: «2␤»
say $a.:<++>;   # OUTPUT: «3␤»

Technically this is not an operator, but syntax special-cased in the compiler.

31.15.16 postfix .::

A class-qualified method call, used to call a method as defined in a parent class or role, even after it has been redefined in the child class.

class Bar {
    method baz { 42 }
}
class Foo is Bar {
    method baz { "nope" }
}
say Foo.Bar::baz;       # OUTPUT: «42␤»

31.16 Autoincrement Precedence

31.16.1 prefix ++

multi sub prefix:<++>($x is rw) is assoc<non>

Increments its argument by one, and returns the updated value.

my $x = 3;
say ++$x;   # OUTPUT: «4␤»
say $x;     # OUTPUT: «4␤»

It works by calling the succ method (for successor) on its argument, which gives custom types the freedom to implement their own increment semantics.

31.16.2 prefix --

multi sub prefix:<-->($x is rw) is assoc<non>

Decrements its argument by one, and returns the updated value.

my $x = 3;
say --$x;   # OUTPUT: «2␤»
say $x;     # OUTPUT: «2␤»

It works by calling the pred method (for predecessor) on its argument, which gives custom types the freedom to implement their own decrement semantics.

31.16.3 postfix ++

multi sub postfix:<++>($x is rw) is assoc<non>

Increments its argument by one, and returns the original value.

my $x = 3;
say $x++;   # OUTPUT: «3␤»
say $x;     # OUTPUT: «4␤»

It works by calling the succ method (for successor) on its argument, which gives custom types the freedom to implement their own increment semantics.

Note that this does not necessarily return its argument; e.g., for undefined values, it returns 0:

my $x;
say $x++;   # OUTPUT: «0␤»
say $x;     # OUTPUT: «1␤»

Increment on Str will increment the number part of a string and assign the resulting string to the container. A is rw-container is required.

my $filename = "somefile-001.txt";
say $filename++ for 1..3;
# OUTPUT: «somefile-001.txt␤somefile-002.txt␤somefile-003.txt␤»

31.16.4 postfix --

multi sub postfix:<-->($x is rw) is assoc<non>

Decrements its argument by one, and returns the original value.

my $x = 3;
say $x--;   # OUTPUT: «3␤»
say $x;     # OUTPUT: «2␤»

It works by calling the pred method (for predecessor) on its argument, which gives custom types the freedom to implement their own decrement semantics.

Note that this does not necessarily return its argument;e.g., for undefined values, it returns 0:

my $x;
say $x--;   # OUTPUT: «0␤»
say $x;     # OUTPUT: «-1␤»

Decrement on Str will decrement the number part of a string and assign the resulting string to the container. A is rw-container is required. Crossing 0 is prohibited and throws X::AdHoc.

my $filename = "somefile-003.txt";
say $filename-- for 1..3;
# OUTPUT: «somefile-003.txt␤somefile-002.txt␤somefile-001.txt␤»

31.17 Exponentiation Precedence

31.17.1 infix **

multi sub infix:<**>(Any, Any --> Numeric:D) is assoc<right>

The exponentiation operator coerces both arguments to Numeric and calculates the left-hand-side raised to the power of the right-hand side.

If the right-hand side is a non-negative integer and the left-hand side is an arbitrary precision type (Int, FatRat), then the calculation is carried out without loss of precision.

31.18 Symbolic Unary Precedence

31.18.1 prefix ?

multi sub prefix:<?>(Mu --> Bool:D)

Boolean context operator.

Coerces the argument to Bool by calling the Bool method on it. Note that this collapses Junctions.

31.18.2 prefix !

multi sub prefix:<!>(Mu --> Bool:D)

Negated boolean context operator.

Coerces the argument to Bool by calling the Bool method on it, and returns the negation of the result. Note that this collapses Junctions.

31.18.3 prefix +

multi sub prefix:<+>(Any --> Numeric:D)

Numeric context operator.

Coerces the argument to Numeric by calling the Numeric method on it.

31.18.4 prefix -

multi sub prefix:<->(Any --> Numeric:D)

Negative numeric context operator.

Coerces the argument to Numeric by calling the Numeric method on it, and then negates the result.

31.18.5 prefix ~

multi sub prefix:<~>(Any --> Str:D)

String context operator.

Coerces the argument to Str by calling the Str method on it.

31.18.6 prefix |

Flattens objects of type Capture, Pair, List, Map and Hash into an argument list.

Outside of argument lists, it returns a Slip, which makes it flatten into the outer list. Inside argument list Positional s are turned into positional arguments and Associative s are turned into named arguments.

31.18.7 prefix ||

TODO

31.18.8 prefix +^

multi sub prefix:<+^>(Any --> Int:D)

Integer bitwise negation operator.

Coerces the argument to Int and does a bitwise negation on the result, assuming two's complement.

31.18.9 prefix ~^

Coerces the argument to a non-variable-encoding string buffer type (e.g. buf8, buf16, buf32) and then flips each bit in that buffer.

Please note that this has not yet been implemented.

31.18.10 prefix ?^

multi sub prefix:<?^>(Mu --> Bool:D)

Boolean bitwise negation operator.

Coerces the argument to Bool and then does a bit flip, which makes it the same as prefix:<!> .

31.18.11 prefix ^

multi sub prefix:<^>(Any --> Range:D)

upto operator.

Coerces the argument to Numeric, and generates a range from 0 up to (but excluding) the argument.

say ^5;         # OUTPUT: «0..^5␤»
for ^5 { }      # 5 iterations

31.19 Dotty Infix Precedence

These operators are like their Method Postfix counterparts, but require surrounding whitespace (before and/or after) to distinguish them.

31.19.1 infix .=

Calls the right-side method on the value in the left-side container, replacing the resulting value in the left-side container.

In most cases this behaves identically to the postfix mutator, but the precedence is lower so:

    my $a = -5 
     say ++$a.=abs 
     # OUTPUT: «6␤» 
     say ++$a .= abs 
     # OUTPUT: «Cannot modify an immutable Int␤ 
     #           in block <unit> at <tmp> line 1␤␤» 

31.19.2 infix .

Calls the following method (whose name must be alphabetic) on the left-side invocant.

Note that the infix form of the operator has a slightly lower precedence than postfix .meth.

say -5.abs;      # like: -(5.abs)
# OUTPUT: «-5␤»
say -5 . abs;    # like: (-5) . abs
# OUTPUT: «5␤»
say -5 .abs;     # following whitespace is optional
# OUTPUT: «5␤»

31.20 Multiplicative Precedence

31.20.1 infix *

multi sub infix:<*>(Any, Any --> Numeric:D)

Multiplication operator.

Coerces both arguments to Numeric and multiplies them. The result is of the wider type. See Numeric for details.

31.20.2 infix /

multi sub infix:</>(Any, Any --> Numeric:D)

Division operator.

Coerces both argument to Numeric and divides the left through the right number. Division of Int values returns Rat, otherwise the "wider type" rule described in Numeric holds.

31.20.3 infix div

multi sub infix:<div>(Int:D, Int:D --> Int:D)

Integer division operator. Rounds down.

31.20.4 infix %

multi sub infix:<%>($x, $y --> Numeric:D)

Modulo operator. Coerces to Numeric first.

Generally the following identity holds:

my ($x, $y) = 1,2;
$x % $y == $x - floor($x / $y) * $y

31.20.5 infix %%

multi sub infix:<%%>($a, $b --> Bool:D)

Divisibility operator. Returns True if $a % $b == 0.

31.20.6 infix mod

multi sub infix:<mod>(Int:D $a, Int:D $b --> Int:D)

Integer modulo operator. Returns the remainder of an integer modulo operation.

31.20.7 infix +&

multi sub infix:<+&>($a, $b --> Int:D)

Numeric bitwise AND operator. Coerces both arguments to Int and does a bitwise AND operation assuming two's complement.

31.20.8 infix +<

multi sub infix:<< +< >>($a, $b --> Int:D)

Integer bit shift to the left.

31.20.9 infix +>

multi sub infix:<< +> >>($a, $b --> Int:D)

Integer bit shift to the right.

31.20.10 infix ~&

Coerces each argument to a non-variable-encoding string buffer type (e.g. buf8, buf16, buf32) and then performs a numeric bitwise AND on corresponding integers of the two buffers, padding the shorter buffer with zeroes.

31.20.11 infix ~<

Coerces the left argument to a non-variable-encoding string buffer type (e.g. buf8, buf16, buf32) and then performs a numeric bitwise left shift on the bits of the buffer.

Please note that this has not yet been implemented.

31.20.12 infix ~>

Coerces the left argument to a non-variable-encoding string buffer type (e.g. buf8, buf16, buf32) and then performs a numeric bitwise right shift on the bits of the buffer.

Please note that this has not yet been implemented.

31.20.13 infix gcd

multi sub infix:<gcd>($a, $b --> Int:D)

Coerces both arguments to Int and returns the greatest common divisor.

31.20.14 infix lcm

multi sub infix:<lcm>($a, $b --> Int:D)

Coerces both arguments to Int and returns the least common multiple, that is the smallest integer that is evenly divisible by both arguments.

31.21 Additive Precedence

31.21.1 infix +

multi sub infix:<+>($a, $b --> Numeric:D)

Addition operator.

Coerces both arguments to Numeric and adds them.

31.21.2 infix -

multi sub infix:<->($a, $b --> Numeric:D)

Subtraction operator.

Coerces both arguments to Numeric and subtracts the second from the first.

31.21.3 infix +|

multi sub infix:<+|>($a, $b --> Int:D)

Integer bitwise OR operator.

Coerces both arguments to Int and does a bitwise OR (inclusive OR) operation.

31.21.4 infix +^

multi sub infix:<+^>($a, $b --> Int:D)

Integer bitwise XOR operator.

Coerces both arguments to Int and does a bitwise XOR (exclusive OR) operation.

31.21.5 infix ~|

Coerces each argument to a non-variable-encoding string buffer type (e.g. buf8, buf16, buf32) and then performs a numeric bitwise OR on corresponding integers of the two buffers, padding the shorter buffer with zeroes.

31.21.6 infix ~^

Coerces each argument to a non-variable-encoding string buffer type (e.g. buf8, buf16, buf32) and then performs a numeric bitwise XOR on corresponding integers of the two buffers, padding the shorter buffer with zeroes.

31.21.7 infix ?|

multi sub infix:<?|>($a, $b --> Bool:D)

Boolean logical OR operator.

Coerces both arguments to Bool and does a logical OR (inclusive OR) operation.

31.22 Replication Precedence

31.22.1 infix x

sub infix:<x>($a, $b --> Str:D)

String repetition operator.

Repeats the string $a $b times, if necessary coercing $a to Str and $b Int . Returns an empty string if $b <= 0 .

say 'ab' x 3;           # OUTPUT: «ababab␤»
say 42 x 3;             # OUTPUT: «424242␤»

my $a = 'a'.IO;
my $b = 3.5;
say $a x $b;            # OUTPUT: «aaa␤»

31.22.2 infix xx

multi sub infix:<xx>($a, $b --> List:D)

List repetition operator.

Returns a list of $a repeated and evaluated $b times ($b is coerced to Int). If $b <= 0 , the empty list is returned.

The left-hand side is evaluated for each repetition, so

say [1, 2] xx 5;
# OUTPUT: «([1 2] [1 2] [1 2] [1 2] [1 2])␤»

returns five distinct arrays (but with the same content each time), and

rand xx 3

returns three pseudo random numbers that are determined independently.

The right-hand side can be *, in which case a lazy, infinite list is returned.

31.23 Concatenation

31.23.1 infix ~

multi sub infix:<~>(Any,   Any)
multi sub infix:<~>(Str:D, Str:D)
multi sub infix:<~>(Buf:D, Buf:D)

String concatenation operator.

Coerces both arguments to Str and concatenates them. If both arguments are Buf, a combined buffer is returned.

say 'ab' ~ 'c';     # OUTPUT: «abc␤»

31.24 Junctive AND (all) Precedence

31.24.1 infix &

multi sub infix:<&>($a, $b --> Junction:D) is assoc<list>

All junction operator.

Creates an all Junction from its arguments. See Junction for more details.

31.25 Junctive OR (any) Precedence

31.25.1 infix |

multi sub infix:<|>($a, $b --> Junction:D) is assoc<list>

Any junction operator.

Creates an any Junction from its arguments. See Junction for more details.

31.25.2 infix ^

multi sub infix:<^>($a, $b --> Junction:D) is assoc<list>

One junction operator.

Creates a one Junction from its arguments. See Junction for more details.

31.26 Named Unary Precedence

31.26.1 prefix temp

sub prefix:<temp>(Mu $a is rw)

"temporizes" the variable passed as the argument. The variable begins with the same value as it had in the outer scope, but can be assigned new values in this scope. Upon exiting the scope, the variable will be restored to its original value.

my $a = "three";
say $a; # OUTPUT: «three␤»
{
    temp $a;
    say $a; # OUTPUT: «three␤»
    $a = "four";
    say $a; # OUTPUT: «four␤»
}
say $a; # OUTPUT: «three␤»

Note that you can also assign immediately as part of the call to temp:

temp $a = "five"; 

31.26.2 prefix let

sub prefix:<let>(Mu $a is rw)

Restores the previous value if the block exits unsuccessfully. A successful exit means the block returned a defined value or a list.

my $answer = 42;

{
    let $answer = 84;
    die if not Bool.pick;
    CATCH {
        default { say "it's been reset :(" }
    }
    say "we made it 84 sticks!";
}

say $answer;

In the above case, if the Bool.pick returns true, the answer will stay as 84 because the block returns a defined value (say returns true). Otherwise the die statement will cause the block to exit unsuccessfully, resetting the answer to 42.

this is duplicated in variables.pod

31.27 Nonchaining Binary Precedence

31.27.1 infix does

sub infix:<does>(Mu $obj, Mu $role) is assoc<non>

Mixes $role into $obj at run time. Requires $obj to be mutable.

$role doesn't need to a be a role, it can be something that knows how to act like a role; e.g., enum values.

If methods of the same name are present already, the last mixed in role takes precedence.

31.27.2 infix but

multi sub infix:<but>(Mu $obj1, Mu   $role) is assoc<non>
multi sub infix:<but>(Mu $obj1, Mu:D $obj2) is assoc<non>

Creates a copy of $obj with $role mixed in. Since $obj is not modified, but can be used to created immutable values with mixins.

Instead of a role, you can provide an instantiated object. In this case, the operator will create a role for you automatically. The role will contain a single method named the same as $obj.^name and that returns $obj:

say 42 but 'forty two'; # OUTPUT: «forty two␤» 
 
 my $s = 12 but class Warbles { method hi { 'hello' } }.new; 
 say $s.Warbles.hi;    # OUTPUT: «hello␤» 
 say $s + 42;          # OUTPUT: «54␤» 

If methods of the same name are present already, the last mixed in role takes precedence. A list of methods can be provided in parentheses separated by comma. In this case conflicts will be reported at runtime.

31.27.3 infix cmp

multi sub infix:<cmp>(Any,       Any)
multi sub infix:<cmp>(Real:D,    Real:D)
multi sub infix:<cmp>(Str:D,     Str:D)
multi sub infix:<cmp>(Version:D, Version:D)

Generic, "smart" three-way comparator.

Compares strings with string semantics, numbers with number semantics, Pair objects first by key and then by value etc.

if $a eqv $b, then $a cmp $b always returns Order::Same.

say (a => 3) cmp (a => 4);   # OUTPUT: «Less␤»
say 4        cmp 4.0;        # OUTPUT: «Same␤»
say 'b'      cmp 'a';        # OUTPUT: «More␤»

31.27.4 infix leg

multi sub infix:<leg>(Any,   Any)
multi sub infix:<leg>(Str:D, Str:D)

String three-way comparator. Short for less, equal or greater?.

Coerces both arguments to Str, and then does a lexicographic comparison.

say 'a' leg 'b';       # OUTPUT: «Less␤»
say 'a' leg 'a';       # OUTPUT: «Same␤»
say 'b' leg 'a';       # OUTPUT: «More␤»

31.27.5 infix <=>

multi sub infix:«<=>»($a, $b --> Order:D) is assoc<non>

Numeric three-way comparator.

Coerces both arguments to Real, and then does a numeric comparison.

31.27.6 infix ..

multi sub infix:<..>($a, $b --> Range:D) is assoc<non>

Range operator

Constructs a Range from the arguments.

31.27.7 infix ..^

multi sub infix:<..^>($a, $b --> Range:D) is assoc<non>

Right-open range operator.

Constructs a Range from the arguments, excluding the end point.

31.27.8 infix ^..

multi sub infix:<^..>($a, $b --> Range:D) is assoc<non>

Left-open range operator.

Constructs a Range from the arguments, excluding the start point.

31.27.9 infix ^..^

multi sub infix:<^..^>($a, $b --> Range:D) is assoc<non>

Open range operator

Constructs a Range from the arguments, excluding both start and end point.

31.28 Chaining Binary Precedence

31.28.1 infix ==

multi sub infix:<==>(Any, Any)
multi sub infix:<==>(Int:D, Int:D)
multi sub infix:<==>(Num:D, Num:D)
multi sub infix:<==>(Rational:D, Rational:D)
multi sub infix:<==>(Real:D, Real:D)
multi sub infix:<==>(Complex:D, Complex:D)
multi sub infix:<==>(Numeric:D, Numeric:D)

Numeric equality operator.

Coerces both arguments to Numeric if necessary, and returns True if they are equal.

31.28.2 infix !=

sub infix:<!=>(Mu, Mu --> Bool:D)

Numeric inequality operator.

Coerces both arguments to Numeric (if necessary), and returns True if they are distinct.

31.28.3 infix

Numeric inequality operator.

Equivalent to !=, at codepoint U+2260 (NOT EQUAL TO).

31.28.4 infix <

multi sub infix:«<»(Int:D, Int:D)
multi sub infix:«<»(Num:D, Num:D)
multi sub infix:«<»(Real:D, Real:D)

Numeric less than operator.

Coerces both arguments to Real (if necessary), and returns True if the first argument is smaller than the second.

31.28.5 infix <=

multi sub infix:«<=»(Int:D, Int:D)
multi sub infix:«<=»(Num:D, Num:D)
multi sub infix:«<=»(Real:D, Real:D)

Numeric less than or equal to operator.

Coerces both arguments to Real (if necessary), and returns True if the first argument is smaller than or equal to the second.

31.28.6 infix

Numeric less than or equal to operator.

Equivalent to <=, at codepoint U+2264 (LESS-THAN OR EQUAL TO).

31.28.7 infix >

multi sub infix:«>»(Int:D, Int:D)
multi sub infix:«>»(Num:D, Num:D)
multi sub infix:«>»(Real:D, Real:D)

Numeric greater than operator.

Coerces both arguments to Real (if necessary), and returns True if the first argument is larger than the second.

31.28.8 infix >=

multi sub infix:«>=»(Int:D, Int:D)
multi sub infix:«>=»(Num:D, Num:D)
multi sub infix:«>=»(Real:D, Real:D)

Numeric greater than or equal to operator.

Coerces both arguments to Real (if necessary), and returns True if the first argument is larger than or equal to the second.

31.28.9 infix

Numeric greater than or equal to operator.

Equivalent to >=, at codepoint U+2265 (GREATER-THAN OR EQUAL TO).

31.28.10 infix eq

multi sub infix:<eq>(Any,   Any)
multi sub infix:<eq>(Str:D, Str:D)

String equality operator.

Coerces both arguments to Str (if necessary), and returns True if both are equal.

Mnemonic: equal

31.28.11 infix ne

multi sub infix:<ne>(Mu,    Mu)
multi sub infix:<ne>(Str:D, Str:D)

String inequality operator.

Coerces both arguments to Str (if necessary), and returns False if both are equal.

Mnemonic: not equal

31.28.12 infix gt

multi sub infix:<gt>(Mu,    Mu)
multi sub infix:<gt>(Str:D, Str:D)

String greater than operator.

Coerces both arguments to Str (if necessary), and returns True if the first is larger than the second, as determined by lexicographic comparison.

Mnemonic: greater than

31.28.13 infix ge

multi sub infix:<ge>(Mu,    Mu)
multi sub infix:<ge>(Str:D, Str:D)

String greater than or equal to operator.

Coerces both arguments to Str (if necessary), and returns True if the first is equal to or larger than the second, as determined by lexicographic comparison.

Mnemonic: greater or equal

31.28.14 infix lt

multi sub infix:<lt>(Mu,    Mu)
multi sub infix:<lt>(Str:D, Str:D)

String less than operator.

Coerces both arguments to Str (if necessary), and returns True if the first is smaller than the second, as determined by lexicographic comparison.

Mnemonic: less than

31.28.15 infix le

multi sub infix:<le>(Mu,    Mu)
multi sub infix:<le>(Str:D, Str:D)

String less than or equal to operator.

Coerces both arguments to Str (if necessary), and returns True if the first is equal to or smaller than the second, as determined by lexicographic comparison.

Mnemonic: less or equal

31.28.16 infix before

multi sub infix:<before>(Any,       Any)
multi sub infix:<before>(Real:D,    Real:D)
multi sub infix:<before>(Str:D,     Str:D)
multi sub infix:<before>(Version:D, Version:D)

Generic ordering, uses the same semantics as cmp. Returns True if the first argument is smaller than the second.

31.28.17 infix after

multi sub infix:<after>(Any,       Any)
multi sub infix:<after>(Real:D,    Real:D)
multi sub infix:<after>(Str:D,     Str:D)
multi sub infix:<after>(Version:D, Version:D)

Generic ordering, uses the same semantics as cmp. Returns True if the first argument is larger than the second.

31.28.18 infix eqv

sub infix:<eqv>(Any, Any)

Equivalence operator. Returns True if the two arguments are structurally the same, i.e. from the same type and (recursively) contain the same values.

say [1, 2, 3] eqv [1, 2, 3];    # OUTPUT: «True␤»
say Any eqv Any;                # OUTPUT: «True␤»
say 1 eqv 2;                    # OUTPUT: «False␤»
say 1 eqv 1.0;                  # OUTPUT: «False␤»

The default eqv operator even works with arbitrary objects. E.g., eqv will consider two instances of the same object as being structurally equivalent:

my class A {
    has $.a;
}
say A.new(a => 5) eqv A.new(a => 5);  # OUTPUT: «True␤»

Although the above example works as intended the eqv code has to fall back to a slower code path in order to do its job. One way to avoid this is to implement an appropriate infix eqv operator:

my class A {
    has $.a;
}
multi infix:<eqv>(A $l, A $r) { $l.a eqv $r.a }
say A.new(a => 5) eqv A.new(a => 5);            # OUTPUT: «True␤»

31.28.19 infix ===

sub infix:<===>(Any, Any)

Value identity operator. Returns True if both arguments are the same object.

my class A { };
my $a = A.new;
say $a === $a;              # OUTPUT: «True␤»
say A.new === A.new;        # OUTPUT: «False␤»
say A === A;                # OUTPUT: «True␤»

For value types, === behaves like eqv:

say 'a' === 'a';            # OUTPUT: «True␤»
say 'a' === 'b';            # OUTPUT: «False␤»

# different types
say 1 === 1.0;              # OUTPUT: «False␤»

=== uses the WHICH method to obtain the object identity, so all value types must override method WHICH.

31.28.20 infix =:=

multi sub infix:<=:=>(Mu \a, Mu \b)

Container identity operator. Returns True if both arguments are bound to the same container. If it returns True, it generally means that modifying one will also modify the other.

my ($a, $b) = (1, 3);
say $a =:= $b;      # OUTPUT: «False␤»
$b = 2;
say $a;             # OUTPUT: «1␤»
$b := $a;
say $a =:= $b;      # OUTPUT: «True␤»
$a = 5;
say $b;             # OUTPUT: «5␤»

31.28.21 infix ~~

The smart-match operator. Aliases the left-hand side to $_, then evaluates the right-hand side, and calls .ACCEPTS($_) on it. The semantics are left to the type of the right-hand side operand.

Here is an excerpt of built-in smart-matching functionality:

Right-hand side Comparison semantics
Mu:U type check
Str string equality
Numeric numeric equality
Regex regex match
Callable boolean result of invocation
Set/Bag equal element values
Any:D object identity

31.28.22 infix =~=

multi sub infix:<=~=>(Any, Any)
multi sub infix:<=~=>(Int:D, Int:D)
multi sub infix:<=~=>(Num:D, Num:D)
multi sub infix:<=~=>(Rational:D, Rational:D)
multi sub infix:<=~=>(Real:D, Real:D)
multi sub infix:<=~=>(Complex:D, Complex:D)
multi sub infix:<=~=>(Numeric:D, Numeric:D)

The approximately-equal operator. Calculates the relative difference between the left-hand and right-hand sides and returns True if the difference is less than $*TOLERANCE (which defaults to 1e-15). However, if either side is zero then it checks that the absolute difference between the sides is less than $*TOLERANCE. Note that this operator is not arithmetically symmetrical (doesn't do ± Δ):

my $x = 1;
say ($x + $*TOLERANCE) =~= $x;   # OUTPUT: «False␤»
say ($x - $*TOLERANCE) =~= $x;   # OUTPUT: «True␤»

The tolerance is supposed to be modifiable via an adverb:

RT #128210
my ($x, $y) = 42, 42.1; 
 say $x =~= $y :tolerance(.1); 

however, this is not yet implemented. The same effect can be achieved by assigning to $*TOLERANCE.

{
    my $*TOLERANCE = .1;
    say 11 =~= 10;        # OUTPUT: «True␤»
}

Note that setting $*TOLERANCE = 0 will cause all comparisons to fail.

{
    my $*TOLERANCE = 0;
    say 1 =~= 1;          # OUTPUT: «False␤»
}

31.29 Tight AND Precedence

31.29.1 infix &&

Returns the first argument that evaluates to False in boolean context, or otherwise the last argument.

Note that this short-circuits, i.e. if one of the arguments evaluates to a false value, the arguments to the right of are never evaluated.

sub a { 1 }
sub b { 0 }
sub c { die "never called" };
say a() && b() && c();      # OUTPUT: «0␤»

31.30 Tight OR Precedence

31.30.1 infix ||

Returns the first argument that evaluates to True in boolean context, or otherwise the last argument.

Note that this short-circuits, i.e. if one of the arguments evaluates to a true value, the arguments to the right of are never evaluated.

sub a { 0 }
sub b { 1 }
sub c { die "never called" };
say a() || b() || c();      # OUTPUT: «1␤»

31.30.2 infix ^^

Short-circuit exclusive-or. Returns the true argument if there is one (and only one). Returns the last argument if all arguments are false. Returns Nil otherwise (when more than one argument is true).

This operator short-circuits in the sense that it does not evaluate any arguments after a 2nd true result.

say 0 ^^ 42;                             # OUTPUT: «42␤»
say '' ^^ 0;                             # OUTPUT: «0␤»
say 0 ^^ 42 ^^ 1 ^^ die "never called";  # OUTPUT: «␤»

Note that the semantics of this operator may not be what you assume: infix ^^ flips to first true value it finds, and then flips to Nil forever after the second, no matter how many more true values there are. (In other words, it has "find the one true value" semantics, not "boolean parity" semantics.)

31.30.3 infix //

Defined-or operator. Returns the first defined operand or else the last operand. Short-circuits.

say Any // 0 // 42;         # OUTPUT: «0␤»

31.30.4 infix min

Returns the smallest of the arguments, as determined by cmp semantics.

my $foo = 42;
$foo min= 0   # read as: $foo decreases to 0

31.30.5 infix max

Returns the largest of the arguments, as determined by cmp semantics.

my $foo = -42;
$foo max= 0   # read as: $foo increases to 0

31.31 Conditional Operator Precedence

31.31.1 infix ?? !!

Ternary operator, conditional operator.

$condition ?? $true !! $false evaluates and returns the expression from the $true branch if $condition is a true value. Otherwise it evaluates and returns the $false branch.

31.31.2 infix ff

sub infix:<ff>(Mu $a, Mu $b)

Flipflop operator.

Compares both arguments to $_ (that is, $_ ~~ $a and $_ ~~ $b). Evaluates to False until the left-hand smartmatch is True, at which point it evaluates to True until the right-hand smartmatch is True.

In effect, the left-hand argument is the "start" condition, and the right-hand is the "stop" condition. This construct is typically used to pick up only a certain section of lines. For example:

my $excerpt = q:to/END/; 
 Here's some unimportant text. 
 =begin code 
     This code block is what we're after. 
     We'll use 'ff' to get it. 
 =end code 
 More unimportant text. 
 END 
 
 my @codelines = gather for $excerpt.lines { 
     take $_ if  "=begin code" ff "=end code"  
 } 
 
 # this will print four lines, starting with "=begin code" and ending with 
 # "=end code" 
 say @codelines.join("\n"); 

After matching the start condition, the operator will then match the same $_ to the stop condition, and act accordingly if successful. In this example, only the first element is printed:

for <AB C D B E F> {
    say $_ if /A/ ff /B/;  # OUTPUT: «AB␤»
}

If you only want to test against a start condition, and have no stop condition, * can be used as the "stop" condition.

for <A B C D E> {
    say $_ if /C/ ff *;    # OUTPUT: «C␤D␤E␤»
}

For the sed-like version, which does not try $_ on the stop condition after succeeding on the start condition, see fff .

This operator cannot be overloaded, as it's handled specially by the compiler.

31.31.3 infix ^ff

sub infix:<^ff>(Mu $a, Mu $b)

Works like ff , except it does not return True for items matching the start condition (including items also matching the stop condition).

A comparison:

my @list = <A B C>;
say $_ if /A/ ff /C/ for @list;    # OUTPUT: «A␤B␤C␤»
say $_ if /A/ ^ff /C/ for @list;   # OUTPUT: «B␤C␤»

The sed-like version can be found in ^fff .

This operator cannot be overloaded, as it's handled specially by the compiler.

31.31.4 infix ff^

sub infix:<ff^>(Mu $a, Mu $b)

Works like ff , except it does not return True for items matching the stop condition (including items that first matched the start condition).

my @list = <A B C>;
say $_ if /A/ ff /C/ for @list;    # OUTPUT: «A␤B␤C␤»
say $_ if /A/ ff^ /C/ for @list;   # OUTPUT: «A␤B␤»

The sed-like version can be found in fff^ .

This operator cannot be overloaded, as it's handled specially by the compiler.

31.31.5 infix ^ff^

sub infix:<^ff^>(Mu $a, Mu $b)

Works like ff , except it does not return True for items matching either the stop or start condition (or both).

my @list = <A B C>;
say $_ if /A/ ff /C/ for @list;    # OUTPUT: «A␤B␤C␤»
say $_ if /A/ ^ff^ /C/ for @list;  # OUTPUT: «B␤»

The sed-like version can be found in ^fff^ .

This operator cannot be overloaded, as it's handled specially by the compiler.

31.31.6 infix fff

sub infix:<fff>(Mu $a, Mu $b)

Performs a sed-like flipflop operation, wherein it returns False until the left argument smartmatches against $_, and after that returns True until the right argument smartmatches against $_.

Works similarly to ff , except that it only tries one argument per invocation. That is, if $_ smartmatches the left argument, fff will not then try to match that same $_ against the right argument.

for <AB C D B E F> {
    say $_ if /A/ fff /B/;         # OUTPUT: «AB␤C␤D␤B␤»
}

The non-sed-like flipflop (which after successfully matching the left argument against $_ will try that same $_ against the right argument and act accordingly), see ff .

This operator cannot be overloaded, as it's handled specially by the compiler.

31.31.7 infix ^fff

sub infix:<^fff>(Mu $a, Mu $b)

Like fff , except it does not return true for matches to the left argument.

my @list = <A B C>;
say $_ if /A/ fff /C/ for @list;   # OUTPUT: «A␤B␤C␤»
say $_ if /A/ ^fff /C/ for @list;  # OUTPUT: «B␤C␤»

For the non-sed version, see ^ff .

This operator cannot be overloaded, as it's handled specially by the compiler.

31.31.8 infix fff^

sub infix:<fff^>(Mu $a, Mu $b)

Like fff , except it does not return true for matches to the right argument.

my @list = <A B C>;
say $_ if /A/ fff /C/ for @list;   # OUTPUT: «A␤B␤C␤»
say $_ if /A/ fff^ /C/ for @list;  # OUTPUT: «A␤B␤»

For the non-sed version, see ff^ .

This operator cannot be overloaded, as it's handled specially by the compiler.

31.31.9 infix ^fff^

sub infix:<^fff^>(Mu $a, Mu $b)

Like fff , except it does not return true for matches to either the left or right argument.

my @list = <A B C>;
say $_ if /A/ fff /C/ for @list;   # OUTPUT: «A␤B␤C␤»
say $_ if /A/ ^fff^ /C/ for @list; # OUTPUT: «B␤»

For the non-sed version, see ^ff^ .

This operator cannot be overloaded, as it's handled specially by the compiler.

31.32 Item Assignment Precedence

31.32.1 infix =

sub infix:<=>(Mu $a is rw, Mu $b) 

Item assignment operator.

Places the value of the right-hand side into the container on the left-hand side. Its exact semantics are left to the container type on the left-hand side.

(Note that item assignment and list assignment have different precedence levels, and the syntax of the left-hand side decides whether an equal sign = is parsed as item assignment or list assignment operator).

31.32.2 infix =>

sub infix:«=>»($key, Mu $value --> Pair:D)

Pair constructor.

Constructs a Pair object with the left-hand side as the key and the right-hand side as the value.

Note that the => operator is syntactically special-cased, in that it allows unquoted identifier on the left-hand side.

my $p = a => 1;
say $p.key;         # OUTPUT: «a␤»
say $p.value;       # OUTPUT: «1␤»

A Pair within an argument list with an unquoted identifier on the left is interpreted as a named argument.

See the Terms language documentation for more ways to create Pair objects.

31.33 Loose Unary Precedence

31.33.1 prefix not

multi sub prefix:<not>(Mu $x --> Bool:D)

Evaluates its argument in boolean context (and thus collapses Junctions), and negates the result. Please note that not is easy to misuse, see traps.

31.33.2 prefix so

multi sub prefix:<so>(Mu $x --> Bool:D)

Evaluates its argument in boolean context (and thus collapses Junctions), and returns the result.

31.34 Comma Operator Precedence

31.34.1 infix ,

sub infix:<,>(*@a --> List:D) is assoc<list>

Constructs a List from its arguments. Also used syntactically as the separator of arguments in calls.

31.34.2 infix :

Used as an argument separator just like infix , and marks the argument to its left as the invocant. That turns what would otherwise be a function call into a method call.

substr('abc': 1);       # same as 'abc'.substr(1)

Infix : is only allowed after the first argument of a non-method call. In other positions it's a syntax error.

31.35 List Infix Precedence

31.35.1 infix Z

sub infix:<Z>(**@lists --> Seq:D) is assoc<chain>

Zip operator.

Interleaves the lists passed to Z like a zipper, stopping as soon as the first input list is exhausted. The returned Seq contains a nested list with values for all Z operators in a chain.

say (1, 2 Z <a b c> Z <+ ->).perl;  # OUTPUT: «((1, "a", "+"), (2, "b", "-")).Seq␤»
for <a b c> Z <1 2 3> -> [$l, $r] {
    say "$l:$r"
}
# OUTPUT: «a:1␤b:2␤c:3␤»

The Z operator also exists as a meta operator, in which case the inner lists are replaced by the value from applying the operator to the list:

say 100, 200 Z+ 42, 23;             # OUTPUT: «(142 223)␤»
say 1..3 Z~ <a b c> Z~ 'x' xx 3;    # OUTPUT: «(1ax 2bx 3cx)␤»

31.35.2 infix X

sub infix:<X>(**@lists --> List:D)

Creates a cross product from all the lists, order so that the rightmost elements vary most rapidly:

1..3 X <a b c> X 9
# produces ((1 a 9) (1 b 9) (1 c 9)
#           (2 a 9) (2 b 9) (2 c 9)
#           (3 a 9) (3 b 9) (3 c 9))

The X operator also exists as a meta operator, in which case the inner lists are replaced by the value from applying the operator to the list:

1..3 X~ <a b c> X~ 9
# produces (1a9 1b9 1c9 2a9 2b9 2c9 3a9 3b9 3c9)

31.35.3 infix ...

multi sub infix:<...>(**@) is assoc<list>
multi sub infix:<...^>(**@) is assoc<list>

The sequence operator is a generic operator to produce lazy lists.

It can have initial elements and a generator on left-hand side, and an endpoint on the right-hand side.

The sequence operator invokes the generator with as many arguments as necessary. The arguments are taken from the initial elements and the already generated elements.

The default generator is *.succ or *.pred, depending on how the end points compare:

say 1 ... 4;        # OUTPUT: «(1 2 3 4)␤»
say 4 ... 1;        # OUTPUT: «(4 3 2 1)␤»
say 'a' ... 'e';    # OUTPUT: «(a b c d e)␤»
say 'e' ... 'a';    # OUTPUT: «(e d c b a)␤»

An endpoint of * (Whatever) generates an infinite sequence, with a default generator of *.succ

say (1 ... *)[^5];  # OUTPUT: «(1 2 3 4 5)␤»

Custom generators are the last argument before the '...' operator. This one takes two arguments, and generates the Fibonacci numbers

say (1, 1, -> $a, $b { $a + $b } ... *)[^8];    # OUTPUT: «(1 1 2 3 5 8 13 21)␤»
# same but shorter
say (1, 1, *+* ... *)[^8];                      # OUTPUT: «(1 1 2 3 5 8 13 21)␤»

Of course the generator can also take only one argument.

say 5, { $_ * 2 } ... 40;                       # OUTPUT: «5 10 20 40␤»

There must be at least as many initial elements as arguments to the generator.

Without a generator, and more than one initial element, and all initial elements numeric, the sequence operator tries to deduce the generator. It knows about arithmetic and geometric sequences.

say 2, 4, 6 ... 12;     # OUTPUT: «(2 4 6 8 10 12)␤»
say 1, 2, 4 ... 32;     # OUTPUT: «(1 2 4 8 16 32)␤»

If the endpoint is not *, it's smart-matched against each generated element, and the sequence is terminated when the smart-match succeeded. For the ... operator, the final element is included, for the ...^ operator it's excluded.

This allows you to write

say 1, 1, *+* ...^ *>= 100;

To generate all Fibonacci numbers up to but excluding 100.

The ... operators consider the initial values as "generated elements" as well, so the are also checked against the endpoint:

my $end = 4;
say 1, 2, 4, 8, 16 ... $end;
# OUTPUT: «(1 2 4)␤»

31.36 List Prefix Precedence

31.36.1 infix =

List assignment operator. Its exact semantics are left to the container type on the left-hand side. See Array and Hash for common cases.

The distinction between item assignment and list assignment is determined by the parser depending on the syntax of the left-hand side.

31.36.2 infix :=

Binding operator. Whereas $x = $y puts the value in $y into $x, $x := $y makes $x and $y the same thing.

my $a = 42;
my $b = $a;
$b++;
say $a;

This will output 42, because $a and $b both contained the number 42, but the containers were different.

my $a = 42;
my $b := $a;
$b++;
say $a;

This will output 43, since $b and $a both represented the same object.

Please note that := is a compile time construct. As such it can not be referred to at runtime and thus can't be used as an argument to meta operators.

31.36.3 infix ::=

Read-only binding operator. See infix := .

31.36.4 listop ...

The yada, yada, yada operator or stub operator. If it's the only statement in a routine or type, it marks that routine or type as a stub (which is significant in the context of pre-declaring types and composing roles).

If the ... statement is executed, it calls fail, with the default message stub code executed.

31.36.5 listop !!!

Fatal stub operator.

If it's the only statement in a routine or type, it marks that routine or type as a stub (which is significant in the context of pre-declaring types and composing roles).

If the !!! statement is executed, it calls die, with the default message stub code executed.

31.36.6 listop ???

Admonitory stub operator.

If it's the only statement in a routine or type, it marks that routine or type as a stub (which is significant in the context of pre-declaring types and composing roles).

If the ??? statement is executed, it calls warn, with the default message stub code executed.

31.36.7 Reduction operators

Any infix operator (except for non-associating operators) can be surrounded by square brackets in term position to create a list operator that reduces using that operation.

say [+] 1, 2, 3;      # 1 + 2 + 3 = 6
my @a = (5, 6);
say [*] @a;           # 5 * 6 = 30

Reduction operators have the same associativity as the operators they are based on.

say [-] 4, 3, 2;      # 4-3-2 = (4-3)-2 = -1
say [**] 4, 3, 2;     # 4**3**2 = 4**(3**2) = 262144

31.37 Loose AND precedence

31.37.1 infix and

Same as #infix &&, except with looser precedence.

Returns the first operand that evaluates to False in boolean context, or otherwise the last operand, it short-circuits. Please note that and is easy to misuse, see traps.

31.37.2 infix andthen

Returns Empty upon encountering the first undefined argument, otherwise the last argument. Short-circuits. The result of the left side is bound to $_ for the right side, or passed as arguments if the right side is a Callable .

A handy use of this operator is to alias a routine's return value to $_ and to do additional manipulation with it, such as printing or returning it to caller. Since the andthen operator short-circuits, statements on the right-hand side won't get executed, unless left-hand side is defined.

sub load-data {
    rand  > .5 or return; # simulated load data failure; return Nil
    (rand > .3 ?? 'error' !! 'good data') xx 10 # our loaded data
}
load-data.first: /good/ andthen say "$_ is good";
# OUTPUT: «(good data is good)␤»

load-data() andthen .return; # return loaded data, if it's defined
die "Failed to load data!!";

The above example will print good data is good only if the subroutine returned any items that match /good/ and will die unless loading data returned defined value. The aliasing behaviour lets us pipe the values across the operator.

The andthen operator is a close relative of with statement modifier, and some compilers compile with to andthen, meaning these two lines have equivalent behaviour:

.say with 42;
42 andthen .say;

31.38 Loose OR Precedence

31.38.1 infix or

Same as infix ||, except with looser precedence.

Returns the first argument that evaluates to True in boolean context, or otherwise the last argument, it short-circuits. Please note that or is easy to misuse, see traps.

31.38.2 infix orelse

Similar to infix //. Returns the first defined argument, or else the last argument. Short-circuits. The result of the left side is bound to $_ for the right side, or passed as arguments if the right side is a Callable .

31.39 Sequencer Precedence

31.39.1 infix ==>

This feed operator takes the result from the left and passes it to the next (right) routine as the last parameter.

The precedence is very loose so you will need to use parentheses to assign the result or you can even just use another feed operator! In the case of routines/methods that take a single argument or where the first argument is a block, it's often required that you call with parentheses (though this is not required for the very last routine/method).

# Traditional structure, read bottom-to-top
my @result =
    sort                # (4) Sort, result is <Earth People>
    grep { /<[PE]>/ },  # (3) Look for P or E
    map { .tc },        # (2) Capitalize the words
    <people of earth>;  # (1) Start with the input

# Feed (left-to-right) with parentheses, read top-to-bottom
my @result = (
    <people of earth>   # (1) Start with the input
    ==> map({ .tc })    # (2) Capitalize the words
    ==> grep /<[PE]>/   # (3) Look for P or E
    ==> sort            # (4) Sort, result is <Earth People>
);

# For illustration, method chaining equivalent, read top-to-bottom
my @result =
    <people of earth>   # (1) Start with the input
    .map({ .tc })       # (2) Capitalize the words
    .grep(/<[PE]>/)     # (3) Look for P or E
    .sort;              # (4) Sort, result is <Earth People>

# To assign without the need of parentheses use another feed operator
my @result =
    <people of earth>
    ==> map({ .tc })
    ==> grep /<[PE]>/
    ==> sort()
    ==> @result;

# It can be useful to capture a partial result, however, unlike
# the leftward feed operator, it does require parentheses or a semicolon
my @result =
    <people of earth>
    ==> map({ .tc })
    ==> my @caps; @caps   # also could wrap in parentheses instead
    ==> grep /<[PE]>/
    ==> sort()
    ==> @result;

The feed operator lets you construct method-chaining-like patterns out of routines and the results of methods on unrelated data. In method-chaining, you are restricted to the methods available on the data or the result of previous method call. With feed operators, that restriction is gone. The resulting code could also be seen to be more readable than a series of method calls broken over multiple lines.

Note: In the future, this operator will see some change as it gains the ability to run list operations in parallel. It will enforce that the left operand is enclosable as a closure (that can be cloned and run in a subthread).

31.39.2 infix <==

This leftward feed operator takes the result from the right and passes it to the previous (left) routine as the last parameter. This elucidates the right-to-left dataflow for a series of list manipulating functions.

# Traditional structure, read bottom-to-top
my @result =
    sort                   # (4) Sort, result is <Earth People>
    grep { /<[PE]>/ },     # (3) Look for P or E
    map { .tc },           # (2) Capitalize the words
    <people of earth>;     # (1) Start with the input

# Feed (right-to-left) with parentheses, read bottom-to-top
my @result = (
    sort()                 # (4) Sort, result is <Earth People>
    <== grep({ /<[PE]>/ }) # (3) Look for P or E
    <== map({ .tc })       # (2) Capitalize the words
    <== <people of earth>  # (1) Start with the input
);

# To assign without parentheses, use another feed operator
my @result
    <== sort()              # (4) Sort, result is <Earth People>
    <== grep({ /<[PE]>/ })  # (3) Look for P or E
    <== map({ .tc })        # (2) Capitalize the words
    <== <people of earth>;  # (1) Start with the input

# It can be useful to capture a partial result
my @result
    <== sort()
    <== grep({ /<[PE]>/ })
    <== my @caps            # unlike ==>, there's no need for additional statement
    <== map({ .tc })
    <== <people of earth>;

Unlike the rightward feed operator, the result is not closely mappable to method-chaining. However, compared to the traditional structure above where each argument is separated by a line, the resulting code is more demonstrative than commas. The leftward feed operator also allows you to "break into" the statement and capture an intermediary result which can be extremely useful for debugging or to take that result and create another variation on the final result.

Note: In the future, this operator will see some change as it gains the ability to run list operations in parallel. It will enforce that the right operand is enclosable as a closure (that can be cloned and run in a subthread).

32 Packages

Organizing and referencing namespaced program elements

* Take a lot of stuff from S02 for this * Document 'import'

Packages are nested namespaces of named program elements. Modules, classes, grammars, and others are types of packages. Like files in a directory, you can generally refer to named elements with their short-name if they are local, or with a longer name to disambiguate.

32.1 Names

A name is anything that is a legal part of a variable name (not counting the sigil). This includes:

$foo                # simple identifiers
$Foo::Bar::baz      # compound identifiers separated by ::
$Foo::($bar)::baz   # compound identifiers that perform interpolations
$42                 # numeric names
$!                  # certain punctuation variables

:: is used to separate nested package names.

32.1.1 Package-qualified names

Ordinary package-qualified names look like:

$Foo::Bar::baz      # the $baz variable in package Foo::Bar

Sometimes it's clearer to keep the sigil with the variable name, so an alternate way to write this is:

Foo::Bar::<$baz>

This is resolved at compile time because the variable name is a constant.

If the name part before :: is null, it means the package is unspecified and must be searched for. Generally this means that an initial :: following the main sigil is a no-op on names that are known at compile time, though ::() can also be used to introduce an interpolation. Also, in the absence of another sigil, :: can serve as its own sigil indicating intentional use of a not-yet-declared package name.

32.2 Pseudo-packages

The following pseudo-package names are reserved at the front of a name:

MY Symbols in the current lexical scope (aka $?SCOPE)
OUR Symbols in the current package (aka $?PACKAGE)
CORE Outermost lexical scope, definition of standard Perl
GLOBAL Interpreter-wide package symbols, really UNIT::GLOBAL
PROCESS Process-related globals (superglobals). The last place dynamic variable
lookup will look.
COMPILING Lexical symbols in the scope being compiled

The following relative names are also reserved but may be used anywhere in a name:

CALLER Contextual symbols in the immediate caller's lexical scope
CALLERS Contextual symbols in any caller's lexical scope
DYNAMIC Contextual symbols in my or any caller's lexical scope
OUTER Symbols in the next outer lexical scope
OUTERS Symbols in any outer lexical scope
LEXICAL Contextual symbols in my or any outer's lexical scope
UNIT Symbols in the outermost lexical scope of compilation unit
SETTING Lexical symbols in the unit's DSL (usually CORE)
PARENT Symbols in this package's parent package (or lexical scope)
CLIENT The nearest CALLER that comes from a different package

The file's scope is known as UNIT, but there are one or more lexical scopes outside of that corresponding to the linguistic setting (often known as the prelude in other cultures). Hence, the SETTING scope is equivalent to UNIT::OUTERS. For a standard Perl program SETTING is the same as CORE, but various startup options (such as -n or -p) can put you into a domain specific language, in which case CORE remains the scope of the standard language, while SETTING represents the scope defining the DSL that functions as the setting of the current file. When used as a search term in the middle of a name, SETTING includes all its outer scopes up to CORE. To get only the setting's outermost scope, use UNIT::OUTER instead.

32.3 Looking up names

32.3.1 Interpolating into names

You may interpolate a string into a package or variable name using ::($expr) where you'd ordinarily put a package or variable name. The string is allowed to contain additional instances of ::, which will be interpreted as package nesting. You may only interpolate entire names, since the construct starts with ::, and either ends immediately or is continued with another :: outside the parentheses. Most symbolic references are done with this notation:

$foo = "Bar";
$foobar = "Foo::Bar";
$::($foo)           # lexically-scoped $Bar
$::("MY::$foo")     # lexically-scoped $Bar
$::("OUR::$foo")    # package-scoped $Bar
$::("GLOBAL::$foo") # global $Bar
$::("PROCESS::$foo")# process $Bar
$::("PARENT::$foo") # current package's parent's $Bar
$::($foobar)        # $Foo::Bar
$::($foobar)::baz   # $Foo::Bar::baz
$::($foo)::Bar::baz # $Bar::Bar::baz
$::($foobar)baz     # ILLEGAL at compile time (no operator baz)

An initial :: doesn't imply global. Here as part of the interpolation syntax it doesn't even imply package. After the interpolation of the ::() component, the indirect name is looked up exactly as if it had been there in the original source code, with priority given first to leading pseudo-package names, then to names in the lexical scope (searching scopes outwards, ending at CORE). The current package is searched last.

Use the MY pseudopackage to limit the lookup to the current lexical scope, and OUR to limit the scopes to the current package scope.

32.3.2 Direct lookup

To do direct lookup in a package's symbol table without scanning, treat the package name as a hash:

Foo::Bar::{'&baz'}  # same as &Foo::Bar::baz
PROCESS::<$IN>      # Same as $*IN
Foo::<::Bar><::Baz> # same as Foo::Bar::Baz

Unlike ::() symbolic references, this does not parse the argument for ::, nor does it initiate a namespace scan from that initial point. In addition, for constant subscripts, it is guaranteed to resolve the symbol at compile time.

The null pseudo-package is the same search list as an ordinary name search. That is, the following are all identical in meaning:

$foo
$::{'foo'}
::{'$foo'}
$::<foo>
::<$foo>

Each of them scans lexical scopes outward, and then the current package scope (though the package scope is then disallowed when "strict" is in effect).

As a result of these rules, you can write any arbitrary variable name as either of:

$::{'!@#$#@'}
::{'$!@#$#@'}

You can also use the ::<> form as long as there are no spaces in the name.

32.3.3 Package lookup

Subscript the package object itself as a hash object, the key of which is the variable name, including any sigil. The package object can be derived from a type name by use of the :: postfix:

MyType::<$foo>

32.4 Globals

Interpreter globals live in the GLOBAL package. The user's program starts in the GLOBAL package, so "our" declarations in the mainline code go into that package by default. Process-wide variables live in the PROCESS package. Most predefined globals such as $*UID and $*PID are actually process globals.

32.5 Version

Any package may have a Version object attached to it. This object can be accessed via $?PACKAGE.^ver or from outside the package Fully::Qualified::Name.^ver.

33 Performance

Measuring and improving run-time or compile-time performance

This page is about anything to do with computer performance in the context of Perl 6.

33.1 First, clarify the problem

Make sure you're not wasting time on the wrong code: start by identifying your "critical 3%" by "profiling" as explained below.

33.1.1 Time with now - INIT now

Expressions of the form now - INIT now, where INIT is a phase in the running of a Perl 6 program, provide a great idiom for timing code snippets.

Use the m: your code goes here #perl6 channel evalbot to write lines like:

m: say now - INIT now 
 rakudo-moar abc1234: OUTPUT«0.0018558␤» 

The now to the left of INIT runs 0.0018558 seconds later than the now to the right of the INIT because the latter occurs during the INIT phase.

33.1.2 Profile locally

When using the MoarVM backend the Rakudo compiler's --profile command line option writes profile information as an HTML file. However, if the profile is too big it can be slow to open in a browser. In that case, if you use the --profile- filename=file.extension option with an extension of .json, you can use the Qt viewer on the resulting JSON file.

Another option (especially useful for profiles too big even for the Qt viewer) is to use an extension of .sql. This will write the profile data as a series of SQL statements, suitable for opening in SQLite.

# create a profile 
 perl6 --profile --profile-filename=demo.sql -e 'say (^20).combinations(3).elems' 
 
 # create a SQLite database 
 sqlite3 demo.sqlite 
 
 # load the profile data 
 sqlite> .read demo.sql 
 
 # the query below is equivalent to the default view of the "Routines" tab in the HTML profile 
 sqlite> select 
    ...>   case when r.name = "" then "<anon>" else r.name end, 
    ...>   r.file, 
    ...>   r.line, 
    ...>   sum(entries) as entries, 
    ...>   sum(case when rec_depth = 0 then inclusive_time else 0 end) as inclusive_time, 
    ...>   sum(exclusive_time) as exclusive_time 
    ...> from 
    ...>   callees c, 
    ...>   routines r 
    ...> where 
    ...>   c.id = r.id 
    ...> group by 
    ...>   c.id 
    ...> order by 
    ...>   inclusive_time desc; 

To learn how to interpret the profile info, use the prof-m: your code goes here evalbot (explained above) and ask questions on channel.

33.1.3 Profile compiling

The Rakudo compiler's --profile-compile option profiles the time and memory used to compile code.

33.1.4 Create or view benchmarks

Use perl6-bench.

If you run perl6-bench for multiple compilers (typically versions of Perl 5, Perl 6, or NQP) then results for each are visually overlaid on the same graphs to provide for quick and easy comparison.

33.1.5 Share problems

Once you've used the above techniques to pinpoint code and performance that really matters you're in a good place to share problems, one at a time:

33.2 Solve problems

This bears repeating: make sure you're not wasting time on the wrong code. Start by identifying the "critical 3%" of your code.

33.2.1 Line by line

A quick, fun, productive way to try improve code line-by-line is to collaborate with others using the #perl6 evalbot camelia.

33.2.2 Routine by routine

With multidispatch you can drop in new variants of routines "alongside" existing ones:

# existing code generically matches a two arg foo call:
multi sub foo(Any $a, Any $b) { ... }

# new variant takes over for a foo("quux", 42) call:
multi sub foo("quux", Int $b) { ... }

The call overhead of having multiple foo definitions is generally insignificant (though see discussion of where below), so if your new definition handles its particular case more quickly/leanly than the previously existing set of definitions then you probably just made your code that much faster/leaner for that case.

33.2.3 Speed up type-checks and call resolution

Most where clauses – and thus most subsets – force dynamic (run-time) type checking and call resolution for any call it might match. This is slower, or at least later, than compile-time.

Method calls are generally resolved as late as possible, so dynamically, at run- time, whereas sub calls are generally resolvable statically, at compile-time.

33.2.4 Choose better algorithms

One of the most reliable techniques for making large performance improvements regardless of language or compiler is to pick an algorithm better suited to your needs.

A classic example is Boyer-Moore. To match a small string in a large string, one obvious way to do it is to compare the first character of the two strings and then, if they match, compare the second characters, or, if they don't match, compare the first character of the small string with the second character in the large string, and so on. In contrast, the Boyer-Moore algorithm starts by comparing the *last* character of the small string with the correspondingly positioned character in the large string. For most strings the Boyer-Moore algorithm is close to N times faster algorithmically, where N is the length of the small string.

The next couple sections discuss two broad categories for algorithmic improvement that are especially easy to accomplish in Perl 6. For more on this general topic, read the wikipedia page on algorithmic efficiency, especially the See also section near the end.

33.2.4.1 Change sequential/blocking code to parallel/non-blocking

This is another very important class of algorithmic improvement.

See the slides for Parallelism, Concurrency, and Asynchrony in Perl 6 and/or the matching video.

33.2.5 Use existing high performance code

Is there an existing high (enough) performance implementation of what you're trying to speed up / slim down?

There are a lot of C libs out there. NativeCall makes it easy to create wrappers for C libs (there's experimental support for C++ libs too) such as Gumbo. (Data marshalling and call handling is somewhat poorly optimized at the time of writing this but for many applications that won't matter.)

Perl 5's compiler can be treated as a C lib. Mix in Perl 6 types, the MOP, and some hairy programming that someone else has done for you, and the upshot is that you can conveniently use Perl 5 modules in Perl 6.

More generally, Perl 6 is designed for smooth interop with other languages and there are a number of modules aimed at providing convenient use of libs from other langs.

33.2.6 Make the Rakudo compiler generate faster code

The focus to date (Feb 2016) regarding the compiler has been correctness, not how fast it generates code or, more importantly, how fast or lean the code it generates runs. But that's expected to change somewhat this year and beyond. You can talk to compiler devs on the freenode IRC channels #perl6 and #moarvm about what to expect. Better still you can contribute yourself:

33.2.7 Still need more ideas?

There are endless performance topics.

Some known current Rakudo performance weaknesses not yet covered in this page include use of gather/take, use of junctions, regexes, and string handling in general.

If you think some topic needs more coverage on this page please submit a PR or tell someone your idea. Thanks. :)

33.3 Not getting the results you need/want?

If you've tried everything on this page to no avail, please consider discussing things with a compiler dev on #perl6 so we can learn from your use-case and what you've found out about it so far.

Once you know one of the main devs knows of your plight, allow enough time for an informed response (a few days or weeks depending on the exact nature of your problem and potential solutions).

If that hasn't worked out either, please consider filing an issue discussing your experience at our user experience repo before moving on. Thanks. :)

34 Phasers

Program execution phases and corresponding phaser blocks

The lifetime (execution timeline) of a program is broken up into phases. A phaser is a block of code called during a specific execution phase.

34.1 Phasers

A phaser block is just a trait of the closure containing it, and is automatically called at the appropriate moment. These auto-called blocks are known as phasers, since they generally mark the transition from one phase of computing to another. For instance, a CHECK block is called at the end of compiling a compilation unit. Other kinds of phasers can be installed as well; these are automatically called at various times as appropriate, and some of them respond to various control exceptions and exit values.

Here is a summary:

BEGIN {...} #  * at compile time, ASAP, only ever runs once
CHECK {...} #  * at compile time, ALAP, only ever runs once
 INIT {...} #  * at run time, ASAP, only ever runs once
  END {...} #  at run time, ALAP, only ever runs once

ENTER {...} #  * at every block entry time, repeats on loop blocks.
LEAVE {...} #  at every block exit time (even stack unwinds from exceptions)
 KEEP {...} #  at every successful block exit, part of LEAVE queue
 UNDO {...} #  at every unsuccessful block exit, part of LEAVE queue

FIRST {...} #  at loop initialization time, before any ENTER
 NEXT {...} #  at loop continuation time, before any LEAVE
 LAST {...} #  at loop termination time, after any LEAVE

  PRE {...} #  assert precondition at every block entry, before ENTER
 POST {...} #  assert postcondition at every block exit, after LEAVE

CATCH {...} #  catch exceptions, before LEAVE
CONTROL {...} #  catch control exceptions, before LEAVE

   LAST {...} #  supply tapped by whenever-block is done, runs very last
   QUIT {...} #  catch async exceptions within a whenever-block, runs very last

COMPOSE {...} #  when a role is composed into a class
CLOSE   {...} #  appears in a supply block, called when the supply is closed

Phasers marked with a * have a run-time value, and if evaluated earlier than their surrounding expression, they simply save their result for use in the expression later when the rest of the expression is evaluated:

my $compiletime = BEGIN { now };
our $temphandle = ENTER { maketemp() };

As with other statement prefixes, these value-producing constructs may be placed in front of either a block or a statement:

my $compiletime = BEGIN now;
our $temphandle = ENTER maketemp();

Most of these phasers will take either a block or a function reference. The statement form can be particularly useful to expose a lexically scoped declaration to the surrounding lexical scope without "trapping" it inside a block.

These declare the same variables with the same scope as the preceding example, but run the statements as a whole at the indicated time:

BEGIN my $compiletime = now;
ENTER our $temphandle = maketemp();

(Note, however, that the value of a variable calculated at compile time may not persist under run-time cloning of any surrounding closure.)

Most of the non-value-producing phasers may also be so used:

END say my $accumulator;

Note, however, that

END say my $accumulator = 0;

sets the variable to 0 at END time, since that is when the "my" declaration is actually executed. Only argumentless phasers may use the statement form. This means that CATCH and CONTROL always require a block, since they take an argument that sets $_ to the current topic, so that the innards are able to behave as a switch statement. (If bare statements were allowed, the temporary binding of $_ would leak out past the end of the CATCH or CONTROL, with unpredictable and quite possibly dire consequences. Exception handlers are supposed to reduce uncertainty, not increase it.)

Some of these phasers also have corresponding traits that can be set on variables. These have the advantage of passing the variable in question into the closure as its topic:

our $h will enter { .rememberit() } will undo { .forgetit() };

Only phasers that can occur multiple times within a block are eligible for this per-variable form.

The topic of the block outside a phaser is still available as OUTER::<$_> . Whether the return value is modifiable may be a policy of the phaser in question. In particular, the return value should not be modified within a POST phaser, but a LEAVE phaser could be more liberal.

Any phaser defined in the lexical scope of a method is a closure that closes over self as well as normal lexicals. (Or equivalently, an implementation may simply turn all such phasers into submethods whose primed invocant is the current object.)

When multiple phasers are scheduled to run at the same moment, the general tiebreaking principle is that initializing phasers execute in order declared, while finalizing phasers execute in the opposite order, because setup and teardown usually want to happen in the opposite order from each other.

34.1.1 Execution Order

Compilation Begins

  BEGIN {...} #  at compile time, ASAP, only ever runs once
  CHECK {...} #  at compile time, ALAP, only ever runs once
COMPOSE {...} #  when a role is composed into a class

Execution Begins

   INIT {...} #  at run time, ASAP, only ever runs once

Before block execution begins

    PRE {...} #  assert precondition at every block entry, before ENTER

Loop execution begins

  FIRST {...} #  at loop initialization time, before any ENTER

Block execution begins

  ENTER {...} #  at every block entry time, repeats on loop blocks.

Exception maybe happens

  CATCH {...} #  catch exceptions, before LEAVE
CONTROL {...} #  catch control exceptions, before LEAVE

End of loop, either continuing or finished

   NEXT {...} #  at loop continuation time, before any LEAVE
   LAST {...} #  at loop termination time, after any LEAVE

End of block

  LEAVE {...} #  at every block exit time (even stack unwinds from exceptions)
   KEEP {...} #  at every successful block exit, part of LEAVE queue
   UNDO {...} #  at every unsuccessful block exit, part of LEAVE queue

Postcondition for block

   POST {...} #  assert postcondition at every block exit, after LEAVE

Async whenever-block is complete

   LAST {...} #  if ended normally with done, runs once after block
   QUIT {...} #  catch async exceptions

Program terminating

    END {...} #  at run time, ALAP, only ever runs once

34.2 Program Execution Phasers

34.2.1 BEGIN

Runs at compile time, as soon as possible, only runs once.

Can have a return value that is provided even in later phases.

34.2.2 CHECK

Runs at compile time, As late as possible, only runs once.

Can have a return value that is provided even in later phases.

Code that is generated at run time can still fire off CHECK and INIT phasers, though of course those phasers can't do things that would require travel back in time. You need a wormhole for that.

34.2.3 INIT

Runs after compilation during main execution, as soon as possible, only runs once.

Can have a return value that is provided even in later phases.

When phasers are in different modules, the INIT and END phasers are treated as if declared at use time in the using module. (It is erroneous to depend on this order if the module is used more than once, however, since the phasers are only installed the first time they're noticed.)

Code that is generated at run time can still fire off CHECK and INIT phasers, though of course those phasers can't do things that would require travel back in time. You need a wormhole for that.

An INIT only runs once for all copies of a cloned closure.

34.2.4 END

Runs after compilation during main execution, as late as possible, only runs once.

When phasers are in different modules, the INIT and END phasers are treated as if declared at use time in the using module. (It is erroneous to depend on this order if the module is used more than once, however, since the phasers are only installed the first time they're noticed.)

34.2.5 CLOSE

Appears in a supply block. Called when the supply is closed.

34.3 Block Phasers

Execution in the context of a block has its own phases.

Block-leaving phasers wait until the call stack is actually unwound to run. Unwinding happens only after some exception handler decides to handle the exception that way. That is, just because an exception is thrown past a stack frame does not mean we have officially left the block yet, since the exception might be resumable. In any case, exception handlers are specified to run within the dynamic scope of the failing code, whether or not the exception is resumable. The stack is unwound and the phasers are called only if an exception is not resumed.

These can occur multiple times within the block. So they aren't really traits, exactly--they add themselves onto a list stored in the actual trait. So if you examine the ENTER trait of a block, you'll find that it's really a list of phasers rather than a single phaser.

All of these phaser blocks can see any previously declared lexical variables, even if those variables have not been elaborated yet when the closure is invoked (in which case the variables evaluate to an undefined value.)

34.3.1 ENTER

Runs at every block entry time, repeats on loop blocks.

Can have a return value that is provided even in later phases.

An exception thrown from an ENTER phaser will abort the ENTER queue, but one thrown from a LEAVE phaser will not.

34.3.2 LEAVE

Runs at every block exit time (even stack unwinds from exceptions).

So LEAVE phasers for a given block are necessarily evaluated after any CATCH and CONTROL phasers. This includes the LEAVE variants, KEEP and UNDO. POST phasers are evaluated after everything else, to guarantee that even LEAVE phasers can't violate postconditions.

An exception thrown from an ENTER phaser will abort the ENTER queue, but one thrown from a LEAVE phaser will not.

If a POST fails or any kind of LEAVE block throws an exception while the stack is unwinding, the unwinding continues and collects exceptions to be handled. When the unwinding is completed all new exceptions are thrown from that point.

sub answer() {
    LEAVE say „I say after the return value.“;

    42 # this is the return value
}

Note: be mindful of LEAVE phasers directly in blocks of routines, as they will get executed even when an attempt to call the routine with wrong arguments is made:

sub foo (Int) {
    say "Hello!";
    LEAVE say "oh noes!"
}
try foo rand; # OUTPUT: «oh noes!␤»

Although the subroutine's body did not get run, because the sub expects an Int and rand returned a Num, its block was entered and left (when param binding failed), and so the LEAVE phaser was run.

34.3.3 KEEP

Runs at every successful block exit, as part of the LEAVE queue (shares the same order of execution).

For phasers such as KEEP and POST that are run when exiting a scope normally, the return value (if any) from that scope is available as the current topic within the phaser.

34.3.4 UNDO

Runs at every unsuccessful block exit, as part of the LEAVE queue (shares the same order of execution).

34.3.5 PRE

Asserts a precondition at every block entry. Runs before the ENTER phase.

PRE phasers fire off before any ENTER or FIRST.

The exceptions thrown by failing PRE and POST phasers cannot be caught by a CATCH in the same block, which implies that POST phaser are not run if a PRE phaser fails.

34.3.6 POST

Asserts a postcondition at every block entry. Runs after the LEAVE phase.

For phasers such as KEEP and POST that are run when exiting a scope normally, the return value (if any) from that scope is available as the current topic within the phaser.

The POST block can be defined in one of two ways. Either the corresponding POST is defined as a separate phaser, in which case PRE and POST share no lexical scope. Alternately, any PRE phaser may define its corresponding POST as an embedded phaser block that closes over the lexical scope of the PRE.

If a POST fails or any kind of LEAVE block throws an exception while the stack is unwinding, the unwinding continues and collects exceptions to be handled. When the unwinding is completed all new exceptions are thrown from that point.

The exceptions thrown by failing PRE and POST phasers cannot be caught by a CATCH in the same block, which implies that POST phaser are not run if a PRE phaser fails.

34.4 Loop Phasers

FIRST, NEXT, and LAST are meaningful only within the lexical scope of a loop, and may occur only at the top level of such a loop block.

34.4.1 FIRST

Runs at loop initialization, before ENTER.

34.4.2 NEXT

Runs when loop is continued (either through next or because you got to the bottom of the loop and are looping back around), before LEAVE.

A NEXT executes only if the end of the loop block is reached normally, or an explicit next is executed. In distinction to LEAVE phasers, a NEXT phaser is not executed if the loop block is exited via any exception other than the control exception thrown by next. In particular, a last bypasses evaluation of NEXT phasers.

34.4.3 LAST

Runs when loop is aborted (either through last, or return, or because you got to the bottom of the loop and are done), after LEAVE.

34.5 Exception Handling Phasers

34.5.1 CATCH

Runs when an exception is raised by the current block, before the LEAVE phase.

34.5.2 CONTROL

Runs when a control exception is raised by the current block, before the LEAVE phase. It is raised by return, fail, redo, next, last, take, warn, proceed and succeed.

# NYI # =head1 Object Phasers # # =head2 COMPOSE # # Runs when a role is composed into a class.

34.6 Asynchronous Phasers

34.6.1 LAST

Runs when a Supply finishes with a call to done or when a supply block exits normally. It runs completely after the whenever block it is placed within finishes.

This phaser reuses the name LAST, but works differently from the LAST loop phaser. This phaser is similar to setting the done routine while tapping a supply with tap.

34.6.2 QUIT

Runs when a Supply terminates early with an exception. It runs after the whenever block it is placed within finishes.

This phaser is similar to setting the quit routine while tapping a Supply with tap.

34.7 DOC phasers

34.7.1 DOC

The phasers BEGIN, CHECK and INIT are run only in documentation mode when prefixed with the DOC keyword. The compiler is in documentation when run with --doc.

DOC INIT { say 'init'  }  # prints 'init' at initialization time when in documentation mode.

35 Perl 6 Pod

An easy-to-use markup language

Pod is an easy-to-use markup language. Pod can be used for writing language documentation, for documenting programs and modules, as well as for other types of document composition.

Every Pod document has to begin with =begin pod and end with =end pod. Everything between these 2 delimiters will be processed and used to generate documentation.

=begin pod 
 
 A very simple Perl 6 Pod document 
 
 =end pod 

35.1 Block Structure

A Pod document may consist of multiple Pod blocks. There are three ways to define a block; all of which yield the same result. You can use whichever form is most convenient for your particular documentation task.

35.1.1 Delimited blocks

Delimited blocks are bound by =begin and =end markers, both of which are followed by the typename of the block.

=begin head1 
 Top Level Heading 
 =end head1 

35.1.2 Paragraph blocks

Paragraph blocks begin by a =for marker and end by the next Pod directive or the first blank line. The =for marker is followed by the typename of the block.

=for head1 
 Top Level Heading 

35.1.3 Abbreviated blocks

Abbreviated blocks begin by an '=' sign, which is followed immediately by the typename of the block. The block ends at the next Pod directive or the first blank line.

=head1 Top Level Heading 

35.2 Block types

Pod offers a wide range of standard block types.

35.2.1 Headings

Headings can be defined using =headN, where N is greater than zero (e.g., =head1, =head2, …).

=head1 A Top Level Heading 
 
 =head2 A Second Level Heading 
 
 =head3 A Third Level Heading 

35.2.2 Ordinary paragraphs

Ordinary paragraph consist of text that is to be formatted into a document at the current level of nesting, with whitespace squeezed, lines filled, and any special inline mark-up applied.

Ordinary paragraphs consist of one or more consecutive lines of text, each of which starts with a non-whitespace character. The paragraph is terminated by the first blank line or block directive.

For example:

=head1 This is a heading block 
 
 This is an ordinary paragraph. 
 Its text  will   be     squeezed     and 
 short lines filled. It is terminated by 
 the first blank line. 
 
 This is another ordinary paragraph. 
 Its     text    will  also be squeezed and 
 short lines filled. It is terminated by 
 the trailing directive on the next line. 
 
 =head2 This is another heading block 
 
 This is yet another ordinary paragraph, 
 at the first virtual column set by the 
 previous directive 

Ordinary paragraphs do not require an explicit marker or delimiters.

Alternatively, there is also an explicit =para marker that can be used to explicitly mark a paragraph.

=para 
 This is an ordinary paragraph. 
 Its text  will   be     squeezed     and 
 short lines filled. 

In addition, the longer =begin para and =end para form can be used.

For example:

=begin para 
 This is an ordinary paragraph. 
 Its text  will   be     squeezed     and 
 short lines filled. 
 
 This is still part of the same paragraph, 
 which continues until an... 
 =end para 

As demonstrated by the previous example, within a delimited =begin para and =end para block, any blank lines are preserved.

35.2.3 Code blocks

Code blocks are used to specify source code, which should be rendered without re-justification, without whitespace-squeezing, and without recognizing any inline formatting codes. Typically these blocks are used to show examples of code, mark-up, or other textual specifications, and are rendered using a fixed-width font.

A code block may be implicitly specified as one or more lines of text, each of which starts with a whitespace character. The implicit code block is then terminated by a blank line.

For example:

This ordinary paragraph introduces a code block: 
 
     my $name = 'John Doe'; 
     say $name; 

Code blocks can also be explicitly defined by enclosing them in =begin code and =end code

    =begin code 
     my $name = 'John Doe'; 
     say $name; 
     =end code 

35.2.4 I/O blocks

Pod provides blocks for specifying the input and output of programs.

The =input block is used to specify pre-formatted keyboard input, which should be rendered without re-justification or squeezing of whitespace.

The =output block is used to specify pre-formatted terminal or file output, which should also be rendered without re-justification or whitespace-squeezing.

35.2.5 Lists

35.2.5.1 Unordered Lists

Lists in Pod are specified as a series of =item blocks.

For example:

The three suspects are: 
 
 =item  Happy 
 =item  Sleepy 
 =item  Grumpy 

The three suspects are:

35.2.5.2 Multi-level Lists

Lists may be multi-level, with items at each level specified using the =item1, =item2, =item3, etc. blocks.

Note that =item is just an abbreviation for =item1.

For example:

=item1  Animal 
 =item2     Vertebrate 
 =item2     Invertebrate 
 
 =item1  Phase 
 =item2     Solid 
 =item2     Liquid 
 =item2     Gas 

35.2.5.3 Multi-paragraph Lists

Using the delimited form of the =item block (=begin item and =end item), we can specify items that contain multiple paragraphs.

For example:

Let's consider two common proverbs: 
 
 =begin item 
 I<The rain in Spain falls mainly on the plain.> 
 
 This is a common myth and an unconscionable slur on the Spanish 
 people, the majority of whom are extremely attractive. 
 =end item 
 
 =begin item 
 I<The early bird gets the worm.> 
 
 In deciding whether to become an early riser, it is worth 
 considering whether you would actually enjoy annelids 
 for breakfast. 
 =end item 
 
 As you can see, folk wisdom is often of dubious value. 

Let's consider two common proverbs:

As you can see, folk wisdom is often of dubious value.

35.2.6 Tables

Check out this page for documentation related to Tables

35.2.7 Pod comments

Pod comments are comments that Pod renderers ignore.

Comments are useful for meta-documentation (documenting the documentation):

=comment Add more here about the algorithm 

35.2.8 Semantic blocks

All uppercase block typenames are reserved for specifying standard documentation, publishing, source components, or meta-information.

=NAME 
 =AUTHOR 
 =VERSION 
 =TITLE 
 =SUBTITLE 

35.3 Formatting Codes

Formatting codes provide a way to add inline mark-up to a piece of text.

All Pod formatting codes consist of a single capital letter followed immediately by a set of angle brackets.

Formatting codes may nest other formatting codes.

35.3.1 Bold

To format a text in bold enclose it in B< >

Perl 6 is B<awesome> 

Perl 6 is awesome

35.3.2 Italic

To format a text in italic enclose it in I< >

Perl 6 is I<awesome> 

Perl 6 is awesome

35.3.3 Underlined

To underline a text enclose it in U< >

Perl 6 is U<awesome> 

35.3.4 Code

To flag text as Code and treat it verbatim enclose it in C< >

C<my $var = 1; say $var;> 

my $var = 1; say $var;

To create a link enclose it in L< >

Perl 6 homepage L<https://perl6.org> 

Perl 6 homepage https://perl6.org

35.3.6 Comments

A comment is text that is never rendered.

To create a comment enclose it in Z< >

Perl 6 is awesome Z<Of course it is!> 

Perl 6 is awesome

35.3.7 Notes

Notes are rendered as footnotes.

To create a note enclose it in N< >

Perl 6 is multi-paradigmatic N<Supporting Procedural, Object Oriented, and Functional programming> 

35.3.8 Keyboard input

To flag text as keyboard input enclose it in K< >

Enter your name K<John Doe> 

35.3.9 Terminal Output

To flag text as terminal output enclose it in T< >

Hello T<John Doe> 

35.3.10 Unicode

To include Unicode code points or HTML5 character references in a Pod document, enclose them in E< >

E< > can enclose a number, that number is treated as the decimal Unicode value for the desired code point. It can also enclose explicit binary, octal, decimal, or hexadecimal numbers using the Perl 6 notations for explicitly based numbers.

Perl 6 makes considerable use of the E<171> and E<187> characters. 
 
 Perl 6 makes considerable use of the E<laquo> and E<raquo> characters. 
 
 Perl 6 makes considerable use of the E<0b10101011> and E<0b10111011> characters. 
 
 Perl 6 makes considerable use of the E<0o253> and E<0o273> characters. 
 
 Perl 6 makes considerable use of the E<0d171> and E<0d187> characters. 
 
 Perl 6 makes considerable use of the E<0xAB> and E<0xBB> characters. 

Perl 6 makes considerable use of the « and » characters.

35.4 Rendering Pod

35.4.1 HTML

In order to generate HTML from Pod, you need the Pod::To::HTML module.

If it is not already installed, install it by running the following command: zef install Pod::To::HTML

Using the terminal run the following command:

perl6 --doc=HTML input.pod6 > output.html 

35.4.2 Markdown

In order to generate Markdown from Pod, you need the Pod::To::Markdown module.

If it is not already installed, install it by running the following command: zef install Pod::To::Markdown

Using the terminal run the following command:

perl6 --doc=Markdown input.pod6 > output.md 

35.4.3 Text

In order to generate Text from Pod, you can use the default Pod::To::Text module.

Using the terminal, run the following command:

perl6 --doc input.pod6 > output.txt 

You can even embed Pod directly in your program and add the traditional Unix command line "--man" option to your program with a multi MAIN subroutine like this:

multi MAIN(Bool :$man) 
 { 
     run $*EXECUTABLE, '--doc', $*PROGRAM; 
 } 

Now myprogram --man will output your Pod rendered as a man page.

36 Pragmas

Special modules for special use

In Perl 6, pragmas are core modules used to either identify a specific version of Perl 6 to be used or to modify its normal behavior in some way. They are "use"ed in your code just as normal modules:

use v6.c; 

Following is a list of pragmas with a short description of each pragma's purpose or a link to more details about its use. (Note: Pragmas marked "[NYI]" are not yet implemented, and those marked "[TBD]" are to be defined later.)

The following should be a table but formatting in tables is not yet rendered properly.

This pragma is not currently part of any Perl 6 specification, but is present in Rakudo as a synonym to use nqp (see below).

A lexical pragma that makes Failures returned from routines fatal. For example, prefix + on a Str coerces it to Numeric, but will return a Failure if the string contains non-numeric characters. Saving that Failure in a variable prevents it from being sunk, and so the first code block below reaches the say $x.^name; line and prints Failure in output.

In the second block, the use fatal pragma is enabled, so the say line is never reached because the Exception contained in the Failure returned from prefix + gets thrown and the CATCH block gets run, printing the Caught... line. Note that both blocks are the same program and use fatal only affects the lexical block it was used in:

{
    my $x = +"a";
    say $x.^name;
    CATCH { default { say "Caught {.^name}" } }
} # OUTPUT: «Failure␤»

{
    use fatal;
    my $x = +"a";
    say $x.^name;
    CATCH { default { say "Caught {.^name}" } }
} # OUTPUT: «Caught X::Str::Numeric␤»

Inside of a try blocks, the fatal pragma is enabled by default, and you can disable it with no fatal:

try {
    my $x = +"a";
    say $x.^name;
    CATCH { default { say "Caught {.^name}" } }
} # OUTPUT: «Caught X::Str::Numeric␤»

try {
    no fatal;
    my $x = +"a";
    say $x.^name;
    CATCH { default { say "Caught {.^name}" } }
} # OUTPUT: «Failure␤»

Use at your own risk.

This is a Rakudo-specific pragma. With it, Rakudo provides access to the nqp opcodes in a top level namespace:

use nqp;
nqp::say("hello world");

This uses the underlying nqp say opcode instead of the Perl 6 routine. This pragma may make your code rely on a particular version of nqp, and since that code is not part of the Perl 6 specification, it's not guaranteed to be stable. You may find a large number of usages in the Rakudo core, which are used to make the core functionality as fast as possible. Future optimizations in the code generation of Rakudo may obsolete these usages.

37 Perl 6 from Python - Nutshell

Learning Perl 6 from Python, in a nutshell.

This page is an attempt to provide a way to learn Perl 6 for folks coming from a Python background. We discuss the equivalent syntax in Perl 6 for a number of Python constructs and idioms.

37.1 Basic Syntax

37.1.1 Hello, world

Let's start with printing "Hello, world!". put in Perl 6 is the equivalent of print in Python. Like Python 2, parentheses are optional. A return is added to the end of the line.

Python 2

print "Hello, world!"

Python 3

print("Hello, world!")

Perl 6

put "Hello, world!"

There is also say, which behaves similarly, but will call the gist method of its argument.

Perl 6

say "Hello, world!";  # also prints "Hello, world"
say $hello;           # same as: put $hello.gist

In Python, ' and " are interchangeable. In Perl 6, both may be used for quoting, but double quotes (") signify that interpolation should be performed. For instance, variables that start with a $, and expressions contained in curly braces are interpolated.

Perl 6

my $planet = 'earth';
say "Hello, $planet";   # Hello, earth
say 'Hello, $planet';   # Hello, $planet
say "Hello, planet number { 1 + 2 }"; # Hello, planet number 3

37.1.2 Statement Separators

In Python, a newline signifies the end of a statement. There are a few exceptions: A backslash before a newline continues a statement across lines. Also if there is an unmatched opening parentheses, bracket, or curly brace, the statement continues across lines, until the matching braces are closed.

In Perl 6, a semicolon signifies the end of a statement. The semicolon may be omitted if it is the last statement of a block. The semicolon may also be omitted if there is a closing curly brace followed by a newline.

Python

print 1 + 2 + \
    3 + 4
print ( 1 +
    2 )

Perl 6

say 1 + 2 +
    3 + 4;
if True { say 1 + 2 }

37.1.3 Blocks

In Python, indentation is used to indicate a block. Perl 6 uses curly braces.

Python

if 1 == 2:
    print "Wait, what?"
else:
    print "1 is not 2."

Perl 6

if 1 == 2 {
    say "Wait, what?"
} else {
    say "1 is not 2."
}

Parentheses are optional in both languages in expressions in conditionals, as shown above.

37.1.4 Variables

In Python, variables are declared and initialized at the same time:

foo = 12
bar = 19

In Perl 6, my declares a lexical variable. A variable can be initialized with =. i.e. these can be written as two statements or one.

my $foo;       # declare
$foo = 12;     # initialize
my $bar = 19;  # both at once

Also, as you may have noticed, variables in Perl 6 usually start with sigils -- symbols indicating the type of their container. Variables starting with a $ hold scalars. Variables starting with an @ hold arrays, and variables starting with a % hold a hash (dict). Immutable variables can be sigil-less, if they are declared with a \.

Python

s = 10
l = [1, 2, 3]
d = { a : 12, b : 99 }

print s
print l[2]
print d['a']
# 10, 2, 12

Perl 6

my $s = 10;
my @l = 1, 2, 3;
my %d = a => 12, b => 99;
my \x = 99;

say $s;
say @l[1];
say %d<a>;  # or %d{'a'}
say x;
# 10, 2, 12, 99

37.1.5 Scope

In Python, functions and classes create a new scope, but no other block constructor (e.g. loops, conditionals) creates a scope. In Python 2, list comprehensions do not create a new scope, but in Python 3, they do.

In Perl 6, every block creates a lexical scope.

Python

if True:
    x = 10
print x
# x is now 10

Perl 6

if True {
    my $x = 10
}
say $x
# error, $x is not declared in this scope

my $x;
if True {
    $x = 10
}
say $x
# ok, x is 10

Python

x = 10
for x in 1, 2, 3:
    pass
print x
# x is 3

Perl 6

my \x = 10;
for 1, 2, 3 -> \x {
    # do nothing
    }
say x;
# x is 10

Lambdas in Python can be written as blocks or pointy blocks in Perl 6.

Python

l = lambda i: i + 12

Perl 6

$l = -> $i { $i + 12 }

Another Perl 6 idiom for constructing lambdas is the Whatever star, *.

Perl 6

$l = * + 12    # same as above

A * in an expression will become a placeholder for the argument, and transform the expression into a lambda at compile time. Each * in an expression is a separate positional parameter.

See the section below for more constructs regarding subroutines and blocks.

Another example (from the Python FAQ):

Python

squares = []
for x in range(5):
    squares.append(lambda: x ** 2)
print squares[2]()
print squares[4]()
# both 16 since there is only one x

Perl 6

my \squares = [];
for ^5 -> \x {
    squares.append({ x² });
}
say squares[2]();
say squares[4]();
# 4, 16 since each loop iteration has a lexically scoped x,

Note that ^N is like range(N). Similarly, N..^M works like range(N, M) (a list from N to M - 1). N..M is a list from N to M. The ^ before or after the .. indicates that the beginning or ending endpoint of the list (or both) should be excluded.

Also, is a cute way of writing $x ** 2 (which also works fine); the unicode superscript 2 squares a number. Many of the other unicode operators work as you would expect (exponents, fractions, π), but every unicode operator or symbol that can be used in Perl 6 has an ASCII equivalent (also known as its Texas counterpart).

37.1.6 Control Flow

Python has for loops and while loops:

for i in 1, 2:
    print i
j = 1
while j < 3:
    print j
    j += 1

# 1, 2, 1, 2

Perl 6 also has for loops and while loops:

for 1, 2 -> $i {
    say $i
}
my $j = 1;
while $j < 3 {
    say $j;
    $j += 1
}

(Perl 6 also has a few more looping constructs: repeat, until, repeat, while, until, and loop.)

last leaves a loop in Perl 6, and is analogous to break in Python. continue in Python is next in Perl 6.

Python

for i in range(10):
    if i == 3:
        continue
    if i == 5:
        break
    print i

Perl 6

for ^10 -> $i {
    next if $i == 3;
    last if $i == 5;
    say $i;
}

Using if as a statement modifier (as above) is acceptable in Perl 6, even outside of a list comprehension.

The yield statement in Python which produces a generator is like a gather, take construct in Perl 6. These both print 1, 2, 3.

Python

def count():
    for i in 1, 2, 3:
        yield i

for c in count():
    print c

Perl 6

sub count {
    gather {
        for 1, 2, 3 -> $i {
            take $i
        }
    }
}

for count() -> $c {
    say $c;
}

37.1.7 Lambdas, Functions and Subroutines

Declaring a function (subroutine) with def in Python is accomplished with sub in Perl 6.

def add(a, b):
    return a + b

sub add(\a, \b) {
    return a + b
}

The return is optional; the value of the last expression is used as the return value:

sub add(\a, \b) {
    a + b
}

# using variables with sigils
sub add($a, $b) {
    $a + $b
}

Python 2 functions can be called with positional arguments or keyword arguments. These are determined by the caller. In Python 3, some arguments may be "keyword only". In Perl 6, positional and named arguments are determined by the signature of the routine.

Python

def speak(word, times):
    for i in range(times):
        print word
speak('hi', 2)
speak(word='hi', times=2)

Perl 6

Positional parameters:

sub speak($word, $times) {
  say $word for ^$times
}
speak('hi', 2);

Named parameters start with a colon:

sub speak(:$word, :$times) {
  say $word for ^$times
}
speak(word => 'hi', times => 2);
speak(:word<hi>, :times<2>);      # Alternative, more idiomatic

Perl 6 supports multiple dispatch, so several signatures could be made available by declaring a routine as a multi.

multi sub speak($word, $times) {
  say $word for ^$times
}
multi sub speak(:$word, :$times) {
    speak($word, $times);
}
speak('hi', 2);
speak(:word<hi>, :times<2>);

Named parameters can be sent using a variety of formats:

# all the same
hello(name => 'world'); # fat arrow syntax
hello(:name('world'));  # pair constructor
hello :name<world>;     # <> quotes words and makes a list
my $name = 'world';
hello(:$name);          # lexical var with the same name

Creating an anonymous function can be done with sub, with a block or with a pointy block.

Python

square = lambda x: x ** 2

Perl 6

$square = sub ($x) { $x ** 2 };  # anonymous sub
$square = -> $x { $x ** 2 };     # pointy block
$square = { $^x ** 2 };          # placeholder variable
$square = { $_ ** 2 };           # topic variable

Placeholder variables are lexicographically ordered to form positional parameters. i.e. these are the same:

$power = { $^x ** $^y }
$power = -> $x, $y { $x ** $y }

37.1.8 List Comprehensions

Postfix modifiers and anonymous functions can be combined to make list comprehensions.

Python

[ i * 2 for i in 3, 9 ]

Perl 6

( -> \i { i * 2 } for 3, 9 );
( { $^i * 2 } for 3, 9 );
( { $_ * 2 } for 3, 9 );

Conditionals can be applied, but the if comes first, unlike in Python where the if comes second.

[ x * 2 for x in 1, 2, 3 if x > 1 ]

vs

( $_ * 2 if $_ > 1 for 1, 2, 3 );

For nested loops, the cross product operator X will help:

[ i + j for i in 3,9 for j in 2,10 ]

becomes either of these:

( { $_[0] + $_[1] } for (3,9) X (2,10) );
( -> (\i, \j) { i + j } for (3,9) X (2,10) );

Using map (which is just like Python's map) is an alternative.

37.1.9 Classes and Objects

Here's an example from the Python docs. First, "instance variables", aka attributes in Perl 6:

Python:

class Dog:
    def __init__(self, name):
        self.name = name

Perl 6:

class Dog {
    has $.name;
}

Constructors by default take named arguments in Perl 6, and use the method new.

Python

d = Dog('Fido')
e = Dog('Buddy')
print d.name
print e.name

Perl 6

my $d = Dog.new(:name<Fido>);
my $e = Dog.new(:name<Buddy>);
say $d.name;
say $e.name;

Class attributes in Perl 6 can be declared in a few ways. One way is to just declare a lexical variable and a method for accessing it.

Python:

class Dog:
    kind = 'canine'                # class attribute
    def __init__(self, name):
        self.name = name           # instance attribute
d = Dog('Fido')
e = Dog('Buddy')
print d.kind
print e.kind
print d.name
print e.name

Perl 6:

class Dog {
    my $kind = 'canine';           # class attribute
    method kind { $kind }
    has $.name;                    # instance attribute
}

my $d = Dog.new(:name<Fido>);
my $e = Dog.new(:name<Buddy>);
say $d.kind;
say $e.kind;
say $d.name;
say $e.name;

To mutate attributes, in Perl 6 you"ll want to use is rw:

Python:

class Dog:
    def __init__(self, name):
        self.name = name
d = Dog()
d.name = 'rover'

Perl 6:

class Dog {
    has $.name is rw;
}
my $d = Dog.new;
$d.name = 'rover';

Inheritance is done using is:

Python

class Animal:
    def jump(self):
        print ("I am jumping")

class Dog(Animal):
    pass

d = Dog()
d.jump()

Perl 6

class Animal {
    method jump {
        say "I am jumping"
    }
}

class Dog is Animal {
}

my $d = Dog.new;
$d.jump;

Multiple inheritance is possible by using is multiple times, or with also.

Python

class Dog(Animal, Friend, Pet):
    pass

Perl 6

class Dog is Animal is Friend is Pet { ... }

or

class Dog is Animal {
    also is Friend;
    also is Pet;
    ...
}

37.1.10 Decorators

Decorators in Python are a way of wrapping a function in another one. In Perl 6, this is done with wrap.

Python

def greeter(f):
    def new():
        print 'hello'
        f()
    return new

@greeter
def world():
    print 'world'

world();

Perl 6

sub world {
    say 'world'
}

&world.wrap(sub () {
    say 'hello';
    callsame;
});

world;

An alternative would be to use a trait:

# declare the trait 'greeter'
multi sub trait_mod:<is>(Routine $r, :$greeter) {
    $r.wrap(sub {
        say 'hello';
        callsame;
    })
}

sub world is greeter {
    say 'world';
}

world;

37.1.11 Context Managers

Context managers in Python declare actions that happen when entering or exiting a scope.

Here's a python context manager that prints the strings 'hello', 'world', and 'bye':

class hello:
    def __exit__(self, type, value, traceback):
        print 'bye'
    def __enter__(self):
        print 'hello'

with hello():
    print 'world'

For enter and exit events, passing a block as an argument would be one option:

sub hello(Block $b) {
    say 'hello';
    $b();
    say 'bye';
}

hello {
    say 'world';
}

A related idea is 'Phasers' which may be set up to run on entering or leaving a block.

{
    LEAVE say 'bye';
    ENTER say 'hello';
    say 'world';
}

37.1.12 Input

See the prompt function.

38 Quoting Constructs

Writing strings, word lists, and regexes in Perl 6

38.1 The Q Lang

Strings are usually represented in Perl 6 code using some form of quoting construct. The most minimalistic of these is Q, usable via the shortcut 「…」, or via Q followed by any pair of delimiters surrounding your text. Most of the time, though, the most you'll need is '…' or "…", described in more detail in the following sections.

38.1.1 Literal strings: Q

 Q[ A literal string ]  
   More plainly.   
  Q ^ Almost any non-word character can be a delimiter! ^  
  Q 「「 Delimiters can be repeated/nested if they are adjacent. 」」  

Delimiters can be nested, but in the plain Q form, backslash escapes aren't allowed. In other words, basic Q strings are as literal as possible.

Some delimiters are not allowed immediately after Q, q, or qq. Any characters that are allowed in identifiers are not allowed to be used, since in such a case, the quoting construct together with such characters are interpreted as an identifier. In addition, ( ) is not allowed because that is interpreted as a function call. If you still wish to use those characters as delimiters, separate them from Q, q, or qq with a space. Please note that some natural languages use a left delimiting quote on the right side of a string. Q will not support those as it relies on unicode properties to tell left and right delimiters apart.

 Q' this will not work! '  
  Q( this won't work either! )  
  Q ( this is fine, because of space after Q )  
  Q ' and so is this '  
Q<Make sure you  < match >  opening and closing delimiters> 
 Q{This is still a closing curly brace →  \ } 

These examples produce:

A literal string 
 More plainly. 
 Almost any non-word character can be a delimiter! 
 Make sure you <match> opening and closing delimiters 
 This is still a closing curly brace → \ 

The behaviour of quoting constructs can be modified with adverbs, as explained in detail in later sections.

Short Long Meaning
:x :exec Execute as command and return results
:w :words Split result on words (no quote protection)
:ww :quotewords Split result on words (with quote protection)
:q :single Interpolate \\, \qq[...] and escaping the delimiter with \
:qq :double Interpolate with :s, :a, :h, :f, :c, :b
:s :scalar Interpolate $ vars
:a :array Interpolate @ vars
:h :hash Interpolate % vars
:f :function Interpolate & calls
:c :closure Interpolate {...} expressions
:b :backslash Interpolate \n, \t, etc. (implies :q at least)
:to :heredoc Parse result as heredoc terminator
:v :val Convert to allomorph if possible

38.1.2 Escaping: q

'Very plain';
q[This back\slash stays];
q[This back\\slash stays]; # Identical output
q{This is not a closing curly brace → \}, but this is → };
Q :q $There are no backslashes here, only lots of \$\$\$>!$;
'(Just kidding. There\'s no money in that string)';
'No $interpolation {here}!';
Q:q!Just a literal "\n" here!;

The q form allows for escaping characters that would otherwise end the string using a backslash. The backslash itself can be escaped, too, as in the third example above. The usual form is '…' or q followed by a delimiter, but it's also available as an adverb on Q, as in the fifth and last example above.

These examples produce:

Very plain 
 This back\slash stays 
 This back\slash stays 
 This is not a closing curly brace → } but this is → 
 There are no backslashes here, only lots of $$$! 
 (Just kidding. There's no money in that string) 
 No $interpolation {here}! 
 Just a literal "\n" here 

38.1.3 Interpolation: qq

my $color = 'blue'; 
  say   " My favorite color is  $color ! "  
 
 My favorite color is blue! 

The qq form – usually written using double quotes – allows for interpolation of backslash sequences and variables, i.e., variables can be written within the string so that the content of the variable is inserted into the string. It is also possible to escape variables within a qq-quoted string:

say  " The  \ $color variable contains the value '$color' " ; 
 
 The $color variable contains the value 'blue' 

Another feature of qq is the ability to interpolate Perl 6 code from within the string, using curly braces:

my ($x, $y, $z) = 4, 3.5, 3; 
 say "This room is  $x  m by  $y  m by  $z  m."; 
 say "Therefore its volume should be  { $x * $y * $z }  m³!"; 
 
 This room is 4 m by 3.5 m by 3 m. 
 Therefore its volume should be 42 m³! 

By default, only variables with the $ sigil are interpolated normally. This way, when you write "documentation@perl6.org", you aren't interpolating the @perl6 variable. If that's what you want to do, append a [] to the variable name:

my @neighbors = "Felix", "Danielle", "Lucinda"; 
 say "@neighbors []  and I try our best to coexist peacefully." 
 
 Felix Danielle Lucinda and I try our best to coexist peacefully. 

Often a method call is more appropriate. These are allowed within qq quotes as long as they have parentheses after the call. Thus the following code will work:

say "@neighbors . join (', ')  and I try our best to coexist peacefully." 
 
 Felix, Danielle, Lucinda and I try our best to coexist peacefully. 

However, "@example.com" produces @example.com.

To call a subroutine use the &-sigil.

say "abc&uc("def")ghi";
# OUTPUT: «abcDEFghi␤»

Postcircumfix operators and therefore subscripts are interpolated as well.

my %h = :1st; say "abc%h<st>ghi";
# OUTPUT: «abc1ghi␤»

To enter unicode sequences use \x or \x[] with the hex-code of the character or a list of characters.

my $s = "I \x[2665] Perl 6!";
dd $s;
# OUTPUT: «Str $s = "I ♥ Perl 6!"␤»
my $s = "I really \x[2661,2665,2764,1f495] Perl 6!";
dd $s;
# OUTPUT: «Str $s = "I really ♡♥❤💕 Perl 6!"␤»

You can also use unicode names with \c[].

my $s = "Camelia \c[BROKEN HEART] my \c[HEAVY BLACK HEART]!";
dd $s;
# OUTPUT: «Str $s = "Str $s = "Camelia 💔 my ❤!"␤»

Interpolation of undefined values will raise a control exception that can be caught in the current block with CONTROL.

sub niler {Nil}; 
 my Str $a = niler; 
 say("$a.html", "sometext"); 
 say "alive"; # this line is dead code 
 CONTROL { .die }; 

38.1.4 Word quoting: qw

 qw| ! @ # $ % ^ & * \| < >  |  eqv '! @ # $ % ^ & * | < >'.words.list 
  q:w {  [ ] \{ \}  }  eqv ('[', ']', '{', '}') 
  Q:w |  [ ] { }  |  eqv ('[', ']', '{', '}') 

The :w form, usually written as qw, splits the string into "words". In this context, words are defined as sequences of non-whitespace characters separated by whitespace. The q:w and qw forms inherit the interpolation and escape semantics of the q and single quote string delimiters, whereas Qw and Q:w inherit the non-escaping semantics of the Q quoter.

This form is used in preference to using many quotation marks and commas for lists of strings. For example, where you could write:

my @directions = 'left', 'right,', 'up', 'down';

It's easier to write and to read this:

my @directions = qw|left right up down|;

38.1.5 Word quoting: < >

 < a b c >   eqv  ('a', 'b', 'c');   # OUTPUT: «True␤» 
  < a b 42 >   eqv  ('a', 'b', '42'); # OUTPUT: «False␤», the 42 become an IntStr allomorph 
 say < 42 > ~~ Int; # OUTPUT: «True␤» 
 say < 42 > ~~ Str; # OUTPUT: «True␤» 

The angle brackets quoting is like qw, but with extra feature that lets you construct allomorphs or literals of certain numbers:

say <42 4/2 1e6 1+1i abc>.perl;
# OUTPUT: «(IntStr.new(42, "42"), RatStr.new(2.0, "4/2"), NumStr.new(1000000e0, "1e6"), ComplexStr.new(<1+1i>, "1+1i"), "abc")␤»

To construct a Rat or Complex literal, use angle brackets around the number, without any extra spaces:

say <42/10>.^name;   # OUTPUT: «Rat␤»
say <1+42i>.^name;   # OUTPUT: «Complex␤»
say < 42/10 >.^name; # OUTPUT: «RatStr␤»
say < 1+42i >.^name; # OUTPUT: «ComplexStr␤»

Compared to 42/10 and 1+42i, there's no division (or addition) operation involved. This is useful for literals in routine signatures, for example:

sub close-enough-π (<355/113>) { 
     say "Your π is close enough!" 
 } 
 close-enough-π 710/226; # OUTPUT: «Your π is close enough!␤» 
 
 # WRONG: can't do this, since it's a division operation 
 
 sub compilation-failure (355/113) {} 

38.1.6 Word quoting with quote protection: qww

The qw form of word quoting will treat quote characters literally, leaving them in the resulting words:

say qw{"a b" c}.perl; # OUTPUT: «("\"a", "b\"", "c")␤»

Thus, if you wish to preserve quoted sub-strings as single items in the resulting words you need to use the qww variant:

say qww{"a b" c}.perl; # OUTPUT: «("a b", "c")␤»

38.1.7 Word quoting with interpolation: qqw

The qw form of word quoting doesn't interpolate variables:

my $a = 42; say qw{$a b c};  # OUTPUT: «$a b c␤»

Thus, if you wish for variables to be interpolated within the quoted string, you need to use the qqw variant:

my $a = 42;
my @list = qqw{$a b c};
say @list;                # OUTPUT: «42 b c␤»

Note that variable interpolation happens before word splitting:

my $a = "a b";
my @list = qqw{$a c};
.say for @list; # OUTPUT: «a␤b␤c␤»

38.1.8 Word quoting with interpolation and quote protection: qqww

The qqw form of word quoting will treat quote characters literally, leaving them in the resulting words:

my $a = 42; say qqw{"$a b" c}.perl;  # OUTPUT: «("\"42", "b\"", "c")␤»

Thus, if you wish to preserve quoted sub-strings as single items in the resulting words you need to use the qqww variant:

my $a = 42; say qqww{"$a b" c}.perl; # OUTPUT: «("42 b", "c")␤»

or equivalently:

my $a = 42; say <<"$a b" c>>.perl;   # OUTPUT: «("42 b", "c")␤»
my $a = 42; say «"$a b" c».perl;     # OUTPUT: «("42 b", "c")␤»

Quote protection happens before interpolation, and interpolation happens before word splitting, so quotes coming from inside interpolated variables are just literal quote characters:

my $a = "1 2";
say qqww{"$a" $a}.perl; # OUTPUT: «("1 2", "1", "2")␤»
my $b = "1 \"2 3\"";
say qqww{"$b" $b}.perl; # OUTPUT: «("1 \"2 3\"", "1", "\"2", "3\"")␤»

38.1.9 Shell quoting: qx

To run a string as an external program, not only is it possible to pass the string to the shell or run functions but one can also perform shell quoting in a similar manner to the backticks a.k.a. qx in Perl 5. There are some subtleties to consider, however. The backticks are no longer used for shell quoting in Perl 6 and the qx quotes don't interpolate Perl variables. Thus

my $world = "there";
say qx{echo "hello $world"}

prints simply hello. Nevertheless, if you have declared an environment variable before calling perl6, this will be available within qx, for instance

WORLD="there" perl6 
 > say qx{echo "hello $WORLD"} 

will now print hello there.

The result of calling qx is returned, so this information can be assigned to a variable for later use:

my $output = qx{echo "hello!"};
say $output;    # OUTPUT: «hello!␤»

See also shell, run and Proc::Async for other ways to execute external commands.

38.1.10 Shell quoting with interpolation: qqx

If one wishes to use the content of a Perl variable within an external command, then the qqx shell quoting construct should be used (this corresponds to Perl 5's qx):

my $world = "there";
say qqx{echo "hello $world"};  # OUTPUT: «hello there␤»

Again, the output of the external command can be kept in a variable:

my $word = "cool";
my $option = "-i";
my $file = "/usr/share/dict/words";
my $output = qqx{grep $option $word $file};
# runs the command: grep -i cool /usr/share/dict/words
say $output;      # OUTPUT: «Cooley␤Cooley's␤Coolidge␤Coolidge's␤cool␤...»

See also shell and run for other ways to execute external commands.

38.1.11 Heredocs: :to

A convenient way to write multi-line string literals are heredocs, which let you choose the delimiter yourself:

say q:to/END/; 
 Here is 
 some multi-line 
 string 
 END 

The contents of the heredoc always begin on the next line, so you can (and should) finish the line.

my $escaped = my-escaping-function(q:to/TERMINATOR/, language => 'html'); 
 Here are the contents of the heredoc. 
 Potentially multiple lines. 
 TERMINATOR 

If the terminator is indented, that amount of indention is removed from the string literals. Therefore this heredoc

say q:to/END/; 
     Here is 
     some multi line 
         string 
     END 

produces this output:

Here is 
 some multi line 
     string 
 
 

Heredocs include the newline from before the terminator.

To allow interpolation of variables use the qq form, but you will then have to escape meta characters {\ as well as $ if it is not the sigil for a defined variable. For example:

my $f = 'db.7.3.8';
my $s = qq:to/END/;
option \{
    file "$f";
};
END
say $s;

would produce:

option { 
     file "db.7.3.8"; 
 }; 

You can begin multiple Heredocs in the same line.

my ($first, $second) = qq:to/END1/, qq:to/END2/; 
   FIRST 
   MULTILINE 
   STRING 
   END1 
    SECOND 
    MULTILINE 
    STRING 
    END2 

38.2 Regexes

For information about quoting as applied in regexes see the regular expression documentation.

39 Perl 6 from Ruby - Nutshell

Learning Perl 6 from Ruby, in a nutshell: What do I already know?

This page attempts to index the high-level differences in syntax and semantics between Ruby and Perl 6. Whatever works in Ruby and must be written differently in Perl 6 should be listed here (whereas many Perl 6 features and idioms won't be).

Hence this should not be mistaken for a beginner tutorial or overview of Perl 6; it is intended as a technical reference for Perl 6 learners with a strong Ruby background.

39.1 Basic Syntax

39.1.1 Statement Ending Semi-Colons

Ruby detects the end of most statements with a newline (and a few exceptions), as long as the expression is complete. It is common break up a long expression by leaving an operator dangling at the end of a line to ensure that the parsing will continue:

foo +     # In Ruby a trailing operator means parsing should continue
  bar +
  baz

In Perl 6 you must explicitly terminate statements with a ;, which allows for better feedback and more flexibility in breaking up long lines. Two exceptions not needing an explicit ; are the last statement in a block, and after the closing curly brace of the block itself (if there is nothing else on that line):

if 5 < $x < 10 {
  say "Yep!";
  $x = 17         # No ; required before closing }
}                 # No ; required after closing } because of the newline
say "Done!";      # The ; is not required here if nothing follows

39.1.2 Whitespace

Ruby allows a surprising amount of flexibility in the use of whitespace, even with strict mode and warnings turned on:

# unidiomatic but valid Ruby
puts"Hello "+
(people [ i]
    . name
    ) . upcase+"!"if$greeted[i]<1

Perl 6 also endorses programmer freedom and creativity, but balanced syntactic flexibility against its design goal of having a consistent, deterministic, extensible grammar that supports single-pass parsing and helpful error messages, integrates features like custom operators cleanly, and doesn't lead programmers to accidentally misstate their intent. Also, the practice of "code golf" is slightly de-emphasized; Perl 6 is designed to be more concise in concepts than in keystrokes.

As a result, there are various places in the syntax where whitespace is optional in Ruby, but is either mandatory or forbidden in Perl 6. Many of those restrictions are unlikely to concern much real-life Perl code (e.g. whitespace being disallowed between an array variable and its square braces), but there are a few that will unfortunately conflict with some Ruby hackers' habitual coding styles:

39.1.3 . Method calls, .send

Method call syntax uses a dot just like Ruby:

person.name    # Ruby
$person.name   # Perl 6

To call a method whose name is not known until runtime:

object.send(methodname, args);  # Ruby
$object."$methodname"(@args);   # Perl 6

If you leave out the quotes, then Perl 6 expects $methodname to contain a Method object, rather than the simple string name of the method.

39.1.4 Variables, Sigils, Scope, and Common Types

In Ruby, variables use sigils primarily to indicate scope. $ for global scope, @@ for class scope, @ for instance scope, and no sigil for local variables (including parameters). The & sigil is also used to indicate method references. Symbols are prefixed with :, but they are not variable and so not really sigils.

In Perl 6 sigils are primarily used to indicate a role that the contained value implements, indicating the type (or at least the interface) of the value. The sigils are invariant, no matter how the variable is being used - you can think of them as part of the variable's name.

The scope of a variable is instead indicated by the declaration itself (my, has, our, etc).

39.1.4.1 Variable Scope

For local variables, Ruby uses implicit variable declaration upon assignment and limited to the current block. In Ruby the content of an if or while built-in construct is not a block or scope.

Perl 6 uses explicit scope indicators, and never creates variables implicitly. Every place you see { ... } is a scope, including the body of a conditional or loop. The commonly used scope declarations:

foo = 7        # Ruby, variable scope is defined by first assignment and
               # extends to the end of the current block

my  $foo = 7   # Perl 6, lexical scoped to the current block
our $foo = 7   # Perl 6, package scoped
has $!foo = 7  # Perl 6, instance scoped (attribute)

39.1.4.2 $ Scalar

The $ sigil is always used with "scalar" variables (e.g. $name). These are single-value containers.

This is the most general-purpose variable type, with no restrictions on its contents. Note that you can still address/use its contents, like $x[1], $x{"foo"}, and $f("foo").

39.1.4.3 @ Array

The @ sigil is always used with "array" variables (e.g. @months, @months[2], @months[2, 4] for an array slice). Variables using the @ sigil can only contain things that do the Positional role, indicating positional indexing and slicing capabilities.

39.1.4.4 % Hash

The % sigil is always used with "hash" variables (e.g. %calories, %calories<apple>, %calories<pear plum>). Variables using the % sigil can only contain things that do the Associative role.

Ruby uses square brackets to access values for both Arrays and Hashes. Perl 6 uses curly braces for hashes instead. The angle-brackets version is available which always autoquotes its contents (strings without quotes):

Adverbs can be used to control the type of slice.

39.1.4.5 & Sub

The & sigil is used very similarly to Ruby's & to refer to the function object of a named subroutine/operator without invoking it, i.e. to use the name as a "noun" instead of a "verb". Variables using the & sigil can only contain things that do the Callable role.

add = -> n, m { n + m } # Ruby lambda for an addition function
add.(2, 3)              # => 5, Ruby invocation of a lambda
add.call(2, 3)          # => 5, Ruby invocation of a lambda

my &add = -> $n, $m { $n + $m } # Perl 6 addition function
&add(2, 3)                      # => 5, you can keep the sigil
add(2, 3)                       # => 5, and it works without it

foo_method = &foo;     # Ruby
my &foo_method = &foo; # Perl 6

some_func(&say) # Ruby pass a function reference
some_func(&say) # Perl 6 passes function references the same way

Often in Ruby we pass a block as the last parameter, which is especially used for DSLs. This can be an implicit parameter called by yield, or an explicit block prefixed with &. In Perl 6 a Callable parameter is always listed and called by the variable name (instead of yield), and there are a variety of ways of invoking the function.

# Ruby, declare a method and call the implicit block argument
def f
  yield 2
end

# Ruby, invoke f, pass it a block with 1 argument
f do |n|
  puts "Hi #{n}"
end

# Perl 6, declare a method with an explicit block argument
sub f(&g:($)) {
  g(2)
}

# Perl 6, invoke f, pass it a block with 1 argument
# There are several other ways to do this
f(-> $n { say "Hi {$n}" }) # Explicit argument
f -> $n { say "Hi {$n}" }  # Explicit argument, no parenthesis
f { say "Hi {$^n}" }       # Implicit argument

# Additionally, if 'f' is a method on instance 'obj' you can use C<:>
# instead of parenthesis
obj.f(-> $n { say "Hi {$n}" })  # Explicit argument
obj.f: -> $n { say "Hi {$n}" }  # Explicit argument, no parenthesis
obj.f: { say "Hi {$^n}" }       # Implicit argument, no parenthesis

39.1.4.6 * Slurpy params / argument expansion

In Ruby you can declare an argument to slurp the remainder of the passed parameters into an array using a * prefix. It works the same way in Perl 6:

def foo(*args); puts "I got #{args.length} args!"; end # Ruby
sub foo(*@args) { say "I got #{@args.elems} args!" }   # Perl 6

You might want to expand an array into a set of arguments. In Perl 6 this is also done using the * prefix:

args = %w(a b c)         # Ruby
foo(*args)

my @args = <a b c>       # Perl 6
foo(*@args)

Perl 6 has many more advanced ways of passing parameters and receiving arguments, see Signatures and Captures.

39.1.5 Twigils

Perl 6 additionally uses "twigils", which are further indicators about the variable and go between the sigil and the rest of the variable name. Examples:

$foo     # Scalar with no twigil
$!foo    # Private instance variable
$.foo    # Instance variable accessor
$*foo    # Dynamically scoped variable
$^foo    # A positional (placeholder) parameter to a block
$:foo    # A named parameter
$=foo    # POD (documentation) variables
$?FILE   # Current source filename. The ? twigil indicates a compile-time value
$~foo    # Sublanguage seen by parser, uncommon

Though each of these examples use the $ sigil, most could use @ (Positional) or % (Associative).

39.1.6 : Symbols

Perl 6 generally uses strings in the places where Ruby uses symbols. A primary example of this is in hash keys.

address[:joe][:street] # Typical Ruby nested hash with symbol keys
%address<joe><street>  # Typical Perl 6 nested hash with string keys

Perl 6 has colon-pair syntax, which can sometimes look like Ruby symbols.

:age            # Ruby symbol

# All of these are equivalent for Perl 6
:age            # Perl 6 pair with implicit True value
:age(True)      # Perl 6 pair with explicit True value
age => True     # Perl 6 pair using arrow notation
"age" => True   # Perl 6 pair using arrow notation and explicit quotes

You could probably get away with using a colon-pair without an explicit value and pretend that it is a Ruby symbol a lot of the time, but it isn't idiomatic Perl 6.

39.2 Operators

Many operators have a similar usage in both Ruby and Perl 6:

You may use $x++ instead of x += 1 as a shortcut for incrementing a variable. This can be used as a pre-increment ++$x (increment, return new value) or post-increment $x++ (increment, return old value).

You may use $x-- instead of x -= 1 as a shortcut for decrementing a variable. This can be used as a pre-decrement --$x (decrement, return new value) or post-decrement $x-- (decrement, return old value).

39.2.1 == != < > <= >= Comparisons

Comparisons in Perl 6 are separated between numeric and string to avoid common errors.

For example, using == tries to convert the values to numbers, and eq tries to convert the values to strings.

39.2.2 <=> Three-way comparisons

In Ruby, the <=> operator returns -1, 0, or 1. In Perl 6, they return Order::Less, Order::Same, or Order::More.

<=> forces numeric context for the comparison.

leg ("Less, Equal, or Greater?") forces string context for the comparison.

cmp does either <=> or leg, depending on the existing type of its arguments.

39.2.3 ~~ Smart-match operator

This is a very common matching operator which doesn't exist in Ruby. Here are some examples:

say "match!" if $foo ~~ /bar/;      # Regex match
say "match!" if $foo ~~ "bar";      # String match
say "match!" if $foo ~~ :(Int, Str) # Signature match (destructure)

See S03/Smart matching

39.2.4 & | ^ Numeric Bitwise ops

39.2.5 & | ^ Boolean ops

In Perl 6, these single-character ops have been removed, and replaced by two-character ops which coerce their arguments to the needed context.

# Infix ops (two arguments; one on each side of the op)
+&  +|  +^  And Or Xor: Numeric
~&  ~|  ~^  And Or Xor: String
?&  ?|  ?^  And Or Xor: Boolean

# Prefix ops (one argument, after the op)
+^  Not: Numeric
~^  Not: String
?^  Not: Boolean (same as the ! op)

39.2.6 &. Conditional chaining operator

Ruby uses the &. operator to chain methods without raising an error if one invocation returns nil. In Perl 6 use .? for the same purpose.

39.2.7 << >> Numeric shift left, right ops, shovel operator

Replaced by +< and +> .

puts 42 << 3  # Ruby
say  42 +< 3; # Perl 6

Note that Ruby often uses the << operator as the "shovel operator", which is similar to .push. This usage isn't common in Perl 6.

39.2.8 => and : Key-Value Separators

In Ruby, => is used in the context of key/value pairs for Hash literal declaration and parameter passing. : is used as a shorthand when the left side is a symbol.

In Perl 6, => is the Pair operator, which is quite different in principle, but works the same in many situations.

If you are using => in a hash literal, then the usage is very similar:

hash = { "AAA" => 1, "BBB" => 2 }  # Ruby, though symbol keys are more common
my %hash = ( AAA => 1, BBB => 2 ); # Perl 6, uses ()'s though {} usually work

39.2.9 ? : Ternary operator

In Perl 6, this is spelled with two question marks instead of one question mark, and two exclamation points instead of one colon. This deviation from the common ternary operators disambiguates several situations and makes the false-case stand out more.

result     = (  score > 60 )  ? 'Pass'  : 'Fail'; # Ruby
my $result = ( $score > 60 ) ?? 'Pass' !! 'Fail'; # Perl 6

39.2.10 + String Concatenation

Replaced by the tilde. Mnemonic: think of "stitching" together the two strings with needle and thread.

$food = 'grape' + 'fruit'  # Ruby
$food = 'grape' ~ 'fruit'; # Perl 6

39.2.11 String interpolation

In Ruby, "#{foo}s" deliminates a block embedded in a double-quoted string. In Perl 6 drop the # prefix: "{$foo}s". As in Ruby, you can place arbitrary code into the embedded block and it will be rendered in string context.

Simple variables can be interpolated into a double-quoted string without using the block syntax:

# Ruby
name = "Bob"
puts "Hello! My name is #{name}!"

# Perl 6
my $name = "Bob"
say "Hello! My name is $name!"

The result of an embedded block in Ruby uses .to_s to get string context. Perl 6 uses .Str, or .gist for the same affect.

39.3 Compound Statements

39.3.1 Conditionals

39.3.1.1 if elsif else unless

This work very similarly between Ruby and Perl 6, but Perl 6 uses { } to clearly delineate the blocks.

# Ruby
if x > 5
    puts "Bigger!"
elsif x == 5
    puts "The same!"
else
    puts "Smaller!"
end

# Perl 6
if x > 5 {
    say "Bigger!"
} elsif x == 5 {
    puts "The same!"
} else {
    puts "Smaller!"
}

Binding the conditional expression to a variable is a little different:

if x = dostuff(); ...; end   # Ruby
if dostuff() -> $x {...}     # Perl 6, block-assignment uses arrow

The unless conditional only allows for a single block in Perl 6; it does not allow for an elsif or else clause.

39.3.1.2 case-when

The Perl 6 given-when construct is like a chain of if-elsif-else statements or like the case-when construct in Ruby. A big difference is that Ruby uses the == comparison for each condition, but Perl 6 uses the more general smart-match ~~ operator.

It has the general structure:

given EXPR {
    when EXPR { ... }
    when EXPR { ... }
    default { ... }
}

In its simplest form, the construct is as follows:

given $value {
    when "a match" {
        do-something();
    }
    when "another match" {
        do-something-else();
    }
    default {
        do-default-thing();
    }
}

This is simple in the sense that a scalar value is matched in the when statements. More generally, the matches are actually smart-matches on the input value such that lookups using more complex entities such as regexps can be used instead of scalar values.

39.3.2 Loops

39.3.2.1 while until

Mostly unchanged; parentheses around the conditions are optional, but if used, must not immediately follow the keyword, or it will be taken as a function call instead. Binding the conditional expression to a variable is also a little different:

while x = dostuff(); ...; end    # Ruby
while dostuff() -> $x {...}      # Perl 6

39.3.2.2 for .each

for loops are rare in Ruby, instead we typically use .each on an enumerable. The most direct translation to Perl 6 would be to use .map for both .each and .map, but we typically use a for loop directly.

# Ruby for loop
for n in 0..5
    puts "n: #{n}"
end

# Ruby, more common usage of .each
(0..5).each do |n|
    puts "n: #{n}"
end

# Perl 6
for 0..5 -> $n {
    say "n: $n";
}

# Perl 6, misusing .map
(0..5).map: -> $n {
    say "n: $n";
}

In Ruby, the iteration variable for .each is a copy of the list element, and modifying it does nothing to the original list. Note that it is a copy of the REFERENCE, so you can still change the values to which it refers.

In Perl 6, that alias is read-only (for safety) and thus behaves exactly like Ruby, unless you change -> to <->.

cars.each { |car| ... }    # Ruby; read-only reference
for @cars  -> $car   {...} # Perl 6; read-only
for @cars <-> $car   {...} # Perl 6; read-write

39.3.3 Flow Interruption statements

Same as Ruby:

This is last in Perl 6.

39.4 Regular Expressions ( Regex / Regexp )

Regular expressions in Perl 6 are significantly different, and more powerful, than in Ruby. By default whitespace is ignored and all characters must be escaped, for example. Regexes can be easily combined and declared in ways to build efficient grammars.

There are many powerful features of Perl 6 regexes, especially defining entire grammars using the same syntax. See Regexes and Grammars.

39.4.1 .match method and =~ operator

In Ruby, regex matches can be done against a variable using the =~ regexp match operator or the .match method. In Perl 6, the ~~ smartmatch op is used instead, or the .match method.

next if line   =~ /static/   # Ruby
next if $line  ~~ /static/;  # Perl 6

next if line  !~  /dynamic/ ; # Ruby
next if $line !~~ /dynamic/ ; # Perl 6

next if line.match(/static/)    # Ruby
next if $line.match(/static/);  # Perl 6

Alternately, the .match and .subst methods can be used. Note that .subst is non-mutating. See S05/Substitution.

39.4.2 .sub and .sub!

In Perl 6 you typically use the s/// operator to do regex substitution.

fixed = line.sub(/foo/, 'bar')        # Ruby, non-mutating
my $fixed = $line.subst(/foo/, 'bar') # Perl 6, non-mutating

line.sub!(/foo/, 'bar')   # Ruby, mutating
$line ~~ s/foo/bar/;      # Perl 6, mutating

39.4.3 Regex options

Move any options from the end of the regex to the beginning. This may require you to add the optional m on a plain match like /abc/.

next if $line =~    /static/i # Ruby
next if $line ~~ m:i/static/; # Perl 6

39.4.4 Whitespace is ignored, most things must be quoted

In order to aid in readability and reusability, whitespace is not significant in Perl 6 regexes.

/this is a test/ # Ruby, boring string
/this.*/         # Ruby, possibly interesting string

/ this " " is " " a " " test / # Perl 6, each space is quoted
/ "this is a test" / # Perl 6, quoting the whole string
/ this .* /          # Perl 6, possibly interesting string

39.4.5 Special matchers generally fall under the <> syntax

There are many cases of special matching syntax that Perl 6 regexes support. They won't all be listed here, but often instead of being surrounded by (), the assertions will be surrounded by <>.

For character classes, this means that:

For look-around assertions:

(Unrelated to <> syntax, the "lookaround" /foo\Kbar/ becomes /foo <( bar )> /

39.4.6 Longest token matching (LTM) displaces alternation

In Perl 6 regexes, | does Longest Token Match (LTM), which decides which alternation wins an ambiguous match based off of a set of rules, rather than about which was written first in the regex.

To avoid the new logic, change any | in your Ruby regex to a ||.

39.5 File-related operations

39.5.1 Reading the lines of a text file into an array

Both Ruby and Perl 6 make it easy to read all of the lines in a file into a single variable, and in both cases each line has the newline removed.

lines = File.readlines("file")   # Ruby
my @lines = "file".IO.lines;     # Perl 6, create an IO object from a string

39.5.2 Iterating over the lines of a text file

Reading the entire file into memory isn't recommended. The .lines method in Perl 6 returns a lazy sequence, but assigning to an array forces the file to be read. It is better to iterate over the results:

# Ruby
File.foreach("file") do |line|
    puts line
end

# Perl 6
for "file".IO.lines -> $line {
    say $line
}

39.6 Object Orientation

39.6.1 Basic classes, methods, attributes

Classes are defined similarly between Ruby and Perl 6, using the class keyword. Ruby uses def for methods, whereas Perl 6 uses method.

# Ruby
class Foo
    def greet(name)
        puts "Hi #{name}!"
    end
end

# Perl 6
class Foo {
    method greet($name) {
        say "Hi $name!"
    }
}

In Ruby you can use an attribute without declaring it beforehand, and you can tell it is an attribute because of the @ sigil. You can also easily create accessors using attr_accessor and it's variants. In Perl 6 you use a has declaration and a variety of sigils. You can use the ! twigil for private attributes or . to create an accessor.

# Ruby
class Person
    attr_accessor :age    # Declare .age as an accessor method for @age
    def initialize
        @name = 'default' # Assign default value to private instance var
    end
end

# Perl 6
class Person
    has $.age;              # Declare $!age and accessor methods
    has $!name = 'default'; # Assign default value to private instance var
end

Creating a new instance of the class uses the .new method. In Ruby you must manually assign instance variables as needed inside initialize. In Perl 6 you get a default constructor that accepts key/value pairs of accessor attributes, and can do further setup in the BUILD method. Like with Ruby, you can override new itself for more advanced functionality, but this is rare.

# Ruby
class Person
    attr_accessor :name, :age
    def initialize(attrs)
        @name = attrs[:name] || 'Jill'
        @age  = attrs[:age] || 42
        @birth_year = Time.now.year - @age
    end
end
p = Person.new( name: 'Jack', age: 23 )

# Perl 6
class Person
    has $.name = 'Jill';
    has $.age  = 42;
    has $!birth_year;
    method BUILD {
        $!birth_year = now.Date.year - $.age;
    }
}
p = Person.new( name => 'Jack', age => 23 )

39.6.2 Private Methods

Private methods in Perl 6 are declared with a ! prefixed in their name, and are invoked with a ! instead of a ..

# Ruby
class Foo
    def visible
        puts "I can be seen!"
        hidden
    end

    private
    def hidden
        puts "I cannot easily be called!"
    end
end

# Perl 6
class Foo {
    method visible {
        say "I can be seen!"
        self!hidden
    }

    method !hidden {
        say "I cannot easily be called!"
    }
}

An important note is that in Ruby child objects can see parent private methods (so they are more like "protected" methods in other languages). In Perl 6 child objects cannot call parent private methods.

39.6.3 Going Meta

Here are a few examples of meta-programming. Note that Perl 6 separates the meta-methods from the regular methods.

person = Person.new       # Ruby, create a new person
my $person = Person.new   # Perl 6, create a new person

person.class              # Ruby, returns Person (class)
$person.WHAT              # Perl 6, returns Person (class)

person.methods            # Ruby
$person.^methods          # Perl 6, using .^ syntax to access meta-methods

person.instance_variables # Ruby
$person.^attributes       # Perl 6

Like Ruby, in Perl 6, everything is an object, but not all operations are equivalent to .send. Many operators are global functions that use typed multi-dispatch (function signatures with types) to decide which implementation to use.

5.send(:+, 3)    # => 8, Ruby
&[+](5, 3)       # => 8, Perl 6, reference to infix addition operator

&[+].^candidates # Perl 6, lists all signatures for the + operator

See Meta-Object Protocol for lots of further details.

39.7 Environment variables

39.7.1 Perl module library path

In Ruby, one of the environment variables to specify extra search paths for modules is RUBYLIB.

$ RUBYLIB="/some/module/lib" ruby program.rb

In Perl 6 this is similar, you merely needs to change the name. As you probably guessed, you just need to use PERL6LIB:

$ PERL6LIB="/some/module/lib" perl6 program.p6

As with Ruby, if you don't specify PERL6LIB, you need to specify the library path within the program via the use lib pragma:

# Ruby and Perl 6
use lib '/some/module/lib';

39.8 Misc.

39.8.1 Importing specific functions from a module

In Ruby there is no built-in way to selectively import/export methods from a module.

In Perl 6 you specifies the functions which are to be exported by using the is export role on the relevant subs and all subs with this role are then exported. Hence, the following module Bar exports the subs foo and bar but not baz:

unit module Bar; # remainder of the file is in module Bar { ... }

sub foo($a) is export { say "foo $a" }
sub bar($b) is export { say "bar $b" }
sub baz($z) { say "baz $z" }

To use this module, simply use Bar and the functions foo and bar will be available

use Bar;
foo(1);    #=> "foo 1"
bar(2);    #=> "bar 2"

If you tries to use baz an "Undeclared routine" error is raised at compile time.

Some modules allow for selectively importing functions, which would look like:

use Bar <foo>; # Import only foo
foo(1);        #=> "foo 1"
bar(2);        # Error!

39.8.2 OptionParser, parsing command-line flags

Command line argument switch parsing in Perl 6 is done by the parameter list of the MAIN subroutine.

# Ruby
require 'optparse'
options = {}
OptionParser.new do |opts|
    opts.banner = 'Usage: example.rb --length=abc'
    opts.on("--length", "Set the file") do |length|
        raise "Length must be > 0" unless length.to_i > 0
        options[:length] = length
    end
    opts.on("--filename", "Set the file") do |filename|
        options[:file] = filename
    end
    opts.on("--verbose", "Increase verbosity") do |verbose|
        options[:verbose] = true
    end
end.parse!

puts options[:length]
puts options[:filename]
puts 'Verbosity ', (options[:verbose] ? 'on' : 'off')

ruby example.rb --filename=foo --length=42 --verbose
    42
    foo
    Verbosity on

ruby example.rb --length=abc
    Length must be > 0

# Perl 6
sub MAIN ( Int :$length where * > 0, :filename = 'file.dat', Bool :$verbose ) {
    say $length;
    say $data;
    say 'Verbosity ', ($verbose ?? 'on' !! 'off');
}

perl6 example.p6 --file=foo --length=42 --verbose
    42
    foo
    Verbosity on
perl6 example.p6 --length=abc
    Usage:
      example.p6 [--length=<Int>] [--file=<Any>] [--verbose]

Note that Perl 6 auto-generates a full usage message on error in command-line parsing.

39.9 RubyGems, External Libraries

See https://modules.perl6.org/, where a growing number of Perl 6 libraries are available along with the tools to manage them.

If the module that you were using has not been converted to Perl 6, and no alternative is listed in this document, then its use under Perl 6 may not have been addressed yet.

You can experiment with Inline::Ruby to call existing Ruby code from your Perl 6 programs. This uses an embedded instance of the ruby interpreter to run Ruby code called from your Perl 6 script. Note that this is an EXPERIMENTAL library. You can similarly call other language's libraries with Inline::Perl5, Inline::Python, and others.

40 Regexes

Pattern matching against strings

Regular expressions, regexes for short, are a sequence of characters that describe a pattern of text. Pattern matching is the process of matching those patterns to actual text.

40.1 Lexical conventions

Perl 6 has special syntax for writing regexes:

m/abc/;         # a regex that is immediately matched against $_
rx/abc/;        # a Regex object
/abc/;          # a Regex object

For the first two examples, delimiters other than the slash can be used:

m{abc};
rx{abc};

Note that neither the colon : nor round parentheses can be delimiters; the colon is forbidden because it clashes with adverbs, such as rx:i/abc/ (case insensitive regexes), and round parentheses indicate a function call instead.

Whitespace in regexes is generally ignored (except with the :s or :sigspace adverb).

As with Perl 6, in general, comments in regexes start with a hash character # and go to the end of the line.

40.2 Literals

The simplest case for a regex is a match against a string literal:

if 'properly' ~~ m/ perl / {
    say "'properly' contains 'perl'";
}

Alphanumeric characters and the underscore _ are matched literally. All other characters must either be escaped with a backslash (for example, \: to match a colon), or be within quotes:

/ 'two words' /;     # matches 'two words' including the blank
/ "a:b"       /;     # matches 'a:b' including the colon
/ '#' /;             # matches a hash character

Strings are searched left to right, so it's enough if only part of the string matches the regex:

if 'abcdef' ~~ / de / {
    say ~$/;            # OUTPUT: «de␤»
    say $/.prematch;    # OUTPUT: «abc␤»
    say $/.postmatch;   # OUTPUT: «f␤»
    say $/.from;        # OUTPUT: «3␤»
    say $/.to;          # OUTPUT: «5␤»
};

Match results are stored in the $/ variable and are also returned from the match. The result is of type Match if the match was successful; otherwise it's Nil.

40.3 Wildcards and character classes

40.3.1 The dot matches any character: .

An unescaped dot . in a regex matches any single character.

So, these all match:

'perl' ~~ /per./;       # matches the whole string
'perl' ~~ / per . /;    # the same; whitespace is ignored
'perl' ~~ / pe.l /;     # the . matches the r
'speller' ~~ / pe.l/;   # the . matches the first l

This doesn't match:

'perl' ~~ /. per /;

because there's no character to match before per in the target string.

40.3.2 Backslashed, predefined character classes

There are predefined character classes of the form \w. Its negation is written with an upper-case letter, \W.

\d matches a single digit (Unicode property N) and \D matches a single character that is not a digit.

'ab42' ~~ /\d/ and say ~$/;     # OUTPUT: «4␤»
'ab42' ~~ /\D/ and say ~$/;     # OUTPUT: «a␤»

Note that not only the Arabic digits (commonly used in the Latin alphabet) match \d, but also digits from other scripts.

Examples for digits are:

U+0035 5 DIGIT FIVE 
 U+07C2 ߂ NKO DIGIT TWO 
 U+0E53 ๓ THAI DIGIT THREE 
 U+1B56 ᭖ BALINESE DIGIT SIX 

\h matches a single horizontal whitespace character. \H matches a single character that is not a horizontal whitespace character.

Examples for horizontal whitespace characters are

U+0020 SPACE 
 U+00A0 NO-BREAK SPACE 
 U+0009 CHARACTER TABULATION 
 U+2001 EM QUAD 

Vertical whitespace like newline characters are explicitly excluded; those can be matched with \v, and \s matches any kind of whitespace.

\n matches a single, logical newline character. \n is supposed to also match a Windows CR LF codepoint pair; though it's unclear whether the magic happens at the time that external data is read, or at regex match time. \N matches a single character that's not a logical newline.

\s matches a single whitespace character. \S matches a single character that is not whitespace.

if 'contains a word starting with "w"' ~~ / w \S+ / {
    say ~$/;        # OUTPUT: «word␤»
}

\t matches a single tab/tabulation character, U+0009. (Note that exotic tabs like the U+000B VERTICAL TABULATION character are not included here). \T matches a single character that is not a tab.

\v matches a single vertical whitespace character. \V matches a single character that is not vertical whitespace.

Examples for vertical whitespace characters:

U+000A LINE FEED 
 U+000B VERTICAL TABULATION 
 U+000C FORM FEED 
 U+000D CARRIAGE RETURN 
 U+0085 NEXT LINE 
 U+2028 LINE SEPARATOR 
 U+2029 PARAGRAPH SEPARATOR 

Use \s to match any kind of whitespace, not just vertical whitespace.

\w matches a single word character; i.e., a letter (Unicode category L), a digit or an underscore. \W matches a single character that isn't a word character.

Examples of word characters:

0041 A LATIN CAPITAL LETTER A 
 0031 1 DIGIT ONE 
 03B4 δ GREEK SMALL LETTER DELTA 
 03F3 ϳ GREEK LETTER YOT 
 0409 Љ CYRILLIC CAPITAL LETTER LJE 

Predefined subrules:

<alnum>   \w       'alpha' plus 'digit' 
 <alpha>   <:L>     Alphabetic characters 
 <blank>   \h       Horizontal whitespace 
 <cntrl>            Control characters 
 <digit>   \d       Decimal digits 
 <graph>            'alnum' plus 'punct' 
 <lower>   <:Ll>    Lowercase characters 
 <print>            'graph' plus 'space', but no 'cntrl' 
 <punct>            Punctuation and Symbols (only Punct beyond ASCII) 
 <space>   \s       Whitespace 
 <upper>   <:Lu>    Uppercase characters 
 <|wb>               Word Boundary (zero-width assertion) 
 <ww>               Within Word (zero-width assertion) 
 <xdigit>           Hexadecimal digit [0-9A-Fa-f] 

40.3.3 Unicode properties

The character classes mentioned so far are mostly for convenience; another approach is to use Unicode character properties. These come in the form <:property> , where property can be a short or long Unicode General Category name. These use pair syntax.

To match against a Unicode Property:

"a".uniprop('Script');                 # OUTPUT: «Latin␤»
"a" ~~ / <:Script<Latin>> /;
"a".uniprop('Block');                  # OUTPUT: «Basic Latin␤»
"a" ~~ / <:Block('Basic Latin')> /;

The following list of Unicode General Categories is stolen from the Perl 5 perlunicode documentation:

Short Long
L Letter
LC Cased_Letter
Lu Uppercase_Letter
Ll Lowercase_Letter
Lt Titlecase_Letter
Lm Modifier_Letter
Lo Other_Letter
M Mark
Mn Nonspacing_Mark
Mc Spacing_Mark
Me Enclosing_Mark
N Number
Nd Decimal_Number (also Digit)
Nl Letter_Number
No Other_Number
P Punctuation (also punct)
Pc Connector_Punctuation
Pd Dash_Punctuation
Ps Open_Punctuation
Pe Close_Punctuation
Pi Initial_Punctuation
(may behave like Ps or Pe depending on usage)
Pf Final_Punctuation
(may behave like Ps or Pe depending on usage)
Po Other_Punctuation
S Symbol
Sm Math_Symbol
Sc Currency_Symbol
Sk Modifier_Symbol
So Other_Symbol
Z Separator
Zs Space_Separator
Zl Line_Separator
Zp Paragraph_Separator
C Other
Cc Control (also cntrl)
Cf Format
Cs Surrogate
Co Private_Use
Cn Unassigned

For example, <:Lu> matches a single, upper-case letter.

It's negation is this: <:!property> . So, <:!Lu> matches a single character that isn't an upper-case letter.

Categories can be used together, with an infix operator:

Operator Meaning
+ set union
| set union
& set intersection
- set difference (first minus second)
^ symmetric set intersection / XOR

To match either a lower-case letter or a number, write <:Ll+:N> or <:Ll+:Number> or <+ :Lowercase_Letter + :Number> .

It's also possible to group categories and sets of categories with parentheses; for example:

'perl6' ~~ m{\w+(<:Ll+:N>)}  # OUTPUT: «0 => 「6」␤»

40.3.4 Enumerated character classes and ranges

Sometimes the pre-existing wildcards and character classes are not enough. Fortunately, defining your own is fairly simple. Within <[ ]> , you can put any number of single characters and ranges of characters (expressed with two dots between the end points), with or without whitespace.

"abacabadabacaba" ~~ / <[ a .. c 1 2 3 ]> /;
# Unicode hex codepoint range
"ÀÁÂÃÄÅÆ" ~~ / <[ \x[00C0] .. \x[00C6] ]> /;
# Unicode named codepoint range
"ÀÁÂÃÄÅÆ" ~~ / <[ \c[LATIN CAPITAL LETTER A WITH GRAVE] .. \c[LATIN CAPITAL LETTER AE] ]> /;

Within the < > you can use + and - to add or remove multiple range definitions and even mix in some of the unicode categories above. You can also write the backslashed forms for character classes between the [ ] .

/ <[\d] - [13579]> /;
# starts with \d and removes odd ASCII digits, but not quite the same as
/ <[02468]> /;
# because the first one also contains "weird" unicodey digits

To negate a character class, put a - after the opening angle:

say 'no quotes' ~~ /  <-[ " ]> + /;  # matches characters except "

A common pattern for parsing quote-delimited strings involves negated character classes:

say '"in quotes"' ~~ / '"' <-[ " ]> * '"'/;

This first matches a quote, then any characters that aren't quotes, and then a quote again. The meaning of * and + in the examples above are explained in section Quantifier.

Just as you can use the - for both set difference and negation of a single value, you can also explicitly put a + in front:

/ <+[123]> /  # same as <[123]>

40.4 Quantifiers

A quantifier makes the preceding atom match a variable number of times. For example, a+ matches one or more a characters.

Quantifiers bind tighter than concatenation, so ab+ matches one a followed by one or more bs. This is different for quotes, so 'ab'+ matches the strings ab, abab, ababab etc.

40.4.1 One or more: +

The + quantifier makes the preceding atom match one or more times, with no upper limit.

For example, to match strings of the form key=value, you can write a regex like this:

/ \w+ '=' \w+ /

40.4.2 Zero or more: *

The * quantifier makes the preceding atom match zero or more times, with no upper limit.

For example, to allow optional whitespace between a and b you can write

/ a \s* b /

40.4.3 Zero or one match: ?

The ? quantifier makes the preceding atom match zero or once.

40.4.4 General quantifier: ** min..max

To quantify an atom an arbitrary number of times, you can write something like a ** 2..5 to match the character a at least twice and at most 5 times.

say so 'a' ~~ /a ** 2..5/;        # OUTPUT: «False␤» 
 say so  'aaa' ~~ /a ** 2..5/;     # OUTPUT: «True␤» 

If the minimal and maximal number of matches are the same, a single integer is possible: a ** 5 matches a exactly five times.

say so 'aaaaa' ~~ /a ** 5/;       # OUTPUT: «True␤» 

It's also possible to use non inclusive ranges using a caret:

say so 'a'    ~~ /a ** 1^..^6/;   # OUTPUT: «False␤» -- there are 2 to 5 'a's in a row 
 say so 'aaaa' ~~ /a ** 1^..^6/;   # OUTPUT: «True␤» 

This includes the numeric ranges starting from 0:

say so 'aaa' ~~ /a ** ^6/;        # OUTPUT: «True␤» -- there are 0 to 5 'a's in a row 

or a Whatever * operator for an infinite range with a non inclusive minimum:

say so 'aaaa' ~~ /a ** 1^..*/;    # OUTPUT: «True␤» -- there are 2 or more 'a's in a row 

40.4.5 Modified quantifier: %

To more easily match things like comma separated values, you can tack on a % modifier to any of the above quantifiers to specify a separator that must occur between each of the matches. For example, a+ % ',' will match a or a,a or a,a,a or so on, but it will not match a, or a,a,. To match those as well, use %% instead of %.

40.4.6 Greedy versus frugal quantifiers: ?

By default, quantifiers request a greedy match:

'abababa' ~~ /a .* a/ && say ~$/;   # OUTPUT: «abababa␤» 

You can attach a ? modifier to the quantifier to enable frugal matching:

'abababa' ~~ /a .*? a/ && say ~$/;   # OUTPUT: «aba␤» 

You can also explicitly request greedy matching with the ! modifier.

40.4.7 Preventing backtracking: :

You can prevent backtracking in regexes by attaching a : modifier to the quantifier:

say so 'abababa' ~~ /a .* aba/;    # OUTPUT: «True␤» 
 say so 'abababa' ~~ /a .*: aba/;   # OUTPUT: «False␤» 

40.5 Alternation: ||

To match one of several possible alternatives, separate them by ||; the first matching alternative wins.

For example, ini files have the following form:

[section] 
 key = value 

Hence, if you parse a single line of an ini file, it can be either a section or a key-value pair and the regex would be (to a first approximation):

/ '[' \w+ ']' || \S+ \s* '=' \s* \S* /

That is, either a word surrounded by square brackets, or a string of non-whitespace characters, followed by zero or more spaces, followed by the equals sign =, followed again by optional whitespace, followed by another string of non-whitespace characters.

40.6 Longest Alternation: |

In regexes branches separated by |, the longest match wins, independent of the lexical ordering in the regexes.

say ('abc' ~~ / a | .b /).Str;    # OUTPUT: «ab␤»

40.7 Anchors

The regex engine tries to find a match inside a string by searching from left to right.

say so 'properly' ~~ / perl/;   # OUTPUT: «True␤»
#          ^^^^

But sometimes this is not what you want. Instead, you may only want to match a whole string, or a whole line, or exactly one or several whole words. Anchors or assertions can help with this.

Assertions need to match successfully in order for the whole regex to match but they do not use up characters while matching.

40.7.1 ^ , Start of String and $ , End of String

The ^ assertion only matches at the start of the string:

say so 'properly' ~~ /  perl/;    # OUTPUT: «True␤»
say so 'properly' ~~ /^ perl/;    # OUTPUT: «False␤»
say so 'perly'    ~~ /^ perl/;    # OUTPUT: «True␤»
say so 'perl'     ~~ /^ perl/;    # OUTPUT: «True␤»

The $ assertion only matches at the end of the string:

say so 'use perl' ~~ /  perl  /;   # OUTPUT: «True␤»
say so 'use perl' ~~ /  perl $/;   # OUTPUT: «True␤»
say so 'perly'    ~~ /  perl $/;   # OUTPUT: «False␤»

You can combine both assertions:

say so 'use perl' ~~ /^ perl $/;   # OUTPUT: «False␤»
say so 'perl'     ~~ /^ perl $/;   # OUTPUT: «True␤»

Keep in mind that ^ matches the start of a string, not the start of a line. Likewise, $ matches the end of a string, not the end of a line.

The following is a multi-line string:

my $str = q:to/EOS/;
   Keep it secret
   and keep it safe
   EOS

say so $str ~~ /safe   $/;   # OUTPUT: «True␤»  -- 'safe' is at the end of the string
say so $str ~~ /secret $/;   # OUTPUT: «False␤» -- 'secret' is at the end of a line -- not the string
say so $str ~~ /^Keep   /;   # OUTPUT: «True␤»  -- 'Keep' is at the start of the string
say so $str ~~ /^and    /;   # OUTPUT: «False␤» -- 'and' is at the start of a line -- not the string

40.7.2 ^^ , Start of Line and $$ , End of Line

The ^^ assertion matches at the start of a logical line. That is, either at the start of the string, or after a newline character. However, it does not match at the end of the string, even if it ends with a newline character.

$$ matches only at the end of a logical line, that is, before a newline character, or at the end of the string when the last character is not a newline character.

(To understand the following example, it's important to know that the q:to/EOS/...EOS "heredoc" syntax removes leading indention to the same level as the EOS marker, so that the first, second and last lines have no leading space and the third and fourth lines have two leading spaces each).

my $str = q:to/EOS/; 
     There was a young man of Japan 
     Whose limericks never would scan. 
       When asked why this was, 
       He replied "It's because 
     I always try to fit as many syllables into the last line as ever I possibly can." 
     EOS 
 
 say so $str ~~ /^^ There/;        # OUTPUT: «True␤»  -- start of string 
 say so $str ~~ /^^ limericks/;    # OUTPUT: «False␤» -- not at the start of a line 
 say so $str ~~ /^^ I/;            # OUTPUT: «True␤»  -- start of the last line 
 say so $str ~~ /^^ When/;         # OUTPUT: «False␤» -- there are blanks between 
                                   #                       start of line and the "When" 
 
 say so $str ~~ / Japan $$/;       # OUTPUT: «True␤»  -- end of first line 
 say so $str ~~ / scan $$/;        # OUTPUT: «False␤» -- there's a . between "scan" 
                                   #                      and the end of line 
 say so $str ~~ / '."' $$/;        # OUTPUT: «True␤»  -- at the last line 

40.7.3 <|w> and <!|w> , word boundary

To match any word boundary, use <|w>. This is similar to other languages’ \b . To match not a word boundary, use <!|w>, similar to other languages \B . These are both zero width assertions.

40.7.4 << and >> , left and right word boundary

<< matches a left word boundary. It matches positions where there is a non-word character at the left (or the start of the string) and a word character to the right.

>> matches a right word boundary. It matches positions where there is a word character at the left and a non-word character at the right (or the end of the string).

my $str = 'The quick brown fox';
say so $str ~~ /br/;              # OUTPUT: «True␤»
say so $str ~~ /<< br/;           # OUTPUT: «True␤»
say so $str ~~ /br >>/;           # OUTPUT: «False␤»
say so $str ~~ /own/;             # OUTPUT: «True␤»
say so $str ~~ /<< own/;          # OUTPUT: «False␤»
say so $str ~~ /own >>/;          # OUTPUT: «True␤»

You can also use the variants « and » :

my $str = 'The quick brown fox';
say so $str ~~ /« own/;          # OUTPUT: «False␤»
say so $str ~~ /own »/;          # OUTPUT: «True␤»

40.8 Grouping and Capturing

In regular (non-regex) Perl 6, you can use parentheses to group things together, usually to override operator precedence:

say 1 + 4 * 2;      # 9, parsed as 1 + (4 * 2)
say (1 + 4) * 2;    # OUTPUT: «10␤»

The same grouping facility is available in regexes:

/ a || b c /;        # matches 'a' or 'bc'
/ ( a || b ) c /;    # matches 'ac' or 'bc'

The same grouping applies to quantifiers:

/ a b+ /;            # matches an 'a' followed by one or more 'b's
/ (a b)+ /;          # matches one or more sequences of 'ab'
/ (a || b)+ /;       # matches a sequence of 'a's and 'b's, at least one long

An unquantified capture produces a Match object. When a capture is quantified (except with the ? quantifier) the capture becomes a list of Match objects instead.

40.8.1 Capturing

The round parentheses don't just group, they also capture; that is, they make the string matched within the group available as a variable, and also as an element of the resulting Match object:

my $str =  'number 42';
if $str ~~ /'number ' (\d+) / {
    say "The number is $0";         # the number is 42
    # or
    say "The number is $/[0]";      # the number is 42
}

Pairs of parentheses are numbered left to right, starting from zero.

if 'abc' ~~ /(a) b (c)/ {
    say "0: $0; 1: $1";             # OUTPUT: «0: a; 1: c␤»
}

The $0 and $1 etc. syntax is shorthand. These captures are canonically available from the match object $/ by using it as a list, so $0 is actually syntactic sugar for $/[0].

Coercing the match object to a list gives an easy way to programmatically access all elements:

if 'abc' ~~ /(a) b (c)/ {
    say $/.list.join: ', '  # OUTPUT: «a, c␤»
}

40.8.2 Non-capturing grouping

The parentheses in regexes perform a double role: they group the regex elements inside and they capture what is matched by the sub-regex inside.

To get only the grouping behavior, you can use square brackets [ ... ] instead.

if 'abc' ~~ / [a||b] (c) / {
    say ~$0;                # OUTPUT: «c␤»
}

If you do not need the captures, using non-capturing groups provides three benefits: they more cleanly communicate the regex intent; they make it easier to count the capturing groups that you do care about; and matching is bit faster.

40.8.3 Capture numbers

It is stated above that captures are numbered from left to right. While true in principle, this is also over simplification.

The following rules are listed for the sake of completeness. When you find yourself using them regularly, it's worth considering named captures (and possibly subrules) instead.

Alternations reset the capture count:

/ (x) (y)  || (a) (.) (.) /
# $0  $1      $0  $1  $2

Example:

if 'abc' ~~ /(x)(y) || (a)(.)(.)/ {
    say ~$1;            # b
}

If two (or more) alternations have a different number of captures, the one with the most captures determines the index of the next capture:

$_ = 'abcd'; 
 
 if / a [ b (.) || (x) (y) ] (.) / { 
     #      $0     $0  $1    $2 
     say ~$2;            # d 
 } 

Captures can be nested, in which case they are numbered per level

if 'abc' ~~ / ( a (.) (.) ) / {
    say "Outer: $0";                # Outer: abc
    say "Inner: $0[0] and $0[1]";   # Inner: b and c
}

40.8.4 Named captures

Instead of numbering captures, you can also give them names. The generic -- and slightly verbose -- way of naming captures is like this:

if 'abc' ~~ / $<myname> = [ \w+ ] / {
    say ~$<myname>      # OUTPUT: «abc␤»
}

The access to the named capture, $<myname> , is a shorthand for indexing the match object as a hash, in other words: $/{ 'myname' } or $/<myname> .

Named captures can also be nested using regular capture group syntax:

if 'abc-abc-abc' ~~ / $<string>=( [ $<part>=[abc] ]* % '-' ) / {
    say ~$<string>;         # OUTPUT: «abc-abc-abc␤»
    say ~$<string><part>;   # OUTPUT: «[abc, abc, abc]␤»
}

Coercing the match object to a hash gives you easy programmatic access to all named captures:

if 'count=23' ~~ / $<variable>=\w+ '=' $<value>=\w+ / {
    my %h = $/.hash;
    say %h.keys.sort.join: ', ';        # OUTPUT: «value, variable␤»
    say %h.values.sort.join: ', ';      # OUTPUT: «23, count␤»
    for %h.kv -> $k, $v {
        say "Found value '$v' with key '$k'";
        # outputs two lines:
        #   Found value 'count' with key 'variable'
        #   Found value '23' with key 'value'
    }
}

A more convenient way to get named captures is discussed in the Subrules section.

40.8.5 Capture markers: <( )>

A <( token indicates the start of the match's overall capture, while the corresponding )> token indicates its endpoint. The <( is similar to other languages \K to discard any matches found before the \K.

40.9 Substitution

Regular expressions can also be used to substitute one piece of text for another. You can use this for anything, from correcting a spelling error (e.g., replacing 'Perl Jam' with 'Pearl Jam'), to reformatting an ISO8601 date from yyyy-mm-ddThh:mm:ssZ to mm-dd-yy h:m {AM,PM} and beyond.

Just like the search-and-replace editor's dialog box, the s/ / / operator has two sides, a left and right side. The left side is where your matching expression goes, and the right side is what you want to replace it with.

40.9.1 Lexical conventions

Substitutions are written similarly to matching, but the substitution operator has both an area for the regex to match, and the text to substitute:

s/replace/with/;           # a substitution that is applied to $_ 
 $str ~~ s/replace/with/;   # a substitution applied to a scalar 

The substitution operator allows delimiters other than the slash:

s|replace|with|;
s!replace!with!;
s,replace,with,;

Note that neither the colon : nor balancing delimiters such as {} or () can be substitution delimiters. Colons clash with adverbs such as s:i/Foo/bar/ and the other delimiters are used for other purposes.

Like the m// operator, whitespace is ignored in general. Comments, as in Perl 6 in general, start with the hash character # and go to the end of the current line.

40.9.2 Replacing string literals

The simplest thing to replace is a string literal. The string you want to replace goes on the left-hand side of the substitution operator, and the string you want to replace it with goes on the right-hand side; for example:

$_ = 'The Replacements';
s/Replace/Entrap/;
.say;                    # OUTPUT: «The Entrapments␤»

Alphanumeric characters and the underscore are literal matches, just as in its cousin the m// operator. All other characters must be escaped with a backslash \ or included in quotes:

$_ = 'Space: 1999';
s/Space\:/Party like it's/;
.say                        # OUTPUT: «Party like it's 1999␤»

Note that the matching restrictions only apply to the left-hand side of the substitution expression.

By default, substitutions are only done on the first match:

$_ = 'There can be twly two';
s/tw/on/;                     # replace 'tw' with 'on' once
.say;                         # OUTPUT: «there can be only two␤»

40.9.3 Wildcards and character classes

Anything that can go into the m// operator can go into the left-hand side of the substitution operator, including wildcards and character classes. This is handy when the text you're matching isn't static, such as trying to match a number in the middle of a string:

$_ = "Blake's 9";
s/\d+/7/;         # replace any sequence of digits with '7'
.say;             # OUTPUT: «Blake's 7␤»

Of course, you can use any of the +, * and ? modifiers, and they'll behave just as they would in the m// operator's context.

40.9.4 Capturing Groups

Just as in the match operator, capturing groups are allowed on the left-hand side, and the matched contents populate the $0..$n variables and the $/ object:

$_ = '2016-01-23 18:09:00';
s/ (\d+)\-(\d+)\-(\d+) /today/;   # replace YYYY-MM-DD with 'today'
.say;                             # OUTPUT: «today 18:09:00␤»
"$1-$2-$0".say;                   # OUTPUT: «01-23-2016␤»
"$/[1]-$/[2]-$/[0]".say;          # OUTPUT: «01-23-2016␤»

Any of these variables $0, $1, $/ can be used on the right-hand side of the operator as well, so you can manipulate what you've just matched. This way you can separate out the YYYY, MM and DD parts of a date and reformat them into MM-DD-YYYY order:

$_ = '2016-01-23 18:09:00';
s/ (\d+)\-(\d+)\-(\d+) /$1-$2-$0/;    # transform YYYY-MM-DD to MM-DD-YYYY
.say;                                 # OUTPUT: «01-23-2016 18:09:00␤»

Since the right-hand side is effectively a regular Perl 6 interpolated string, you can reformat the time from HH:MM to h:MM {AM,PM} like so:

$_ = '18:38';
s/(\d+)\:(\d+)/{$0 % 12}\:$1 {$0 < 12 ?? 'AM' !! 'PM'}/;
.say;                                                    # OUTPUT: «6:38 PM␤»

Using the modulo % operator above keeps the sample code under 80 characters, but is otherwise the same as $0 < 12 ?? $0 !! $0 - 12 . When combined with the power of the Parser Expression Grammars that really underlies what you're seeing here, you can use "regular expressions" to parse pretty much any text out there.

40.9.4.1 Common adverbs

The full list of adverbs that you can apply to regular expressions can be found elsewhere in this document (section Adverbs), but the most common are probably :g and :i.

Ordinarily, matches are only made once in a given string, but adding the :g modifier overrides that behavior, so that substitutions are made everywhere possible. Substitutions are non-recursive; for example:

$_ = q{I can say "banana" but I don't know when to stop};
s:g/na/nana,/;    # substitute 'nana,' for 'na'
.say;             # OUTPUT: «I can say "banana,nana," but I don't ...␤»

Here, na was found twice in the original string and each time there was a substitution. The substitution only applied to the original string, though. The resulting string was not impacted.

Ordinarily, matches are case-sensitive. s/foo/bar/ will only match 'foo' and not 'Foo'. If the adverb :i is used, though, matches become case-insensitive.

$_ = 'Fruit';
s/fruit/vegetable/;
.say;                          # OUTPUT: «Fruit␤»

s:i/fruit/vegetable/;
.say;                          # OUTPUT: «vegetable␤»

For more information on what these adverbs are actually doing, refer to the section Adverbs section of this document.

These are just a few of the transformations you can apply with the substitution operator. Some of the simpler uses in the real world include removing personal data from log files, editing mySQL timestamps into PostgreSQL format, changing copyright information in HTML files and sanitizing form fields in a web application.

As an aside, novices to regular expressions often get overwhelmed and think that their regular expression needs to match every piece of data in the line, including what they want to match. Write just enough to match the data you're looking for, no more, no less.

40.10 Tilde for nesting structures

The ~ operator is a helper for matching nested subrules with a specific terminator as the goal. It is designed to be placed between an opening and closing bracket, like so:

/ '(' ~ ')' <expression> /

However, it mostly ignores the left argument, and operates on the next two atoms (which may be quantified). Its operation on those next two atoms is to "twiddle" them so that they are actually matched in reverse order. Hence the expression above, at first blush, is merely shorthand for:

/ '(' <expression> ')' /

But beyond that, when it rewrites the atoms it also inserts the apparatus that will set up the inner expression to recognize the terminator, and to produce an appropriate error message if the inner expression does not terminate on the required closing atom. So it really does pay attention to the left bracket as well, and it actually rewrites our example to something more like:

$<OPEN> = '(' <SETGOAL: ')'> <expression> [ $GOAL || <FAILGOAL> ] 

FAILGOAL is a special method that can be defined by the user and it will be called on parse failure:

grammar A { token TOP { '[' ~ ']' \w+  };
            method FAILGOAL($goal) {
                die "Cannot find $goal near position {self.pos}"
            }
}

A.parse: '[good]';  # OUTPUT: «「[good]」␤»
A.parse: '[bad';    # will throw FAILGOAL exception
CATCH { default { put .^name, ': ', .Str } };
# OUTPUT: «X::AdHoc: Cannot find ']'  near position 5␤»

Note that you can use this construct to set up expectations for a closing construct even when there's no opening bracket:

"3)"  ~~ / <?> ~ ')' \d+ /;  # RESULT: «「3)」»
"(3)" ~~ / <?> ~ ')' \d+ /;  # RESULT: «「3)」»

Here <?> returns true on the first null string.

The order of the regex capture is original:

"abc" ~~ /a ~ (c) (b)/;
say $0; # OUTPUT: «「c」␤»
say $1; # OUTPUT: «「b」␤»

40.11 Subrules

Just like you can put pieces of code into subroutines, you can also put pieces of regex into named rules.

my regex line { \N*\n }
if "abc\ndef" ~~ /<line> def/ {
    say "First line: ", $<line>.chomp;      # OUTPUT: «First line: abc␤»
}

A named regex can be declared with my regex regex_name { body here }, and called with <regex_name> . At the same time, calling a named regex installs a named capture with the same name.

To give the capture a different name from the regex, use the syntax <capture_name=regex_name> . If no capture is desired, a leading dot will suppress it: <.regex_name> .

Here's more complete code for parsing ini files:

my regex header { \s* '[' (\w+) ']' \h* \n+ }
my regex identifier  { \w+ }
my regex kvpair { \s* <key=identifier> '=' <value=identifier> \n+ }
my regex section {
    <header>
    <kvpair>*
}

my $contents = q:to/EOI/;
    [passwords]
        jack=password1
        joy=muchmoresecure123
    [quotas]
        jack=123
        joy=42
EOI

my %config;
if $contents ~~ /<section>*/ {
    for $<section>.list -> $section {
        my %section;
        for $section<kvpair>.list -> $p {
            say $p<value>;
            %section{ $p<key> } = ~$p<value>;
        }
        %config{ $section<header>[0] } = %section;
    }
}
say %config.perl;
# OUTPUT: «("passwords" => {"jack" => "password1", "joy" => "muchmoresecure123"},␤
#          "quotas" => {"jack" => "123", "joy" => "42"}).hash»

Named regexes can and should be grouped in grammars. A list of predefined subrules is listed in S05.

40.12 Adverbs

Adverbs modify how regexes work and provide convenient shortcuts for certain kinds of recurring tasks.

There are two kinds of adverbs: regex adverbs apply at the point where a regex is defined and matching adverbs apply at the point that a regex matches against a string.

This distinction often blurs, because matching and declaration are often textually close but using the method form of matching makes the distinction clear.

'abc' ~~ /../ is roughly equivalent to 'abc'.match(/../), or even more clearly written in separate lines:

my $regex = /../;           # definition
if 'abc'.match($regex) {    # matching
    say "'abc' has at least two characters";
}

Regex adverbs like :i go into the definition line and matching adverbs like :overlap are appended to the match call:

my $regex = /:i . a/;
for 'baA'.match($regex, :overlap) -> $m {
    say ~$m;
}
# OUTPUT: «ba␤aA␤»

40.12.1 Regex Adverbs

Adverbs that appear at the time of a regex declaration are part of the actual regex and influence how the Perl 6 compiler translates the regex into binary code.

For example, the :ignorecase (:i) adverb tells the compiler to ignore the distinction between upper case, lower case and title case letters.

So 'a' ~~ /A/ is false, but 'a' ~~ /:i A/ is a successful match.

Regex adverbs can come before or inside a regex declaration and only affect the part of the regex that comes afterwards, lexically. Note that regex adverbs appearing before the regex must appear after something that introduces the regex to the parser, like 'rx' or 'm' or a bare '/'. This is NOT valid:

my $rx1 = :i/a/;      # adverb is before the regex is recognized => exception 

but these are valid:

my $rx1 = rx:i/a/;     # before
my $rx2 = m:i/a/;      # before
my $rx3 = /:i a/;      # inside

These two regexes are equivalent:

my $rx1 = rx:i/a/;      # before
my $rx2 = rx/:i a/;     # inside

Whereas these two are not:

my $rx3 = rx/a :i b/;   # matches only the b case insensitively
my $rx4 = rx/:i a b/;   # matches completely case insensitively

Brackets and parentheses limit the scope of an adverb:

/ (:i a b) c /;         # matches 'ABc' but not 'ABC'
/ [:i a b] c /;         # matches 'ABc' but not 'ABC'

40.12.1.1 Ratchet

The :ratchet or :r adverb causes the regex engine not to backtrack.

Without this adverb, parts of a regex will try different ways to match a string in order to make it possible for other parts of the regex to match. For example, in 'abc' ~~ /\w+ ./, the \w+ first eats up the whole string, abc but then the . fails. Thus \w+ gives up a character, matching only ab, and the . can successfully match the string c. This process of giving up characters (or in the case of alternations, trying a different branch) is known as backtracking.

say so 'abc' ~~ / \w+ . /;        # OUTPUT: «True␤»
say so 'abc' ~~ / :r \w+ . /;     # OUTPUT: «False␤»

Ratcheting can be an optimization, because backtracking is costly. But more importantly, it closely corresponds to how humans parse a text. If you have a regex my regex identifier { \w+ } and my regex keyword { if | else | endif }, you intuitively expect the identifier to gobble up a whole word and not have it give up its end to the next rule, if the next rule otherwise fails.

For example, you don't expect the word motif to be parsed as the identifier mot followed by the keyword if. Instead, you expect motif to be parsed as one identifier; and if the parser expects an if afterwards, best that it should fail than have it parse the input in a way you don't expect.

Since ratcheting behavior is often desirable in parsers, there's a shortcut to declaring a ratcheting regex:

my token thing { .... } 
 # short for 
 my regex thing { :r ... } 

40.12.1.2 Sigspace

The :sigspace or :s adverb makes whitespace significant in a regex.

say so "I used Photoshop®"   ~~ m:i/   photo shop /;      # OUTPUT: «True␤» 
 say so "I used a photo shop" ~~ m:i :s / photo shop /;   # OUTPUT: «True␤» 
 say so "I used Photoshop®"   ~~ m:i :s / photo shop /;   # OUTPUT: «False␤» 

m:s/ photo shop / acts the same as m/ photo <.ws> shop <.ws> /. By default, <.ws> makes sure that words are separated, so a b and ^& will match <.ws> in the middle, but ab won't.

Where whitespace in a regex turns into <.ws> depends on what comes before the whitespace. In the above example, whitespace in the beginning of a regex doesn't turn into <.ws>, but whitespace after characters does. In general, the rule is that if a term might match something, whitespace after it will turn into <.ws>.

In addition, if whitespace comes after a term but before a quantifier (+, *, or ?), <.ws> will be matched after every match of the term. So, foo + becomes [ foo <.ws> ]+. On the other hand, whitespace after a quantifier acts as normal significant whitespace; e.g., "foo+" becomes foo+ <.ws>.

In all, this code:

rx :s { 
     ^^ 
     { 
         say "No sigspace after this"; 
     } 
     <.assertion_and_then_ws> 
     characters_with_ws_after+ 
     ws_separated_characters * 
     [ 
     | some "stuff" .. . 
     | $$ 
     ] 
     :my $foo = "no ws after this"; 
     $foo 
 } 

Becomes:

rx { 
     ^^  <.ws>  
     { 
         say "No space after this"; 
     } 
     <.assertion_and_then_ws>  <.ws>  
     characters_with_ws_after+  <.ws>  
     [ws_separated_characters  <.ws> ]*  <.ws>  
     [ 
     | some  <.ws>  "stuff"  <.ws>  ..  <.ws>  .  <.ws>  
     | $$  <.ws>  
     ]  <.ws>  
     :my $foo = "no ws after this"; 
     $foo  <.ws>  
 } 

If a regex is declared with the rule keyword, both the :sigspace and :ratchet adverbs are implied.

Grammars provide an easy way to override what <.ws> matches:

grammar Demo {
    token ws {
        <!ww>       # only match when not within a word
        \h*         # only match horizontal whitespace
    }
    rule TOP {      # called by Demo.parse;
        a b '.'
    }
}

# doesn't parse, whitespace required between a and b
say so Demo.parse("ab.");                 # OUTPUT: «False␤»
say so Demo.parse("a b.");                # OUTPUT: «True␤»
say so Demo.parse("a\tb .");              # OUTPUT: «True␤»

# \n is vertical whitespace, so no match
say so Demo.parse("a\tb\n.");             # OUTPUT: «False␤»

When parsing file formats where some whitespace (for example, vertical whitespace) is significant, it's advisable to override ws.

40.12.2 Matching adverbs

In contrast to regex adverbs, which are tied to the declaration of a regex, matching adverbs only make sense when matching a string against a regex.

They can never appear inside a regex, only on the outside – either as part of an m/.../ match or as arguments to a match method.

40.12.2.1 Continue

The :continue or short :c adverb takes an argument. The argument is the position where the regex should start to search. By default, it searches from the start of the string, but :c overrides that. If no position is specified for :c, it will default to 0 unless $/ is set, in which case, it defaults to $/.to.

given 'a1xa2' {
    say ~m/a./;         # OUTPUT: «a1␤»
    say ~m:c(2)/a./;    # OUTPUT: «a2␤»
}

Note: unlike :pos, a match with :continue() will attempt to match further in the string, instead of failing:

say "abcdefg" ~~ m:c(3)/e.+/; # OUTPUT: «「efg」␤»
say "abcdefg" ~~ m:p(3)/e.+/; # OUTPUT: «False␤»

40.12.2.2 Exhaustive

To find all possible matches of a regex – including overlapping ones – and several ones that start at the same position, use the :exhaustive (short :ex) adverb.

given 'abracadabra' {
    for m:exhaustive/ a .* a / -> $match {
        say ' ' x $match.from, ~$match;
    }
}

The above code produces this output:

abracadabra 
 abracada 
 abraca 
 abra 
    acadabra 
    acada 
    aca 
      adabra 
      ada 
        abra 

40.12.2.3 Global

Instead of searching for just one match and returning a Match object, search for every non-overlapping match and return them in a List. In order to do this, use the :global adverb:

given 'several words here' {
    my @matches = m:global/\w+/;
    say @matches.elems;         # OUTPUT: «3␤»
    say ~@matches[2];           # OUTPUT: «here␤»
}

:g is shorthand for :global.

40.12.2.4 Pos

Anchor the match at a specific position in the string:

given 'abcdef' {
    my $match = m:pos(2)/.*/;
    say $match.from;        # OUTPUT: «2␤»
    say ~$match;            # OUTPUT: «cdef␤»
}

:p is shorthand for :pos.

Note: unlike :continue, a match anchored with :pos() will fail, instead of attempting to match further down the string:

say "abcdefg" ~~ m:c(3)/e.+/; # OUTPUT: «「efg」␤»
say "abcdefg" ~~ m:p(3)/e.+/; # OUTPUT: «False␤»

40.12.2.5 Overlap

To get several matches, including overlapping matches, but only one (the longest) from each starting position, specify the :overlap (short :ov) adverb:

given 'abracadabra' {
    for m:overlap/ a .* a / -> $match {
        say ' ' x $match.from, ~$match;
    }
}

produces

abracadabra 
    acadabra 
      adabra 
        abra 

40.13 Look-around assertions

40.13.1 Lookahead assertions

To check that a pattern appears before another pattern, use a lookahead assertion via the before assertion. This has the form:

<?before pattern>

Thus, to search for the string foo which is immediately followed by the string bar, use the following regexp:

rx{ foo <?before bar> }

For example:

say "foobar" ~~ rx{ foo <?before bar> };   # OUTPUT: «foo␤»

However, if you want to search for a pattern which is not immediately followed by some pattern, then you need to use a negative lookahead assertion, this has the form:

<!before pattern>

Hence, all occurrences of foo which is not before bar would match with

rx{ foo <!before bar> }

40.13.2 Lookbehind assertions

To check that a pattern appears before another pattern, use a lookbehind assertion via the after assertion. This has the form:

<?after pattern>

Therefore, to search for the string bar immediately preceded by the string foo, use the following regexp:

rx{ <?after foo> bar }

For example:

say "foobar" ~~ rx{ <?after foo> bar };   # OUTPUT: «bar␤»

However, if you want to search for a pattern which is not immediately preceded by some pattern, then you need to use a negative lookbehind assertion, this has the form:

<!after pattern>

Hence all occurrences of bar which do not have foo before them would be matched by

rx{ <!after foo> bar }

40.14 Best practices and gotchas

To help with robust regexes and grammars, here are some best practices for code layout and readability, what to actually match, and avoiding common pitfalls.

40.14.1 Code layout

Without the :sigspace adverb, whitespace is not significant in Perl 6 regexes. Use that to your own advantage and insert whitespace where it increases readability. Also, insert comments where necessary.

Compare the very compact

my regex float { <[+-]>?\d*'.'\d+[e<[+-]>?\d+]? }

to the more readable

my regex float {
     <[+-]>?        # optional sign
     \d*            # leading digits, optional
     '.'
     \d+
     [              # optional exponent
        e <[+-]>?  \d+
     ]?
}

As a rule of thumb, use whitespace around atoms and inside groups; put quantifiers directly after the atom; and vertically align opening and closing brackets and parentheses.

When you use a list of alternations inside a parenthesis or brackets, align the vertical bars:

my regex example {
    <preamble>
    [
    || <choice_1>
    || <choice_2>
    || <choice_3>
    ]+
    <postamble>
}

40.14.2 Keep it small

Regexes are often more compact than regular code. Because they do so much with so little, keep regexes short.

When you can name a part of a regex, it's usually best to put it into a separate, named regex.

For example, you could take the float regex from earlier:

my regex float {
     <[+-]>?        # optional sign
     \d*            # leading digits, optional
     '.'
     \d+
     [              # optional exponent
        e <[+-]>?  \d+
     ]?
}

And decompose it into parts:

my token sign { <[+-]> }
my token decimal { \d+ }
my token exponent { 'e' <sign>? <decimal> }
my regex float {
    <sign>?
    <decimal>?
    '.'
    <decimal>
    <exponent>?
}

That helps, especially when the regex becomes more complicated. For example, you might want to make the decimal point optional in the presence of an exponent.

my regex float {
    <sign>?
    [
    || <decimal>?  '.' <decimal> <exponent>?
    || <decimal> <exponent>
    ]
}

40.14.3 What to match

Often the input data format has no clear-cut specification, or the specification is not known to the programmer. Then, it's good to be liberal in what you expect, but only so long as there are no possible ambiguities.

For example, in ini files:

[section] 
 key=value 

What can be inside the section header? Allowing only a word might be too restrictive. Somebody might write [two words], or use dashes, or so on. Instead of asking what's allowed on the inside, it might be worth asking instead: what's not allowed?

Clearly, closing brackets are not allowed, because [a]b] would be ambiguous. By the same argument, opening brackets should be forbidden. This leaves us with

token header { '[' <-[ \[\] ]>+ ']' }

which is fine if you are only processing one line. But if you're processing a whole file, suddenly the regex parses

[with a 
 newline in between] 

which might not be a good idea. A compromise would be

token header { '[' <-[ \[\] \n ]>+ ']' }

and then, in the post-processing, strip leading and trailing spaces and tabs from the section header.

40.14.4 Matching Whitespace

The :sigspace adverb (or using the rule declarator instead of token or regex) is very handy for implicitly parsing whitespace that can appear in many places.

Going back to the example of parsing ini files, we have

my regex kvpair { \s* <key=identifier> '=' <value=identifier> \n+ }

which is probably not as liberal as we want it to be, since the user might put spaces around the equals sign. So, then we may try this:

my regex kvpair { \s* <key=identifier> \s* '=' \s* <value=identifier> \n+ }

But that's looking unwieldy, so we try something else:

my rule kvpair { <key=identifier> '=' <value=identifier> \n+ }

But wait! The implicit whitespace matching after the value uses up all whitespace, including newline characters, so the \n+ doesn't have anything left to match (and rule also disables backtracking, so no luck there).

Therefore, it's important to redefine your definition of implicit whitespace to whitespace that is not significant in the input format.

This works by redefining the token ws; however, it only works for grammars:

grammar IniFormat {
    token ws { <!ww> \h* }
    rule header { \s* '[' (\w+) ']' \n+ }
    token identifier  { \w+ }
    rule kvpair { \s* <key=identifier> '=' <value=identifier> \n+ }
    token section {
        <header>
        <kvpair>*
    }

    token TOP {
        <section>*
    }
}

my $contents = q:to/EOI/;
    [passwords]
        jack = password1
        joy = muchmoresecure123
    [quotas]
        jack = 123
        joy = 42
EOI
say so IniFormat.parse($contents);

Besides putting all regexes into a grammar and turning them into tokens (because they don't need to backtrack anyway), the interesting new bit is

token ws { <!ww> \h* }

which gets called for implicit whitespace parsing. It matches when it's not between two word characters (<!ww> , negated "within word" assertion), and zero or more horizontal space characters. The limitation to horizontal whitespace is important, because newlines (which are vertical whitespace) delimit records and shouldn't be matched implicitly.

Still, there's some whitespace-related trouble lurking. The regex \n+ won't match a string like "\n \n", because there's a blank between the two newlines. To allow such input strings, replace \n+ with \n\s*.

41 Sets, Bags, and Mixes

Unordered collections of unique and weighted objects in Perl 6

Often you want to collect objects in a container but you do not care about the order of these objects. For such cases, Perl 6 provides the unordered collection types Set , SetHash , Bag , BagHash , Mix , and MixHash . Being unordered, these containers can be more efficient than Lists for looking up elements or dealing with repeated items.

If you want to get the contained objects (elements) without duplicates and you only care whether an element is in the collection or not, you can use a Set or SetHash . (If you want to get rid of duplicates but still preserve order, take a look at the unique routine for Lists .)

=defn Set or SetHash Collection of distinct objects

If you want to keep track of the number of times each object appeared, you can use a Bag or BagHash . In these Baggy containers each element has a weight (an unsigned integer) indicating the number of times the same object has been included in the collection. The types Mix and MixHash are similar, but they also allow fractional weights.

=defn Bag or BagHash Collection of distinct objects mapped to integer weights =defn Mix or MixHash Collection of distinct objects mapped to real-number weights TODO: Partial type graph showing only QuantHash, Setty, Baggy, Mixy, Set, SetHash, Bag, BagHash, Mix, MixHash.

Set , Bag , and Mix are immutable types. Use the mutable variants SetHash , BagHash , and MixHash if you want to add or remove elements after the container has been constructed.

The six collection classes Set, SetHash, Bag, BagHash, Mix, MixHash, all share similar semantics.

For one thing, as far as they are concerned, identical objects refer to the same element – where identity is determined using the WHICH methods (i.e. the same way that the === operator checks identity). For value types like Str, this means having the same value; for reference types like Array, it means referring to the same object instance.

Secondly, they provide a Hash-like interface where the actual elements of the collection (which can be objects of any type) are the 'keys', and the associated weights are the 'values':

type of $a value of $a{$b} if $b is an element value of $a{$b} if $b is not an element
Set / SetHash True False
Bag / BagHash a positive integer 0
Mix / MixHash a non-zero real number 0

41.1 Set/Bag Operators

TODO: Update this after ab5tract's set/bag/mix operator redesign.

There are many infixes devoted to preforming common operations on Set s, such as unions and set differences. Other operations include boolean checks, like whether an object is an element of a Set, or whether one Set is a subset of another Set.

These infixes can be written using the UTF-8 character that represents the function (like , or ), or they can be written with an equivalent ASCII version (like (elem) or (|) ).

Most of the time, explicitly using Set objects with these infixes is unnecessary. All of the infix operators will work on any objects of type Any for its arguments (e.g., List s, Array s, Mix es, etc.) and coerce them to Sets where needed.

In some cases, if the type of an argument is a Bag, the infix operator will behave in a different but analogous way to the way it would behave with only Set arguments.

41.1.1 Operators that return Bool

41.1.1.1 infix (elem)

multi sub infix:<(elem)>($a, Any $b --> Bool)
multi sub infix:<(elem)>($a, Set $b --> Bool)

Membership operator.

Returns True if $a is an element of $b.

say 2 (elem) (1, 2, 3).Set;              # OUTPUT: «True␤»
say 4 (elem) (1, 2, 3).Set;              # OUTPUT: «False␤»

41.1.1.1.1 infix ∈

only sub infix:<∈>($a, $b --> Bool)

Membership operator (alternate).

Equivalent to (elem), at codepoint U+2208 (ELEMENT OF).

41.1.1.1.2 infix ∉

only sub infix:<∉>($a, $b --> Bool)

Non-membership operator.

Equivalent to !(elem), i.e., returns True if $a is not an element of $b, at codepoint U+2209 (NOT AN ELEMENT OF).

say 2 !(elem) (1, 2, 3).Set;             # OUTPUT: «False␤»
say 4 !(elem) (1, 2, 3).Set;             # OUTPUT: «True␤»

41.1.1.2 infix (cont)

multi sub infix:<(cont)>(Any $a, $b --> Bool)
multi sub infix:<(cont)>(Set $a, $b --> Bool)

Contains operator.

Returns True if $a contains $b as an element.

say (1, 2, 3).Set (cont) 2;              # OUTPUT: «True␤»
say (1, 2, 3).Set (cont) 4;              # OUTPUT: «False␤»

41.1.1.2.1 infix ∋

only sub infix:<∋>($a, $b --> Bool)

Contains operator (alternate).

Equivalent to (cont), at codepoint U+220B (CONTAINS AS MEMBER).

41.1.1.2.2 infix ∌

only sub infix:<∌>($a, $b --> Bool)

Does not contain operator.

Equivalent to !(cont), i.e., returns True if $a does not contain $b, at codepoint U+220C (DOES NOT CONTAIN AS MEMBER).

say (1, 2, 3).Set !(cont) 2;             # OUTPUT: «False␤»
say (1, 2, 3).Set !(cont) 4;             # OUTPUT: «True␤»

41.1.1.3 infix (<=)

multi sub infix:<<(<=)>>(Any $a, Any $b --> Bool)
multi sub infix:<<(<=)>>(Setty $a, Setty $b --> Bool)

Subset of or equal to operator.

Returns True if $a is a subset or is equal to $b, i.e., if all the elements of $a are elements of $b and $a is a smaller or equal sized set than $b.

say (1, 2, 3).Set (<=) (3, 2, 1).Set;    # OUTPUT: «True␤»
say (1, 3).Set (<=) (2, 1).Set;          # OUTPUT: «False␤»
say ∅ (<=) (3, 2, 1).Set;                # OUTPUT: «True␤»

41.1.1.3.1 infix ⊆

only sub infix:<⊆>($a, $b --> Bool)

Subset of or equal to operator (alternate).

Equivalent to (<=), at codepoint U+2286 (SUBSET OF OR EQUAL TO).

41.1.1.3.2 infix ⊈

only sub infix:<⊈>($a, $b --> Bool)

Neither subset of nor equal to operator.

Equivalent to !(<=), at codepoint U+2288 (NEITHER A SUBSET OF NOR EQUAL TO).

say (1, 2, 3).Set !(<=) (3, 2, 1).Set;   # OUTPUT: «False␤»
say (1, 3).Set ⊈ (2, 1).Set;             # OUTPUT: «True␤»

41.1.1.4 infix (<)

multi sub infix:<<(<)>>(Any $a, Any $b --> Bool)
multi sub infix:<<(<)>>(Setty $a, Setty $b --> Bool)

Subset of operator.

Returns True if $a is a strict subset of $b, i.e., that all the elements of $a are elements of $b but $a is a smaller set than $b.

say (1, 2, 3).Set (<) (3, 2, 1).Set;     # OUTPUT: «False␤»
say (1, 3).Set (<) (3, 2, 1).Set;        # OUTPUT: «True␤»
say ∅ (<) (3, 2, 1).Set;                 # OUTPUT: «True␤»

41.1.1.4.1 infix ⊂

only sub infix:<⊂>($a, $b --> Bool)

Subset of operator (alternate).

Equivalent to (<), at codepoint U+2282 (SUBSET OF).

41.1.1.4.2 infix ⊄

only sub infix:<⊄>($a, $b --> Bool)

Not a subset of operator.

Equivalent to !(<), at codepoint U+2284 (NOT A SUBSET OF).

say (1, 2, 3).Set !(<) (3, 2, 1).Set;    # OUTPUT: «True␤»
say (1, 3).Set ⊄ (3, 2, 1).Set;          # OUTPUT: «False␤»

41.1.1.5 infix (>=)

multi sub infix:<<(>=)>>(Any $a, Any $b --> Bool)
multi sub infix:<<(>=)>>(Setty $a, Setty $b --> Bool)

Superset of or equal to operator.

Like (<=) with reversed arguments. Returns True if