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;