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.

Raku highlighting

need MyModule;

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

Raku highlighting

# 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:

Raku highlighting

# MyModule.rakumod
unit module MyModule;

class Class is export {}

And then

Raku highlighting

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.

Raku highlighting

use MyModule;

This is equivalent to:

Raku highlighting

need MyModule;
import MyModule;

See also selective importing to restrict what you import.

`require`§

require loads a compunit and imports definite symbols at runtime.

Raku highlighting

say "loading MyModule";
require MyModule;

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

Raku highlighting

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:

Raku highlighting

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:

Raku highlighting

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:

Raku highlighting

# *** 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:

Raku highlighting

# 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 ^[1] . This means that we will have to use a class in every scope in which we actually employ it.

Raku highlighting

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

Raku highlighting

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 quux(Str $x, |) is export { * };
multi quux(Str $x) { ... };
multi 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 quux(Str $x) is export { ... };
multi 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.

Raku highlighting

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.

Raku highlighting

# 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)       { ... }

Raku highlighting

# 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:

Raku highlighting

use Foo :ALL;

or (2) import one or more objects selectively:

Raku highlighting

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:

Raku highlighting

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

Raku highlighting

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.

Raku highlighting

unit module MyModule;

sub foo is export { ... }
sub bar is export(:other) { ... }

Is the same as:

Raku highlighting

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:

Raku highlighting

# 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"() };
      }
   }
}

Raku highlighting

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

Raku highlighting

# 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:

Raku highlighting

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

Raku highlighting

# 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

Raku highlighting

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

Raku highlighting

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

Which is used from here:

Raku highlighting

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.

Raku highlighting

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

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

Raku highlighting

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:

Raku highlighting

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:

Raku highlighting

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

1 [↑] This change was introduced in late 2016. If you are using versions older than this, behavior will be different