Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 221 lines (165 sloc) 9.934 kb
be1862e P6 Synopsis : ws changes - to help BOMers, added leading blank line to f...
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
e5cca2d [S10] specify time of execution of package blocks and module (non)mainli...
lwall authored
16 Last Modified: 7 Sep 2009
17 Version: 10
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 do...
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 do...
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 do...
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 do...
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 do...
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 do...
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)mainli...
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
114 other contextual information, since other users may also depend on
115 this single "first-use" execution and expect consistent semantics.
116 (Really, all such contextual dependencies should be passed in at run
117 time to the routines or methods of your module as normal parameters or
118 contextual variables. For instance, you cannot know at module compile
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
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
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we do...
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
150 locate C<$PROCESS::PID> if not hidden by an inner context's C<$PID>.)
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 do...
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
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
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we do...
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
185 multi CANDO ( MyPackage, &:($), $name, *%args --> Container) # 1 arg
186 multi CANDO ( MyPackage, &:($,$), $name, *%args --> Container) # 2 args
187
ea2a000 [Spec]reverted \x20 to \xC2A0. "Perl 6" and "Perl 5" are words, so we do...
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),
195 or a proxy object that can "autovivify" lazily, or C<undef> if that
196 name is not to be considered declared in the namespace in question.
197 (Only bare C<undef> is interpreted as "not there", since typed undefs
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
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
218 are inherited only to the extent allowed by the MMD mechanism.)
219
220 =for vim:set expandtab sw=4:
Something went wrong with that request. Please try again.