Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 250 lines (189 sloc) 11.336 kB
be1862e P6 Synopsis : ws changes - to help BOMers, added leading blank line t…
Darren_Duncan authored
1
68d062f Move synopses to their new home.
pmichaud authored
2 =encoding utf8
3
4 =head1 TITLE
5
6 Synopsis 10: Packages
7
04840a3 [Spec] treat all authors equally
lwall authored
8 =head1 AUTHORS
68d062f Move synopses to their new home.
pmichaud authored
9
04840a3 [Spec] treat all authors equally
lwall authored
10 Larry Wall <larry@wall.org>
68d062f Move synopses to their new home.
pmichaud authored
11
12 =head1 VERSION
13
04840a3 [Spec] treat all authors equally
lwall authored
14 Created: 27 Oct 2004
15
831d805 [spec] random cleanup of fossils from before proto became a multi wra…
lwall authored
16 Last Modified: 9 Jul 2010
17 Version: 13
68d062f Move synopses to their new home.
pmichaud authored
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
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
jimmy authored
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,
12e3e35 [S10] updates to package policies
lwall authored
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
30
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
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
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
jimmy authored
41 the file is Perl 5 code.
68d062f Move synopses to their new home.
pmichaud authored
42
43 package Foo; # the entire file is Perl 5
44 ...
45
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
jimmy authored
46 This form is illegal in a Perl 6 file. If you wish to have a file-scoped package,
12e3e35 [S10] updates to package policies
lwall authored
47 either use the brace form or declare it with the C<module> keyword instead.
68d062f Move synopses to their new home.
pmichaud authored
48
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
jimmy 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
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
jimmy authored
52 it does in Perl 5. (Use C<GLOBAL::> for that.)
68d062f Move synopses to their new home.
pmichaud authored
53
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
58
59 To declare a lexically scoped package, use C<my package>.
60
60cc0db Allow use of :: as anonymous package name
lwall authored
61 To declare an anonymous package you can use either of
62
63 package {...}
64 package :: {...}
65
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
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
jimmy authored
69 the parsing switches to the "C<main>" package for Perl 5 code. Perl 6 code
12e3e35 [S10] updates to package policies
lwall authored
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
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
e5cca2d [S10] specify time of execution of package blocks and module (non)mai…
lwall authored
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
dff2364 [Spec] slaughter various confusing overloadings of the term 'context'
lwall authored
114 other dynamic information, since other users may also depend on
e5cca2d [S10] specify time of execution of package blocks and module (non)mai…
lwall authored
115 this single "first-use" execution and expect consistent semantics.
dff2364 [Spec] slaughter various confusing overloadings of the term 'context'
lwall authored
116 (Really, all such dynamic dependencies should be passed in at run
e5cca2d [S10] specify time of execution of package blocks and module (non)mai…
lwall authored
117 time to the routines or methods of your module as normal parameters or
dff2364 [Spec] slaughter various confusing overloadings of the term 'context'
lwall authored
118 as dynamic variables. For instance, you cannot know at module compile
e5cca2d [S10] specify time of execution of package blocks and module (non)mai…
lwall authored
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
12e3e35 [S10] updates to package policies
lwall authored
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
0698449 @felher fix a few typos
felher authored
130 C<c> inside of C<B>. Such empty packages may subsequently be redeclared as any other
12e3e35 [S10] updates to package policies
lwall authored
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
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
jimmy authored
144 does not imply globalness (unlike in Perl 5). True globals are always
12e3e35 [S10] updates to package policies
lwall authored
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
dff2364 [Spec] slaughter various confusing overloadings of the term 'context'
lwall authored
150 locate C<$PROCESS::PID> if not hidden by an inner callframe's C<$*PID>.)
12e3e35 [S10] updates to package policies
lwall authored
151
68d062f Move synopses to their new home.
pmichaud authored
152 =head1 Autoloading
153
154 A package (or any other similar namespace) can control autoloading.
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
jimmy authored
155 However, Perl 5's C<AUTOLOAD> is being superseded by MMD autoloaders
68d062f Move synopses to their new home.
pmichaud authored
156 that distinguish declaration from definition, but are not restricted
157 to declaring subs. A run-time declarator multisub is declared as:
158
0ebf6ac @moritz get rid of Container fossil
moritz authored
159 multi CANDO ( MyPackage, $type, $name, *%args)
68d062f Move synopses to their new home.
pmichaud authored
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
0ebf6ac @moritz get rid of Container fossil
moritz authored
171 multi CANDO ( MyPackage, Item, $name, *%args)
172 multi CANDO ( MyPackage, Array, $name, *%args)
173 multi CANDO ( MyPackage, Hash, $name, *%args)
174 multi CANDO ( MyPackage, Code, $name, *%args)
68d062f Move synopses to their new home.
pmichaud authored
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
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
jimmy authored
180 its container name, unlike Perl 5's magical C<$AUTOLOAD> variable.
68d062f Move synopses to their new home.
pmichaud authored
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
0ebf6ac @moritz get rid of Container fossil
moritz authored
185 multi CANDO ( MyPackage, &:($), $name, *%args) # 1 arg
186 multi CANDO ( MyPackage, &:($,$), $name, *%args) # 2 args
68d062f Move synopses to their new home.
pmichaud authored
187
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we…
jimmy authored
188 The slurpy C<%args> hash is likely to be empty in standard Perl 6
68d062f Move synopses to their new home.
pmichaud authored
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),
62d7cb7 clobber undef as a poorly defined noun, use Object or Nil
lwall authored
195 or a proxy object that can "autovivify" lazily, or C<Nil> if that
68d062f Move synopses to their new home.
pmichaud authored
196 name is not to be considered declared in the namespace in question.
62d7cb7 clobber undef as a poorly defined noun, use Object or Nil
lwall authored
197 (Only bare C<Nil> is interpreted as "not there", since typed undefs
68d062f Move synopses to their new home.
pmichaud authored
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
9d5a38d P6 Synopsis : ws changes - remove trailing spaces
Darren_Duncan authored
209 When the package in question is a class, it is also possible to declare
68d062f Move synopses to their new home.
pmichaud authored
210 real methods or submethods:
211
0ebf6ac @moritz get rid of Container fossil
moritz authored
212 multi method CANDO ($self: Code, $name, *%args)
68d062f Move synopses to their new home.
pmichaud authored
213
0ebf6ac @moritz get rid of Container fossil
moritz authored
214 multi submethod CANDO ($self: Item, $name, *%args)
68d062f Move synopses to their new home.
pmichaud authored
215
216 The method form is inherited by subclasses. Submethods are never
217 inherited but may still do MMD within the class. (Ordinary multisubs
831d805 [spec] random cleanup of fossils from before proto became a multi wra…
lwall authored
218 are "inherited" only to the extent allowed by nested lexical scopes.)
68d062f Move synopses to their new home.
pmichaud authored
219
9fc187b [S10] define how CANDO works with respect to lexically-scoped functio…
lwall authored
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
c010170 [S10] fix thinkos and bad writing
lwall authored
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.
9fc187b [S10] define how CANDO works with respect to lexically-scoped functio…
lwall authored
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
68d062f Move synopses to their new home.
pmichaud authored
249 =for vim:set expandtab sw=4:
Something went wrong with that request. Please try again.