Author: larry
Date: Tue Apr 24 18:29:02 2007
New Revision: 14381
Modified:
doc/trunk/design/syn/S11.pod
Log:
Clarifications to module naming suggested by TheDamian++.
Modified: doc/trunk/design/syn/S11.pod
==============================================================================
--- doc/trunk/design/syn/S11.pod (original)
+++ doc/trunk/design/syn/S11.pod Tue Apr 24 18:29:02 2007
@@ -12,9 +12,9 @@
Maintainer: Larry Wall <[EMAIL PROTECTED]>
Date: 27 Oct 2004
- Last Modified: 16 Apr 2007
+ Last Modified: 24 Apr 2007
Number: 11
- Version: 18
+ Version: 19
=head1 Overview
@@ -44,9 +44,10 @@
or use the sigil-like C<::ModuleName> syntax. The C<::> prefix does not
imply top-levelness as it does in Perl 5. (Use C<::*> or C<GLOBAL::> for
that.)
-A bare C<module> declarator declares an C<our> module name in the current
-package. At the start of the file, the current package is C<*>, so the
-first declaration in the file is automatically global.
+A bare (unscoped) C<module> declarator declares a nested C<our> module
+name within the current package. However, at the start of the file,
+the current package is C<*>, so the first such declaration in the
+file is automatically global.
You can use C<our module> to explicitly
declare a module in the current package (or module, or class).
@@ -149,25 +150,33 @@
=head1 Runtime Importation
-Importing via C<require> also binds into the current lexical scope by
-default, but performs the binding at runtime:
+Importing via C<require> also installs names into the current lexical scope by
+default, but delays the actual binding till runtime:
require Sense <common @horse>;
require "/home/non/Sense.pm" <common @horse>;
-Tagsets are not recognized in the default import list to C<:MY>, but you can
-explicitly request to put them into the C<:OUR> scope:
+Only explicitly mentioned names may be so installed. In order
+to protect the run-time sanctity of the lexical pad, it may not be
+modified by C<require>. Tagsets are assumed to be unknown at compile
+time, hence tagsets are not allowed in the default import list to
+C<:MY>, but you can explicitly request to put names into the C<:OUR>
+scope, since that is modifiable at run time:
require Sense <:ALL> # does not work
require Sense :MY<ALL> # this doesn't work either
require Sense :OUR<ALL> # but this works
-If the import list is omitted, then nothing is imported. Calling C<.import>
-at runtime cannot import into the lexical scope:
+If the import list is omitted, then nothing is imported. Since you
+may not modify the lexical pad, calling an importation routine at
+runtime cannot import into the lexical scope, and defaults to importation
+to the package scope instead:
require Sense;
Sense.EXPORTALL; # goes to the OUR scope by default, not MY
+(Such a routine I<may> rebind existing lexicals, however.)
+
=head1 Importing from a pseudo-package
You may also import symbols from the various pseudo-packages listed in S02.
@@ -236,6 +245,24 @@
class Dog:<1.2.1 cpan:JRANDOM>
+The pieces are interpreted as follows:
+=over
+
+=item *
+
+Anything matching C<< [<ident> '::']* <ident> >> is treated as a
+package name
+
+=item *
+
+Anything matching C<< v? [\d+ '.']* \d+ >> is treated as a version number
+
+=item *
+
+Anything matching C<< <alpha>+ \: \S+ >> is treated as an author(ity)
+
+=back
+
These declarations automatically alias the full name of the class
(or module) to the short name. So for the rest of the lexical scope,
C<Dog> refers to the longer name. The real library name can be
@@ -286,7 +313,8 @@
When specifying the version of your own module, C<1.2> is equivalent
to C<1.2.0>, C<1.2.0.0>, and so on. However C<use> searches for
modules matching a version prefix, so the subversions are wildcarded,
-and in this context C<1.2> really means C<1.2.*>. If you say:
+and in this context C<< :vers<1.2> >> really means C<< :vers<1.2.*> >>.
+If you say:
use v6;
