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...
}
}
