Changeset 10050

Timestamp:

04/21/06 17:39:01 (3 years ago)

Author:

yiyihu

Message:

Edit docs/Perl6/Makefile.PL. So that It will update docs/Perl6/Spec from "http://svn.perl.org/perl6/doc/trunk/design/syn" automatically.
In docs/Perl6/Spec/, S17.pod(Threads.pod) and S29.pod(Functions.pod) isn't in Spec yet, Added...
Update files in docs/Perl6/Spec too... :-)

Location:

docs/Perl6

Files:

• Makefile.PL (modified) (2 diffs)
• Spec/Functions.pod (added)
• Spec/Object.pod (modified) (2 diffs)
• Spec/Rule.pod (modified) (109 diffs)
• Spec/Subroutine.pod (modified) (5 diffs)
• Spec/Syntax.pod (modified) (3 diffs)
• Spec/Threads.pod (added)

docs/Perl6/Makefile.PL

@@ -2 +2 @@
 use lib "../..", "../../inc";
 use inc::Module::Install prefix => '../../inc';
+use File::Path;
 
 name       ('Perl6-Doc');
@@ -7 +8 @@
 license    ('perl');
 
+
+my $svn_path = "/usr/bin/svn";
+my $location = "http://svn.perl.org/perl6/doc/trunk/design/syn";
+my $synopsis_svn = "synopsis-svn";
+
+my %commands = ( 'checkout' => "$svn_path co $location $synopsis_svn",
+                 'update'   => "$svn_path update $synopsis_svn"
+                );
+
+my %table = ( 'S01' => 'Overview',
+              'S02' => 'Syntax',
+              'S03' => 'Operator',
+              'S04' => 'Block',
+              'S05' => 'Rule',
+              'S06' => 'Subroutine',
+#             'S07' => '',
+#             'S08' => '',
+              'S09' => 'Structure',
+              'S10' => 'Package',
+              'S11' => 'Module',
+              'S12' => 'Object',
+              'S13' => 'Overload',
+              'S17' => 'Threads',
+              'S29' => 'Functions'
+              );
+
+print "Checkout the newest Synopsis from $location\n";
+if ( -e $svn_path ) {
+        if( -d $synopsis_svn && ! -f $synopsis_svn) {
+#               system( $commands{'update'} );
+        } else {
+                system( $commands{'checkout'} );
+        }
+}
+print "Moving newest synopsis to Spec\n";
+for (keys %table) {
+        rename "$synopsis_svn/$_.pod", "Spec/$table{$_}.pod";
+}
+print "Removing temporary download directory.\n";
+rmtree $synopsis_svn, 0, 0;
+
+
 install_script( 'p6doc' );
 makemaker_args( PMLIBDIRS => [ grep { -d } glob("[A-Z]*") ]);

docs/Perl6/Spec/Object.pod

@@ -222 +222 @@
     .doit ()    # ILLEGAL (two terms in a row)
     .doit.()    # okay, no arguments, same as .doit()
-    .doit .()   # okay, no arguments, same as .doit()
+    .doit. .()  # okay, no arguments, same as .doit() (long dot form)
 
 However, you can turn any of the legal forms above into a list
@@ -231 +231 @@
     .doit (): 1,2,3     # ILLEGAL (two terms in a row)
     .doit.(1): 2,3      # okay, same as .doit(1,2,3)
-    .doit .(1,2): 3     # okay, same as .doit(1,2,3)
+    .doit. .(1,2): 3    # okay, same as .doit(1,2,3)
 
 In particular, this allows us to pass a closure in addition to the

docs/Perl6/Spec/Rule.pod

@@ -12 +12 @@
 =head1 VERSION
 
-   Maintainer: Patrick Michaud <pmichaud@pobox.com>
+   Maintainer: Patrick Michaud <pmichaud@pobox.com> and
+               Larry Wall <larry@wall.org>
    Date: 24 Jun 2002
-   Last Modified: 6 Apr 2006
+   Last Modified: 20 Apr 2006
    Number: 5
-   Version: 15
+   Version: 18
 
 This document summarizes Apocalypse 5, which is about the new regex
-syntax.  We now try to call them "rules" because they haven't been
-regular expressions for a long time.  (The term "regex" is still
-acceptable.)
+syntax.  We now try to call them I<regex> because they haven't been
+regular expressions for a long time.  When referring to their use in
+a grammar, the term I<rule> is preferred.
 
 =head1 New match state and capture variables
@@ -31 +32 @@
 C<$1>, etc.) are just elements of C<$/>.
 
-By the way, the numbered capture variables now start at C<$0>, C<$1>,
-C<$2>, etc. See below.
+By the way, the numbered capture variables now start at C<$0> rather than
+C<$1>.  See below.
 
 =head1 Unchanged syntactic features
@@ -69 +70 @@
 
 The extended syntax (C</x>) is no longer required...it's the default.
+(In fact, it's pretty much mandatory--the only way to get back to
+the old syntax is with the C<:Perl5>/C<:P5> modifier.)
 
 =item *
@@ -79 +82 @@
 There is no C</e> evaluation modifier on substitutions; instead use:
 
-     s/pattern/{ code() }/
+     s/pattern/{ doit() }/
+
+Instead of C</ee> say:
+
+     s/pattern/{ eval doit() }/
 
 =item *
@@ -88 +95 @@
 
 Every modifier must start with its own colon.  The delimiter must be
-separated from the final modifier by a colon or whitespace if it would
-be taken as an argument to the preceding modifier.
+separated from the final modifier by whitespace if it would be taken
+as an argument to the preceding modifier (which is true for any
+bracketing character).
 
 =item *
@@ -120 +128 @@
 Since this is implicitly anchored to the position, it's suitable for
 building parsers and lexers.  The pattern you supply to a Perl macro's
-"is parsed" trait has an implicit C<:p> modifier.
+C<is parsed> trait has an implicit C<:p> modifier.
 
 Note that
@@ -128 +136 @@
 is roughly equivalent to
 
-     m:p/.*? pattern/
-
-=item *
-
-The new C<:once> modifier replaces the Perl 5 C<?...?> syntax:
-
-     m:once/ pattern /    # only matches first time
-
-=item *
-
-[Note: We're still not sure if :w is ultimately going to work exactly 
-as described below.  But this is how it works for now.]
+     m:p/.*? <( pattern )> /
+
+Also note that any regex called as a subrule is implicitly anchored to the
+current position anyway.
+
+=item *
 
 The new C<:w> (C<:words>) modifier causes whitespace sequences to be
@@ -164 +166 @@
 C<< <?ws> >> can't decide what to do until it sees the data.  It still does
 the right thing.  If not, define your own C<< <?ws> >> and C<:w> will use that.
+
+In general you don't need to use C<:w> within grammars because
+the parser rules automatically handle whitespace policy for you.
 
 =item *
@@ -178 +183 @@
 =item *
 
-The new C<:perl5> modifier allows Perl 5 regex syntax to be used instead:
-
-     m:perl5/(?mi)^[a-z]{1,2}(?=\s)/
+The new C<:Perl5> modifier allows Perl 5 regex syntax to be used instead:
+
+     m:Perl5/(?mi)^[a-z]{1,2}(?=\s)/
 
 (It does not go so far as to allow you to put your modifiers at
@@ -195 +200 @@
 general form.  So
 
-     s:4x { (<?ident>) = (\N+) $$}{$0 => $1};
+     s:4x [ (<?ident>) = (\N+) $$] [$0 => $1];
 
 is the same as:
 
-     s:x(4) { (<?ident>) = (\N+) $$}{$0 => $1};
+     s:x(4) [ (<?ident>) = (\N+) $$] [$0 => $1];
 
 which is almost the same as:
 
      $_.pos = 0;
-     s:c{ (<?ident>) = (\N+) $$}{$0 => $1} for 1..4;
+     s:c [ (<?ident>) = (\N+) $$] [$0 => $1] for 1..4;
 
 except that the string is unchanged unless all four matches are found.
@@ -231 +236 @@
 =item *
 
-With the new C<:ov> (C<:overlap>) modifier, the current rule will
+With the new C<:ov> (C<:overlap>) modifier, the current regex will
 match at all possible character positions (including overlapping)
 and return all matches in a list context, or a disjunction of matches
@@ -239 +244 @@
 
      if $str ~~ m:overlap/ a (.*) a / {
-         @substrings = $/.matches();    # bracadabr cadabr dabr br
-     }
-
-=item *
-
-With the new C<:ex> (C<:exhaustive>) modifier, the current rule will match
+         @substrings = @;();    # bracadabr cadabr dabr br
+     }
+
+=item *
+
+With the new C<:ex> (C<:exhaustive>) modifier, the current regex will match
 every possible way (including overlapping) and return all matches in a list
 context, or a disjunction of matches in a scalar context.
@@ -251 +256 @@
 
      if $str ~~ m:exhaustive/ a (.*) a / {
-         @substrings = $/.matches();    # br brac bracad bracadabr
-                                        # c cad cadabr d dabr br
-     }
-
-
-=item *
-
-The new C<:rw> modifier causes this rule to "claim" the current
+         say "@()";    # br brac bracad bracadabr c cad cadabr d dabr br
+     }
+
+Note that the C<~~> above can return as soon as the first match is found,
+and the rest of the matches may be performed lazily by C<@()>.
+
+[Conjecture: the C<:exhaustive> modifier should have an optional argument
+specifying how many seconds to run before giving up, since it's trivially
+easy to ask for the heat death of the universe to happen first.]
+
+=item *
+
+The new C<:rw> modifier causes this regex to I<claim> the current
 string for modification rather than assuming copy-on-write semantics.
 All the bindings in C<$/> become lvalues into the string, such
@@ -269 +279 @@
 =item *
 
-The new C<:keepall> modifier causes this rule and all invoked subrules
+The new C<:keepall> modifier causes this regex and all invoked subrules
 to remember everything, even if the rules themselves don't ask for
 their subrules to be remembered.  This is for forcing a grammar that
@@ -276 +286 @@
 =item *
 
-The C<:i>, C<:w>, C<:perl5>, and Unicode-level modifiers can be
-placed inside the rule (and are lexically scoped):
+The new C<:ratchet> modifier causes this regex to not backtrack by default.
+(Generally you do not use this modifier directly, since it's implied by
+C<token> and C<rule> declarations.)  The effect of this modifier is
+to imply a C<:> after every construct that could backtrack, including
+bare C<*>, C<+>, and C<?> quantifiers, as well as alternations.
+
+=item *
+
+The new C<:panic> modifier causes this regex and all invoked subrules
+to try to backtrack on any rules that would otherwise default to
+not backtracking because they have C<:ratchet> set.  Never panic
+unless you're desperate and want the pattern matcher to do a lot of
+unnecessary work.  If you have an error in your grammar, it's almost
+certainly a bad idea to fix it by backtracking.
+
+=item *
+
+The C<:i>, C<:w>, C<:Perl5>, and Unicode-level modifiers can be
+placed inside the regex (and are lexically scoped):
 
      m/:w alignment = [:i left|right|cent[er|re]] /
@@ -298 +325 @@
 
          m:fuzzy (pattern);
-         m:fuzzy:(pattern);
 
 or you'll end up with:
@@ -347 +373 @@
 =item *
 
-An unescaped C<#> now always introduces a comment.
+An unescaped C<#> now always introduces a comment.  If followed
+by an opening bracket character (and if not in the first column),
+it introduces an embedded comment that terminates with the closing
+bracket.  Otherwise the comment terminates at the newline.
 
 =item *
@@ -367 +396 @@
 =item *
 
-C<.> matches an "anything", while C<\N> matches an "anything except
-newline". (The C</s> modifier is gone.)  In particular, C<\N> matches
+C<.> matches an I<anything>, while C<\N> matches an I<anything except
+newline>. (The C</s> modifier is gone.)  In particular, C<\N> matches
 neither carriage return nor line feed.
 
@@ -401 +430 @@
 =item *
 
-You can call Perl code as part of a rule match by using a closure.
+You can call Perl code as part of a regex match by using a closure.
 Embedded code does not usually affect the match--it is only used
 for side-effects:
@@ -424 +453 @@
 with a corresponding C<**{...}?> for minimal matching.  Space is
 allowed on either side of the asterisks.  The curlies are taken to
-be a closure returning a number or a range.
+be a closure returning an Int or a Range object.
 
      / value was (\d ** {1..6}?) with ([\w]**{$m..$n}) /
@@ -432 +461 @@
      / [foo]**{1,3} /
 
-(At least, it fails in the absence of "C<use rx :listquantifier>",
+(At least, it fails in the absence of C<use rx :listquantifier>,
 which is likely to be unimplemented in Perl 6.0.0 anyway).
 
@@ -439 +468 @@
 a closure that must be run in the general case, so you can use
 it to generate a range on the fly based on the earlier matching.
-(Of course, bear in mind the closure is run I<before> attempting to
+(Of course, bear in mind the closure must be run I<before> attempting to
 match whatever it quantifies.)
 
 =item *
 
-C<< <...> >> are now extensible metasyntax delimiters or "assertions"
+C<< <...> >> are now extensible metasyntax delimiters or I<assertions>
 (i.e. they replace Perl 5's crufty C<(?...)> syntax).
 
@@ -455 +484 @@
 =item *
 
-In Perl 6 rules, variables don't interpolate.
-
-=item *
-
-Instead they're passed "raw" to the rule engine, which can then decide
+In Perl 6 regexes, variables don't interpolate.
+
+=item *
+
+Instead they're passed I<raw> to the regex engine, which can then decide
 how to handle them (more on that below).
 
@@ -474 +503 @@
      / \Q$var\E /
 
-(To get rule interpolation use an assertion - see below)
+However, if C<$var> contains a Regex object, rather attempting to
+convert it to a string, it is called as a subrule, as if you said
+C<< <$var> >>.  (See assertions below.)  This form does not capture,
+and it fails if C<$var> is tainted.
 
 =item *
@@ -487 +519 @@
 
 
-As with a scalar variable, each element is matched as a literal.
+As with a scalar variable, each element is matched as a literal
+unless it happens to be a Regex object, in which case it is matched
+as a subrule.  As with scalar subrules, a tainted subrule always fails.
+All values pay attention to the current C<:ignorecase> setting.
 
 =item *
@@ -504 +539 @@
 =item *
 
-If it is a string or rule object, it is executed as a subrule.
-
-=item *
-
-If it has the value 1, nothing special happens beyond the match.
+If the value is a string, it is matched literally, starting after where
+the key left off matching.  As a natural consequence, if the value is
+C<"">, nothing special happens except that the key match succeeds.
+
+=item *
+
+If it is a Regex object, it is executed as a subrule, with an initial
+position I<after> the matched key.  As with scalar subrules, a tainted
+subrule always fails, and no capture is attempted.
+
+=item *
+
+If the value is a number, the key is rematched ignoring any keys
+longer than the number.  (This is measured in the default Unicode
+level in effect where the hash was declared, usually graphemes. If
+the current Unicode level is lower, the results are as if the string
+to be matched had been upconverted to the hash's Unicode level.  If
+the current Unicode level is higher, the results are undefined if the
+string contains any characters whose interpretation would be changed
+by the higher Unicode level, such as language-dependent ligatures.)
 
 =item *
@@ -516 +566 @@
 =back
 
+All hash keys, and values that are strings, pay attention to the
+C<:ignorecase> setting.  (Subrules maintain their own case settings.)
+
 =back
 
@@ -524 +577 @@
 =item *
 
-The first character after C<< < >> determines the behaviour of the assertion.
+The first character after C<< < >> determines the behavior of the assertion.
 
 =item *
@@ -540 +593 @@
      / <after pattern> /     # was /(?<pattern)/
 
-     / <ws> /                # match whitespace by :w rules
+     / <ws> /                # match whitespace by :w policy
 
      / <sp> /                # match a space char
@@ -548 +601 @@
 It is illegal to do lookbehind on a pattern that cannot be reversed.
 
+Note: the effect of a forward-scanning lookbehind at the top level
+can be achieved with:
+
+    / .*? prestuff <( mainpat )> /
+
 =item *
 
@@ -557 +615 @@
      / <?ident> <?ws> /      # nothing captured
 
-=item *
-
-A leading C<$> indicates an indirect rule.  The variable must contain
-either a hard reference to a rule, or a string containing the rule.
-
-=item *
-
-A leading C<::> indicates a symbolic indirect rule:
-
-     / <::($somename)>
-
-The variable must contain the name of a rule.
-
-=item *
-
-A leading C<@> matches like a bare array except that each element
-is treated as a rule (string or hard ref) rather than as a literal.
-
-=item *
-
-A leading C<%> matches like a bare hash except that each key
-is treated as a rule (string or hard ref) rather than as a literal.
-
-=item *
-
-A leading C<{> indicates code that produces a rule to be interpolated
-into the pattern at that point:
+The non-capturing behavior may be overridden with a C<:keepall>.
+
+=item *
+
+A leading C<$> indicates an indirect subrule.  The variable must contain
+either a Regex object, or a string to be compiled as the regex.  The
+string is never matched literally.
+
+By default C<< <$foo> >> is captured into C<< $<foo> >>, but you can
+use the C<< <?$foo> >> form to suppress capture, and you can always say
+C<< $<$foo> := <$foo> >> if you prefer to include the sigil in the key.
+
+=item *
+
+A leading C<::> indicates a symbolic indirect subrule:
+
+     / <::($somename)> /
+
+The variable must contain the name of a subrule.  By the rules of
+single method dispatch this is first searched for in the current
+grammar and its ancestors.  If this search fails an attempt is made
+to dispatch via MMD, in which case it can find subrules defined as
+multis rather than methods.  This form is not captured by default.
+
+=item *
+
+A leading C<@> matches like a bare array except that each element is
+treated as a subrule (string or Regex object) rather than as a literal.
+That is, a string is forced to be compiled as a subrule rather than
+matched literally.  (There is no difference for a Regex object.)
+
+By default C<< <@foo> >> is captured into C<< $<foo> >>, but you can
+use the C<< <?@foo> >> form to suppress capture, and you can always say
+C<< $<@foo> := <@foo> >> if you prefer to include the sigil in the key.
+
+=item *
+
+A leading C<%> matches like a bare hash except that each value is
+always treated as a subrule, even if it is a string that must be compiled
+to a regex at match time.
+
+By default C<< <%foo> >> is captured into C<< $<foo> >>, but you can
+use the C<< <?%foo> >> form to suppress capture, and you can always say
+C<< $<%foo> := <%foo> >> if you prefer to include the sigil in the key.
+
+With both bare hash and hash in angles, the key is always skipped
+over before calling any subrule in the value.  That subrule may, however,
+magically access the key anyway as if the subrule had started before the
+key and matched with C<< <KEY> >> assertion.  That is, C<< $<KEY> >>
+will contain the keyword or token that this subrule was looked up under,
+and that value will be returned by the current match object even if
+you do nothing special with it within the match.  (This also works
+for the name of a macro as seen from an C<is parsed> regex, since
+internally that turns into a hash lookup.)
+
+As with bare hash, the longest key matches according to the venerable
+I<longest token rule>, but in addition, you may combine multiple hashes
+under the same longest-token consideration like this:
+
+    <%statement|%prefix|%term>
+
+This means that, despite being in a later hash, C<< %term<food> >>
+will be selected in preference to C<< %prefix<foo> >> because it's
+the longer token.  However, if there is a tie, the earlier hash wins,
+so C<< %statement<if> >> hides any C<< %prefix<if> >> or C<< %term<if> >>.
+
+In contrast, if you say
+
+    [ <%prefix> | <%term> ]
+
+a C<< %prefix<foo> >> would be selected in preference to a C<< %term<food> >>.
+(Which is not what you usually want if your language is to do longest-token
+consistently.)
+
+=item *
+
+A leading C<{> indicates code that produces a regex to be interpolated
+into the pattern at that point as a subrule:
 
      / (<?ident>)  <{ %cache{$0} //= get_body($0) }> /
@@ -590 +699 @@
 
 As with an ordinary embedded closure, an B<explicit> return from a
-rule closure binds the I<result object> for this match, ignores the
-rest of the current rule, and reports success:
-
-        / (\d) <{ return $0.sqrt }> NotReached /;
+regex closure binds the I<result object> for this match, ignores the
+rest of the current regex, and reports success:
+
+        / (\d) <{ return $0.sqrt }> NotReached /;
 
 This has the effect of capturing the square root of the numified string,
@@ -604 +713 @@
 
 A leading C<&> interpolates the return value of a subroutine call as
-a rule.  Hence
+a regex.  Hence
 
      <&foo()>
@@ -614 +723 @@
 =item *
 
-In any case of rule interpolation, if the value already happens to be
-a rule object, it is not recompiled.  If it is a string, the compiled
+In any case of regex interpolation, if the value already happens to be
+a Regex object, it is not recompiled.  If it is a string, the compiled
 form is cached with the string so that it is not recompiled next
 time you use it unless the string changes.  (Any external lexical
@@ -621 +730 @@
 interpolated with unbalanced bracketing.  An interpolated subrule
 keeps its own inner C<$/>, so its parentheses never count toward the
-outer rules groupings.  (In other words, parenthesis numbering is always
+outer regexes groupings.  (In other words, parenthesis numbering is always
 lexically scoped.)
 
@@ -654 +763 @@
     / <after foo> \d+ <before bar> /
 
-except that the scan for "foo" can be done in the forward direction,
-while a lookbehind assertion would presumably scan for \d+ and then
-match "foo" backwards.  The use of C<< <(...)> >> affects only the
-meaning of the "result object" and the positions of the beginning and
+except that the scan for "C<foo>" can be done in the forward direction,
+while a lookbehind assertion would presumably scan for C<\d+> and then
+match "C<foo>" backwards.  The use of C<< <(...)> >> affects only the
+meaning of the I<result object> and the positions of the beginning and
 ending of the match.  That is, after the match above, C<$()> contains
 only the digits matched, and C<.pos> is pointing to after the digits.
@@ -663 +772 @@
 through C<$/>.
 
+It is a syntax error to use an unbalanced C<< <( >> or C<< )> >>.
+
 =item *
 
@@ -718 +829 @@
      / <!before _ > /    # We aren't before an _
 
+Note that C<< <!alpha> >> is different from C<< <-alpha> >> because the
+latter matches C</./> when it is not an alpha.
+
+=item *
+
+Conjecture: Multiple opening angles are matched by a corresponding
+number of closing angles, and otherwise function as single angles.
+This can be used to visually isolate unmatched angles inside:
+
+    <<<Ccode: a >> 1>>>
+
 =back
 
@@ -732 +854 @@
 
 The C<\L...\E>, C<\U...\E>, and C<\Q...\E> sequences are gone.  In the
-rare cases that need them you can use C<< <{ lc $rule }> >> etc.
+rare cases that need them you can use C<< <{ lc $regex }> >> etc.
 
 =item *
@@ -800 +922 @@
 =back
 
-=head1 Regexes are rules
+=head1 Regexes really are regexes now
 
 =over
@@ -812 +934 @@
 The Perl 6 equivalents are:
 
-     rule { pattern }    # always takes {...} as delimiters
-       rx / pattern /    # can take (almost any) chars as delimiters
+     regex { pattern }    # always takes {...} as delimiters
+        rx / pattern /    # can take (almost any) chars as delimiters
 
 You may not use whitespace or alphanumerics for delimiters.  Space is
 optional unless needed to distinguish from modifier arguments or
 function parens.  So you may use parens as your C<rx> delimiters,
-but only if you interpose a colon or whitespace:
-
-     rx:( pattern )      # okay
+but only if you interpose whitespace:
+
      rx ( pattern )      # okay
      rx( 1,2,3 )         # tries t