Modules

How to create, use, and distribute Raku modules

Creating and using modules

A module is usually a source file or set of source files that expose Raku constructs [1].

Modules are typically packages (classes, roles, grammars), subroutines, and sometimes variables. In Raku module can also refer to a type of package declared with the module keyword (see Module Packages and the examples below) but here we mostly mean "module" as a set of source files in a namespace.

Looking for and installing modules.

zef is the application used for installing modules in Raku. Modules are listed in the Raku ecosystem and can be searched there or from the command line using zef search:

zef search WWW

will return a list of modules that includes WWW in their name, for instance. Then,

zef install WWW

will install the module with that particular name, if it is not already installed [2].

Basic structure

Module distributions (in the set of related source files sense) in Raku have the same structure as any distribution in the Perl family of languages: there is a main project directory containing a README and a LICENSE file, a lib directory for the source files, which may be individually referred to as modules and/or may themselves define modules with the module keyword [3] , a t directory for tests, and possibly a bin directory for executable programs and scripts.

Source files generally use the .rakumod extension, and scripts or executables use the .raku. Test files use the .rakutest (or .t) extension. Files which contain documentation use the .rakudoc extension [4].

Loading and basic importing

Loading a module makes the packages in the same namespace declared within available in the file scope of the loader. Importing from a module makes the symbols exported available in the lexical scope of the importing statement.

need

need loads a compunit at compile time.

need MyModule;

Any packages in the namespace defined within will also be available.

# MyModule.rakumod 
unit module MyModule;
 
class Class {}

MyModule::Class will be defined when MyModule is loaded, and you can use it directly employing its fully qualified name (FQN). Classes and other types defined that way are not automatically exported; you will need to explicitly export it if you want to use it by its short name:

# MyModule.rakumod 
unit module MyModule;
 
class Class is export {}

And then

use MyModule;
 
my $class = Class.new();
say $class.raku;

use

use loads and then imports from a compunit at compile time. It will look for files that end in .rakumod. See here for where the runtime will look for modules.

use MyModule;

This is equivalent to:

need MyModule;
import MyModule;

See also selective importing to restrict what you import.

require

require loads a compunit and imports definite symbols at runtime.

say "loading MyModule";
require MyModule;

The compunit name can be in a runtime variable if you put it inside an indirect lookup.

my $name = 'MyModule';
require ::($name);

The symbols provided by the loaded module will not be imported into the current scope. You may use dynamic lookup or dynamic subsets to use them by providing the fully qualified name of a symbol, for instance:

require ::("Test");
my &mmk = ::("Test::EXPORT::DEFAULT::&ok");
mmk('oi‽'); # OUTPUT: «ok 1 - ␤»

The FQN of ok is Test::EXPORT::DEFAULT::&ok. We are aliasing it to mmk so that we can use that symbol provided by Test in the current scope.

To import symbols you must define them at compile time. NOTE: require is lexically scoped:

sub do-something {
   require MyModule <&something>;
   say ::('MyModule'); # MyModule symbol exists here 
   something() # &something will be defined here 
}
say ::('MyModule'); # This will NOT contain the MyModule symbol 
do-something();
# &something will not be defined here

If MyModule doesn't export &something then require will fail.

A require with compile-time symbol will install a placeholder package that will be updated to the loaded module, class, or package. Note that the placeholder will be kept, even if require failed to load the module. This means that checking if a module loaded like this is wrong:

# *** WRONG: *** 
try require Foo;
if ::('Foo') ~~ Failure { say "Failed to load Foo!"; }
# *** WRONG: ***

As the compile-time installed package causes ::('Foo') to never be a Failure. The correct way is:

# Use return value to test whether loading succeeded: 
(try require Foo) === Nil and say "Failed to load Foo!";
 
# Or use a runtime symbol lookup with require, to avoid compile-time 
# package installation: 
try require ::('Foo');
if ::('Foo') ~~ Failure {
    say "Failed to load Foo!";
}

In the current (6.d) version of the language, required symbols are no longer transitively exposed, which means that you need to import symbols from the module they were originally declared, not from the module where they have been imported.

Lexical module loading

Raku takes great care to avoid global state, i.e. whatever you do in your module, it should not affect other code. For instance, that's why subroutine definitions are lexically (my) scoped by default. If you want others to see them, you need to explicitly make them our scoped or export them.

Classes are exported by default on the assumption that loading a module will not be of much use when you cannot access the classes it contains. Loaded classes are thus registered only in the scope which loaded them in the first place [5]. This means that we will have to use a class in every scope in which we actually employ it.

use Foo;           # Foo has "use Bar" somewhere. 
use Bar;
my $foo = Foo.new;
my $bar = Bar.new;

Exporting and selective importing

is export

Packages, subroutines, variables, constants, and enums are exported by marking them with the is export trait (also note the tags available for indicating authors and versions).

unit module MyModule:ver<1.0.3>:auth<John Hancock (jhancock@example.com)>;
our $var is export = 3;
sub foo is export { ... };
constant FOO is export = "foobar";
enum FooBar is export <one two three>;
 
# for multi methods, if you declare a proto you 
# only need to mark the proto with is export 
proto sub quux(Str $x, |) is export { * };
multi sub quux(Str $x) { ... };
multi sub quux(Str $x, $y) { ... };
 
# for multi methods, you only need to mark one with is export 
# but the code is most consistent if all are marked 
multi sub quux(Str $x) is export { ... };
multi sub quux(Str $x, $y) is export { ... };
 
# Packages like classes can be exported too 
class MyClass is export {};
 
# If a subpackage is in the namespace of the current package 
# it doesn't need to be explicitly exported 
class MyModule::MyClass {};

As with all traits, if applied to a routine, is export should appear after any argument list.

sub foo(Str $string) is export { ... }

You can pass named parameters to is export to group symbols for exporting so that the importer can pick and choose. There are three predefined tags: ALL, DEFAULT and MANDATORY.

# lib/MyModule.rakumod 
unit module MyModule;
sub bag        is export             { ... }
# objects with tag ':MANDATORY' are always exported 
sub pants      is export(:MANDATORY) { ... }
sub sunglasses is export(:day)       { ... }
sub torch      is export(:night)     { ... }
sub underpants is export(:ALL)       { ... }
# main.raku 
use lib 'lib';
use MyModule;          # bag, pants 
use MyModule :DEFAULT; # the same 
use MyModule :day;     # pants, sunglasses 
use MyModule :night;   # pants, torch 
use MyModule :ALL;     # bag, pants, sunglasses, torch, underpants 

Note: there currently is no way for the user to import a single object if the module author hasn't made provision for that, and it is not an easy task at the moment (see RT #127305). One way the author can provide such access is to give each export trait its own unique tag. (And the tag can be the object name!). Then the user can either (1) import all objects:

use Foo :ALL;

or (2) import one or more objects selectively:

use Foo :bar, :s5;

Notes:

1. The :MANDATORY tag on an exported sub ensures it will be exported no matter whether the using program adds any tag or not.

2. All exported subs without an explicit tag are implicitly :DEFAULT.

3. The space after the module name and before the tag is mandatory.

4. Multiple import tags may be used (separated by commas). For example:

# main.raku 
use lib 'lib';
use MyModule :day, :night; # pants, sunglasses, torch 

5. Multiple tags may be used in the export trait, but they must all be separated by either commas, or whitespace, but not both.

sub foo() is export(:foo :s2 :net) {}
sub bar() is export(:bar, :s3, :some) {}

UNIT::EXPORT::*

Beneath the surface, is export is adding the symbols to a UNIT scoped package in the EXPORT namespace. For example, is export(:FOO) will add the target to the UNIT::EXPORT::FOO package. This is what Raku is really using to decide what to import.

unit module MyModule;
 
sub foo is export { ... }
sub bar is export(:other) { ... }

Is the same as:

unit module MyModule;
 
my package EXPORT::DEFAULT {
    our sub foo { ... }
}
 
my package EXPORT::other {
    our sub bar { ... }
}

For most purposes, is export is sufficient but the EXPORT packages are useful when you want to produce the exported symbols dynamically. For example:

# lib/MyModule.rakumod 
unit module MyModule;
 
my package EXPORT::DEFAULT {
   for <zero one two three four>.kv -> $number, $name {
      for <sqrt log> -> $func {
         OUR::{'&' ~ $func ~ '-of-' ~ $name } := sub { $number."$func"() };
      }
   }
}
 
# main.raku 
use MyModule;
say sqrt-of-four; # OUTPUT: «2␤» 
say log-of-zero;  # OUTPUT: «-Inf␤» 

EXPORT

You can export arbitrary symbols with an EXPORT sub. EXPORT must return a Map, where the keys are the symbol names and the values are the desired values. The names should include the sigil (if any) for the associated type.

# lib/MyModule.rakumod 
 
class MyModule::Class { }
 
sub EXPORT {
    Map.new:
      '$var'      => 'one',
      '@array'    => <one two three>,
      '%hash'     => %( one => 'two', three => 'four' ),
      '&doit'     => sub { say 'Greetings from exported sub' },
      'ShortName' => MyModule::Class
}

Which is going to be used from this main file:

# main.raku 
use lib 'lib';
use MyModule;
say $var;          # OUTPUT: «one␤» 
say @array;        # OUTPUT: «(one two three)␤» 
say %hash;         # OUTPUT: «{one => two, three => four}␤» 
doit();            # OUTPUT: «Greetings from exported sub␤» 
say ShortName.new; # OUTPUT: «MyModule::Class.new␤» 

Please note that EXPORT can't be declared inside a package because it is part of the compunit rather than the package.

Whereas UNIT::EXPORT packages deal with the named parameters passed to use, the EXPORT sub handles positional parameters. If you pass positional parameters to use, they will be passed to EXPORT. If a positional is passed, the module no longer exports default symbols. You may still import them explicitly by passing :DEFAULT to use along with your positional parameters.

# lib/MyModule 
 
class MyModule::Class {}
 
sub EXPORT($short_name?) {
    Map.new: do $short_name => MyModule::Class if $short_name
}
 
sub always is export(:MANDATORY) { say "works" }
 
#import with :ALL or :DEFAULT to get 
sub shy is export { say "you found me!" }

Used from this main program

# main.raku 
use lib 'lib';
use MyModule 'foo';
say foo.new(); # OUTPUT: «MyModule::Class.new␤» 
 
always();      # OK   - is imported 
shy();         # FAIL - «shy used at line 8. Did you mean 'say'?» 

You can combine EXPORT with type captures for interesting effect. This example creates a ? postfix which will only work on Cools; please note that, by using $_ as an argument, we don't need to use a variable in the routine body and use just .so, acting by default on the topic variable.

# lib/MakeQuestionable.rakumod 
sub EXPORT(::Questionable) {
    my multi postfix:<?>(Questionable $_) { .so };
    Map.new: '&postfix:<?>' => &postfix:<?>,
}

Which is used from here:

use lib 'lib';
use MakeQuestionable Cool;
say ( 0?, 1?, {}?, %( a => "b" )? ).join(' '); # OUTPUT: «False True False True␤» 

Introspection

To list exported symbols of a module first query the export tags supported by the module.

use URI::Escape;
say URI::Escape::EXPORT::.keys;
# OUTPUT: «(DEFAULT ALL)␤»

Then use the tag you like and pick the symbol by its name.

say URI::Escape::EXPORT::DEFAULT::.keys;
# OUTPUT: «(&uri-escape &uri-unescape &uri_escape &uri_unescape)␤» 
my &escape-uri = URI::Escape::EXPORT::DEFAULT::<&uri_escape>;

Be careful not to put sub EXPORT after unit declarator. If you do so, it'll become just a sub inside your package, rather than the special export sub:

unit module Bar;
sub EXPORT { Map.new: Foo => &say } # WRONG!!! Sub is scoped wrong 

As explained in its definition, sub EXPORT is part of the compunit, not the package. So this would be the right way to do it:

sub EXPORT { Map.new: Foo => &say } # RIGHT!!! Sub is outside the module 
unit module Bar;

Finding installed modules

It is up to the module installer to know where compunit expects modules to be placed. There will be a location provided by the distribution and in the current home directory. In any case, letting the module installer deal with your modules is a safe bet.

cd your-module-dir
zef --force install .

A user may have a collection of modules not found in the normal ecosystem, maintained by a module or package manager, but needed regularly. Instead of using the use lib pragma one can use the RAKULIB environment variable to point to module locations. For example:

export RAKULIB=/path/to/my-modules,/path/to/more/modules

Note that the comma (',') is used as the directory separator.

The directories in the RAKULIB path will be searched for modules when Raku needs, uses or requires them. Directories that start with a dot are ignored and symlinks are followed.

Testing modules and a distribution

It is important in this section to repeat the note at the beginning of this document, namely that there is a difference between a Raku distribution, which approximates a module in other languages, and a Raku module declaration. The reason for this is that a single file may contain a number of class, module, role etc declarations, or these declarations may be spread between different files. In addition, when a distribution is published (see Distributing modules) it may be necessary to provide access to other resources, such as callable utilities.

Raku also allows for a single distribution to provide multiple compunits that can be used (or required etc). The information about a distribution is contained in the META6.json file in the distribution's root directory. See below for more about META6.json. Each entity that the distribution allows to be used (or required etc), also called a compunit, is placed in the provides section of the META6.json (as specified below).

It should also be noted that when writing the depends section of the META6.json file, it is the name of the distribution that is listed, not the name of the compunit that is desired. Although, for very many entities, the name of the distribution and the name of the compunit are the same. Another global effect of the depends list in a distribution made available to the Ecosystem, is that package managers, e.g. zef, can look for compunit names in all distributions available.

Given this arrangement, the rakudo compiler, or a package manager such as zef, can obtain all the information needed about each compunit from a META6.json file in a directory.

This also means that a testing program such as Perl's prove or the Raku equivalent prove6 can be run in the root directory of the distribution as, e.g.,

prove -e 'raku -I.'

or

prove6 -I.

In both cases, the testing program looks for a directory t/ and runs the test programs there (see Testing).

The parameter -I., rather than -Ilib, in the examples above is significant because then the compiler will inspect the META6.json file in the root directory of the distribution.

If you are just beginning to develop a module (or series of modules), and you have not decided what to call or where to place the code (perhaps splitting it into several *.rakumod files), but assuming all the module files are under the lib/ directory, then it is possible to use

prove6 -Ilib

This is deceptive. A distribution may pass all the tests based on local files, and it may pass release steps, but the distribution (and the modules/classes/roles it contains) may not be automatically installed. To give a common example, but not the only way this problem can manifest itself, if the distribution is listed in the depends section of another distribution, and a user is trying to install the other distribution using zef (or a package manager using the same testing regime), perhaps using a CLI command zef install --deps-only ., then zef arranges for the tests of the dependent modules based on -I. and not -Ilib. This will lead to rakudo errors complaining about the absence of named compunits unless the META6.json file is correct.

The most basic test that should be run for each compunit that is defined for the distribution is

use-ok 'MyModule';

assuming inside META6.json there is a line such as

provides: { "MyModule": "lib/MyModule.rakumod" },

It is also highly recommended to use the Test::META meta-ok test, which verifies the validity of the META6.json file. If you wish to add a distribution (module) to the Ecosystem, then this test will be applied to the distribution.

Since meta-ok only needs to be tested by the developer/maintainer of a module, it can be within a set of extended tests in another directory, e.g. /xt. This is because prove6, for example, only runs the tests in t/ by default. Then to run the extended tests:

prove6 -I. xt/

Indeed it is becoming common practice by Raku community developers to place the extensive testing of a distribution in xt/ and to put minimal sanity tests in t/. Extensive testing is essential for development and quality control, but it can slow down the installation of popular distributions.

An alternative to placing the meta-ok test in an extended test directory, but to ensure that it is only run when a developer or maintainer wants to, is to make the test dependent on an environment variable, e.g., in t/99-author-test.t there is the following code

use Test;
 
plan 1;
 
if ?%*ENV<AUTHOR_TESTING> {
    require Test::META <&meta-ok>;
    meta-ok;
    done-testing;
} else {
    skip-rest "Skipping author test";
    exit;
}

Then when testing the module by the developer, use

    AUTHOR_TEST=1 prove6 -I.

Distributing modules

If you've written a Raku module and would like to share it with the community, we'd be delighted to have it listed in the Raku modules directory. :)

Currently, there are three ways to distribute a module. No matter which method you choose, your module will be indexed on the raku.land and modules.raku.org websites. The three module distribution networks, or ecosystems, are:

The process of sharing your module consists of two steps, preparing the module and uploading the module to one of the ecosystems mentioned above. More details on the two steps are below.

Preparing the module

For a module to work in any of the ecosystems, it needs to follow a certain structure. Here is how to do that:

Upload your module to CPAN

A prerequisite for using CPAN is a PAUSE user account. If you don't have an account already, you can create one here The process takes about 5 minutes and some e-mail back and forth.

Upload your module to zef ecosystem

If you want to use the zef ecosystem then you need to register your username using fez.

zef install fez
fez register
>>= Email: your@email.com
>>= Username: username
>>= Password:
>>= registration successful, requesting auth key
>>= login successful, you can now upload dists

Before doing the following, ensure your META6.json file's "auth" matches "zef:<username>" and then:

fez upload
>>= Vortex::TotalPerspective:ver<0.1.2>:auth<zef:username> looks OK
>>= Hey! You did it! Your dist will be indexed shortly

Upload your module to p6c

If you want to use the p6c ecosystem you need to use git for your module's version control. The instructions herein assume that you have a GitHub account so that your module can be shared from its GitHub repository, however another provider such as GitLab should work as long as it works in a similar way.

That's it! Thanks for contributing to the Raku community!

If you'd like to try out installing your module, use the zef module installer tool which is included with Rakudo Star Raku:

zef install Vortex::TotalPerspective

This will download your module to its own working directory (~/.zef), build it there, and install the module into your local Raku installation directory.

To use Vortex::TotalPerspective from your scripts, just write use Vortex::TotalPerspective, and your Raku implementation will know where to look for the module file(s).

Modules and tools related to module authoring

You can find a list of modules and tools that aim to improve the experience of writing/test modules at Modules Extra

Contact information

To discuss module development in general, or if your module would fill a need in the ecosystem, naming, etc., you can use the raku on irc.libera.chat IRC channel.

To discuss toolchain specific questions, you can use the raku-toolchain on irc.libera.chat IRC channel. A repository to discuss tooling issues is also available at https://github.com/Raku/toolchain-bikeshed.