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