Raku borrows many concepts from human language. Which is not surprising, considering it was designed by a linguist.

It reuses common elements in different contexts; it has the notion of nouns (terms) and verbs (operators); it is context-sensitive (in the every day sense, not necessarily in the Computer Science interpretation), so a symbol can have a different meaning depending on whether a noun or a verb is expected.

It is also self-clocking, so that the parser can detect most of the common errors and give good error messages.

Lexical conventions §

Raku code is Unicode text. Current implementations support UTF-8 as the input encoding.

Free form §

Raku code is also free-form, in the sense that you are mostly free to chose the amount of whitespace you use, though in some cases, the presence or absence of whitespace carries meaning.

So you can write

Raku highlighting

if True {
    say "Hello";
}

Raku highlighting

    if True {
say "Hello"; # Bad indentation intended 
        }

Raku highlighting

if True { say "Hello" }

or even

Raku highlighting

if True {say "Hello"}

though you can't leave out any more whitespace in this last example.

Unspace §

In places where the compiler would not allow a space you can use any amount of whitespace, as long as it is quoted with a backslash. Unspaces in tokens, however, are not supported. Newlines that are unspaced still count when the compiler produces line numbers. Use cases for unspace are separation of postfix operators and routine argument lists.

Raku highlighting

sub alignment(+@l) { +@l };
sub long-name-alignment(+@l) { +@l };
alignment\         (1,2,3,4).say;
long-name-alignment(3,5)\   .say;
say Inf+Inf\i;

In this case, our intention was to make the . of both statements, as well as the parentheses, align, so we precede the whitespace used for padding with a \.

Separating statements with semicolons §

A Raku program is a list of statements, separated by semicolons ;.

Raku highlighting

say "Hello";
say "world";

A semicolon after the final statement (or after the final statement inside a block) is optional.

Raku highlighting

say "Hello";
say "world"

Raku highlighting

if True {
    say "Hello"
}
say "world"

Implied separator rule (for statements ending in blocks)§

Complete statements ending in bare blocks can omit the trailing semicolon, if no additional statements on the same line follow the block's closing curly brace }. This is called the "implied separator rule." For example, you don't need to write a semicolon after an if statement block as seen above, and below.

Raku highlighting

if True { say "Hello" }
say "world";

However, semicolons are required to separate a block from trailing statements in the same line.

Raku highlighting

if True { say "Hello" }; say "world";
#                     ^^^ this ; is required

This implied statement separator rule applies in other ways, besides control statements, that could end with a bare block. For example, in combination with the colon : syntax for method calls.

Raku highlighting

my @names = <Foo Bar Baz>;
my @upper-case-names = @names.map: { .uc }    # OUTPUT: [FOO BAR BAZ]

For a series of blocks that are part of the same if/elsif/else (or similar) construct, the implied separator rule only applies at the end of the last block of that series. These three are equivalent:

Raku highlighting

if True { say "Hello" } else { say "Goodbye" }; say "world";
#                                            ^^^ this ; is required

Raku highlighting

if True { say "Hello" } else { say "Goodbye" } # <- implied statement separator 
say "world";

Raku highlighting

if True { say "Hello" }   # still in the middle of an if/else statement 
else    { say "Goodbye" } # <- no semicolon required because it ends in a block 
                          #    without trailing statements in the same line 
say "world";

Comments §

Comments are parts of the program text which are only intended for human readers; the Raku compilers do not evaluate them as program text. They are part of the non-ambient code that includes Pod6 text.

Comments count as whitespace in places where the absence or presence of whitespace disambiguates possible parses.

Single-line comments §

The most common form of comments in Raku starts with a single hash character # and goes until the end of the line.

Raku highlighting

if $age > 250 {     # catch obvious outliers 
    # this is another comment! 
    die "That doesn't look right"
}

Multi-line / embedded comments §

Multi-line and embedded comments start with a hash character, followed by a backtick, and then a Unicode Open Punctuation character, and end with the matching Close Punctuation character. Whitespace is not permitted between the backtick and the punctuation character; it will be treated as a single-line comment. The content can not only span multiple lines, but can also be embedded inline.

Raku highlighting

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

These comments can extend multiple lines

Raku highlighting

#`[
And this is how a multi would work.
That says why we do what we do below.
]
say "No more";

Curly braces inside the comment can be nested, so in #`{ a { b } c }, the comment goes until the very end of the string; this is why if the opening bracketing character also occurs in the body of the comment, e.g. #`[ This is a box [ of stuff ] ], it must have a paired closing character, as shown. You may also use multiple curly braces, such as #`{{ double-curly-brace }}, which might help disambiguate from nested delimiters. You can embed these comments in expressions, as long as you don't insert them in the middle of keywords or identifiers.

Pod comments §

Pod syntax can be used for multi-line comments

Raku highlighting

say "this is code";
 
=begin comment
 
Here are several
lines
of comment
 
=end comment
 
say 'code again';

Identifiers §

Identifiers are grammatical building blocks that may be used to give a name to entities/objects such as constants, variables (e.g. Scalars) and routines (e.g. Subs and Methods). In a variable name, any sigil (and twigil) precedes the identifier and does not form a part thereof.

Raku highlighting

constant c = 299792458;     # identifier "c" names an Int 
my $a = 123;                # identifier "a" in the name "$a" of a Scalar 
sub hello { say "Hello!" }; # identifier "hello" names a Sub

Identifiers come in different forms: ordinary, extended, and compound identifiers.

Ordinary identifiers §

An ordinary identifier is composed of a leading alphabetic character which may be followed by one or more alphanumeric characters. It may also contain isolated, embedded apostrophes ' and/or hyphens -, provided that the next character is each time alphabetic.

The definitions of "alphabetic" and "alphanumeric" include appropriate Unicode characters. Which characters are "appropriate" depends on the implementation. In the Rakudo/MoarVM Raku implementation alphabetic characters include characters with the Unicode General Category value Letter (L), and the underscore _. Alphanumeric characters additionally include characters with the Unicode General Category value Number, Decimal Digit (Nd).

Raku highlighting

# valid ordinary identifiers: 
x
_snake_oil
something-longer
with-numbers1234
don't-do-that
piece_of_π
駱駝道              # "Rakuda-dō", Japanese for "Way of the camel"

Raku highlighting

# invalid ordinary identifiers: 
42                 # identifier does not start with alphabetic character 
with-numbers1234-5 # embedded hyphen not followed by alphabetic character 
is-prime?          # question mark is not alphanumeric 
x²                 # superscript 2 is not alphanumeric (explained above)

Extended identifiers §

It is often convenient to have names that contain characters that are not allowed in ordinary identifiers. Use cases include situations where a set of entities shares a common "short" name, but still needs for each of its elements to be identifiable individually. For example, you might use a module whose short name is Dog, while its long name includes its naming authority and version:

Raku highlighting

Dog:auth<Somebody>:ver<1.0>  # long module names including author and version 
Dog:auth<Somebody>:ver<2.0>
 
use Dog:auth<Somebody>:ver<2.0>;
# Selection of second module causes its full name to be aliased to the 
# short name for the rest of # the lexical scope, allowing a declaration 
# like this. 
my Dog $spot .= new("woof");

Similarly, sets of operators work together in various syntactic categories with names like prefix, infix and postfix. The official names of these operators often contain characters that are excluded from ordinary identifiers. The long name is what constitutes the extended identifier, and includes this syntactic category; the short name will be included in quotes in the definition:

Raku highlighting

infix:<+>                 # the official name of the operator in $a + $b 
infix:<*>                 # the official name of the operator in $a * $b 
infix:«<=»                # the official name of the operator in $a <= $b

For all such uses, you can append one or more colon-separated strings to an ordinary identifier to create a so-called extended identifier. When appended to an identifier (that is, in postfix position), this colon-separated string generates unique variants of that identifier.

These strings have the form :key<value>, wherein key or value are optional; that is, after the colon that separates it from a regular identifier, there will be a key and/or a quoting bracketing construct such as < >, « » or [' '] which quotes one or more arbitrary characters value.^[1]

Raku highlighting

# exemplary valid extended identifiers: 
postfix:<²>               # the official long name of the operator in $x² 
WOW:That'sAwesome
WOW:That's<<🆒>>
party:sweet<16>
 
# exemplary invalid extended identifiers: 
party:16<sweet>           # 16 is not an ordinary identifier 
party:16sweet
party:!a                  # ...and neither is !a 
party:$a                  # ...nor $a

In an extended identifier, the postfix string is considered an integral part of the name, so infix:<+> and infix:<-> are two different operators. The bracketing characters used, however, do not count as part of it; only the quoted data matters. So these are all the same name:

Raku highlighting

infix:<+>
infix:<<+>>
infix:«+»
infix:['+']
infix:('+')

Similarly, all of this works:

Raku highlighting

my $foo:bar<baz> = 'quux';
say $foo:bar«baz»;                               # OUTPUT: «quux␤» 
my $take-me:<home> = 'Where the glory has no end';
say $take-me:['home'];                           # OUTPUT: «Where [...]␤» 
my $foo:bar<2> = 5;
say $foo:bar(1+1);                               # OUTPUT: «5␤»

Where an extended identifier comprises two or more colon pairs, their order is generally significant:

Raku highlighting

my $a:b<c>:d<e> = 100;
my $a:d<e>:b<c> = 200;
say $a:b<c>:d<e>;               # OUTPUT: «100␤», NOT: «200␤»

An exception to this rule is module versioning; so these identifiers effectively name the same module:

Raku highlighting

use ThatModule:auth<Somebody>:ver<2.7.18.28.18>
use ThatModule:ver<2.7.18.28.18>:auth<Somebody>

Furthermore, extended identifiers support compile-time interpolation; this requires the use of constants for the interpolation values:

Raku highlighting

constant $c = 42;  # Constant binds to Int; $-sigil enables interpolation 
my $a:foo<42> = "answer";
say $a:foo«$c»;    # OUTPUT: «answer␤»

Although quoting bracketing constructs are generally interchangeable in the context of identifiers, they are not identical. In particular, angle brackets < > (which mimic single quote interpolation characteristics) cannot be used for the interpolation of constant names.

Raku highlighting

constant $what = 'are';
my @we:<are>= <the champions>;
say @we:«$what»;     # OUTPUT: «[the champions]␤» 
say @we:<$what>;
# Compilation error: Variable '@we:<$what>' is not declared

Compound identifiers §

A compound identifier is an identifier that is composed of two or more ordinary and/or extended identifiers that are separated from one another by a double colon ::.

The double colon :: is known as the namespace separator or the package delimiter, which clarifies its semantic function in a name: to force the preceding portion of the name to be considered a package/namespace through which the subsequent portion of the name is to be located:

Raku highlighting

module MyModule {               # declare a module package 
    our $var = "Hello";         # declare package-scoped variable 
}
say $MyModule::var              # OUTPUT: «Hello␤»

In the example above, MyModule::var is a compound identifier, composed of the package name identifier MyModule and the identifier part of the variable name var. Altogether $MyModule::var is often referred to as a package-qualified name.

Separating identifiers with double colons causes the rightmost name to be inserted into existing (see above example) or automatically created packages:

Raku highlighting

my $foo::bar = 1;
say OUR::.keys;           # OUTPUT: «(foo)␤» 
say OUR::foo.HOW          # OUTPUT: «Perl6::Metamodel::PackageHOW.new␤»

The last lines shows how the foo package was created automatically, as a deposit for variables in that namespace.

The double colon syntax enables runtime interpolation of a string into a package or variable name using ::($expr) where you'd ordinarily put a package or variable name:

Raku highlighting

my $buz = "quux";
my $bur::quux = 7;
say $bur::($buz);               # OUTPUT: «7␤»

term term:<>§

You can use term:<> to introduce new terms, which is handy for introducing constants that defy the rules of normal identifiers:

Raku highlighting

use Test; plan 1; constant &term:<👍> = &ok.assuming(True);
👍
# OUTPUT: «1..1␤ok 1 - ␤»

But terms don't have to be constant: you can also use them for functions that don't take any arguments, and force the parser to expect an operator after them. For instance:

Raku highlighting

sub term:<dice> { (1..6).pick };
say dice + dice;

can print any number between 2 and 12.

If instead we had declared dice as a regular

Raku highlighting

sub dice() {(1...6).pick }

, the expression dice + dice would be parsed as dice(+(dice())), resulting in an error since sub dice expects zero arguments.

Statements and expressions §

Raku programs are made of lists of statements. A special case of a statement is an expression, which returns a value. For example if True { say 42 } is syntactically a statement, but not an expression, whereas 1 + 2 is an expression (and thus also a statement).

The do prefix turns statements into expressions. So while

Raku highlighting

my $x = if True { 42 };     # Syntax error!

is an error,

Raku highlighting

my $x = do if True { 42 };

assigns the return value of the if statement (here 42) to the variable $x.

Terms §

Terms are the basic nouns that, optionally together with operators, can form expressions. Examples for terms are variables ($x), barewords such as type names (Int), literals (42), declarations (sub f() { }) and calls (f()).

For example, in the expression 2 * $salary, 2 and $salary are two terms (an Int literal and a variable).

Variables §

Variables typically start with a special character called the sigil, and are followed by an identifier. Variables must be declared before you can use them.

Raku highlighting

# declaration: 
my $number = 21;
# usage: 
say $number * 2;

See the documentation on variables for more details.

Barewords (constants, type names)§

Pre-declared identifiers can be terms on their own. Those are typically type names or constants, but also the term self which refers to an object that a method was called on (see objects), and sigilless variables:

Raku highlighting

say Int;                # OUTPUT: «(Int)␤» 
#   ^^^ type name (built in) 
 
constant answer = 42;
say answer;
#   ^^^^^^ constant 
 
class Foo {
    method type-name {
        self.^name;
      # ^^^^ built-in term 'self' 
    }
}
say Foo.type-name;     # OUTPUT: «Foo␤» 
#   ^^^ type name

Packages and qualified names §

Named entities, such as variables, constants, classes, modules or subs, are part of a namespace. Nested parts of a name use :: to separate the hierarchy. Some examples:

Raku highlighting

$foo                # simple identifiers 
$Foo::Bar::baz      # compound identifiers separated by :: 
$Foo::($bar)::baz   # compound identifiers that perform interpolations 
Foo::Bar::bob(23)   # function invocation given qualified name

See the documentation on packages for more details.

Literals §

A literal is a representation of a constant value in source code. Raku has literals for several built-in types, like Str, several numeric types, Pairs and more.

String literals §

String literals are surrounded by quotes:

Raku highlighting

say 'a string literal';
say "a string literal\nthat interprets escape sequences";

See quoting for many more options, including interpolation quoting q. Raku uses the standard escape characters in literals: \0 \a \b \t \n \f \r \e, with the same meaning as the ASCII escape codes, specified in the design document.

Raku highlighting

say "🔔\a";  # OUTPUT: «🔔␇␤»

Number literals §

Number literals are generally specified in base ten (which can be specified literally, if needed, via the prefix 0d), unless a prefix like 0x (hexadecimal, base 16), 0o (octal, base 8) or 0b (binary, base 2) or an explicit base in adverbial notation like :16<A0> specifies it otherwise. Unlike other programming languages, leading zeros do not indicate base 8; instead a compile-time warning is issued.

In all literal formats, you can use underscores to group digits, although they don't carry any semantic information; the following literals all evaluate to the same number:

Raku highlighting

`Int` literals§

Integers default to signed base-10, but you can use other bases. For details, see Int.

Raku highlighting

# not a single literal, but unary - operator applied to numeric literal 2 
-2
12345
0xBEEF      # base 16 
0o755       # base 8 
:3<1201>    # arbitrary base, here base 3

`Rat` literals§

Rat literals (rationals) are very common, and take the place of decimals or floats in many other languages. Integer division also results in a Rat.

Raku highlighting

1.          # Error: A number must have at least one digit after the radix point 
1.0
3.14159
-2.5        # Not actually a literal, but still a Rat 
:3<21.0012> # Base 3 rational 
⅔
2/3         # Not actually a literal, but still a Rat

`Num` literals§

Scientific notation with an integer exponent to base ten after an e produces a Num (a floating point value):

Raku highlighting

1.e0        # error: A number must have at least one digit after the radix point 
1e0
6.022e23
1e-9
-2e48
2e2.5       # error

`Complex` literals§

Complex numbers are written either as an imaginary number (which is just a rational number with postfix i appended), or as a sum of a real and an imaginary number:

Raku highlighting

1.+2i       # error: A number must have at least one digit after the radix point 
1+2.i       # error: A number must have at least one digit after the radix point 
1+2i
6.123e5i    # note that this is 6.123e5 * i, not 6.123 * 10 ** (5i)

Pair literals §

Pairs are made of a key and a value, and there are two basic forms for constructing them: key => 'value' and :key('value').

Arrow pairs §

Arrow pairs can have an expression, a string literal or a "bare identifier", which is a string with ordinary-identifier syntax that does not need quotes on the left-hand side:

Raku highlighting

like-an-identifier-ain't-it => 42
"key" => 42
('a' ~ 'b') => 1

Adverbial pairs (colon pairs)§

Short forms without explicit values:

Raku highlighting

my $thing = 42;
:$thing                 # same as  thing => $thing 
:thing                  # same as  thing => True 
:!thing                 # same as  thing => False

The variable form also works with other sigils, like :&callback or :@elements. If the value is a number literal, it can also be expressed in this short form:

Raku highlighting

:42thing            # same as  thing => 42 
:٤٢thing            # same as  thing => 42

This order is inverted if you use another alphabet

Raku highlighting

:٤٢ث              # same as   ث => ٤٢

the thaa letter precedes the number.

Long forms with explicit values:

Raku highlighting

:thing($value)              # same as  thing => $value 
:thing<quoted list>         # same as  thing => <quoted list> 
:thing['some', 'values']    # same as  thing => ['some', 'values'] 
:thing{a => 'b'}            # same as  thing => { a => 'b' }

Boolean literals §

True and False are Boolean literals; they will always have initial capital letter.

Array literals §

A pair of square brackets can surround an expression to form an itemized Array literal; typically there is a comma-delimited list inside:

Raku highlighting

say ['a', 'b', 42].join(' ');   # OUTPUT: «a b 42␤» 
#   ^^^^^^^^^^^^^^ Array constructor

If the constructor is given a single Iterable, it'll clone and flatten it. If you want an Array with just 1 element that is an Iterable, ensure to use a comma after it:

Raku highlighting

my @a = 1, 2;
say [@a].raku;  # OUTPUT: «[1, 2]␤» 
say [@a,].raku; # OUTPUT: «[[1, 2],]␤»

The Array constructor does not flatten other types of contents. Use the Slip prefix operator (|) to flatten the needed items:

Raku highlighting

my @a = 1, 2;
say [@a, 3, 4].raku;  # OUTPUT: «[[1, 2], 3, 4]␤» 
say [|@a, 3, 4].raku; # OUTPUT: «[1, 2, 3, 4]␤»

List type can be explicitly created from an array literal declaration without a coercion from Array, using is trait on declaration.

Raku highlighting

my @a is List = 1, 2; # a List, not an Array 
# wrong: creates an Array of Lists 
my List @a;

Hash literals §

A leading associative sigil and pair of parenthesis %( ) can surround a List of Pairs to form a Hash literal; typically there is a comma-delimited List of Pairs inside. If a non-pair is used, it is assumed to be a key and the next element is the value. Most often this is used with simple arrow pairs.

Raku highlighting

say %( a => 3, b => 23, :foo, :dog<cat>, "french", "fries" );
# OUTPUT: «a => 3, b => 23, dog => cat, foo => True, french => fries␤» 
 
say %(a => 73, foo => "fish").keys.join(" ");   # OUTPUT: «a foo␤» 
#   ^^^^^^^^^^^^^^^^^^^^^^^^^ Hash constructor

When assigning to a %-sigiled variable on the left-hand side, the sigil and parenthesis surrounding the right-hand side Pair are optional.

Raku highlighting

my %ages = fred => 23, jean => 87, ann => 4;

By default, keys in %( ) are forced to strings. To compose a hash with non-string keys, use curly brace delimiters with a colon prefix :{ } :

Raku highlighting

my $when = :{ (now) => "Instant", (DateTime.now) => "DateTime" };

Note that with objects as keys, you cannot access non-string keys as strings:

Raku highlighting

say :{ -1 => 41, 0 => 42, 1 => 43 }<0>;  # OUTPUT: «(Any)␤» 
say :{ -1 => 41, 0 => 42, 1 => 43 }{0};  # OUTPUT: «42␤»

Particular types that implement Associative role, Map (including Hash and Stash subclasses) and QuantHash (and its subclasses), can be explicitly created from a hash literal without a coercion, using is trait on declaration:

Raku highlighting

my %hash;                    # Hash 
my %hash is Hash;            # explicit Hash 
my %map is Map;              # Map 
my %stash is Stash;          # Stash 
 
my %quant-hash is QuantHash; # QuantHash 
 
my %setty is Setty;          # Setty 
my %set is Set;              # Set 
my %set-hash is SetHash;     # SetHash 
 
my %baggy is Baggy;          # Baggy 
my %bag is Bag;              # Bag 
my %bag-hash is BagHash;     # BagHash 
 
my %mixy is Mixy;            # Mixy 
my %mix is Mix;              # Mix 
my %mix-hash is MixHash;     # MixHash

Note that using a usual type declaration with a hash sigil creates a typed Hash, not a particular type:

Raku highlighting

# This is wrong: creates a Hash of Mixes, not Mix: 
my Mix %mix;
# Works with $ sigil: 
my Mix $mix;
# Can be typed: 
my Mix[Int] $mix-of-ints;

Regex literals §

A Regex is declared with slashes like /foo/. Note that this // syntax is shorthand for the full rx// syntax.

Raku highlighting

/foo/          # Short version 
rx/foo/        # Longer version 
Q :regex /foo/ # Even longer version
 
my $r = /foo/; # Regexes can be assigned to variables

Signature literals §

Signatures can be used standalone for pattern matching, in addition to the typical usage in sub and block declarations. A standalone signature is declared starting with a colon:

Raku highlighting

say "match!" if 5, "fish" ~~ :(Int, Str); # OUTPUT: «match!␤» 
 
my $sig = :(Int $a, Str);
say "match!" if (5, "fish") ~~ $sig; # OUTPUT: «match!␤» 
 
given "foo", 42 {
  when :(Str, Str) { "This won't match" }
  when :(Str, Int $n where $n > 20) { "This will!" }
}

See the signatures documentation for more information.

Declarations §

Variable declaration §

Raku highlighting

my $x;                          # simple lexical variable 
my $x = 7;                      # initialize the variable 
my Int $x = 7;                  # declare the type 
my Int:D $x = 7;                # specify that the value must be defined (not undef) 
my Int $x where { $_ > 3 } = 7; # constrain the value based on a function 
my Int $x where * > 3 = 7;      # same constraint, but using Whatever shorthand

See Variable Declarators and Scope for more details on other scopes (our, has).

Callable declarations §

Raku provides syntax for multiple Callable code objects (that is, code objects that can be invoked, such as subroutines). Specifically, Raku provides syntax for subroutines (both single- and multiple-dispatch), code blocks, and methods (again, both single- and multiple-dispatch).

Subroutine declaration §

Subroutines are created with the keyword sub followed by an optional name, an optional signature and a code block. Subroutines are lexically scoped, so if a name is specified at the declaration time, the same name can be used in the lexical scope to invoke the subroutine. A subroutine is an instance of type Sub and can be assigned to any container.

Raku highlighting

sub {}
# The minimal legal subroutine declaration 
 
sub say-hello1 { say "Hello!" }
# A subroutine with a name 
 
sub say-hello2(Str $to-whom) { say "Hello $to-whom!" }
# A subroutine with a name and a signature

You can assign subroutines to variables.

Raku highlighting

my &greet0 = sub { say "Hello!" }            # Unnamed sub assigned to &greet0 
my &greet1 = sub say-hello1 { say "Hello!" } # Named sub assigned to &greet1

Multiple-dispatch subroutine declaration §

Subroutines can be declared as a multi – that is, as a subroutine that with multiple candidates, each with a different signature. A multiple dispatch subroutine is created almost exactly like a single-dispatch subroutine: with the keyword multi, optionally followed by the keyword sub, followed by an optional name, an optional signature, and a code block. See Multi-dispatch for details.

The two single-dispatch subroutines greet0 and greet1 (defined above) could be combined into a single greet multi as follows:

Raku highlighting

multi greet { say "Hello!" }
#     ^^^ optional 
multi greet($name) { say "Hello $name!" }

You may optionally precede multi declarations with a proto declarations; protos declare a signature that any call must conform to before being dispatched to candidates. For example, this proto requires that all candidates take at least one positional parameter:

Raku highlighting

proto at-least1($, |) {*}
multi at-least1($first)          { note $first }
multi at-least1($first, $second) { note "got two" }
multi at-least1($first, :$named) { note "got named" }
 
# The following is legal to *declare* but can never be called 
multi at-least1 { note "Got none"}

Block declaration §

Blocks are invocable code objects similar to subroutines but intended for small-scale code reuse. Blocks are created by a code block inside of { } curly braces, optionally preceded by -> followed by a signature (or <-> followed by a signature for rw (aka, read-write) blocks). If no signature is provided, Blocks can accept parameters implicitly by using placeholder variables with the ^ twigil and the C: twigil|/language/variables#The_:_twigil>. Blocks with neither an explicit nor implicit signature have a default signature of $_.

Raku highlighting

my &greet0 = { say "Hello!" }     # Block stored in &greet0 
my &greet1 = { say "Hello $_!" }  # Block with default signature 
my &greet2 = -> $to-whom { say "Hello $to-whom!" }  # Block with explicit signature 
my &greet3 = { say "Hello $^to-whom!" }             # Block with implicit positional 
my &greet4 = { say "Hello $:to-whom!" }             # Block with implicit named 
 
my &add1-in-place = <-> $a { ++$a }                 # Block with rw signature

Although doing so is less idiomatic, Blocks may also be stored in scalar variables

Raku highlighting

my $greet = { say "Hello!" }

Method declaration §

Methods are a callable code object invoked against a specific object (called the method's "invocant"). Outside of a class declaration, methods are declared by the method keyword, followed by a signature, followed by a code block. Within the method signature, the method's invocant is followed by a : instead of the , that normally separates arguments. Methods declared outside of a class must be stored in a variable to be used.

Raku highlighting

my &m = method ($invocant: $arg1, $arg2) { note }

This syntax is unusual – typically, methods are declared inside a class. In this context, method declaration more closely resembles subroutine declaration: methods are declared by the keyword method followed by a name, followed by an optional signature, followed by a code block. Methods defined inside a class, have that class as their default invocant but can override that default (for example, to constrain the invocant's definiteness).

Raku highlighting

class Greeter {
   method greet($to-whom)           { say "Hello $to-whom!" }
   method defined-greet(Greeter:D:) { say "Hello!" }
}

For more details on methods, see Methods.

Multiple-dispatch method declaration §

Inside of a class, you can declare multiple-dispatch methods with syntax that's very similar to the syntax for multiple-dispatch subroutines. As with multi subroutines, you can also declare a proto for multiple-dispatch methods.

Raku highlighting

class Greeter {
      multi method greet           { say "Hello!" }
      multi method greet($to-whom) { say "Hello $to-whom!" }
 
      proto method at-least1($, |)   {*}
      multi method at-least1($first) { note $first }
      # The following is legal to *declare* but can never be called 
      multi method at-least1         { note "Got none"}
}

Grammar_declaration" data-indexedheader="Syntax;unit">`package`, `module`, `class`, `role`, and `Grammar` declaration§

There are several types of package, each declared with a keyword, a name, some optional traits, and a body of subroutines, methods, or rules.

Raku highlighting

package P { }
 
module M { }
 
class C { }
 
role R { }
 
grammar G { }

Several packages may be declared in a single file. However, you can declare a unit package at the start of the file (preceded only by comments or use statements), and the rest of the file will be taken as being the body of the package. In this case, the curly braces are not required.

Raku highlighting

unit module M;
# ... stuff goes here instead of in {}'s

Invoking code objects §

Raku provides standard syntax for invoking subroutines/blocks and for invoking methods. Additionally, Raku provides alternate syntax to invoke subroutines with method-like syntax and to invoke methods with subroutine-like syntax

Invoking subroutines or blocks §

Lexically declared subroutines and subroutine/blocks assigned to &-sigiled variables can be invoked by their name followed by their arguments (optionally enclosed in (…)). Alternatively, their name may be preceded by the & sigil but, in that case, the (…) surrounding the function's arguments is mandatory but may be preceded by an optional .. (An &-sigiled variable without (…) refers to the function as an object – that is, without invoking it). Thus, all of the following call the function foo with no arguments:

Raku highlighting

foo;
foo();
&foo();
&foo.();

If a subroutine or block is assigned to a $-sigiled variable, then it can only be invoked using parentheses:

Raku highlighting

my $foo = sub { note }
$foo();
$foo.();

For more information on invoking subroutines/blocks, see functions.

Invoking methods §

A method defined in a class is invoked on an instance of that class by referring to the class followed by a . followed by the method name. Invoking the method without arguments doesn't require parentheses. To supply arguments, you must either surround them in (…) or follow the method name with a :. The following code shows the syntax described above:

Raku highlighting

class Person {
    has $.age = 0;
    has Str $.name = "Anon";
 
    multi method greet        { say "Hello, $.name()!" }
    multi method greet($name) { say "Hello, $name!" }
};
my $person = Person.new(:name<Jane>, :age(98));
 
$person.greet;   # Calls greet method with 0 args 
$person.greet(); # Calls greet method with 0 args 
$person.greet('Nushi'); # Calls greet method with 1 arg 
$person.greet: 'Nushi'; # Calls greet method with 1 arg

Invoking methods with : (precedence drop)§

Note that the syntax in the final line results in the method treating the remainder of the statement as its argument list. (Or, said differently, it drops the precedence of the method call; for that reason, the : used here is sometimes called the "precedence drop"). The following code illustrates the consequences of that change:

Raku highlighting

    my $band = 'Foo Fighters';
    say $band.substr( 0, 3 ).uc; # OUTPUT: «FOO␤» 
    say $band.substr: 0, 3  .uc; # OUTPUT: «Foo␤»

The final line isn't equivalent to the one above it; instead, it's the same as $band.substr(0, 3.uc – likely not what was intended here. That's because in the second method call the uc method is called on "3" and not to the result of the leftmost substr; in other words, the substr method yields precedence to the uc method.

Invoking methods on the topic §

If a method is called without an invocant (that is, with nothing to the left of the .), then it will use the current topic variable as its invocant. For example:

Raku highlighting

given 'Foo Fighters' {
   say .substr: 0, 3;  # OUTPUT: «Foo␤» 
}

Method-like function calls & function-like method calls §

Subroutines can be invoked with method-like syntax – that is, you can call a function on an object followed by a dot in much the same way that you can call a method (including by optionally using a :). The only limitation is that you must precede the function name with an &. For example:

Raku highlighting

sub greet($name, :$excited = True) {
    say "Hello $name" ~ ($excited ?? '!' !! '.')
}
greet "Maria";    # OUTPUT: «Hello Maria!␤» 
"Maria".&greet;   # OUTPUT: «Hello Maria!␤» 
"Maria".&greet(); # OUTPUT: «Hello Maria!␤» 
given "Maria" { .&greet } # OUTPUT: «Hello Maria!␤» 
 
"Maria".&greet(:!excited); # OUTPUT: «Hello Maria.␤» 
"Maria".&greet: :!excited; # OUTPUT: «Hello Maria.␤»

Similarly, methods may be invoked with function-like syntax – that is, you can call a method by providing the method name first followed by the method's arguments (including its invocant). To do so, simply supply the invocant as the first argument followed by a :.

Raku highlighting

class Person {
    has Str $.name;
 
    multi method greet        { say "Hello, $.name()!" }
    multi method greet($name) { say "Hello, $name!" }
};
my $person = Person.new(:name<Ruòxī>, :age(11));
 
greet $person:;         # same as $person.greet; 
greet Person: 'Yasmin'; # same as Person.greet('Yasmin');

Due to the presence of method-like function syntax and function-like method syntax, it is especially important to be clear on whether a given syntactic form calls a method or a subroutine. This detail can be easy to neglect, especially because in many cases Raku provides a method and a subroutine of the same name.

For instance, the following simple example produces the same output for both function and method calls.

Raku highlighting

say 42;  # Subroutine call 
42.&say; # Still a subroutine call 
42.say;  # Method call 
say 42:; # Also a method call

However, even when both a subroutine and a method exist, calling the correct one can make a large difference. To see this in action, consider map, which exists as both a subroutine and a method but where the method expects its arguments in a different order:

Raku highlighting

my @list = 1..9;
sub add1($a) { $a + 1 }
 
map &add1, @list; # Sub call; expects list last 
map @list: &add1; # Method call; expects function last 
 
@list.map(&add1);  # Method call; expects function last 
&add1.&map(@list); # Sub call; expects list last

Operators §

See Operators for lots of details.

Operators are functions with a more symbol heavy and composable syntax. Like other functions, operators can be multi-dispatch to allow for context-specific usage.

There are five types (arrangements) for operators, each taking either one or two arguments.

Raku highlighting

++$x           # prefix, operator comes before single input 
5 + 3          # infix, operator is between two inputs 
$x++           # postfix, operator is after single input 
<the blue sky> # circumfix, operator surrounds single input 
%foo<bar>      # postcircumfix, operator comes after first input and surrounds second

Metaoperators §

Operators can be composed. A common example of this is combining an infix (binary) operator with assignment. You can combine assignment with any binary operator.

Raku highlighting

$x += 5     # Adds 5 to $x, same as $x = $x + 5 
$x min= 3   # Sets $x to the smaller of $x and 3, same as $x = $x min 3 
$x .= child # Equivalent to $x = $x.child

Wrap an infix operator in [ ] to create a new reduction operator that works on a single list of inputs, resulting in a single value.

Raku highlighting

say [+] <1 2 3 4 5>;    # OUTPUT: «15␤» 
(((1 + 2) + 3) + 4) + 5 # equivalent expanded version

Wrap an infix operator in « » (or the ASCII equivalent << >>) to create a new hyper operator that works pairwise on two lists.

Raku highlighting

say <1 2 3> «+» <4 5 6> # OUTPUT: «(5 7 9)␤»

The direction of the arrows indicates what to do when the lists are not the same size.

Raku highlighting

@a «+« @b # Result is the size of @b, elements from @a will be re-used 
@a »+» @b # Result is the size of @a, elements from @b will be re-used 
@a «+» @b # Result is the size of the biggest input, the smaller one is re-used 
@a »+« @b # Exception if @a and @b are different sizes

You can also wrap a unary operator with a hyper operator.

Raku highlighting

say -« <1 2 3> # OUTPUT: «(-1 -2 -3)␤»

1 [↑] Starting with Raku language version 6.d, colon pairs with sym as the key (e.g. :sym<foo>) are reserved for possible future use.

Int literals§

Rat literals§

Num literals§

Complex literals§

Grammar_declaration" data-indexedheader="Syntax;unit">package, module, class, role, and Grammar declaration§

`Int` literals§

`Rat` literals§

`Num` literals§

`Complex` literals§

Grammar_declaration" data-indexedheader="Syntax;unit">`package`, `module`, `class`, `role`, and `Grammar` declaration§