TITLE
Synopsis 10: Packages
AUTHORS
Larry Wall <larry@wall.org>VERSION
Created: 27 Oct 2004
Last Modified: 9 Jul 2010
Version: 13Overview
This synopsis summarizes Apocalypse 10, which discusses packages despite never having been written.
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 package keyword. Unlike in Perl 5, in Perl 6 it can only be used with a block:
package Bar {...} # block is in package BarA named package declaration can occur as part of an expression, just like named subroutine declarations.
As a special exception, if a braceless 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 module keyword instead.
Since there are no barewords in Perl 6, package names must be predeclared, or use the sigil-like ::PackageName syntax to indicate that the type will be supplied some other way. The :: prefix does not imply globalness as it does in Perl 5. (Use GLOBAL:: for that.)
A bare package declarator (without an explicit scope declarator such as my) declares an our package within the current package (or module, or class, or role, or...). Use GLOBAL:: to declare a global package name.
To declare a lexically scoped package, use my package.
To declare an anonymous package you can use either of
package {...}
package :: {...}All files start out being parsed in the 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 "main" package for Perl 5 code. Perl 6 code stays GLOBAL in that situation. The mainline code is thus in the GLOBAL namespace unless declared otherwise.
Package traits are set using is:
package Foo is bar {...}All symbolic links are done with the ::($expr) syntax, which is legal in any variable, package, module, or class name anywhere a ::Ident is legal. The string returned by the expression will be parsed for :: 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 ::. 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 "Declaring a MAIN subroutine" in S06.
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 use or 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.
Package nesting
A declaration of any object of the form A::B::c also creates (if needed) an empty package A, and an empty package B inside of A, in addition to creating c inside of 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 A::B::c has anything to say about the type of package A or package 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 GLOBAL. If it is not found, a compiler error results.
As with an initial ::, the presence of a :: within the name does not imply globalness (unlike in Perl 5). True globals are always in the GLOBAL:: namespace.
The PROCESS:: namespace, shared by all interpreters within the process, is notionally outside of GLOBAL::, but package searches do not look there for anything. (Contextual variable searches do; $*PID will eventually locate $PROCESS::PID if not hidden by an inner callframe's $*PID.)
Autoloading
A package (or any other similar namespace) can control autoloading. However, Perl 5's 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, .can calls CANDO when trying to determine if a class supports a particular method.) The arguments to 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 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 $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 argsThe slurpy %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 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 Nil if that name is not to be considered declared in the namespace in question. (Only bare 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 CANDO routine is certainly 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 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 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 CANDO as a last resort after that). There is no performance impact on existing lexically scoped definitions, including those from 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 CORE. If this is a problem, use the direct OUR call above.
Another way to look at it is that a lexical 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.