Raku Guide

Raku is a high-level, general-purpose, gradually typed language. Raku is multi-paradigmatic. It supports Procedural, Object Oriented, and Functional programming.

https://rakubrew.org is a platform independent environment manager (think pyenv for Raku)

To install Rakudo Star, run the following commands from your terminal:

For other Unix options, go to https://rakudo.org/star/source

Four options are available:

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 uses frequently 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 table lists the most commonly used operators.

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.

Some of the methods that can be called on hashes are:

.push: (key => 'Value') adds a new key/value pair.
.kv returns a list containing all keys and values.
.keys returns a list that contains all keys.
.values returns a list that contains all values.
We can access a specific value in the hash by specifying its key %hash<key>

In the previous examples, we did not specify what type of values the variables should hold.

As you can see in the above example, the type of value in $var was once (Str) and then (Int).

This style of programming is called dynamic typing. Dynamic in the sense that variables may contain values of Any type.

Now try running the below example:
Notice Int before the variable name.

It will fail and return this error message: Type check failed in assignment to $var; expected Int but got Str

What happened is that we specified beforehand that the variable should be of type (Int). When we tried to assign an (Str) to it, it failed.

This style of programming is called static typing. Static in the sense that variable types are defined before assignment and cannot change.

Raku is classified as gradually typed; it allows both static and dynamic typing.

You will most probably never use the first two but they are listed for informational purpose.

Introspection is the process of getting information about an object properties like its type.
In one of the previous example 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.

Several declarators are used in Raku. We’ve been using my, so far.

The my declarator give the variable lexical scope. In other words, the variable will only be accessible in the same block it was declared.

A block in Raku is delimited by { }. If no block is found, the variable will be available in the whole Raku script.

Since a variable is only accessible in the block where it is defined, the same variable name can be used in another block.

We’ve seen in the previous examples, how to assign values to variables.
Assignment is done using the = operator.

We can change the value assigned to a variable:

On the other hand, we cannot change the value bound to a variable.
Binding is done using the := operator.

Binding variables is bi-directional.
$a := $b and $b := $a have the same effect.

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.

Notice that we created an iteration variable $array-item and then performed the operation *100 on each array item.

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.

Raku belongs to the C-family languages.

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.

Raku can list the contents of a directory without resorting to shell commands (by using ls, for example).

In addition, you can create and delete directories.

mkdir creates a new directory.
rmdir deletes an empty directory and returns an error if not empty.

You can also check if a path exists; if it is a file; or a directory:

In the directory where you will be running the below script, create an empty folder folder123 and an empty raku file script123.raku

IO.e checks if the directory/file exists.
IO.f checks if the path is a file.
IO.d checks if the path is a directory.

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:

Optional parameters are defined by appending ? to the parameter name.

If the user doesn’t need to supply an argument, a default value can be defined.
This is done by assigning a value to the parameter within the subroutine definition.

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.

If a function is allowed to run through it’s block to the end, the last statement or expression will determine the return value.

For the sake of clarity, it might be a good idea to explicitly specify what we want returned. This can be done using the return keyword.

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

Let’s rewrite the map example and have it use an anonymous function

Notice that instead of declaring the squared subroutine and passing it as an argument to map, we defined it within the anonymous subroutine as -> $x {$x ** 2}.

In Raku parlance, we call this notation a pointy block

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.

Note that the flow of the method calls is top-down — from first to final step.

The backward feed is like the forward feed, but in reverse.
The flow of the method calls is bottom-up — from final to first step.

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 …​
A lazy list has initial element(s), a generator and an endpoint.

The initial element is 1 and the endpoint is 10. No generator was defined so the default generator is the successor (+1)
In other words this lazy list may return (if requested) the following elements (1, 2, 3, 4, 5, 6, 7, 8, 9, 10)

This list may return (if requested) any integer between 1 and infinity, in other words any integer number.

The initial elements are 0 and 2 and the endpoint is 10. No generator was defined, but using the initial elements, Raku will deduce that the generator is (+2)
This lazy list may return (if requested) the following elements (0, 2, 4, 6, 8, 10)

In this example, we defined explicitly a generator enclosed in { }
This lazy list may return (if requested) the following elements (0, 3, 6, 9, 12)

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.

Object Oriented programming is one of the widely used paradigms nowadays.
An object is a set of variables and subroutines bundled together.
The variables are called attributes and the subroutines are called methods.
Attributes define the state and methods define the behavior of an object.

A class is a template for creating objects.

In order to understand the relationship consider the below example:

In object oriented parlance, we say that objects are instances of a class.

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 but it is a good habit to always use the ! twigil.

Therefore, we should rewrite the above class as:

Append to the script the following statement: say $john.age;
It will return this error: Method 'age' not found for invocant of class '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 observe the result of say $john.age;

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.

Class attributes are attributes that belong to the class itself and not to its objects.
They can be initialized during definition.
Class attributes are declared using my instead of has.
They are called on the class itself instead of its objects.

Until now, all the examples that we’ve seen have used accessors to get information from the objects' attributes.

What if we need to modify the value of an attribute?
We need to label it as read/write using the keywords is rw

By default, all attributes are declared as read only but you can explicitly do it using is readonly

Multiple inheritance is allowed in Raku. A class can inherit from multiple other classes.

The combo-chart class should be able to hold two series, one for the actual values plotted on bars, and another for forecast values plotted on a line.
This is why we defined it as a child of line-chart and bar-chart.
You should have noticed that calling the method plot on the combo-chart didn’t yield the required result. Only one series was plotted.
Why did this happen?
combo-chart inherits from line-chart and bar-chart, and both of them have a method called plot. When we call that method on combo-chart Raku internals will try to resolve the conflict by calling one of the inherited methods.

In order to behave correctly, we should have overridden the method plot in the combo-chart.

Roles are similar to classes in that they are a collection of attributes and methods.

Roles are declared with the keyword role. Classes that wish to implement a role, do so using the does keyword.

Run the above script and you will see that results are the same.

By now you’re asking yourself: If roles behave like classes, what’s their use?
To answer your question, modify the first script used to showcase multiple inheritance, the one where we forgot to override the plot method.

If multiple roles are applied to the same class and a conflict exists, a compile-time error will be thrown.
This is a much safer approach than multiple inheritance, where conflicts are not considered errors and are simply resolved at runtime.

Roles will warn you that there’s a conflict.

Introspection is the process of getting information about an object, like its type, attributes or methods.

Introspection is facilitated by:

Exceptions are a special behavior that happens at runtime when something goes wrong.
We say that exceptions are thrown.

Consider the below script that runs correctly:

Now consider this script that throws an exception:

Notice that whenever an error occurs (in this case, assigning a number to a string variable) the program will stop and other lines of code will not be evaluated.

Exception handling is the process of catching an exception that has been thrown in order for the script to continue working.

Exception handling is done by using a try-catch block.

The CATCH block can be defined the same way a given block is defined. This means we can catch and handle differently many types of exceptions.

Raku also allows you to explicitly throw exceptions.
Two types of exceptions can be thrown:

Ad-hoc exceptions are thrown using the die subroutine, followed by the exception message.

Typed exceptions are objects, hence the use of the .new() constructor in the above example.
All typed exceptions descend from class X , below are a few examples:
X::AdHoc is the simplest exception type
X::IO is related to IO errors
X::OS is related to OS errors
X::Str::Numeric related to trying to coerce a string to a number

A regular expression can be defined like this:

Unless specified explicitly, white space is ignored; m/light/ and m/ light / are the same.

Alphanumeric characters and the underscore _ are written as is.
All other characters have to be escaped using a backslash or surrounded by quotes.

Characters can be classified into categories and we can match against them.
We can also match against the inverse of that category (everything except it):

Matching against categories of characters, as seen in the preceding section, is convenient.
That being said, a more systematic approach would be to use Unicode properties.
This allows you to match against categories of characters inside and outside of
the ASCII standard.
Unicode properties are enclosed in <: >

Wildcards can also be used in a regex.

The dot . means any single character.

Quantifiers come after a character and are used to specify how many times we are expecting it.

The question mark ? means zero or one time.

The star * means zero or multiple times.

The + means at least one time.

Whenever the process of matching a string against a regex is successful, the match result is stored in a special variable $/

$/ returns a Match Object (the string that matches the regex)
The following methods can be called on the Match Object:
.prematch returns the string preceding the match.
.postmatch returns the string following the match.
.from returns the starting position of the match.
.to returns the ending position of the match.

Let’s check if an email is valid or not.
For the sake of this example we will assume that a valid email address has this format:
first name [dot] last name [at] company [dot] (com/org/net)

[email protected] is a valid email

<:L> matches a single letter
<:L>` matches one or more letters + `\.` matches a single [dot] character + `\@` matches a single [at] character + `<:L:N> matches a letter or a single number
<:L+:N>+ matches one or more letters or numbers

The regex can be decomposed as following:

A named regex is defined using the following syntax: my regex regex-name { regex definition }
A named regex can be called using the following syntax: <regex-name>

MD5 is a cryptographic hash function that produces a 128-bit hash value.
MD5 has a variety of applications, including the encryption of stored passwords in a database. When a new user registers, their credentials are not stored as plain text but rather hashed. The rationale behind this is that if the DB gets compromised, the attacker will not be able to know what the passwords are.

Luckily, you don’t need to implement the MD5 algorithm yourself; there’s a Raku module already implemented.

Let’s install it:
zef install Digest::MD5

Now, run the below script:

In order to run the md5() function that creates hashes, we need to load the required module.
The use keyword loads the module for use in the script which provides an md5 subroutine.

The above 3 lines showcase different ways of building a character:

The letter á can be written:

NFC returns the unique code point.
NFD decomposes the character and return the code point of each part.
uniname returns the code point name.

Under normal circumstances, all tasks in a program run sequentially.
This might not be a problem, unless what you’re trying to do takes a lot of time.

Thankfully, Raku has features that will enable you to run things in parallel.
At this stage, it is important to note that parallelism can mean one of two things:

Let’s begin with the latter.

Consider the below C code that defines a function called hellofromc. This function prints on the terminal Hello from C. It doesn’t accept any argument nor return any value.

Depending on your OS run the following commands to compile the above C code into a library.

Within the same directory where you compiled your C library, create a new Raku file that contains the below code and run it.

First of all we declared that we will be using the NativeCall module.
Then we created a constant LIBPATH that holds the path to the C library.
Notice that $*CWD returns the current working directory.
Then we created a new Raku subroutine called hellofromc() that should act as a wrapper to its counterpart C function having the same name and residing in the C library found in LIBPATH.
All of this was done by using the is native trait.
Finally we called our Raku subroutine.

In essence, it all boils down to declaring a subroutine with the trait is native and the name of the C library.

In the above part, we saw how we can call a very simple C function by wrapping it with a Raku subroutine having the same name, using the is native trait.

In some cases, we would want to change the name of the Raku subroutine.
To do so, we use the is symbol trait.

Lets modify the above Raku script and rename the Raku subroutine hello instead of hellofromc

In case the Raku subroutine has a different name than its C counterpart, we should use the is symbol trait with the name of the original C function.

Compile the following modified C library and run the Raku script found below again.
Notice how we modified both C and Raku code to accept a string (char* in C and Str in Raku)

Lets repeat the process one more time and create a simple calculator that takes 2 integers and add them.
Compile the C library and run the Raku script.

Notice how both C and Raku functions accept two integers and return one (int in C and int32 in Raku)

You might have asked yourself why did we use int32 instead of Int in the latest Raku script.
Some Raku types like Int, Rat etc. can’t be used as is to pass and receive values from a C function.
One must use in Raku the same types as the ones in C.

Luckily Raku provides many types that map to their respective C counterpart.