=encoding utf8

=head1 TITLE

Synopsis 10: Packages

=head1 AUTHORS

    Larry Wall <larry@wall.org>

=head1 VERSION

    Created: 27 Oct 2004

    Last Modified: 9 Jul 2010
    Version: 13

=head1 Overview

This synopsis summarizes Apocalypse 10, which discusses packages
despite never having been written.

=head1 Packages

As in Perl 5, packages are the basis of modules and classes.  Unlike in
Perl 5, modules and classes are declared with distinct keywords,
but they're still just packages with extra behaviors.  Likewise every
typename has an associated package namespace, even if unused.

An ordinary package is declared with the C<package> keyword.  Unlike in
Perl 5, in Perl 6 it can only be used with a block:

    package Bar {...}   # block is in package Bar

A named package declaration can occur as part of an expression, just like
named subroutine declarations.

As a special exception, if a braceless C<package> declaration occurs
as the first executable statement in a file, then it's taken to mean that the rest of
the file is Perl 5 code.

    package Foo;        # the entire file is Perl 5
    ...

This form is illegal in a Perl 6 file.  If you wish to have a file-scoped package,
either use the brace form or declare it with the C<module> keyword instead.

Since there are no barewords in Perl 6, package names must be predeclared,
or use the sigil-like C<::PackageName> syntax to indicate that the type will
be supplied some other way.  The C<::> prefix does not imply globalness as
it does in Perl 5.  (Use C<GLOBAL::> for that.)

A bare C<package> declarator (without an explicit scope declarator
such as C<my>) declares an C<our> package within the current package
(or module, or class, or role, or...).  Use C<GLOBAL::> to declare
a global package name.

To declare a lexically scoped package, use C<my package>.

To declare an anonymous package you can use either of

    package {...}
    package :: {...}

All files start out being parsed in the C<GLOBAL>
package, but may switch to some other package scope depending on the first
package-ish declaration.  If that first declaration is not a package variant, then
the parsing switches to the "C<main>" package for Perl 5 code.  Perl 6 code
stays C<GLOBAL> in that situation.  The mainline code is thus in the
C<GLOBAL> namespace unless declared otherwise.

Package traits are set using C<is>:

    package Foo is bar {...}

All symbolic links are done with the C<::($expr)> syntax, which is
legal in any variable, package, module, or class name anywhere a
C<::Ident> is legal.  The string returned by the expression will be
parsed for C<::> indicating subpackage names.  Do not confuse this
with the

    Foo::{$key}

syntax that lets you do a lookup in a particular symbol table.  In this case,
the key is not parsed for C<::>.  It's just a hash lookup.

All package bodies (including module and class bodies) execute at the
normal execution time of the code in which they are embedded.  For normal
mainline code, this is the normal flow of execution; if this is too late
to initialize something in the package that you want to be initialized, consider
use of a MAIN subroutine, which is invoked at the end of normal execution.
See L<S06/Declaring a C<MAIN> subroutine>.

For packages (modules, classes, roles, etc.) defined in separate files
from the mainline code, there can be no mainline code by definition,
but the top-level code in the used module needs to be executed at
some point in case things need initialization.  Invocation of this
pseudo-mainline code in the module notionally happens no later than at
the point of the C<use> or C<need> call in the process of compilation,
but the module's code is assumed to be sufficiently uninteresting that
it need be executed only once regardless of how many times the module
is used subsequently in the compilation.  (In fact, it might not need
to run at all if the result of some previous compilation's run has
been cached.)

If it is desired to have code that varies in meaning from run to run,
then you should put such code into an INIT block.  (Likewise, you
could put code into a CHECK block that has inconsistent semantics
from compilation to compilation, but that's probably a bad idea.)

In any case, it is erroneous for any external module to depend
on any knowledge of its user with respect to compilation order or
other dynamic information, since other users may also depend on
this single "first-use" execution and expect consistent semantics.
(Really, all such dynamic dependencies should be passed in at run
time to the routines or methods of your module as normal parameters or
as dynamic variables.  For instance, you cannot know at module compile
time whether your caller is going to be using 'fatal' semantics or not.
That is dynamically scoped info.)

If you wish to have a module that does something extra if invoked
standalone, define a MAIN subroutine, which will be ignored if
the module is merely used/needed elsewhere.

=head1 Package nesting

A declaration of any object of the form C<A::B::c> also creates (if needed)
an empty package C<A>, and an empty package C<B> inside of C<A>, in addition to creating
C<c> inside of C<B>.  Such empty packages may be subsequently be redeclared as any other
package-like object (module, class, etc.), and no redeclaration warning will be issued
for such a redeclaration.  If a parent package already exists, no stub package
needs to be created, and no declaration of the form C<A::B::c> has anything
to say about the type of package C<A> or package C<A::B>, since any package variant
can function as a package for the purposes of naming things.

Apart of package declaration constructs, package names are always searched
for from the innermost lexical scope to outermost.  If not defined in any
surrounding lexical scope, the package is searched for from the current
package up through the containing packages to C<GLOBAL>.  If it is not found,
a compiler error results.

As with an initial C<::>, the presence of a C<::> within the name
does not imply globalness (unlike in Perl 5).  True globals are always
in the C<GLOBAL::> namespace.

The C<PROCESS::> namespace, shared by all interpreters within the process,
is notionally outside of C<GLOBAL::>, but package searches do not look
there for anything.  (Contextual variable searches do; C<$*PID> will eventually
locate C<$PROCESS::PID> if not hidden by an inner callframe's C<$*PID>.)

=head1 Autoloading

A package (or any other similar namespace) can control autoloading.
However, Perl 5's C<AUTOLOAD> is being superseded by MMD autoloaders
that distinguish declaration from definition, but are not restricted
to declaring subs.  A run-time declarator multisub is declared as:

    multi CANDO ( MyPackage, $type, $name, *%args --> Container)

which stands in for the declaration of a container object within
another container object; it is called when anyone is searching for
a name in the package (or module, or class), and the name doesn't
already exist in the package.  (In particular, C<.can> calls C<CANDO>
when trying to determine if a class supports a particular method.)
The arguments to C<CANDO> include type information on what kind
of object is expected in context, or this may be intuited from the
name requested.  In any case, there may be multiple C<CANDO> routines
that are dispatched via MMD:

    multi CANDO ( MyPackage, Item, $name, *%args --> Container)
    multi CANDO ( MyPackage, Array, $name, *%args --> Container)
    multi CANDO ( MyPackage, Hash, $name, *%args --> Container)
    multi CANDO ( MyPackage, Code, $name, *%args --> Container)

The package itself is just passed as the first argument, since it's
the container object.  Subsequent arguments identify the desired type
of the inner container and the "name" or "key" by which the object is
to be looked up in the outer container.  Such a name does not include
its container name, unlike Perl 5's magical C<$AUTOLOAD> variable.
Nor does it include the type information of a Code object's "long
name"; this information comes in via the type parameter, and may be
matched against using ordinary subsignature matching:

    multi CANDO ( MyPackage, &:($), $name, *%args --> Container)     # 1 arg
    multi CANDO ( MyPackage, &:($,$), $name, *%args --> Container)   # 2 args

The slurpy C<%args> hash is likely to be empty in standard Perl 6
usage, but it's possible that some dialects of Perl will desire
a mechanism to pass in additional contextual information, so this
parameter is reserved for such purposes.

The C<CANDO> is expected to return an inner container object of
the proper sort (i.e. a variable, subroutine, or method object),
or a proxy object that can "autovivify" lazily, or C<Nil> if that
name is not to be considered declared in the namespace in question.
(Only bare C<Nil> is interpreted as "not there", since typed undefs
may function as autovivifiable proxy objects.  See S12.)

The declaration merely defines the interface to the new object.  That object
need not be completely defined yet, though the C<CANDO> routine is certainly
I<allowed> to define it eagerly, and even install the inner object into the
outer container (the symbol table) if it wants to cache the declaration.

At declaration time it might not yet be known whether the inner
container object will be used in lvalue or rvalue context; the use
of a proxy object can supply either readonly or rw semantics later.

When the package in question is a class, it is also possible to declare
real methods or submethods:

    multi method CANDO ($self: Code, $name, *%args --> Container)

    multi submethod CANDO ($self: Item, $name, *%args --> Container)

The method form is inherited by subclasses.  Submethods are never
inherited but may still do MMD within the class.   (Ordinary multisubs
are "inherited" only to the extent allowed by nested lexical scopes.)

When the package in question is not a class, there is a slight problem
insofar as Perl 6 doesn't by default look into packages for functions
anymore, only lexical scopes.  However, we'd still like the ability
to dynamic add functions to a package, so there are two ways to get
around the lexical limitation.

First, presuming you have a C<CANDO> that adds to your current package,
you can simply call a newly-minted subroutine explicitly via the
current package:

    OUR::($somename)();

This bypasses the lexical namespaces entirely.  Alternately, we can set
up a mechanism whereby, if you import or define a C<CANDO> into a given
lexical scope, all calls from within that scope register a failover that
adds the current package to the list of places to look for subroutines (or,
obviously, call the C<CANDO> as a last resort after that).  There is no
performance impact on existing lexically scoped definitions, including those
from C<CORE>.  This approach does require that failure to find a function name
cannot be reported at compile time, but must be delayed till run time instead.
Another potential disadvantage is that the package's symbols are also shadowed
by all symbols defined in your outer lexical scopes, including C<CORE>.
If this is a problem, use the direct C<OUR> call above.

Another way to look at it is that a lexical C<CANDO> adds itself to
the end of the function dispatcher's search, but sets up the current
package as a kind of cache for newly-defined functions just ahead of itself
in the search path.

=for vim:set expandtab sw=4: