Skip to content
This repository
Newer
Older
100644 249 lines (189 sloc) 11.465 kb
be1862e9 » Darren_Duncan
2009-07-05 P6 Synopsis : ws changes - to help BOMers, added leading blank line t…
1
68d062fc » pmichaud
2008-11-26 Move synopses to their new home.
2 =encoding utf8
3
4 =head1 TITLE
5
6 Synopsis 10: Packages
7
04840a3a » lwall
2009-06-26 [Spec] treat all authors equally
8 =head1 AUTHORS
68d062fc » pmichaud
2008-11-26 Move synopses to their new home.
9
04840a3a » lwall
2009-06-26 [Spec] treat all authors equally
10 Larry Wall <larry@wall.org>
68d062fc » pmichaud
2008-11-26 Move synopses to their new home.
11
12 =head1 VERSION
13
04840a3a » lwall
2009-06-26 [Spec] treat all authors equally
14 Created: 27 Oct 2004
15
831d805b » lwall
2010-07-10 [spec] random cleanup of fossils from before proto became a multi wra…
16 Last Modified: 9 Jul 2010
17 Version: 13
68d062fc » pmichaud
2008-11-26 Move synopses to their new home.
18
19 =head1 Overview
20
21 This synopsis summarizes Apocalypse 10, which discusses packages
22 despite never having been written.
23
24 =head1 Packages
25
ea2a0002 » jimmy
2009-08-07 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
26 As in Perl 5, packages are the basis of modules and classes. Unlike in
27 Perl 5, modules and classes are declared with distinct keywords,
12e3e355 » lwall
2009-02-12 [S10] updates to package policies
28 but they're still just packages with extra behaviors. Likewise every
29 typename has an associated package namespace, even if unused.
68d062fc » pmichaud
2008-11-26 Move synopses to their new home.
30
12e3e355 » lwall
2009-02-12 [S10] updates to package policies
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:
68d062fc » pmichaud
2008-11-26 Move synopses to their new home.
33
34 package Bar {...} # block is in package Bar
35
36 A named package declaration can occur as part of an expression, just like
37 named subroutine declarations.
38
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
ea2a0002 » jimmy
2009-08-07 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
41 the file is Perl 5 code.
68d062fc » pmichaud
2008-11-26 Move synopses to their new home.
42
43 package Foo; # the entire file is Perl 5
44 ...
45
ea2a0002 » jimmy
2009-08-07 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
46 This form is illegal in a Perl 6 file. If you wish to have a file-scoped package,
12e3e355 » lwall
2009-02-12 [S10] updates to package policies
47 either use the brace form or declare it with the C<module> keyword instead.
68d062fc » pmichaud
2008-11-26 Move synopses to their new home.
48
ea2a0002 » jimmy
2009-08-07 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
49 Since there are no barewords in Perl 6, package names must be predeclared,
12e3e355 » lwall
2009-02-12 [S10] updates to package policies
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
ea2a0002 » jimmy
2009-08-07 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
52 it does in Perl 5. (Use C<GLOBAL::> for that.)
68d062fc » pmichaud
2008-11-26 Move synopses to their new home.
53
12e3e355 » lwall
2009-02-12 [S10] updates to package policies
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.
68d062fc » pmichaud
2008-11-26 Move synopses to their new home.
58
59 To declare a lexically scoped package, use C<my package>.
60
60cc0dba » lwall
2009-02-14 Allow use of :: as anonymous package name
61 To declare an anonymous package you can use either of
62
63 package {...}
64 package :: {...}
65
12e3e355 » lwall
2009-02-12 [S10] updates to package policies
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
ea2a0002 » jimmy
2009-08-07 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
69 the parsing switches to the "C<main>" package for Perl 5 code. Perl 6 code
12e3e355 » lwall
2009-02-12 [S10] updates to package policies
70 stays C<GLOBAL> in that situation. The mainline code is thus in the
71 C<GLOBAL> namespace unless declared otherwise.
68d062fc » pmichaud
2008-11-26 Move synopses to their new home.
72
73 Package traits are set using C<is>:
74
75 package Foo is bar {...}
76
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
82
83 Foo::{$key}
84
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.
87
e5cca2dd » lwall
2009-09-07 [S10] specify time of execution of package blocks and module (non)mai…
88 All package bodies (including module and class bodies) execute at the
89 normal execution time of the code in which they are embedded. For normal
90 mainline code, this is the normal flow of execution; if this is too late
91 to initialize something in the package that you want to be initialized, consider
92 use of a MAIN subroutine, which is invoked at the end of normal execution.
93 See L<S06/Declaring a C<MAIN> subroutine>.
94
95 For packages (modules, classes, roles, etc.) defined in separate files
96 from the mainline code, there can be no mainline code by definition,
97 but the top-level code in the used module needs to be executed at
98 some point in case things need initialization. Invocation of this
99 pseudo-mainline code in the module notionally happens no later than at
100 the point of the C<use> or C<need> call in the process of compilation,
101 but the module's code is assumed to be sufficiently uninteresting that
102 it need be executed only once regardless of how many times the module
103 is used subsequently in the compilation. (In fact, it might not need
104 to run at all if the result of some previous compilation's run has
105 been cached.)
106
107 If it is desired to have code that varies in meaning from run to run,
108 then you should put such code into an INIT block. (Likewise, you
109 could put code into a CHECK block that has inconsistent semantics
110 from compilation to compilation, but that's probably a bad idea.)
111
112 In any case, it is erroneous for any external module to depend
113 on any knowledge of its user with respect to compilation order or
dff23644 » lwall
2009-11-20 [Spec] slaughter various confusing overloadings of the term 'context'
114 other dynamic information, since other users may also depend on
e5cca2dd » lwall
2009-09-07 [S10] specify time of execution of package blocks and module (non)mai…
115 this single "first-use" execution and expect consistent semantics.
dff23644 » lwall
2009-11-20 [Spec] slaughter various confusing overloadings of the term 'context'
116 (Really, all such dynamic dependencies should be passed in at run
e5cca2dd » lwall
2009-09-07 [S10] specify time of execution of package blocks and module (non)mai…
117 time to the routines or methods of your module as normal parameters or
dff23644 » lwall
2009-11-20 [Spec] slaughter various confusing overloadings of the term 'context'
118 as dynamic variables. For instance, you cannot know at module compile
e5cca2dd » lwall
2009-09-07 [S10] specify time of execution of package blocks and module (non)mai…
119 time whether your caller is going to be using 'fatal' semantics or not.
120 That is dynamically scoped info.)
121
122 If you wish to have a module that does something extra if invoked
123 standalone, define a MAIN subroutine, which will be ignored if
124 the module is merely used/needed elsewhere.
125
12e3e355 » lwall
2009-02-12 [S10] updates to package policies
126 =head1 Package nesting
127
128 A declaration of any object of the form C<A::B::c> also creates (if needed)
129 an empty package C<A>, and an empty package C<B> inside of C<A>, in addition to creating
130 C<c> inside of C<B>. Such empty packages may be subsequently be redeclared as any other
131 package-like object (module, class, etc.), and no redeclaration warning will be issued
132 for such a redeclaration. If a parent package already exists, no stub package
133 needs to be created, and no declaration of the form C<A::B::c> has anything
134 to say about the type of package C<A> or package C<A::B>, since any package variant
135 can function as a package for the purposes of naming things.
136
137 Apart of package declaration constructs, package names are always searched
138 for from the innermost lexical scope to outermost. If not defined in any
139 surrounding lexical scope, the package is searched for from the current
140 package up through the containing packages to C<GLOBAL>. If it is not found,
141 a compiler error results.
142
143 As with an initial C<::>, the presence of a C<::> within the name
ea2a0002 » jimmy
2009-08-07 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
144 does not imply globalness (unlike in Perl 5). True globals are always
12e3e355 » lwall
2009-02-12 [S10] updates to package policies
145 in the C<GLOBAL::> namespace.
146
147 The C<PROCESS::> namespace, shared by all interpreters within the process,
148 is notionally outside of C<GLOBAL::>, but package searches do not look
149 there for anything. (Contextual variable searches do; C<$*PID> will eventually
dff23644 » lwall
2009-11-20 [Spec] slaughter various confusing overloadings of the term 'context'
150 locate C<$PROCESS::PID> if not hidden by an inner callframe's C<$*PID>.)
12e3e355 » lwall
2009-02-12 [S10] updates to package policies
151
68d062fc » pmichaud
2008-11-26 Move synopses to their new home.
152 =head1 Autoloading
153
154 A package (or any other similar namespace) can control autoloading.
ea2a0002 » jimmy
2009-08-07 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
155 However, Perl 5's C<AUTOLOAD> is being superseded by MMD autoloaders
68d062fc » pmichaud
2008-11-26 Move synopses to their new home.
156 that distinguish declaration from definition, but are not restricted
157 to declaring subs. A run-time declarator multisub is declared as:
158
159 multi CANDO ( MyPackage, $type, $name, *%args --> Container)
160
161 which stands in for the declaration of a container object within
162 another container object; it is called when anyone is searching for
163 a name in the package (or module, or class), and the name doesn't
164 already exist in the package. (In particular, C<.can> calls C<CANDO>
165 when trying to determine if a class supports a particular method.)
166 The arguments to C<CANDO> include type information on what kind
167 of object is expected in context, or this may be intuited from the
168 name requested. In any case, there may be multiple C<CANDO> routines
169 that are dispatched via MMD:
170
171 multi CANDO ( MyPackage, Item, $name, *%args --> Container)
172 multi CANDO ( MyPackage, Array, $name, *%args --> Container)
173 multi CANDO ( MyPackage, Hash, $name, *%args --> Container)
174 multi CANDO ( MyPackage, Code, $name, *%args --> Container)
175
176 The package itself is just passed as the first argument, since it's
177 the container object. Subsequent arguments identify the desired type
178 of the inner container and the "name" or "key" by which the object is
179 to be looked up in the outer container. Such a name does not include
ea2a0002 » jimmy
2009-08-07 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
180 its container name, unlike Perl 5's magical C<$AUTOLOAD> variable.
68d062fc » pmichaud
2008-11-26 Move synopses to their new home.
181 Nor does it include the type information of a Code object's "long
182 name"; this information comes in via the type parameter, and may be
183 matched against using ordinary subsignature matching:
184
185 multi CANDO ( MyPackage, &:($), $name, *%args --> Container) # 1 arg
186 multi CANDO ( MyPackage, &:($,$), $name, *%args --> Container) # 2 args
187
ea2a0002 » jimmy
2009-08-07 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
188 The slurpy C<%args> hash is likely to be empty in standard Perl 6
68d062fc » pmichaud
2008-11-26 Move synopses to their new home.
189 usage, but it's possible that some dialects of Perl will desire
190 a mechanism to pass in additional contextual information, so this
191 parameter is reserved for such purposes.
192
193 The C<CANDO> is expected to return an inner container object of
194 the proper sort (i.e. a variable, subroutine, or method object),
62d7cb7c » lwall
2009-11-24 clobber undef as a poorly defined noun, use Object or Nil
195 or a proxy object that can "autovivify" lazily, or C<Nil> if that
68d062fc » pmichaud
2008-11-26 Move synopses to their new home.
196 name is not to be considered declared in the namespace in question.
62d7cb7c » lwall
2009-11-24 clobber undef as a poorly defined noun, use Object or Nil
197 (Only bare C<Nil> is interpreted as "not there", since typed undefs
68d062fc » pmichaud
2008-11-26 Move synopses to their new home.
198 may function as autovivifiable proxy objects. See S12.)
199
200 The declaration merely defines the interface to the new object. That object
201 need not be completely defined yet, though the C<CANDO> routine is certainly
202 I<allowed> to define it eagerly, and even install the inner object into the
203 outer container (the symbol table) if it wants to cache the declaration.
204
205 At declaration time it might not yet be known whether the inner
206 container object will be used in lvalue or rvalue context; the use
207 of a proxy object can supply either readonly or rw semantics later.
208
9d5a38d5 » Darren_Duncan
2009-07-05 P6 Synopsis : ws changes - remove trailing spaces
209 When the package in question is a class, it is also possible to declare
68d062fc » pmichaud
2008-11-26 Move synopses to their new home.
210 real methods or submethods:
211
212 multi method CANDO ($self: Code, $name, *%args --> Container)
213
214 multi submethod CANDO ($self: Item, $name, *%args --> Container)
215
216 The method form is inherited by subclasses. Submethods are never
217 inherited but may still do MMD within the class. (Ordinary multisubs
831d805b » lwall
2010-07-10 [spec] random cleanup of fossils from before proto became a multi wra…
218 are "inherited" only to the extent allowed by nested lexical scopes.)
68d062fc » pmichaud
2008-11-26 Move synopses to their new home.
219
9fc187b4 » lwall
2010-06-19 [S10] define how CANDO works with respect to lexically-scoped functio…
220 When the package in question is not a class, there is a slight problem
221 insofar as Perl 6 doesn't by default look into packages for functions
222 anymore, only lexical scopes. However, we'd still like the ability
223 to dynamic add functions to a package, so there are two ways to get
224 around the lexical limitation.
225
226 First, presuming you have a C<CANDO> that adds to your current package,
227 you can simply call a newly-minted subroutine explicitly via the
228 current package:
229
c010170b » lwall
2010-06-19 [S10] fix thinkos and bad writing
230 OUR::($somename)();
231
232 This bypasses the lexical namespaces entirely. Alternately, we can set
233 up a mechanism whereby, if you import or define a C<CANDO> into a given
234 lexical scope, all calls from within that scope register a failover that
235 adds the current package to the list of places to look for subroutines (or,
236 obviously, call the C<CANDO> as a last resort after that). There is no
237 performance impact on existing lexically scoped definitions, including those
238 from C<CORE>. This approach does require that failure to find a function name
239 cannot be reported at compile time, but must be delayed till run time instead.
240 Another potential disadvantage is that the package's symbols are also shadowed
241 by all symbols defined in your outer lexical scopes, including C<CORE>.
242 If this is a problem, use the direct C<OUR> call above.
9fc187b4 » lwall
2010-06-19 [S10] define how CANDO works with respect to lexically-scoped functio…
243
244 Another way to look at it is that a lexical C<CANDO> adds itself to
245 the end of the function dispatcher's search, but sets up the current
246 package as a kind of cache for newly-defined functions just ahead of itself
247 in the search path.
248
68d062fc » pmichaud
2008-11-26 Move synopses to their new home.
249 =for vim:set expandtab sw=4:
Something went wrong with that request. Please try again.