Skip to content

Commit ea23fcd

Browse files
author
Brock Wilcox
committed
Move into a dedicated Packages doc
1 parent e2054c9 commit ea23fcd

File tree

3 files changed

+174
-160
lines changed

3 files changed

+174
-160
lines changed

‎doc/Language/modules.pod

Lines changed: 0 additions & 159 deletions
Original file line numberDiff line numberDiff line change
@@ -33,165 +33,6 @@ written in Perl 6 you can use the C<.pm6> extension for modules, and the
3333
C<.p6> extension for scripts. Test files still use the normal C<.t>
3434
extension.
3535
36-
=head2 Names
37-
38-
A I<name> is anything that is a legal part of a variable name (not counting
39-
the sigil). This includes
40-
41-
$foo # simple identifiers
42-
$Foo::Bar::baz # compound identifiers separated by ::
43-
$Foo::($bar)::baz # compound identifiers that perform interpolations
44-
$42 # numeric names
45-
$! # certain punctuational variables
46-
47-
When not used as a sigil, the semantic function of C<::> within a name is to
48-
force the preceding portion of the name to be considered a package through
49-
which the subsequent portion of the name is to be located. If the preceding
50-
portion is null, it means the package is unspecified and must be searched
51-
for according to the nature of what follows. Generally this means that an
52-
initial C<::> following the main sigil is a no-op on names that are known at
53-
compile time, though C<::()> can also be used to introduce an interpolation
54-
(see below). Also, in the absence of another sigil, C<::> can serve as its
55-
own sigil indicating intentional use of a not-yet-declared package name.
56-
57-
=head3 Package-qualified names
58-
59-
Ordinary package-qualified names look like:
60-
61-
$Foo::Bar::baz # the $baz variable in package Foo::Bar
62-
63-
Sometimes it's clearer to keep the sigil with the variable name, so an
64-
alternate way to write this is:
65-
66-
Foo::Bar::<$baz>
67-
68-
This is resolved at compile time because the variable name is a constant.
69-
70-
=head3 Pseudo-packages
71-
72-
The following pseudo-package names are reserved at the front of a name:
73-
74-
MY # Symbols in the current lexical scope (aka $?SCOPE)
75-
OUR # Symbols in the current package (aka $?PACKAGE)
76-
CORE # Outermost lexical scope, definition of standard Perl
77-
GLOBAL # Interpreter-wide package symbols, really UNIT::GLOBAL
78-
PROCESS # Process-related globals (superglobals)
79-
COMPILING # Lexical symbols in the scope being compiled
80-
81-
The following relative names are also reserved but may be used
82-
anywhere in a name:
83-
84-
CALLER # Contextual symbols in the immediate caller's lexical scope
85-
CALLERS # Contextual symbols in any caller's lexical scope
86-
DYNAMIC # Contextual symbols in my or any caller's lexical scope
87-
OUTER # Symbols in the next outer lexical scope
88-
OUTERS # Symbols in any outer lexical scope
89-
LEXICAL # Contextual symbols in my or any outer's lexical scope
90-
UNIT # Symbols in the outermost lexical scope of compilation unit
91-
SETTING # Lexical symbols in the unit's DSL (usually CORE)
92-
PARENT # Symbols in this package's parent package (or lexical scope)
93-
CLIENT # The nearest CALLER that comes from a different package
94-
95-
The file's scope is known as C<UNIT>, but there are one or more lexical
96-
scopes outside of that corresponding to the linguistic setting (often known
97-
as the prelude in other cultures). Hence, the C<SETTING> scope is
98-
equivalent to C<UNIT::OUTERS>. For a standard Perl program C<SETTING> is the
99-
same as C<CORE>, but various startup options (such as C<-n> or C<-p>) can
100-
put you into a domain specific language, in which case C<CORE> remains the
101-
scope of the standard language, while C<SETTING> represents the scope
102-
defining the DSL that functions as the setting of the current file. When used
103-
as a search term in the middle of a name, C<SETTING> includes all its outer scopes
104-
up to C<CORE>. To get I<only> the setting's outermost scope, use C<UNIT::OUTER> instead.
105-
106-
=head3 Interpolating into names
107-
108-
You may interpolate a string into a package or variable name using
109-
C<::($expr)> where you'd ordinarily put a package or variable name. The
110-
string is allowed to contain additional instances of C<::>, which will be
111-
interpreted as package nesting. You may only interpolate entire names,
112-
since the construct starts with C<::>, and either ends immediately or is
113-
continued with another C<::> outside the parens. Most symbolic references
114-
are done with this notation:
115-
116-
$foo = "Bar";
117-
$foobar = "Foo::Bar";
118-
$::($foo) # lexically-scoped $Bar
119-
$::("MY::$foo") # lexically-scoped $Bar
120-
$::("OUR::$foo") # package-scoped $Bar
121-
$::("GLOBAL::$foo") # global $Bar
122-
$::("PROCESS::$foo")# process $Bar
123-
$::("PARENT::$foo") # current package's parent's $Bar
124-
$::($foobar) # $Foo::Bar
125-
$::($foobar)::baz # $Foo::Bar::baz
126-
$::($foo)::Bar::baz # $Bar::Bar::baz
127-
$::($foobar)baz # ILLEGAL at compile time (no operator baz)
128-
129-
Note that unlike in Perl 5, initial C<::> doesn't imply global. Here as part
130-
of the interpolation syntax it doesn't even imply package. After the
131-
interpolation of the C<::()> component, the indirect name is looked up exactly
132-
as if it had been there in the original source code, with priority given first
133-
to leading pseudo-package names, then to names in the lexical scope (searching
134-
scopes outwards, ending at C<CORE>). The current package is searched last.
135-
136-
Use the C<MY> pseudopackage to limit the lookup to the current lexical
137-
scope, and C<OUR> to limit the scopes to the current package scope.
138-
139-
=head3 Direct lookup
140-
141-
To do direct lookup in a package's symbol table without scanning, treat the
142-
package name as a hash:
143-
144-
Foo::Bar::{'&baz'} # same as &Foo::Bar::baz
145-
PROCESS::<$IN> # Same as $*IN
146-
Foo::<::Bar><::Baz> # same as Foo::Bar::Baz
147-
148-
The C<::> before the subscript is required here, because the
149-
C<Foo::Bar{...}> syntax is reserved for attaching a "WHENCE" initialization
150-
closure to an autovivifiable type object. (see S12).
151-
152-
Unlike C<::()> symbolic references, this does not parse the argument for
153-
C<::>, nor does it initiate a namespace scan from that initial point. In
154-
addition, for constant subscripts, it is guaranteed to resolve the symbol at
155-
compile time.
156-
157-
The null pseudo-package is reserved to mean the same search list as an
158-
ordinary name search. That is, the following are all identical in meaning:
159-
160-
$foo
161-
$::{'foo'}
162-
::{'$foo'}
163-
$::<foo>
164-
::<$foo>
165-
166-
That is, each of them scans lexical scopes outward, and then the current
167-
package scope (though the package scope is then disallowed when "strict" is
168-
in effect).
169-
170-
As a result of these rules, you can write any arbitrary variable name as
171-
either of:
172-
173-
$::{'!@#$#@'}
174-
::{'$!@#$#@'}
175-
176-
You can also use the C<< ::<> >> form as long as there are no spaces in the
177-
name.
178-
179-
=head3 Package lookup
180-
181-
Subscript the package object itself as a hash object, the key of which is
182-
the variable name, including any sigil. The package object can be derived
183-
from a type name by use of the C<::> postfix:
184-
185-
MyType::<$foo>
186-
187-
=head3 Globals
188-
189-
Interpreter globals live in the C<GLOBAL> package. The user's program
190-
starts in the C<GLOBAL> package, so "our" declarations in the mainline code
191-
go into that package by default. Process-wide variables live in the
192-
C<PROCESS> package. Most predefined globals such as C<$*UID> and C<$*PID>
193-
are actually process globals.
194-
19536
=head2 Loading and Basic Importing
19637
19738
Loading a module makes the packages in the same namespace declared

‎doc/Language/packages.pod

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
=begin pod
2+
3+
=TITLE Packages and Namespaces
4+
5+
=SUBTITLE Creating and referencing things
6+
7+
=begin comment
8+
9+
* Take a lot of stuff from S02 for this
10+
* Document 'import'
11+
12+
=end comment
13+
14+
=head2 Names
15+
16+
A I<name> is anything that is a legal part of a variable name (not counting
17+
the sigil). This includes
18+
19+
$foo # simple identifiers
20+
$Foo::Bar::baz # compound identifiers separated by ::
21+
$Foo::($bar)::baz # compound identifiers that perform interpolations
22+
$42 # numeric names
23+
$! # certain punctuational variables
24+
25+
When not used as a sigil, the semantic function of C<::> within a name is to
26+
force the preceding portion of the name to be considered a package through
27+
which the subsequent portion of the name is to be located. If the preceding
28+
portion is null, it means the package is unspecified and must be searched
29+
for according to the nature of what follows. Generally this means that an
30+
initial C<::> following the main sigil is a no-op on names that are known at
31+
compile time, though C<::()> can also be used to introduce an interpolation
32+
(see below). Also, in the absence of another sigil, C<::> can serve as its
33+
own sigil indicating intentional use of a not-yet-declared package name.
34+
35+
=head3 Package-qualified names
36+
37+
Ordinary package-qualified names look like:
38+
39+
$Foo::Bar::baz # the $baz variable in package Foo::Bar
40+
41+
Sometimes it's clearer to keep the sigil with the variable name, so an
42+
alternate way to write this is:
43+
44+
Foo::Bar::<$baz>
45+
46+
This is resolved at compile time because the variable name is a constant.
47+
48+
=head3 Pseudo-packages
49+
50+
The following pseudo-package names are reserved at the front of a name:
51+
52+
MY # Symbols in the current lexical scope (aka $?SCOPE)
53+
OUR # Symbols in the current package (aka $?PACKAGE)
54+
CORE # Outermost lexical scope, definition of standard Perl
55+
GLOBAL # Interpreter-wide package symbols, really UNIT::GLOBAL
56+
PROCESS # Process-related globals (superglobals)
57+
COMPILING # Lexical symbols in the scope being compiled
58+
59+
The following relative names are also reserved but may be used
60+
anywhere in a name:
61+
62+
CALLER # Contextual symbols in the immediate caller's lexical scope
63+
CALLERS # Contextual symbols in any caller's lexical scope
64+
DYNAMIC # Contextual symbols in my or any caller's lexical scope
65+
OUTER # Symbols in the next outer lexical scope
66+
OUTERS # Symbols in any outer lexical scope
67+
LEXICAL # Contextual symbols in my or any outer's lexical scope
68+
UNIT # Symbols in the outermost lexical scope of compilation unit
69+
SETTING # Lexical symbols in the unit's DSL (usually CORE)
70+
PARENT # Symbols in this package's parent package (or lexical scope)
71+
CLIENT # The nearest CALLER that comes from a different package
72+
73+
The file's scope is known as C<UNIT>, but there are one or more lexical
74+
scopes outside of that corresponding to the linguistic setting (often known
75+
as the prelude in other cultures). Hence, the C<SETTING> scope is
76+
equivalent to C<UNIT::OUTERS>. For a standard Perl program C<SETTING> is the
77+
same as C<CORE>, but various startup options (such as C<-n> or C<-p>) can
78+
put you into a domain specific language, in which case C<CORE> remains the
79+
scope of the standard language, while C<SETTING> represents the scope
80+
defining the DSL that functions as the setting of the current file. When used
81+
as a search term in the middle of a name, C<SETTING> includes all its outer scopes
82+
up to C<CORE>. To get I<only> the setting's outermost scope, use C<UNIT::OUTER> instead.
83+
84+
=head3 Interpolating into names
85+
86+
You may interpolate a string into a package or variable name using
87+
C<::($expr)> where you'd ordinarily put a package or variable name. The
88+
string is allowed to contain additional instances of C<::>, which will be
89+
interpreted as package nesting. You may only interpolate entire names,
90+
since the construct starts with C<::>, and either ends immediately or is
91+
continued with another C<::> outside the parens. Most symbolic references
92+
are done with this notation:
93+
94+
$foo = "Bar";
95+
$foobar = "Foo::Bar";
96+
$::($foo) # lexically-scoped $Bar
97+
$::("MY::$foo") # lexically-scoped $Bar
98+
$::("OUR::$foo") # package-scoped $Bar
99+
$::("GLOBAL::$foo") # global $Bar
100+
$::("PROCESS::$foo")# process $Bar
101+
$::("PARENT::$foo") # current package's parent's $Bar
102+
$::($foobar) # $Foo::Bar
103+
$::($foobar)::baz # $Foo::Bar::baz
104+
$::($foo)::Bar::baz # $Bar::Bar::baz
105+
$::($foobar)baz # ILLEGAL at compile time (no operator baz)
106+
107+
Note that unlike in Perl 5, initial C<::> doesn't imply global. Here as part
108+
of the interpolation syntax it doesn't even imply package. After the
109+
interpolation of the C<::()> component, the indirect name is looked up exactly
110+
as if it had been there in the original source code, with priority given first
111+
to leading pseudo-package names, then to names in the lexical scope (searching
112+
scopes outwards, ending at C<CORE>). The current package is searched last.
113+
114+
Use the C<MY> pseudopackage to limit the lookup to the current lexical
115+
scope, and C<OUR> to limit the scopes to the current package scope.
116+
117+
=head3 Direct lookup
118+
119+
To do direct lookup in a package's symbol table without scanning, treat the
120+
package name as a hash:
121+
122+
Foo::Bar::{'&baz'} # same as &Foo::Bar::baz
123+
PROCESS::<$IN> # Same as $*IN
124+
Foo::<::Bar><::Baz> # same as Foo::Bar::Baz
125+
126+
The C<::> before the subscript is required here, because the
127+
C<Foo::Bar{...}> syntax is reserved for attaching a "WHENCE" initialization
128+
closure to an autovivifiable type object. (see S12).
129+
130+
Unlike C<::()> symbolic references, this does not parse the argument for
131+
C<::>, nor does it initiate a namespace scan from that initial point. In
132+
addition, for constant subscripts, it is guaranteed to resolve the symbol at
133+
compile time.
134+
135+
The null pseudo-package is reserved to mean the same search list as an
136+
ordinary name search. That is, the following are all identical in meaning:
137+
138+
$foo
139+
$::{'foo'}
140+
::{'$foo'}
141+
$::<foo>
142+
::<$foo>
143+
144+
That is, each of them scans lexical scopes outward, and then the current
145+
package scope (though the package scope is then disallowed when "strict" is
146+
in effect).
147+
148+
As a result of these rules, you can write any arbitrary variable name as
149+
either of:
150+
151+
$::{'!@#$#@'}
152+
::{'$!@#$#@'}
153+
154+
You can also use the C<< ::<> >> form as long as there are no spaces in the
155+
name.
156+
157+
=head3 Package lookup
158+
159+
Subscript the package object itself as a hash object, the key of which is
160+
the variable name, including any sigil. The package object can be derived
161+
from a type name by use of the C<::> postfix:
162+
163+
MyType::<$foo>
164+
165+
=head3 Globals
166+
167+
Interpreter globals live in the C<GLOBAL> package. The user's program
168+
starts in the C<GLOBAL> package, so "our" declarations in the mainline code
169+
go into that package by default. Process-wide variables live in the
170+
C<PROCESS> package. Most predefined globals such as C<$*UID> and C<$*PID>
171+
are actually process globals.
172+
173+
=end pod

‎doc/Language/syntax.pod

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -237,7 +237,7 @@ Named entities, such as variables, constants, classes, modules, subs, etc, are
237237
part of a namespace. Nested parts of a name use C<::> to separate the
238238
heirarchy. Some examples:
239239
240-
See the L<documentaton on modules|/language/modules> for more details.
240+
See the L<documentaton on packages|/language/packages> for more details.
241241
242242
243243
=head2 Literals

0 commit comments

Comments
 (0)