Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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