Author: larry
Date: Wed Mar  7 20:38:15 2007
New Revision: 14317

Modified:
   doc/trunk/design/syn/S02.pod
   doc/trunk/design/syn/S11.pod

Log:
Module longnames now specified in terms of ident plus adverbials.


Modified: doc/trunk/design/syn/S02.pod
==============================================================================
--- doc/trunk/design/syn/S02.pod        (original)
+++ doc/trunk/design/syn/S02.pod        Wed Mar  7 20:38:15 2007
@@ -2531,6 +2531,21 @@
         END
     }
 
+=item *
+
+A version literal are written with a 'v' followed by the version
+number in dotted form.  This always constructs a C<Version> object, not
+a string.  Only integers are allowed; for anything fancier you must
+coerce a string to a C<Version>:
+
+    v1.2.3                      # okay
+    v1.2.3beta                  # illegal
+    Version('1.2.3beta')        # okay
+
+Note though that most places that take a version number in Perl accept
+it as a named argument, in which case saying C<< :ver<1.2.3beta> >> is fine.
+See S11 for more on using versioned modules.
+
 =back
 
 =head1 Context

Modified: doc/trunk/design/syn/S11.pod
==============================================================================
--- doc/trunk/design/syn/S11.pod        (original)
+++ doc/trunk/design/syn/S11.pod        Wed Mar  7 20:38:15 2007
@@ -202,46 +202,72 @@
 where to keep them, such that multiple versions by different authors
 can coexist, all of them available to any installed version of Perl.
 
-The syntax of a versioned module or class declaration has three parts
-separated by hyphens.  The three parts are the short name of the
-class/module, its version number, and a URI identifying the author
-(or authorizing authority). For example:
-
-    class Dog-1.2.1-cpan:JRANDOM;
-    class Dog-1.2.1-http://www.some.com/~jrandom;
-    class Dog-1.2.1-mailto:[EMAIL PROTECTED];
-
-Such a declaration automatically aliases 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 syntax of a versioned module or class declaration has multiple
+parts in which the non-identifier parts are specified in adverbial pair
+notation without intervening spaces.  Internally these are stored in
+a canonical string form which you should ignore.  You may write the
+various parts in any order, except that the bare identifer must come
+first.  The required parts for library insertion are the short name of
+the class/module, its version number, and a URI identifying the author
+(or authorizing authority, so we call it "auth" to be intentionally ambiguous).
+For example:
+
+    class Dog:ver<1.2.1>:auth<cpan:JRANDOM>;
+    class Dog:ver<1.2.1>:auth<http://www.some.com/~jrandom>;
+    class Dog:ver<1.2.1>:auth<mailto:[EMAIL PROTECTED]>;
+
+Since these are somewhat unweildy to look at, we allow a shorthand in 
+which a bare subscripty adverb interprets its elements according to their
+form:
+
+    class Dog:<1.2.1 cpan:JRANDOM>
+
+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
+specified separately as another adverb, in which case the identifier
+indicates only the alias within the current lexical scope:
+
+    class Pooch:name<Dog>:ver<1.2.1>:auth<cpan:JRANDOM>
+
+or 
+
+    class Pooch:<Dog 1.2.1 cpan:JRANDOM>
+
+for short.
+
+Here the real name of the module starts C<Dog>, but we refer to it
+as C<Pooch> for the rest of this file.  Aliasing is handy if you need to
+interface to more than one module named C<Dog>
 
 If there are extra classes or modules or packages declared within
 the same file, they implicitly have a long name including the file's
 version and author, but you needn't declare them again.
 
-Since these long names are the actual names of the classes, when you say:
+Since these long names are the actual names of the classes as far as
+the library system is concerned, when you say:
 
     use Dog;
 
 you're really wildcarding the unspecified bits:
 
-    use Dog-(Any)-(Any);
+    use Dog:ver(Any):auth(Any);
 
 And when you say:
 
-    use Dog-1.2.1;
+    use Dog:<1.2.1>;
 
 you're really asking for:
 
-    use Dog-1.2.1-(Any);
+    use Dog:ver<1.2.1>:auth(Any);
 
 Saying C<1.2.1> specifies an I<exact> match on the version number,
 not a minimum match.  To match more than one version, put a range
 operator in parens:
 
-    use Dog-(1.2.1..1.2.3);
-    use Dog-(1.2.1..^1.3);
-    use Dog-(1.2.1..*);
+    use Dog:ver(1.2.1..1.2.3);
+    use Dog:ver(1.2.1..^1.3);
+    use Dog:ver(1.2.1..*);
 
 Subversions are wildcarded, so C<1.2> really means C<1.2.*>.  If you
 say:
@@ -250,45 +276,45 @@
 
 which is short for:
 
-    use Perl-6;
+    use Perl:ver<6>;
 
-you're asking for any version of Perl 6.  You need to say:
+you're asking for any version of Perl 6.  You need to say something like
 
-    use Perl-6.0;
-    use Perl-6.0.0;
-    use Perl-6.2.7.1;
+    use Perl:<6.0>;
+    use Perl:<6.0.0>;
+    use Perl:<6.2.7.1>;
 
 if you want to lock in a particular set of semantics at some greater
 degree of specificity.  And if some large company ever forks Perl, you can say
+something like:
 
-    use Perl-6-cpan:TPF
+    use Perl:auth<cpan:TPF>
 
 to guarantee that you get the unembraced Perl.  C<:-)>
 
-Perl is the default module name, so this means the same thing:
-
-    use v6-cpan:TPF;
-
+To allow a version specification that works with both Perl 5 and 6, we
+use variants of the "v6" pseudomodule.  This form specifically allows
+use of a subsequent hyphenated identifier.
 Before the full specification of Perl 6.0.0 is released, you can use C<alpha>
-as the author slot to denote a program using syntax that is still subject
+to denote a program using syntax that is still subject
 to change:
 
     use v6-alpha;
 
+Later on
+
+    use v6-std;
+
+will indicate standard version 6 of Perl.
+
 The C<use v6-alpha> line also serves as the Perl 5 incantation to switch to
 Perl 6 parsing.  In Perl 5 this actually ends up calling the v6.pm module with 
a
 C<-alpha> argument, for insane-but-useful reasons.
 
 For wildcards any valid smartmatch selector works:
 
-    use Dog-(1.2.1 | 1.3.4)-(/:i jrandom/);
-    use Dog-(Any)-(/^cpan\:/)
-
-Parens are optional on a closure smartmatcher.  The preceding may
-also be written:
-
-    use Dog-{$^ver ~~ 1.2.1 | 1.3.4}-{$^auth ~~ /:i jrandom/};
-    use Dog-{$^ver ~~ Any}-{$^auth ~~ /^cpan\:/}
+    use Dog:ver(1.2.1 | 1.3.4):auth(/:i jrandom/);
+    use Dog:ver(Any):auth({ .substr(0,5) eq 'cpan:'})
 
 In any event, however you select the module, its full name is
 automatically aliased to the short name for the rest of your lexical
@@ -298,23 +324,25 @@
 
 and it knows (even if you don't) that you mean
 
-    my Dog-1.3.4-cpan:JRANDOM $spot .= new("woof");
+    my Dog:<1.3.4 cpan:JRANDOM> $spot .= new("woof");
 
-The C<use> statement actually allows a language on the front of a module name,
-so that you can use modules from other languages.  The language is separated
-by a colon.  For instance:
+The C<use> statement allows an external language to be specified in
+addition to (or instead of) an authority, so that you can use modules
+from other languages.  The C<from> adverb also parses any additional
+parts as short-form arguments.  For instance:
 
-    use perl5:Acme::Bleach-1.12-DCONWAY;
-    use ruby:Rails <PR_MACHINE>;
+    use Whiteness:from<perl5>:name<Acme::Bleach>ver<1.12>:auth<cpan:DCONWAY>;
+    use Whiteness:from<perl5 Acme::Bleach 1.12 cpan:DCONWAY>;  # same thing
 
 =head1 Forcing Perl 6
 
 To get Perl 6 parsing rather than the default Perl 5 parsing,
 we said you could force Perl 6 mode in your main program with:
 
-    use Perl-6;
+    use v6-alpha;
 
-Actually, you can just start your main program with any of:
+Actually, if you're running a parser that is aware of Perl 6, you
+can just start your main program with any of:
 
     use v6;
     module;
@@ -322,10 +350,12 @@
 
 Those all specify the latest Perl 6 semantics, and are equivalent to
 
-    use Perl-(v6..*)-(Any);
+    use Perl:ver(v6..*):auth(Any);
 
-To lock the semantics to 6.0.0, say:
+To lock the semantics to 6.0.0, say one of:
 
+    use Perl:ver<6.0.0>;
+    use :<6.0.0>;
     use v6.0.0;
 
 In any of those cases, strictures and warnings are the default
@@ -341,17 +371,17 @@
 a bare literal in a void context I<ought> to have produced a warning.
 (Invoking perl with C<-e6> has the same effect.)
 
-In the other direction, to inline Perl 5 code  inside a Perl 6 program,  put
+In the other direction, to inline Perl 5 code inside a Perl 6 program, put
 C<use v5> at the beginning of a lexical block.  Such blocks can nest 
arbitrarily
 deeply to switch between Perl versions:
 
-    use v6-alpha;
+    use v6-std;
     # ...some Perl 6 code...
     {
         use v5;
         # ...some Perl 5 code...
         {
-            use v6-alpha;
+            use v6-std;
             # ...more Perl 6 code...
         }
     }

Reply via email to