TITLE

Information about the people working on and using Raku


SUBTITLE

head

"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 (circa 2000)


"I am in favor of this change [a community driven renaming from Perl 6 to Raku], because it reflects an ancient wisdom:
'No one sews a patch of unshrunk cloth on an old garment, for the patch will pull away from
the garment, making the tear worse. Neither do people pour new wine into old wineskins.
If they do, the skins will burst; the wine will run out and the wineskins will be ruined.
No, they pour new wine into new wineskins, and both are preserved.'" - Larry Wall
(L<2019|https://github.com/Raku/problem-solving/pull/89#pullrequestreview-300789072>)


L<IRC|/language/glossary#IRC> communication has played an integral role in the Raku community for more than a decade. There are various channels for Raku-related activities on C<libera.chat>. There are several L<bots|/language/glossary#Bot> to make IRC activity more convenient and fun. You can read about IRC content L<here|https://raku.org/community/irc/> in greater details.


L<The Raku Discord server|https://discord.gg/VzYpdQ6> serves a similar purpose. Thanks to the bridges written by fellow Raku members, it integrates well with the main IRC channels.


L<StackOverflow|https://stackoverflow.com/questions/tagged/raku> is also a great
resource for asking questions and helping others with their Raku problems and
challenges.


More resources can be found in the
L<raku.org community page|https://raku.org/community/>.


Raku is also a common topic at
L<Perl conferences|https://www.perl.org/events.html> and
L<Perl Monger meetings|https://www.pm.org/>.
If you prefer in-person meetings, these are warmly recommended!


L<Camelia|https://raku.org/>, the multi-color butterfly with P 6 in her wings, is the symbol of this diverse and welcoming community.


Elizabeth Mattijsen usually posts in L<the "Rakudo Weekly" blog|https://rakudoweekly.blog/>, a summary of Raku posts, tweets, comments and other interesting tidbits.
If you want a single resource to know what is going on in the Raku community now, this is your best resource.


Historical articles (pre name change) can be found archived on
L<the "Perl 6 Weekly" blog|https://p6weekly.wordpress.com/>.


The Raku community publishes every December an
L<Advent Calendar|https://raku-advent.blog/>, with Raku tutorials every day until
Christmas. Previous calendars (pre name change) are
L<still available|https://perl6advent.wordpress.com/> and relevant.


Organization and assignment of days is done through the different Raku channels and the
L<Raku/advent|https://github.com/Raku/advent> repository. If you want to
participate, its organization starts by the end of October, so check out
the channels above to keep up to date.


comment

root

Valid opening/closing paired delimiters


Brackets


Frequently asked questions about Raku


FAQ


Glossary of Raku terminology


Glossary


An easy-to-use markup language for documenting Raku modules and programs


Pod6


Valid, invalid, and unexpected tables


Pod6 tables


Raku terms


Terms


Writing and running tests in Raku


Testing


Traps to avoid when getting started with Raku


Traps to avoid


para

L<Examples| file:../examples/index.podlite>


L<Download |file:../download/index.podlite>


React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


HEADER

FOOTER

Community


How and when Raku modules are compiled, where they are stored, and how to access them in compiled form.


Programs in Raku, as a member of the Perl language family, tend at the top level to be more at the interpreted
end of the interpreted-compiled spectrum. In this tutorial, an 'interpreted' program means that the source code,
namely the human-readable text such as C<say 'hello world';>, is immediately processed by the C<Raku> program into code
that can be executed by the computer, with any intermediate stages being stored in memory.


A compiled program, by contrast, is one where the human readable source is first processed into machine-executable code
and some form of this code is stored 'on disk'. In order to execute the program, the machine-readable version is loaded
into memory and then run by the computer.


Both compiled and interpreted forms have advantages. Briefly, interpreted programs can be 'whipped up' quickly and
the source changed quickly. Compiled programs can be complex and take a significant time to pre-process into machine-readable
code, but then running them is much faster for a user, who only 'sees' the loading and running time, not the compilation
time.


C<Raku> has both paradigms. At the B<top level> a Raku program is interpreted, but code that is separated out into a
Module will be compiled and the preprocessed version is then loaded when necessary. In practice, Modules that have been
written by the community will only need to be precompiled once by a user when they are 'installed', for example by a
Module manager such as C<zef>. Then they can be C<use>d  by a developer in her own program. The effect is to make C<Raku>
top level programs run quickly.


One of the great strengths of the C<Perl> family of languages was the ability to integrate a whole ecosystem of modules
written by competent programmers into a small program. This strength was widely copied and is now the norm for all
languages. C<Raku> takes integration even further, making it relatively easy for C<Raku> programs to incorporate system
libraries written in other languages into C<Raku> programs, see L<Native Call|/language/nativecall>.


The experience from C<Perl> and other languages is that the distributive nature of Modules generate several practical difficulties:


item

C<Raku> enables all of these possibilities, allowing for multiple versions, multiple authorities, and multiple APIs to be present,
installed, and available locally. The way classes and modules can be accessed with specific attributes
is explained L<elsewhere|/language/typesystem#Versioning,_authorship,_and_API_version.>. This tutorial is about how C<Raku> handles these
possibilities.


Before considering the C<Raku> framework, let's have a look at how languages like C<Perl> or C<Python> handle module
installation and loading.


code

=begin code :lang<text>
ACME::Foo::Bar -> ACME/Foo/Bar.pm
os.path -> os/path.py
=end code


In those languages, module names have a 1:1 relation with filesystem paths.
We simply replace the double colons or periods with slashes and add a C<.pm> or C<.py>.


Note that these are relative paths.
Both C<Python> and C<Perl> use a list of include paths, to complete these paths.
In C<Perl> they are available in the global C<@INC> array.


=begin code :lang<text>
@INC

/usr/lib/perl5/site_perl/5.22.1/x86_64-linux-thread-multi
/usr/lib/perl5/site_perl/5.22.1/
/usr/lib/perl5/vendor_perl/5.22.1/x86_64-linux-thread-multi
/usr/lib/perl5/vendor_perl/5.22.1/
/usr/lib/perl5/5.22.1/x86_64-linux-thread-multi
/usr/lib/perl5/5.22.1/
=end code


Each of these include directories is checked for whether it contains a relative path determined from the module name.
If the shoe fits, the file is loaded.


Of course that's a bit of a simplified version.
Both languages support caching compiled versions of modules.
So instead of just the C<.pm> file C<Perl> first looks for a C<.pmc> file.
And C<Python> first looks for C<.pyc> files.


Module installation in both cases means mostly copying files into locations determined by the same simple mapping. The
system is easy to explain, easy to understand, simple and robust.


Why would C<Raku> need another framework? The reason is there are features that those languages lack, namely:


The set of 26 Latin characters is too restrictive for virtually all real modern languages, including English, which
have diacritics for many commonly-used words.


With a 1:1 relation between module names and filesystem paths, you enter a world of pain
once you try to support Unicode on multiple platforms and filesystems.


Then there's sharing module names between multiple authors. This one may or may not work out well in practice.
I can imagine using it for example for publishing a module with some fix until the original author includes
the fix in the "official" version.


Finally there's multiple versions. Usually people who need certain versions of modules reach for local::lib or
containers or some home grown workarounds. They all have their own disadvantages. None of them would be necessary
if applications could just say, hey I need good old, trusty version 2.9 or maybe a bug fix release of that branch.


If you had any hopes of continuing using the simple name mapping solution, you probably gave up at the
versioning requirement. Because, how would you find version 3.2 of a module when looking for a 2.9 or higher?


Popular ideas included collecting information about installed modules in JSON files but when those turned out to be
toe-nail growing slow, text files were replace by putting the metadata into SQLite databases.
However, these ideas can be easily shot down by introducing another requirement: distribution packages.


Packages for Linux distributions are mostly just archives containing some files plus some metadata.
Ideally the process of installing such a package means just unpacking the files and updating the central package database.
Uninstalling means deleting the files installed this way and again updating the package database.
Changing existing files on install and uninstall makes packagers' lives much harder, so we really want to avoid that.
Also the names of the installed files may not depend on what was previously installed.
We must know at the time of packaging what the names are going to be.


=begin code :lang<text>
Foo::Bar:auth<cpan:nine>:ver<0.3>:api<1>
=end code


Step 0 in getting us back out of this mess is to define a long name.
A full module name in C<Raku> consists of the short-name, auth, version and API


At the same time, the thing you install is usually not a single module but a distribution which probably contains one or more modules.
Distribution names work just the same way as module names.
Indeed, distributions often will just be called after their main module.
An important property of distributions is that they are immutable.
C«Foo:auth<cpan:nine>:ver<0.3>:api<1>» will always be the name for exactly the same code.


In C<Perl> and C<Python> you deal with include paths pointing to filesystem directories.
In C<Raku> we call such directories "repositories" and each of these repositories is governed by an object that does the
L<C<CompUnit::Repository>|/type/CompUnit::Repository> role.
Instead of an B<C<@INC>> array, there's the C<$*REPO> variable.
It contains a single repository object.
This object has a B<next-repo> attribute that may contain another repository.
In other words: repositories are managed as a I<linked list>.
The important difference to the traditional array is, that when going through the list, each object has a say in whether
to pass along a request to the next-repo or not.
C<Raku> sets up a standard set of repositories, "core", "vendor", and "site".
In addition, there is a "home" repository for the current user.


Repositories must implement the C<need> method.
A C<use> or C<require> statement in C<Raku> code is basically translated to a call to B<C<$*REPO>>'s C<need> method.
This method may in turn delegate the request to the next-repo.


=begin code :preamble<class CompUnit::Store {};> :method
role CompUnit::Repository {
    has CompUnit::Repository $.next-repo is rw;

    method need(CompUnit::DependencySpecification $spec,
                CompUnit::PrecompilationRepository $precomp,
                CompUnit::Store :@precomp-stores
                --> CompUnit:D
                )
        { ... }
    method loaded(
                --> Iterable
                )
        { ... }

    method id( --> Str )
        { ... }
}
=end code


Rakudo comes with several classes that can be used for repositories.
The most important ones are L<C<CompUnit::Repository::FileSystem>|/type/CompUnit::Repository::FileSystem> and L<C<CompUnit::Repository::Installation>|/type/CompUnit::Repository::Installation>.
The FileSystem repo is meant to be used during module development and actually works just like C<Perl> when
looking for a module.
It doesn't support versions or C<auth>s and simply maps the short-name to a filesystem path.


The Installation repository is where the real smarts are. When requesting a module, you will usually either do it
via its exact long name, or you say something along the lines of "give me a module that matches this filter."
Such a filter is given by way of a C<CompUnit::DependencySpecification> object which has fields for


When looking through candidates, the Installation repository will smartmatch a module's long name against this
DependencySpecification or rather the individual fields against the individual matchers.
Thus a matcher may be some concrete value, a version range, or even a regex (though an arbitrary regex, such as C<.*>,
would not produce a useful result, but something like C<3.20.1+> will only find candidates higher than 3.20.1).


Loading the metadata of all installed distributions would be prohibitively slow. The current implementation of
the C<Raku> framework uses
the filesystem as a kind of database. However, another implementation may use another strategy. The following description
shows how one implementation works and is included here to illustrate what is happening.


We store not only a distribution's files but also create indices for speeding up lookups.
One of these indices comes in the form of directories named after the short-name of installed modules.
However most of the filesystems in common use today cannot handle Unicode names, so we cannot just use
module names directly.
This is where the now infamous SHA-1 hashes enter the game.
The directory names are the ASCII encoded SHA-1 hashes of the UTF-8 encoded module short-names.


In these directories we find one file per distribution that contains a module with a matching short name.
These files again contain the ID of the dist and the other fields that make up the long name: auth, version, and api.
So by reading these files we have a usually short list of auth-version-api triplets which we can match against our
DependencySpecification.
We end up with the winning distribution's ID, which we use to look up the metadata, stored in a JSON encoded file.
This metadata contains the name of the file in the sources/ directory containing the requested module's code.
This is what we can load.


Finding names for source files is again a bit tricky, as there's still the Unicode issue and in addition the same
relative file names may be used by different installed distributions (think versions).
So for now at least, we use SHA-1 hashes of the long-names.


It's not only source files that are stored and found this way.
Distributions may also contain arbitrary resource files.
These could be images, language files or shared libraries that are compiled on installation.
They can be accessed from within the module through the C<%?RESOURCES> hash.


As long as you stick to the standard layout conventions for distributions, this even works during development
without installing anything.


A nice result of this architecture is that it's fairly easy to create special purpose repositories.


A tutorial about creating and using classes in Raku


Classes and objects


Concurrency and asynchronous programming


Concurrency


Creating your own CLI in Raku


Command line interface


An introduction to grammars


Grammar tutorial


File-related operations


Input/Output


Programs running other programs and communicating with them


Inter-process communication


Functionalities available for visiting all items in a complex data structure


Iterating


Different mathematical paradigms and how they are implemented in this language


Doing math with Raku


Creating module packages for code reuse


Module packages


Core modules that may be useful to module authors


Core modules


What can help you write/test/improve your module(s)


Module development utilities


How to create, use, and distribute Raku modules


Modules


A short tutorial on how to declare operators and create new ones.


Creating operators


Some tips on regexes and grammars


Regexes: best practices and gotchas


Read-eval-print loop


REPL


Input methods for unicode characters in terminals, the shell, and editors


Entering unicode characters


CompUnits and where to find them


X<|Tutorial,OOP>
Raku provides a rich built-in syntax for defining and using classes. It makes writing classes
expressive and short for most cases, but also provides mechanisms to cover
the rare corner cases.


Let's start with an example to give an overview:


=begin code
class Rectangle {
    has Int $.length = 1;
    has Int $.width = 1;

    method area(--> Int) {
        return $!length * $!width;
    }
}

my $r1 = Rectangle.new(length => 2, width => 3);
say $r1.area(); # OUTPUT: «6␤»
=end code


We define a new I<Rectangle> class using the L<class|/language/objects#Classes> keyword. It has two L<attributes|#Attributes>, C<$!length> and C<$!width> introduced
with the L<has|/syntax/has> keyword. Both default to C<1>. Read only accessor methods are automatically generated. (Note the C<.> instead of C<!> in the declaration, which triggers the generation. Mnemonic: C<!> resembles a closed door, C<.> an open one.)


The L<method|/language/objects#Methods> named C<area> will return the area of the rectangle.


It is rarely necessary to explicitly write a constructor. An automatically inherited default constructor called L<new|/language/objects#Object_construction> will automatically initialize attributes from named parameters passed to the constructor.


As a more elaborate example the following piece of code implements a dependency
handler. It showcases custom constructors, private and public attributes,
methods, and various aspects of signatures. It's not a lot of code, and yet the
result is interesting and useful. It will be used as an example throughout the
following sections.


=begin code
class Task {
    has      &!callback     is built;
    has Task @!dependencies is built;
    has Bool $.done;

    method new(&callback, *@dependencies) {
        return self.bless(:&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();
=end code


Raku, like many other languages, uses the C<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 C<has> keyword, and behaviors, introduced through the C<method>
keyword.


X<Attributes|Tutorial,attributes;Tutorial,encapsulation;Tutorial,has>


In the C<Task> class, the first three lines inside the block all
declare attributes (called I<fields> or I<instance storage> in other
languages) using the C<has> declarator. Just as a C<my> variable cannot be
accessed from outside its declared scope, attributes are never directly
accessible from outside of the class (this is in contrast to many other
languages). This I<encapsulation> is one of the key principles of object
oriented design.


X<Twigil C<$!>|Tutorial,twigils;Tutorial,!;Tutorial,&>


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


The C<&> sigil indicates that this attribute represents something invocable.
The C<!> character is a I<twigil>, or secondary sigil. A twigil forms part
of the name of the variable. In this case, the C<!> twigil emphasizes that
this attribute is private to the class. The attribute is I<encapsulated>.
Private attributes will not be set by the default constructor by default, which is
why we add the C<is built> trait to allow just that. Mnemonic: C<!> looks like a closed door.


The second declaration also uses the private twigil:


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


X<|Tutorial,.>
X<|Tutorial,accessors>
X<|Tutorial,accessor methods>


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


This scalar attribute (with the C<$> sigil) has a type of L<C<Bool>|/type/Bool>. Instead
of the C<!> twigil, the C<.> twigil is used. While Raku does enforce
encapsulation on attributes, it also saves you from writing accessor
methods. Replacing the C<!> with a C<.> both declares a private attribute
and an accessor method named after the attribute. In this case,
both the attribute C<$!done> and the accessor method C<done> are declared.
It's as if you had written:


=begin code
has Bool $!done;
method done() { return $!done }
=end code


Note that this is not like declaring a public attribute, as some languages
allow; you really get I<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 returning the value.


Note that using the C<.> 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:


The C<is rw> trait causes the generated accessor method to return a container
so external code can modify the value of the attribute.


X<|Types,traits;Types,is built>
By default private attributes are not automatically set by the default constructor. (They are private after
all.) In the above example we want to allow the user to provide the initial value but keep the attribute
otherwise private. The C<is built> trait allows to do just that.


One can also use it to do the opposite for public attributes, i.e. prevent them to be automatically
initialized with a user provided value, but still generate the accessor method:


Above declaration makes sure one can't construct finished tasks, but still allow users to look if a task is done.


The C<is built> trait was introduced in Rakudo version 2020.01.


X<|Types,traits;Types,is required>
Providing a value for an attribute during initialization is optional by default. Which in the task example
makes sense for all three, the C<&!callback>, the C<@!dependencies> and the C<$.done> attribute. But lets say
we want to add another attribute, C<$.name>, that holds a tasks name and we want to force the user to
provide a value on initialization. We can do that as follows:


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


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


=begin code :preamble<class Task {}>
has Task @!dependencies;
has $.ready = not @!dependencies;
=end code


The Raku Knowledge Base


=begin React :component<HeaderCol> :id<footer>  
=begin nested :!nested
=item1 B<Language>
    =item2 L<Get started|file:../getting-started/getting-started.podlite>
    =item2 L<Why Raku?|/doc/language/faq#Why-should-I-learn-Raku-What's-so-great-about-it>
    =item2 L<Try Raku|https://glot.io/new/raku>
    =item2 L<Raku cheat sheet|https://github.com/Raku/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.txt>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<Raku on Exercism|https://exercism.org/tracks/raku>
    =item2 L<Wikipedia|https://en.wikipedia.org/wiki/Raku_(programming_language)>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=begin nested :!nested

=item1 B<L<Documentation|/doc>>
    =item2 L<Getting started, Migration guides from other languages, & Tutorials | file:../doc/introduction.podlite>
    =item2 L<Language References|file:../doc/reference.podlite>
    =item2 L<Type Reference| file:../doc/types.podlite>
    =item2 L<Miscellaneous| file:../doc/miscellaneous.podlite>
    =item2 L<FAQs (Frequently Asked Questions)|/doc/language/faq>
    =item2 L<Community|/doc/language/community>
    =item2 L<The list of all documents|file:../doc/index.podlite>

=item1 B<Resources>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>

=end nested
=begin nested :!nested

=item1 B<Resoures>
    =item2 L<Download | file:../download/index.podlite>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=item1 B<Learning>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Wikibook |https://en.wikibooks.org/wiki/Raku_Programming>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>
    =item2 L<Learn Raku in Y minutes|https://learnxinyminutes.com/docs/raku/>
    =item2 L<Golfing |https://github.com/AlexDaniel/raku-golf-cheatsheet>
=end nested
=begin nested :!nested

=item1 B<Explore>
    =item2 L<Raku Blog Aggregator|https://planet.raku.org/>
    =item2 L<Rakudo Weekly|https://rakudoweekly.blog/>
    =item2 L<The Weekly Challenge |https://perlweeklychallenge.org/>
    =item2 L<Raku Advent Calendar|https://raku-advent.blog/>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=end React


=begin React :component<CookieConsent> :id<CookieConsent> :buttonCaption("Got it!")
=para
This website uses cookies for analytics.
=end React


Community

Overview

The Raku community

Online communities

Offline communities

Other resources

Rakudo Weekly

Raku Advent calendar

See Also