Raku Guide

Raku is a high-level, general-purpose, gradually typed language. Raku is multi-paradigmatic. It supports procedural, object oriented, and functional programming.

There are several ways of installing Raku.

Running Raku code can be done using the REPL (Read-Eval-Print Loop). To do this, open a terminal, type raku into the terminal window, and hit [Enter]. This will cause a prompt of > to appear. Next, type a line of code and hit [Enter]. The REPL will print out the value of the line. You may then type another line, or type exit and hit [Enter] to leave the REPL.

Alternatively, write your code in a file, save it and run it. It is recommended that Raku scripts have a .raku file name extension. Run the file by typing raku filename.raku into the terminal window and hitting [Enter]. Unlike the REPL, this will not automatically print the result of each line: the code must contain a statement like say to print output.

The REPL is mostly used for trying a specific piece of code, typically a single line. For programs with more than a single line it is recommended to store them in a file and then run them.

Single lines may also be tried non-interactively on the command-line by typing raku -e 'your code here' and hitting [Enter].

Since most of the time we will be writing and storing our Raku programs in files, we should have a decent text editor that recognizes Raku syntax.

The community frequently uses the following editors:

We shall begin with the hello world ritual.

that can also be written as:

Raku is free form: Most of the time you are free to use any amount of whitespace, although in certain cases whitespace carries meaning.

Statements are typically a single line of code separated with semicolons:

Semicolons are not required after the last statement in a file or block of code, but it’s good practice to include them anyway.

Blocks can contain a collection of statements. Surround statements with curly braces to create a block:

Expressions are a special type of statement that returns a value: 1+2 will return 3

Expressions are made of terms and operators.

Terms are:

Operators are classified into types:

The below tables list the most commonly used operators.

Logical operators combine conditions or choose between two values.

Logical operators are mostly used to combine comparisons:

The defined-or operator // is a convenient way of providing a default value:

Adding R before any operator will have the effect of reversing its operands.

Reduction operators work on lists of values. They are formed by surrounding the operator with brackets []

A scalar holds one value or reference.

A specific set of operations can be performed on a scalar, depending on the value it holds.

Arrays are lists containing multiple values.

Many operations can be performed on arrays as shown in the below example:

.elems returns the number of elements in an array.
.push() adds one or more elements to the array.
We can access a specific element in the array by specifying its position @animals[0].
.pop removes the last element from the array and returns it.
.splice(a, b) will remove b elements starting at position a.

Below are a few more operations that can be performed on arrays:

@animals[*-1] returns the last element of the array.
@animals[0, 1] returns several elements at once. This is called a slice.
.join(', ') returns a single string made of all the elements, separated by a comma and a space.
.unshift() adds one or more elements to the beginning of the array.
.shift removes the first element from the array and returns it.

Introspection is the process of getting information about an object’s properties, like its type.
In one of the previous examples we used .WHAT to return the type of the variable.

The type of a variable holding a value is correlated to its value.
The type of a strongly declared empty variable is the type with which it was declared.
The type of an empty variable that wasn’t strongly declared is (Any)
To clear the value of a variable, assign Nil to it.

Before using a variable for the first time, it needs to be declared.

A string delimited by double quotes replaces the variables it contains with their values.
This is called interpolation.

Interpolation is not limited to variables. Code that is enclosed in curly braces is run, and its result is inserted in the string.

The last string is delimited by single quotes, so nothing is interpolated.

A list of words can be written without quotes and without commas, by enclosing it in angle brackets.

It is a shorter way of writing:

Many methods can be called on a string, as shown in the below example:

.chars returns the number of characters in the string.
.uc and .lc return the string in uppercase and in lowercase.
.flip returns the string reversed.
.contains() checks if the string contains another string.
.starts-with() and .ends-with() check how the string begins and how it ends.
.substr(a, b) returns b characters starting at position a.
.index() returns the position of another string inside the string.
.trim removes the whitespace at the beginning and at the end of the string.

A string can be split into a list, and a list can be joined into a string.

.words splits a string into its words.
.join() joins the elements of a list into a single string, using the given separator.
.split() splits a string wherever the given separator is found.
.comb splits a string into its characters.

sprintf builds a string from a template.
The template contains placeholders that start with %. Each placeholder is replaced by one of the values that follow the template.

%s is replaced by a string.
%d is replaced by an integer.
%.2f is replaced by a number rounded to 2 decimal places.
%05d is replaced by an integer, padded with zeros to a width of 5 digits.

The code runs only if a condition has been met; i.e., an expression evaluates to True.

In Raku, we can invert the code and the condition.
Even if the code and the condition have been inverted, the condition is always evaluated first.

If the condition is not met, we can specify alternate blocks for execution by using:

The negated version of an if statement can be written using unless.

The following code:

can be written as:

Negation in Raku is done using either ! or not.

unless (condition) is used instead of if not (condition).

unless cannot have an else clause.

with behaves like the if statement, but checks if the variable is defined.

If you run the code without assigning a value to the variable, nothing should happen.

without is the negated version of with. You should be able to relate it to unless.

If the first with condition is not met, an alternate path can be specified using orwith.
with and orwith can be compared to if and elsif.

The for loop iterates over multiple values.

given is the Raku equivalent of the switch statement in other languages, but much more powerful.

After a successful match, the matching process will stop.

Alternatively proceed will instruct Raku to continue matching even after a successful match.

loop is another way of writing a for loop.

Actually, loop is how for loops are written in C-family programming languages.

The while loop repeats a block of code as long as a condition is true.

until is the negated version of while. It repeats the block as long as the condition is false.
You should be able to relate it to unless.

The above example can be written as:

next and last give us more control over a loop. They can be used in for, loop, while and until.

next unless $number %% 2 skips the numbers that are not divisible by 2
last if $number > 8 stops the loop as soon as the number is greater than 8, so 10 is never displayed.

Two subroutines can be used to run shell commands:

echo and ls are common shell keywords on Linux:
echo prints text to the terminal (the equivalent of say in Raku)
ls lists all files and folders in the current directory

dir is the equivalent of ls on Windows.

Subroutines (also called subs or functions) are a means of packaging and reusing functionality.

A subroutine definition begins with the keyword sub. After their definition, they can be called by their handle.
Check out the below example:

The previous example showcased a subroutine that doesn’t require any input.

Subroutines can require input. That input is provided by arguments. A subroutine may define zero or more parameters. The number and type of parameters that a subroutine defines is called its signature.

The below subroutine accepts a string argument.

It is possible to define multiple subroutines that have the same name but different signatures. When the subroutine is called, the runtime environment will decide which version to use based on the number and type of supplied arguments. This type of subroutine is defined the same way as normal subs except that we use the multi keyword instead of sub.

If a subroutine is defined to accept an argument, and we call it without providing it with the required argument, it will fail.

Raku provides us the ability to define subroutines with:

The parameters we have used so far are called positional parameters. The arguments are matched to them by position: the first argument goes to the first parameter, the second argument to the second parameter and so on.

A named parameter is matched by its name instead. It is defined by adding a colon : before the parameter.

Since the arguments are matched by name, they can be supplied in any order.

A subroutine can accept any number of arguments by using a slurpy parameter.
A slurpy parameter is an array preceded by an asterisk, like *@names. It collects all the remaining arguments.

We have seen that a parameter can be restricted to a type, like Str $name.
It can be restricted further by adding the keyword where followed by a condition.

The first call succeeds. The second call fails because 15 is an Int but does not meet the condition.

All the subroutines we’ve seen so far do something — they display some text on the terminal.

Sometimes, though, we execute a subroutine for its return value so we can use it later in the flow of our program.

Functions/subroutines are first-class citizens:

A great example is the map function.
map is a higher order function, it can accept another function as an argument.

We defined a subroutine called squared that takes an argument and multiplies that argument by itself.
Next, we used map, a higher order function, and gave it two arguments, the squared subroutine and an array.
The result is a list of the squared elements of the array.

Notice that when passing a subroutine as an argument, we need to prepend & to its name.

An anonymous function is also called a lambda.
An anonymous function is not bound to an identifier (it has no name).

In Raku, methods can be chained, so you’re not required to pass the result of one method to another as an argument.

To illustrate: Given an array, you may need to return the unique values of the array, sorted from biggest to smallest.

Here’s a non-chained solution:

Here, we call unique on @array, pass the result as an argument to sort, and then pass that result to reverse.

In contrast, with chained methods, the above example can be rewritten as:

You can already see that chaining methods is easier on the eye.

The feed operator, called pipe in some functional programming languages, further illustrates method chaining.

The hyper operator >>. will call a method on all elements of a list and return a list of the results.

Using the hyper operator we can call methods already defined in Raku, e.g. is-prime that tells us if a number is prime or not.
In addition we can define new subroutines and call them using the hyper operator. In this case we have to prepend & to the name of the method; e.g., &is-even.

This is very practical as it relieves us from writing a for loop to iterate over each value.

A junction is a logical superposition of values.

In the below example 1|2|3 is a junction.

The use of junctions usually triggers autothreading; the operation is carried out for each junction element, and all the results are combined into a new junction and returned.

A lazy list is a list that is lazily evaluated.
Lazy evaluation delays the evaluation of an expression until required, and avoids repeating evaluations by storing results in a lookup table.

The benefits include:

To build a lazy list we use the infix operator ... called the sequence operator. What it builds is called a sequence.
A sequence has initial element(s), a generator and an endpoint.

All code objects in Raku are closures, which means they can reference lexical variables from an outer scope.

If you run the above code, it will display Good Morning John Doe on the terminal.
While the result is fairly simple, what is interesting about this example, is that the greeting inner subroutine was returned from the outer subroutine before being executed.

$generated has become a closure.

A closure is a special kind of object that combines two things:

The environment consists of any local variable that was in-scope at the time that the closure was created. In this case, $generated is a closure that incorporates both the greeting subroutine and the John Doe string that existed when the closure was created.

Let’s take a look at a more interesting example.

In this example, we have defined a subroutine greeting-generator($period) that accepts a single argument $period and returns a new subroutine. The subroutine it returns accepts a single argument $name and returns the constructed greeting.

Basically, greeting-generator is a subroutine factory. In this example, we used greeting-generator to create two new subroutines, one that says Good Morning and one that says Good Evening.

$morning and $evening are both closures. They share the same subroutine body definition, but store different environments.
In $morning 's environment $period is Morning. In $evening 's environment $period is Evening.

Consider the below script:

The class keyword is used to define a class.
The has keyword is used to define attributes of a class.
The .new() method is called a constructor. It creates the object as an instance of the class it has been called on.

In the above script, a new variable $john holds a reference to a new instance of "Human" defined by Human.new().
The arguments passed to the .new() method are used to set the attributes of the underlying object.

A class can be given lexical scope using my:

Encapsulation is an object oriented concept that bundles a set of data and methods together.
The data (attributes) within an object should be private, in other words, accessible only from within the object.
In order to access the attributes from outside the object, we use methods called accessors.

The below two scripts have the same result.

The method sayvar is an accessor. It lets us access the value of the variable without getting direct access to it.

Encapsulation is facilitated in Raku with the use of twigils.
Twigils are secondary sigils. They come between the sigil and the attribute name.
Two twigils are used in classes:

By default, all attributes are private. The . twigil is what makes an attribute readable from outside the object.

To see the difference, let’s declare the attributes of our class with ! instead of .

Run it and say $john will print Human.new. The object is empty.
The default constructor only sets the attributes that have an accessor, so the values we passed to it were ignored.

Append to the script the following statement: say $john.age;
It will return this error: No such method 'age' for invocant of type 'Human' because $!age is private and can only be used within the object. Trying to access it outside the object will return an error.

Now replace has $!age with has $.age and run the script again.
say $john will print Human.new(age ⇒ 23) and say $john.age will print 23

Private attributes are set and used from within the class. We will see how in the section about methods.

In Raku, all classes inherit a default .new() constructor.
It can be used to create objects by providing it with arguments.
The default constructor can only be provided with named arguments.
In our example above, notice that the arguments supplied to .new() are defined by name:

What if I do not want to supply the name of each attribute each time I want to create an object?
Then I need to create another constructor that accepts positional arguments.

We have seen that a subroutine fails if it is called without one of its arguments.
The default constructor behaves differently. An attribute that is not supplied to .new() is simply left empty.

Like the parameters of a subroutine, an attribute can be given a default value.
This is done by assigning a value to the attribute within the class definition.

If an attribute must always be supplied, we label it using the keywords is required

The nationality of $john was not supplied, so the default value was used.
$nobody could not be created because a name is required.

Methods are the subroutines of an object.
Like subroutines, they are a means of packaging a set of functionality, they accept arguments, have a signature and can be defined as multi.

Methods are defined using the method keyword.
In normal circumstances, methods are required to perform some sort of action on the objects' attributes. This enforces the concept of encapsulation. Object attributes can only be manipulated from within the object using methods. The outside world can only interact with the object methods, and has no direct access to its attributes.