Author: Darren_Duncan Date: 2009-07-05 05:43:57 +0200 (Sun, 05 Jul 2009) New Revision: 27413
Modified: docs/Perl6/Spec/S02-bits.pod docs/Perl6/Spec/S11-modules.pod docs/Perl6/Spec/S12-objects.pod docs/Perl6/Spec/S19-commandline.pod docs/Perl6/Spec/S21-calling-foreign-code.pod Log: P6 Synopsis : with module full names, reversed canonical order of :auth and :ver so :auth is first Modified: docs/Perl6/Spec/S02-bits.pod =================================================================== --- docs/Perl6/Spec/S02-bits.pod 2009-07-05 02:53:43 UTC (rev 27412) +++ docs/Perl6/Spec/S02-bits.pod 2009-07-05 03:43:57 UTC (rev 27413) @@ -2416,8 +2416,8 @@ extensions, in which case the names matter but their order does not. These name the same module: + use ThatModule:auth<Somebody>:ver<2.7.18.28.18> use ThatModule:ver<2.7.18.28.18>:auth<Somebody> - use ThatModule:auth<Somebody>:ver<2.7.18.28.18> Adverbial syntax will be described more fully later. Modified: docs/Perl6/Spec/S11-modules.pod =================================================================== --- docs/Perl6/Spec/S11-modules.pod 2009-07-05 02:53:43 UTC (rev 27412) +++ docs/Perl6/Spec/S11-modules.pod 2009-07-05 03:43:57 UTC (rev 27413) @@ -328,7 +328,7 @@ you're really only giving one part of the name of the module. The full name of the module or class includes other metadata, -in particular, the version, and the author. +in particular, the author, and the version. Modules posted to CPAN or entered into any standard Perl 6 library are required to declare their full name so that installations can know @@ -371,20 +371,20 @@ 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). +first. The required parts for library insertion are the short name of the +class/module, a URI identifying the author (or authorizing authority, so we +call it "auth" to be intentionally ambiguous), and its version number. 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:jran...@some.com>; + class Dog:auth<cpan:JRANDOM>:ver<1.2.1>; + class Dog:auth<http://www.some.com/~jrandom>:ver<1.2.1>; + class Dog:auth<mailto:jran...@some.com>:ver<1.2.1>; 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> + class Dog:<cpan:JRANDOM 1.2.1> The pieces are interpreted as follows: @@ -397,11 +397,11 @@ =item * -Anything matching C<< v? [\d+ '.']* \d+ >> is treated as a version number +Anything matching C<< <alpha>+ \: \S+ >> is treated as an author(ity) =item * -Anything matching C<< <alpha>+ \: \S+ >> is treated as an author(ity) +Anything matching C<< v? [\d+ '.']* \d+ >> is treated as a version number =back @@ -411,11 +411,11 @@ 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> + class Pooch:name<Dog>:auth<cpan:JRANDOM>:ver<1.2.1> or - class Pooch:<Dog 1.2.1 cpan:JRANDOM> + class Pooch:<Dog cpan:JRANDOM 1.2.1> for short. @@ -434,7 +434,7 @@ you're really wildcarding the unspecified bits: - use Dog:ver(Any):auth(Any); + use Dog:auth(Any):ver(Any); And when you say: @@ -442,7 +442,7 @@ you're really asking for: - use Dog:ver<1.2.1>:auth(Any); + use Dog:auth(Any):ver<1.2.1>; Saying C<1.2.1> specifies an I<exact> match on that part of the version number, not a minimum match. To match more than one version, @@ -495,8 +495,8 @@ For wildcards any valid smartmatch selector works: - use Dog:ver(v1.2.1 | v1.3.4):auth(/:i jrandom/); - use Dog:ver(Any):auth({ .substr(0,5) eq 'cpan:'}) + use Dog:auth(/:i jrandom/):ver(v1.2.1 | v1.3.4); + use Dog:auth({ .substr(0,5) eq 'cpan:'}):ver(Any); In any event, however you select the module, its full name is automatically aliased to the short name for the rest of your lexical @@ -506,15 +506,15 @@ and it knows (even if you don't) that you mean - my Dog:<1.3.4 cpan:JRANDOM> $spot .= new("woof"); + my Dog:<cpan:JRANDOM 1.3.4> $spot .= new("woof"); 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 Whiteness:from<perl5>:name<Acme::Bleach>:ver<1.12>:auth<cpan:DCONWAY>; - use Whiteness:from<perl5 Acme::Bleach 1.12 cpan:DCONWAY>; # same thing + use Whiteness:from<perl5>:name<Acme::Bleach>:auth<cpan:DCONWAY>:ver<1.12>; + use Whiteness:from<perl5 Acme::Bleach cpan:DCONWAY 1.12>; # same thing The string form of a version recognizes the C<*> wildcard in place of any position. It also recognizes a trailing C<+>, so @@ -551,19 +551,19 @@ To declare that a module emulates an older version, declare it like this: - class Dog:<1.2.1 cpan:JRANDOM> emulates :<1.2.0>; + class Dog:<cpan:JRANDOM 1.2.1> emulates :<1.2.0>; Or to simply exclude use of the older module and (presumably) force the user to upgrade: - class Dog:<1.2.1 cpan:JRANDOM> excludes :<1.2.0>; + class Dog:<cpan:JRANDOM 1.2.1> excludes :<1.2.0>; The name is parsed like a C<use> wildcard, and you can have more than one, so you can say things like: - class Dog:<1.2.1 cpan:JRANDOM> + class Dog:<cpan:JRANDOM 1.2.1> emulates Dog:auth(DCONWAY|JCONWAY|TCONWAY):ver<1.0+> - excludes Fox:<3.14159 http://oreillymedia.com> + excludes Fox:<http://oreillymedia.com 3.14159> emulates Wolf:from<C# 0.8..^1.0>; =head1 Forcing Perl 6 @@ -582,7 +582,7 @@ Those all specify the latest Perl 6 semantics, and are equivalent to - use Perl:ver(v6..*):auth(Any); + use Perl:auth(Any):ver(v6..*); To lock the semantics to 6.0.0, say one of: Modified: docs/Perl6/Spec/S12-objects.pod =================================================================== --- docs/Perl6/Spec/S12-objects.pod 2009-07-05 02:53:43 UTC (rev 27412) +++ docs/Perl6/Spec/S12-objects.pod 2009-07-05 03:43:57 UTC (rev 27413) @@ -1946,10 +1946,10 @@ Class traits may include: - identifier { :name<Dog> :ver<1.2.1> :auth<http://www.some.com/~jrandom> } + identifier { :name<Dog> :auth<http://www.some.com/~jrandom> :ver<1.2.1> } name Dog + authority http://www.some.com/~jrandom version v1.2.1 - authority http://www.some.com/~jrandom author Joe Random description This class implements camera obscura. subject optics, boxes Modified: docs/Perl6/Spec/S19-commandline.pod =================================================================== --- docs/Perl6/Spec/S19-commandline.pod 2009-07-05 02:53:43 UTC (rev 27412) +++ docs/Perl6/Spec/S19-commandline.pod 2009-07-05 03:43:57 UTC (rev 27413) @@ -483,7 +483,7 @@ C<--use *module*> and C<-u *module*> desugars to C<-e 'use *module*'>. Specify version info and import symbols by appending info to the module name: - -u'Sense:ver<1.2.1>:auth<cpan:JRANDOM> <common @horse>' + -u'Sense:auth<cpan:JRANDOM>:ver<1.2.1> <common @horse>' You'll need the quotes so your shell doesn't complain about redirection. There is no special command-line syntax for C<'no *module*>, use C<-e>. Modified: docs/Perl6/Spec/S21-calling-foreign-code.pod =================================================================== --- docs/Perl6/Spec/S21-calling-foreign-code.pod 2009-07-05 02:53:43 UTC (rev 27412) +++ docs/Perl6/Spec/S21-calling-foreign-code.pod 2009-07-05 03:43:57 UTC (rev 27413) @@ -37,8 +37,8 @@ from other languages. The C<from> adverb also parses any additional parts as short-form arguments. For instance: - 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 + use Whiteness:from<perl5>:name<Acme::Bleach>:auth<cpan:DCONWAY>:ver<1.12>; + use Whiteness:from<perl5 Acme::Bleach cpan:DCONWAY 1.12>; # same thing use libc:from<C>;