=encoding utf8

=head1 TITLE

Synopsis 11: Modules

=head1 AUTHOR

Larry Wall <larry@wall.org>

=head1 VERSION

  Maintainer: Larry Wall <larry@wall.org>
  Date: 27 Oct 2004
  Last Modified: 2 Dec 2004
  Number: 11
  Version: 4

=head1 Overview

This synopsis discusses those portions of Apocalypse 12 that ought to have
been in Apocalypse 11.

=head1 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 C<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.

Since there are no barewords in Perl 6, module names must be predeclared,
or use the sigil-like C<::ModuleName> syntax.  The C<::> prefix does not
imply top-levelness as it does in Perl 5.  (Use C<::*> for that.)

A bare C<module> declarator declares a global module name in C<::*>.
To declare a module in the current package (or module, or class), use
C<our module>.  To declare a lexically scoped module, use C<my module>.
Module names are always searched for from innermost scopes to outermost.
As with an initial C<::>, the presence of a C<::> within the name
does not imply globalness (unlike in Perl 5).

The C<::*> namespace is not "main".  The default namespace for the main
program is C<::*Main>.  (Putting C<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.  A bare C<module;> defaults to C<Main>.)

Module traits are set using C<is>:

    module Foo is bar {...}

=head1 Exportation

Exportation is now done by trait declaration on the exportable item:

                                               # 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

=head1 Importation

All imports are done by default into the current lexical scope (rather
than the current package, as in Perl 5).

    use Sense <common @horse>;

You can be explicit about the desired scoping:

    use Sense :my<common> :our<@horse> :state<$haslearnedsome>;

That's pretty much equivalent to:

    use Sense;
    my &common ::= &Sense::common;
    our @horse ::= @Sense::horse;
    state $haslearnedsome ::= $Sense::haslearnedsome;

=head1 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, C<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 C<1.2.1> specifies an I<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 C<1.2> really means C<1.2.0...>.  If you
say:

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

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");

=head1 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.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 obvously
a bare literal in a void context I<ought> to have produced a warning.
(Invoking perl with C<-e6> has the same effect.)
