
=encoding utf8

=head1 TITLE

Synopsis 10: Packages

=head1 AUTHORS

    Larry Wall <larry@wall.org>

=head1 VERSION

    Created: 27 Oct 2004

    Last Modified: 13 Feb 2009
    Version: 9

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

=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 context'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<undef> if that
name is not to be considered declared in the namespace in question.
(Only bare C<undef> 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 the MMD mechanism.)

=for vim:set expandtab sw=4:
