Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
100644 183 lines (134 sloc) 7.825 kb
68d062f Move synopses to their new home.
pmichaud authored
1 =encoding utf8
3 =head1 TITLE
5 Synopsis 10: Packages
7 =head1 AUTHOR
9 Larry Wall <>
11 =head1 VERSION
13 Maintainer: Larry Wall <>
14 Date: 27 Oct 2004
60cc0db Allow use of :: as anonymous package name
lwall authored
15 Last Modified: 13 Feb 2009
68d062f Move synopses to their new home.
pmichaud authored
16 Number: 10
60cc0db Allow use of :: as anonymous package name
lwall authored
17 Version: 9
68d062f Move synopses to their new home.
pmichaud authored
19 =head1 Overview
21 This synopsis summarizes Apocalypse 10, which discusses packages
22 despite never having been written.
24 =head1 Packages
26 As in Perl 5, packages are the basis of modules and classes. Unlike in
12e3e35 [S10] updates to package policies
lwall authored
27 Perl 5, modules and classes are declared with distinct keywords,
28 but they're still just packages with extra behaviors. Likewise every
29 typename has an associated package namespace, even if unused.
68d062f Move synopses to their new home.
pmichaud authored
12e3e35 [S10] updates to package policies
lwall authored
31 An ordinary package is declared with the C<package> keyword. Unlike in
32 Perl 5, in Perl 6 it can only be used with a block:
68d062f Move synopses to their new home.
pmichaud authored
34 package Bar {...} # block is in package Bar
36 A named package declaration can occur as part of an expression, just like
37 named subroutine declarations.
39 As a special exception, if a braceless C<package> declaration occurs
40 as the first executable statement in a file, then it's taken to mean that the rest of
41 the file is Perl 5 code.
43 package Foo; # the entire file is Perl 5
44 ...
12e3e35 [S10] updates to package policies
lwall authored
46 This form is illegal in a Perl 6 file. If you wish to have a file-scoped package,
47 either use the brace form or declare it with the C<module> keyword instead.
68d062f Move synopses to their new home.
pmichaud authored
49 Since there are no barewords in Perl 6, package names must be predeclared,
12e3e35 [S10] updates to package policies
lwall authored
50 or use the sigil-like C<::PackageName> syntax to indicate that the type will
51 be supplied some other way. The C<::> prefix does not imply globalness as
52 it does in Perl 5. (Use C<GLOBAL::> for that.)
68d062f Move synopses to their new home.
pmichaud authored
12e3e35 [S10] updates to package policies
lwall authored
54 A bare C<package> declarator (without an explicit scope declarator
55 such as C<my>) declares an C<our> package within the current package
56 (or module, or class, or role, or...). Use C<GLOBAL::> to declare
57 a global package name.
68d062f Move synopses to their new home.
pmichaud authored
59 To declare a lexically scoped package, use C<my package>.
60cc0db Allow use of :: as anonymous package name
lwall authored
61 To declare an anonymous package you can use either of
63 package {...}
64 package :: {...}
12e3e35 [S10] updates to package policies
lwall authored
66 All files start out being parsed in the C<GLOBAL>
67 package, but may switch to some other package scope depending on the first
68 package-ish declaration. If that first declaration is not a package variant, then
69 the parsing switches to the "C<main>" package for Perl 5 code. Perl 6 code
70 stays C<GLOBAL> in that situation. The mainline code is thus in the
71 C<GLOBAL> namespace unless declared otherwise.
68d062f Move synopses to their new home.
pmichaud authored
73 Package traits are set using C<is>:
75 package Foo is bar {...}
77 All symbolic links are done with the C<::($expr)> syntax, which is
78 legal in any variable, package, module, or class name anywhere a
79 C<::Ident> is legal. The string returned by the expression will be
80 parsed for C<::> indicating subpackage names. Do not confuse this
81 with the
83 Foo::{$key}
85 syntax that lets you do a lookup in a particular symbol table. In this case,
86 the key is not parsed for C<::>. It's just a hash lookup.
12e3e35 [S10] updates to package policies
lwall authored
88 =head1 Package nesting
90 A declaration of any object of the form C<A::B::c> also creates (if needed)
91 an empty package C<A>, and an empty package C<B> inside of C<A>, in addition to creating
92 C<c> inside of C<B>. Such empty packages may be subsequently be redeclared as any other
93 package-like object (module, class, etc.), and no redeclaration warning will be issued
94 for such a redeclaration. If a parent package already exists, no stub package
95 needs to be created, and no declaration of the form C<A::B::c> has anything
96 to say about the type of package C<A> or package C<A::B>, since any package variant
97 can function as a package for the purposes of naming things.
99 Apart of package declaration constructs, package names are always searched
100 for from the innermost lexical scope to outermost. If not defined in any
101 surrounding lexical scope, the package is searched for from the current
102 package up through the containing packages to C<GLOBAL>. If it is not found,
103 a compiler error results.
105 As with an initial C<::>, the presence of a C<::> within the name
106 does not imply globalness (unlike in Perl 5). True globals are always
107 in the C<GLOBAL::> namespace.
109 The C<PROCESS::> namespace, shared by all interpreters within the process,
110 is notionally outside of C<GLOBAL::>, but package searches do not look
111 there for anything. (Contextual variable searches do; C<$*PID> will eventually
112 locate C<$PROCESS::PID> if not hidden by an inner context's C<$PID>.)
68d062f Move synopses to their new home.
pmichaud authored
114 =head1 Autoloading
116 A package (or any other similar namespace) can control autoloading.
117 However, Perl 5's C<AUTOLOAD> is being superseded by MMD autoloaders
118 that distinguish declaration from definition, but are not restricted
119 to declaring subs. A run-time declarator multisub is declared as:
121 multi CANDO ( MyPackage, $type, $name, *%args --> Container)
123 which stands in for the declaration of a container object within
124 another container object; it is called when anyone is searching for
125 a name in the package (or module, or class), and the name doesn't
126 already exist in the package. (In particular, C<.can> calls C<CANDO>
127 when trying to determine if a class supports a particular method.)
128 The arguments to C<CANDO> include type information on what kind
129 of object is expected in context, or this may be intuited from the
130 name requested. In any case, there may be multiple C<CANDO> routines
131 that are dispatched via MMD:
133 multi CANDO ( MyPackage, Item, $name, *%args --> Container)
134 multi CANDO ( MyPackage, Array, $name, *%args --> Container)
135 multi CANDO ( MyPackage, Hash, $name, *%args --> Container)
136 multi CANDO ( MyPackage, Code, $name, *%args --> Container)
138 The package itself is just passed as the first argument, since it's
139 the container object. Subsequent arguments identify the desired type
140 of the inner container and the "name" or "key" by which the object is
141 to be looked up in the outer container. Such a name does not include
142 its container name, unlike Perl 5's magical C<$AUTOLOAD> variable.
143 Nor does it include the type information of a Code object's "long
144 name"; this information comes in via the type parameter, and may be
145 matched against using ordinary subsignature matching:
147 multi CANDO ( MyPackage, &:($), $name, *%args --> Container) # 1 arg
148 multi CANDO ( MyPackage, &:($,$), $name, *%args --> Container) # 2 args
150 The slurpy C<%args> hash is likely to be empty in standard Perl 6
151 usage, but it's possible that some dialects of Perl will desire
152 a mechanism to pass in additional contextual information, so this
153 parameter is reserved for such purposes.
155 The C<CANDO> is expected to return an inner container object of
156 the proper sort (i.e. a variable, subroutine, or method object),
157 or a proxy object that can "autovivify" lazily, or C<undef> if that
158 name is not to be considered declared in the namespace in question.
159 (Only bare C<undef> is interpreted as "not there", since typed undefs
160 may function as autovivifiable proxy objects. See S12.)
162 The declaration merely defines the interface to the new object. That object
163 need not be completely defined yet, though the C<CANDO> routine is certainly
164 I<allowed> to define it eagerly, and even install the inner object into the
165 outer container (the symbol table) if it wants to cache the declaration.
167 At declaration time it might not yet be known whether the inner
168 container object will be used in lvalue or rvalue context; the use
169 of a proxy object can supply either readonly or rw semantics later.
171 When the package in question is a class, it is also possible to declare
172 real methods or submethods:
174 multi method CANDO ($self: Code, $name, *%args --> Container)
176 multi submethod CANDO ($self: Item, $name, *%args --> Container)
178 The method form is inherited by subclasses. Submethods are never
179 inherited but may still do MMD within the class. (Ordinary multisubs
180 are inherited only to the extent allowed by the MMD mechanism.)
182 =for vim:set expandtab sw=4:
Something went wrong with that request. Please try again.