Perl6::Bible::S11(3) User Contributed Perl Documentation Perl6::Bible::S11(3)NAME
Synopsis_11 - Modules
AUTHOR
Larry Wall <larry@wall.org>
VERSION
Maintainer: Larry Wall <larry@wall.org>
Date: 27 Oct 2004
Last Modified: 23 Feb 2006
Number: 11
Version: 9
Overview
This synopsis discusses those portions of Apocalypse 12 that ought to
have been in Apocalypse 11.
Modules
As in Perl 5, a module is just a kind of package. Unlike in Perl 5,
modules and classes are declared with separate keywords, but they're
still just packages with extra behaviors.
A module is declared with the "module" keyword. There are two basic
declaration syntaxes:
module Foo; # rest of scope is in module Foo
...
module Bar {...} # block is in module Bar
The first form is allowed only as the first statement in the file.
A named module declaration can occur as part of an expression, just
like named subroutine declarations.
Since there are no barewords in Perl 6, module names must be
predeclared, or use the sigil-like "::ModuleName" syntax. The "::"
prefix does not imply top-levelness as it does in Perl 5. (Use "::*"
or "GLOBAL::" for that.)
A bare "module" declarator declares an "our" module name in the current
package. At the start of the file, the current package is "*", so the
first declaration in the file is automatically global.
You can use "our module" to explicitly declare a module in the current
package (or module, or class). To declare a lexically scoped module,
use "my module". Module names are always searched for from innermost
scopes to outermost. As with an initial "::", the presence of a "::"
within the name does not imply globalness (unlike in Perl 5).
The "::*" namespace is not "main". The default namespace for the main
program is "::*Main", which it switches to from * as soon as it sees
the first declaration, if that declaration doesn't set the package
name. (Putting "module Main;" at the top of your program is redundant,
except insofar as it tells Perl that the code is Perl 6 code and not
Perl 5 code. But it's better to say "use v6" for that.)
But note that if you say
use v6;
module Foo {...}
you've just created Main::Foo, not *Foo.
Module traits are set using "is":
module Foo is bar {...}
Exportation
Exportation is now done by trait declaration on the exportable item:
module Foo; # Tagset...
sub foo is export(:DEFAULT) {...} # :DEFAULT, :ALL
sub bar is export(:DEFAULT :others) {...} # :DEFAULT, :ALL, :others
sub baz is export(:MANDATORY) {...} # (always exported)
sub bop is export {...} # :ALL
sub qux is export(:others) {...} # :ALL, :others
Declarations marked as "is export" are bound into the "EXPORT" inner
modules, with their tagsets as inner module names within it. For
example, the "sub bar" above will bind as &Foo::EXPORT::DEFAULT::bar,
&Foo::EXPORT::ALL::bar, and &Foo::EXPORT::others::bar.
Inner modules automatically add their export list to modules in all
their outer scopes:
module Foo {
sub foo is export {...}
module Bar {
sub bar is export {...}
module Baz {
sub baz is export {...}
}
}
}
The "Foo" module will export &foo, &bar and &baz by default; calling
"Foo::Bar.import" will import &bar and &baz at runtime.
Compile-time Importation
Importing via "use" binds into the current lexical scope by default
(rather than the current package, as in Perl 5).
use Sense <common @horse>;
You can be explicit about the desired namespace:
use Sense :MY<common> :OUR<@horse> :GLOBAL<$warming>;
That's pretty much equivalent to:
use Sense;
my &common ::= &Sense::common;
our @horse ::= @Sense::horse;
$*warming ::= $Sense::warming;
It is also possible to re-export the imported symbols:
use Sense :EXPORT; # import and re-export the defaults
use Sense <common> :EXPORT; # import "common" and re-export it
use Sense <common> :EXPORT<@horse>; # import "common" but export "@horse"
In the absence of a specific scoping specified by the caller, the
module may also specify a different scoping default by use of ":MY" or
":OUR" tags as arguments to "is export". (Of course, mixing
incompatible scoping in different scopes is likely to lead to
confusion.)
Runtime Importation
Importing via "require" also binds into the current lexical scope by
default, but performs the binding at runtime:
require Sense <common @horse>;
require "/home/non/Sense.pm" <common @horse>;
Tagsets are not recognized in the default import list to ":MY", but you
can explicitly request to put them into the ":OUR" scope:
require Sense <:ALL> # does not work
require Sense :MY<ALL> # this doesn't work either
require Sense :OUR<ALL> # but this works
If the import list is omitted, then nothing is imported. Calling
".import" at runtime cannot import into the lexical scope:
require Sense;
Sense.import; # goes to the OUR scope by default, not MY
Importing from a pseudo-package
You may also import symbols from the various pseudo-packages listed in
S02. They behave as if all their symbols are in the ":ALL" export
list:
use GLOBAL <$IN $OUT $ERR>;
require CALLER <$x $y>;
# Same as:
# my ($IN, $OUT, $ERR) ::= ($*IN, $*OUT, $*ERR)
# my ($x, $y) := ($CALLER::x, $CALLER::y)
As pseudo-packages are always already preloaded, "use" and "require"
will never attempt to load, for example, "GLOBAL.pm" from an external
source.
Versioning
When at the top of a file you say something like
module Cat;
or
class Dog;
you're really only giving one part of the name of the module. The full
name of the module or class includes other metadata, in particular, the
version, and the author.
Modules posted to CPAN or entered into any standard Perl 6 library are
required to declare their full name so that installations can know
where to keep them, such that multiple versions by different authors
can coexist, all of them available to any installed version of Perl.
The syntax of a versioned module or class declaration has three parts
separated by hyphens. The three parts are the short name of the
class/module, its version number, and a URI identifying the author (or
authorizing authority). For example:
class Dog-1.2.1-cpan:JRANDOM;
class Dog-1.2.1-http://www.some.com/~jrandom;
class Dog-1.2.1-mailto:jrandom@some.com;
Such a declaration automatically aliases the full name of the class (or
module) to the short name. So for the rest of the lexical scope, "Dog"
refers to the longer name.
If there are extra classes or modules or packages declared within the
same file, they implicitly have a long name including the file's
version and author, but you needn't declare them again.
Since these long names are the actual names of the classes, when you
say:
use Dog;
you're really wildcarding the unspecified bits:
use Dog-(Any)-(Any);
And when you say:
use Dog-1.2.1;
you're really asking for:
use Dog-1.2.1-(Any);
Saying 1.2.1 specifies an exact match on the version number, not a
minimum match. To match more than one version, put a range operator in
parens:
use Dog-(1.2.1..1.2.3);
use Dog-(1.2.1..^1.3);
use Dog-(1.2.1...);
Subversions are wildcarded, so 1.2 really means 1.2.0.... If you say:
use v6;
which is short for:
use Perl-6;
you're asking for any version of Perl 6. Say:
use Perl-6.0;
use Perl-6.0.0;
use Perl-6.2.7.1;
if you want to lock in a particular set of semantics at some greater
degree of specificity. And some large company ever forks Perl, you can
say
use Perl-6-cpan:TPF
to guarantee that you get the unembraced Perl. ":-)"
For wildcards any valid smartmatch selector works:
use Dog-(1.2.1 | 1.3.4)-(/:i jrandom/);
use Dog-(Any)-(/^cpan\:/)
Parens are optional on a closure smartmatcher. The preceding may also
be written:
use Dog-{$^ver ~~ 1.2.1 | 1.3.4}-{$^auth ~~ /:i jrandom/};
use Dog-{$^ver ~~ Any}-{$^auth ~~ /^cpan\:/}
In any event, however you select the module, its full name is
automatically aliased to the short name for the rest of your lexical
scope. So you can just say
my Dog $spot .= new("woof");
and it knows (even if you don't) that you mean
my Dog-1.3.4-cpan:JRANDOM $spot .= new("woof");
The use statement actually allows a language on the front of a module
name, so that you can use modules from other languages. The language
is separated by a colon. For instance:
use perl5:Acme::Bleach-1.12-DCONWAY;
use ruby:Rails <PR_MACHINE>;
Forcing Perl 6
To get Perl 6 parsing rather than the default Perl 5 parsing, we said
you could force Perl 6 mode in your main program with:
use Perl-6;
Actually, you can just start your main program with any of:
use v6;
module;
class;
Those all specify the latest Perl 6 semantics, and are equivalent to
use Perl-(v6.0...)-(Any);
To lock the semantics to 6.0.0, say:
use v6.0.0;
In any of those cases, strictures and warnings are the default in your
main program. But if you start your program with a bare version number
or other literal:
v6.0.0;
v6;
6;
"Coolness, dude!";
it runs Perl 6 in "lax" mode, without strictures or warnings, since
obviously a bare literal in a void context ought to have produced a
warning. (Invoking perl with "-e6" has the same effect.)
perl v5.14.0 2006-02-28 Perl6::Bible::S11(3)
