Changeset 22445 for docs

Timestamp:

09/28/08 23:00:50 (2 months ago)

Author:

moritz

Message:

[docs/tutorial] book update
Including, but not limited to:

• optional params now have the ? after the name
• capture interpolation is done with prefix:<|> (used to be prefix:<*>)
• Chapter 7 is vastly out of date. Updated to use "regex" instead of "rule" (but got only half way), updated much other stuff, added a huge TODO list

Location:

docs/tutorial

Files:

• ch04_basic_syntax.pod (modified) (1 diff)
• ch05_subroutines.pod (modified) (15 diffs)
• ch07_grammars.pod (modified) (28 diffs)

docs/tutorial/ch04_basic_syntax.pod

@@ -466 +466 @@
 a boolean context, no matter what the actual value is. This particular
 property means the Perl 6 C<run> call can be checked with a simple
-conditional. It still returns the same numeric values it always has (0
-on success and a numeric error code on failure), but it flags the
-value with a property as true when the call succeeds and false when it
-fails.
+conditional. It still returns the same numeric values as its Perl 5
+equivalent C<system> did (0 on success and a numeric error code on failure),
+but it flags the value with a property as true when the call succeeds and
+false when it fails.
 
 Properties and traits can also store a value. Both C<constant> and

docs/tutorial/ch05_subroutines.pod

@@ -30 +30 @@
 Blocks of reusable code can also be called the "methods" of a particular
 class of object. Methods have a few significant differences from
-subroutines, a few significant differences from those found in Perl 5.
+subroutines, and a few significant differences from those found in Perl 5.
 For instance, in Perl 6 they're distinguished by a separate keyword,
 C<method>. Because of these differences, they'll be discussed in
@@ -73 +73 @@
 X<subroutines;parameters>
 One of the most significant additions to subroutines in Perl 6 is
-named formal parameters. The parameter list, often called the
+formal parameters. The parameter list, often called the
 I<signature> of the subroutine, is part of the subroutine declaration:
 
@@ -135 +135 @@
 for the average programmer, Perl 6 also allows optional parameters.
 Optional parameters can be included or ignored without causing any
-errors. Each optional parameter is marked with a C<?> before the
+errors. Each optional parameter is marked with a C<?> after the
 parameter name:
 
-  sub someopt ($required1, $required2, ?$optional1, ?$optional2) {
+  sub someopt ($required1, $required2, $optional1?, $optional2?) {
       ...
   }
@@ -243 +243 @@
   sub transport (:$planet, *%flags) {...}
 
-  transport('name'    => 'Arthur',
-            'luggage' => 'lost',
-            'planet'  => 'Magrathea',
-            'towel'   => 'required');
+  transport(:name('Arthur'),
+            :luggage('lost'),
+            :planet('Magrathea'),
+            :towel('required'));
 
 When they're combined with other kinds of parameters, variadic
@@ -268 +268 @@
 optional, named, or variadic parameters:
 
-  sub typedparams (Int $first, Str ?$second) {...}
+  sub typedparams (Int $first, Str $second?) {...}
 
 The parameter type declares the type of argument that can be bound to
@@ -322 +322 @@
 if the call doesn't pass an argument for that parameter.
 
-  sub default_vals ($required, ?$optional = 5) {...}
+  sub default_vals ($required, $optional? = 5) {...}
 
 Default values are only used with optional parameters. This should make
@@ -410 +410 @@
 optional parameters:
 
-  sub namedparams ($first, ?$second, ?$third is rw) {...}
+  sub namedparams ($first, $second?, $third? is rw) {...}
   
   namedparams(third => 'Trillian', first => $name);
@@ -426 +426 @@
 To get the Perl 5-style behavior where the elements of an array (or
 the pairs of a hash) flatten out into the parameter list, use the
-flattening operator C<*> in the call to the subroutine. Here,
+flattening operator C<|> in the call to the subroutine. Here,
 C<$first> binds to C<@array[0]> and C<$second> binds to C<@array[1]>:
 
   sub flat ($first, $second) {...}
   
-  flat(*@array);
+  flat(|@array);
 
 A flattened hash argument acts as a list of pairs, which are bound to
@@ -438 +438 @@
 C<%hash{'second'}>:
 
-  sub flat_hash ($first, $second) {...}
+  sub flat_hash (:$first, :$second) {...}
 
 
   %hash = (first => 1, second => 2);
-  flat_hash(*%hash);
+  flat_hash(|%hash);
 
 Flattened hash arguments are useful for building up hashes of named
@@ -489 +489 @@
 array:
 
-  sub mixed ($req, ?$opt, ?$another, *@slurpy) {...}
+  sub mixed ($req, $opt?, $another?, *@slurpy) {...}
 
   mixed('a', 'opt' => 1, 'b', 'c', 'd', 'e');
@@ -511 +511 @@
 array with or without any named arguments in the call:
 
-  sub mixed ($req, +$opt, +$another, *@slurpy) {...}
+  sub mixed ($req, $opt?, $another?, *@slurpy) {...}
 
   mixed('a', 'opt' => 1, 'b', 'c', 'd', 'e');
@@ -524 +524 @@
 X<subroutines;stub>
 To declare a subroutine without defining it you give it a body
-consisting of nothing but the C<...> (or "yada, yada, yada") operator.
+consisting of nothing but the C<...> (or "yada, yada, yada") operator,
+optionally followed by a message.
 So, all the preceding examples that look like pseudocode with C<{...}>
 for their body are actually valid subroutine declarations.
 
-  sub stubbly (Str $name, Int ?$days) {...}
+  sub stubbly (Str $name, Int $days?) {...}
+
+You can include a message that appears in the error message if you try to
+execute a stu subroutine.
+
+  sub stubbly (Str $name, Int $days?) { ... "Don't call me" }
 
 When you later define the subroutine, the signature and defined traits
 must exactly match the declaration.
 
-  sub stubbly (Str $name, Int ?$days) {
+  sub stubbly (Str $name, Int $days?) {
       print "$name hasn't shaved in $days day";
       print "s" if $days > 1;
@@ -651 +657 @@
 subroutine.
 
-  $make_tea = sub ($tealeaves, ?$sugar, ?$milk) {...}
-
-The arrow operator used with C<for> and C<given> is just another way
-of defining anonymous subroutines. The arrow doesn't require
+  $make_tea = sub ($tealeaves, :$sugar, :$milk) {...}
+
+The arrow operator used with C<for> and C<given> is just a way
+of defining anonymous blocks. The arrow doesn't require
 parentheses around its parameter list. It can't declare named subs,
 and can't declare a return type.
 
-  $make_tea = -> $tealeaves, ?$sugar, ?$milk {...}
+  $make_tea = -> $tealeaves, :$sugar, :$milk {...}
 
 X<blocks;bare>
@@ -672 +678 @@
 
 
-You can't use the C<return> statement within an arrow sub or bare
-block sub to return from an anonymous sub. Blocks and arrow subs are
+You can't use the C<return> statement within an arrow block or bare
+block sub to return from that block. Blocks and arrow subs are
 commonly used for ordinary control flow, so C<return> ignores them and
 only returns from subroutines defined with C<sub> keyword or
 methods.
+
+Instead you can C<leave> a block:
+
+  my $make_tea {
+      leave unless teamtime();
+      my $tea = boil 'tealeaves';
+      combine $tea, 'sugar', 'milk';
+  }
+
+The simple rule is that everything declared with a C<sub> or C<method>
+keyword use the C<return> statement, blocks declared without such a keyword
+can use C<leave>.
 
 =head1 Multi Subroutines
@@ -711 +729 @@
 This version of C<add> will dispatch based on the types of the first
 two arguments passed in, and ignore the type of the third.
+
+Multisubs can also differ in the number of arguments as long as no
+ambiguities arise.
 
 =head1 Curried Subroutines

docs/tutorial/ch07_grammars.pod

@@ -3 +3 @@
 =pod
 
-=head0 Grammars and Rules
+=head0 Grammars and Regexes
+
+
+TODO: This chapter is outdated in some ways
+
+  * It uses the old word "rule" instead of "regex" in far too many places
+  * The interpolation rules are outdated
+  * <'...'> and <"..."> are now '...' and "..."
+  * some of the assertion syntax has changed, for example <foo()> means
+    something different now
+  * Modifiers: explain :sigspace and :ratchet modifiers
+  * Modifiers: :u1, :u2... are now :bytes, :codes, :graphemes etc.
+  * Other missing modifiers: :overlap, :ignoreaccent
+  * The match object needs explanation
 
 Z<CHP-7>
 
-X<rules;grammars and>
-X<grammars and rules>
+X<regexes;grammars and>
+X<grammars and regexes>
 X<regular expressions>
 Perl 6 "regular expressions" are so far beyond the formal definition
-of regular expressions that we decided it was time for a more
-meaningful name.N<Regular expressions describe regular languages, and
+of regular expressions that we don't use that name anymore, but simply
+stick to the abbreviation I<Regex>.N<Regular expressions describe regular
+languages, and
 consist of three primitives and a limited set of operations (three or
 so, depending on the formulation). So, even Perl 5 "regular
-expressions" weren't formal regular expressions.> We now call them
-"rules." Perl 6 rules bring the full power of recursive descent
-parsing to the core of Perl, but are comfortably useful even if you
+expressions" weren't formal regular expressions.> 
+Perl 6 regexes bring the full power of recursive descent
+parsingN<A computer scientist would classify the most common usage of Perl 6
+regexes as I<deterministic context-free languages>> to the core of Perl, but are comfortably useful even if you
 don't know anything about recursive descent parsing. In the usual
-case, all you'll ever need to know is that rules are X<patterns>
+case, all you'll ever need to know is that regexes are X<patterns>
 patterns for matching text.
 
-=head1 Using Rules
+=head1 Using Regexes
 
 Z<CHP-7-SECT-1>
 
-X<rules;syntax>
-Rules are a language within a language, with their own syntax and
+X<regexes;syntax>
+Regexes are a language within a language, with their own syntax and
 conventions. At the highest level, though, they're just another set of
-Perl constructs. So the first thing to learn about rules is the Perl
+Perl constructs. So the first thing to learn about regexes is the Perl
 "glue" code for creating and using them.
 
@@ -36 +51 @@
 Z<CHP-7-SECT-1.1>
 
-The simplest way to create and use a rule is an immediate match. A rule
+The simplest way to create and use a regex is an immediate match. A regex
 defined with the C<m//>X<m// (match) operator> operator always
 immediately matches.  Substitutions, defined with the C<s///>
 X<s/// (substitution) operator> operator also immediately match.  A
-rule defined with the C<//>X</ (slash);//;;(see m// operator)>
+regex defined with the C<//>X</ (slash);//;;(see m// operator)>
 operator immediately matches when it's in void, boolean, string, or
 numeric context, or the argument of the smart-match operator (C<~~>).
 X<~ (tilde);~~ (smart match) operator>
 
-  if $string ~~ m/\w+/      {...}
-  if $string ~~ s/\w+/word/ {...}
-  if $string ~~ /\w+/       {...}
+  if $string ~~ m/ \w+ /      {...}
+  if $string ~~ s/ \w+ /word/ {...}
+  if $string ~~ / \w+ /       {...}
 
 You can substitute other delimiters, like C<#...#>, C<[...]>, and
@@ -85 +100 @@
 
 Sometimes you want a little more flexibility than an immediate match.
-The C<rx//>X<rx// (anonymous rule) operator> operator defines an
-anonymous rule that can be executed later.
+The C<rx//>X<rx// (anonymous regex) operator> operator defines an
+anonymous regex that can be executed later.
 
   $digits = rx/\d+/;
 
-The simple C<//> operator also defines an anonymous rule in all
+The simple C<//> operator also defines an anonymous regex in all
 contexts other than void, boolean, string, or numeric, or as an
 argument of C<~~>.
 
-  $digits = /\d+/; # store rule
+  $digits = /\d+/; # store regex
 
 You can use the unary context forcing operators, C<+>, C<?>, and C<~>,
@@ -107 +122 @@
   $string = ~/^\w+/;      # match $_ and return string
 
-Another option for deferred matches is a C<rule> block. The C<rule>
-keyword defines a named or anonymous rule, in much the same way that
+Another option for deferred matches is a C<regex> block. The C<regex>
+keyword defines a named or anonymous regex, in much the same way that
 C<sub> declares a subroutine or C<method> declares a method. But the
-code within the block of a C<rule> is rule syntax, not Perl syntax.
-
-  $digits = rule {\d+};
-
-  rule digits {\d+}
-
-To match a named or anonymous rule, call it as a subrule within
-another rule. Subrules, whether they're named rules or a variable
-containing an anonymous rule, are enclosed in assertion delimiters 
+code within the block of a C<regex> is regex syntax, not Perl syntax.
+
+  $digits = regex {\d+};
+
+  regex digits {\d+}
+
+There are two more keywords that defines regexes similarly to C<regex>, but
+they imply different modifiers. C<token> introduces a regex that does
+not backtrack,N<technically it implies the C<:ratchet> modifier> (more details
+on that below; for now it's enough to know that it matches simple regexes
+faster), and C<rule> is the same as C<token> except that whitespaces in
+regexes also match optional whitespaces in the string.N<it implies both the
+C<:ratchet> and the C<:sigspace> modifer>.
+
+To match a named or anonymous regex, call it as a subregex within
+another regex. Subregexes, whether they're named regexes or a variable
+containing an anonymous regex, are enclosed in assertion delimiters 
 C<< <...> >>. You can read more about assertions in A<CHP-7-SECT-2.4>
 "Assertions" later in this chapter.
@@ -166 +189 @@
 =cell C</.../>
 
-=cell Immediately match or define an anonymous rule, depending on the
+=cell Immediately match or define an anonymous regex, depending on the
 context.
 
 =row 
 
-=cell C<rule {...}>
-
-=cell Define an anonymous rule.
-
-=row 
-
-=cell C<rule name {...}>
-
-=cell Define a named rule.
+=cell C<regex {...}>
+
+=cell Define an anonymous regex.
+
+=row 
+
+=cell C<regex name {...}>
+
+=cell Define a named regex.
 
 =end table
@@ -189 +212 @@
 X<grammars>
 
-A grammar is a collection of rules, in much the same way that a class is
+A grammar is a collection of regexes, in much the same way that a class is
 a collection of methods. In fact, grammars are classes, they're just
-classes that inherit from the universal base class C<Rule>X<Rule class>.
+classes that inherit from the universal base class C<Regex>X<Regex class>.
 This means that grammars can inherit from other grammars, and that they
-define a namespace for their rules.
+define a namespace for their regexes.
 
   grammar Hitchhikers {
-      rule name {Zaphod|Ford|Arthur}
+      token name { Zaphod | Ford | Arthur }
   
-      rule id   {\d+}
+      token id   { \d+ }
 
       ...
   }
 
-Any rule in the current grammar or in one of its parents can be called
-directly, but a rule from an external grammar needs to have its package
+Any regex in the current grammar or in one of its parents can be called
+directly, but a regex from an external grammar needs to have its package
 specified:
 
-  if $newsrelease ~~ /E<lt>Hitchhikers.nameE<gt>/ {
+  if $newsrelease ~~ / E<lt>Hitchhikers.nameE<gt> / {
       send_alert($1);
   }
 
-If you want to match against the entire grammar, you can define a rule
+If you want to match against the entire grammar, you can define a regex
 C<TOP> in that grammar.
 
   grammar Hitchhikers {
-      rule TOP { <name> <id> }
+      regex TOP { <name> <id> }
       ...
   }
@@ -235 +258 @@
 
 Every language has a set of basic components (words or parts of words)
-and a set of syntax rules for combining them. The "words" in rules are
+and a set of syntax rules for combining them. The "words" in regexes are
 literal characters (or symbols), some X<metacharacters> metacharacters
-(or metasymbols),  and X<rules;escape sequences>X<escape sequences,
-rules> escape sequences, while the combining syntax includes other
-metacharacters, X<quantifiers, rules> X<rules;quantifiers> quantifiers,
+(or metasymbols),  and X<regexes;escape sequences>X<escape sequences,
+regexes> escape sequences, while the combining syntax includes other
+metacharacters, X<quantifiers, regexes> X<regexes;quantifiers> quantifiers,
 bracketing characters, and assertions.
 
@@ -250 +273 @@
 C<.> matches any single character, even a newline character. Actually,
 what it matches by default is a Unicode grapheme, but you can change
-that behavior with a pragma in your code, or a modifier on the rule.
+that behavior with a pragma in your code, or a modifier on the regex.
 We'll talk more about modifiers in A<CHP-7-SECT-2.5>"Modifiers" later
 in this chapter. The C<^> and C<$> metacharacters are zero-width
@@ -264 +287 @@
 C<#> marks a comment to the end of the line. Whitespace insensitivity
 (the old C</x> modifier) is on by default, so you can start a comment at
-any point on any line in a rule. Just make sure you don't comment out
-the symbol that terminates the rule. The C<:=>
-X<: (colon);:= (binding);in rules> binds a hypothetical variable to
-the result of a subrule or grouped pattern. Hypotheticals are covered
+any point on any line in a regex. Just make sure you don't comment out
+the symbol that terminates the regex. The C<:=>
+X<: (colon);:= (binding);in regex> binds a hypothetical variable to
+the result of a subregex or grouped pattern. Hypotheticals are covered
 in A<CHP-7-SECT-5>"Hypothetical Variables" later in this chapter.
 
 The metacharacters C<()>, C<[]>, C<{}> and C<E<lt>E<gt>> are bracketing
-pairs. The pairs always have to be balanced within the rule, unless they
+pairs. The pairs always have to be balanced within the regex, unless they
 are literal characters (escaped with a C<\>). The brackets C<()> and
 C<[]> group patterns to match as a single atom. They're often used to
@@ -277 +300 @@
 of patterns with a quantifier, among other things. Parentheses C<()> are
 capturing and square brackets C<[]> are non-capturing. The C<{}>
-brackets define a section of Perl code (a closure) within a rule. These
+brackets define a section of Perl code (a closure) within a regex. These
 closures are always a successful zero-width match, unless the code
 explicitly calls the C<fail> function. The C<E<lt>...E<gt>> brackets
@@ -305 +328 @@
 
 =cell Match any single character, including a newline.
-X<. (dot);. match single character (rules)>
+X<. (dot);. match single character (regexes)>
 
 =row 
@@ -312 +335 @@
 
 =cell Match the beginning of a string.
-X<^ (caret);^ beginning of string (rules)>
+X<^ (caret);^ beginning of string (regexes)>
 
 =row 
@@ -319 +342 @@
 
 =cell Match the end of a string.
-X<$ (dollar sign);$ end of string (rules)>
+X<$ (dollar sign);$ end of string (regexes)>
 
 =row 
@@ -326 +349 @@
 
 =cell Match the beginning of a line.
-X<^ (caret);^^ beginning of line (rules)>
+X<^ (caret);^^ beginning of line (regexes)>
 
 =row 
@@ -333 +356 @@
 
 =cell Match the end of a line.
-X<$ (dollar sign);$$ end of line (rules)>
+X<$ (dollar sign);$$ end of line (regexes)>
 
 =row 
@@ -353 +376 @@
 =cell Escape a metacharacter to get a literal character, or escape a
 literal character to get a metacharacter.
-X<\ (backslash);\ escape sequences (rules)>
-X<\ (backslash);\ to escape metacharacters (rules)>
+X<\ (backslash);\ escape sequences (regexes)>
+X<\ (backslash);\ to escape metacharacters (regexes)>
 
 =row 
@@ -367 +390 @@
 
 =cell Bind the result of a match to a hypothetical variable.
-X<: (colon);:= (binding);in rules>
+X<: (colon);:= (binding);in regexes>
 
 =row 
@@ -385 +408 @@
 =cell C<{...}>
 
-=cell Execute a closure (Perl 6 code) within a rule.
+=cell Execute a closure (Perl 6 code) within a regex.
 
 =row 
@@ -400 +423 @@
 Z<CHP-7-SECT-2.2>
 
-X<escape sequences, rules>
-X<rules;escape sequences>
-X<\ (backslash);\ escape sequences (rules)>
+X<escape sequences, regexes>
+X<regexes;escape sequences>
+X<\ (backslash);\ escape sequences (regexes)>
 The escape sequences are literal characters acting as metacharacters,
 marked with the C<\> escape. Some escape sequences represent single
@@ -412 +435 @@
 brackets, C<()>, C<{}>, and C<E<lt>E<gt>> work in place of C<[]>. 
 
-X<variable interpolation in rules>
-X<rules;variable interpolation>
+X<variable interpolation in regexes>
+X<regexes;variable interpolation>
 Note that since an ordinary variable now interpolates as a literal
-string by default, the C<\Q> escape sequence is rarely needed.
-
-A<CHP-7-TABLE-3>Table 7-3 shows the escape sequences for rules. 
+string by default, the C<\Q> escape is rarely needed.
+
+A<CHP-7-TABLE-3>Table 7-3 shows the escape sequences for regexes. 
 
 =begin table picture Escape sequences
@@ -625 +648 @@
 match.
 
-X<. (dot);.. (range);quantifier (rules)>
-X<. (dot);... (infinite range);quantifier (rules)>
-The numeric quantifiers use assertion syntax. A single number
-(C<E<lt>3E<gt>>) requires exactly that many matches. A numeric range
-quantifier (C<E<lt>3C<..>5E<gt>>) succeeds if the number of matches is
-between the minimum and maximum numbers. A range with three trailing
-dots (C<E<lt>2...E<gt>>) is shorthand for C<E<lt>R<n>..InfE<gt>> and
-matches as many times as possible.
+X<. (dot);.. (range);quantifier (regexes)>
+X<. (dot);... (infinite range);quantifier (regexes)>
+The numeric quantifiers use the C<**> operator followed by the number of
+desired matches. For a range of matches you can use a closure that returns
+a range (C<a**{2..4}> matches two to four C<a>'s, (C<a**{2..Inf}>) two or
+more C<a>'s).
 
 Each quantifier has a minimal alternate form, marked with a trailing
@@ -683 +704 @@
 =row 
 
-=cell C<E<lt>>R<n>C<E<gt>>
-
-=cell C<E<lt>>R<n>C<E<gt>?>
+=cell C**n>
+
+=cell C<**?n>
 
 =cell Match exactly R<n> times.
@@ -691 +712 @@
 =row 
 
-=cell C<E<lt>>R<n>C<..>R<m>C<E<gt>>
-
-=cell C<E<lt>>R<n>C<..>R<m>C<E<gt>?>
+=cell C<**{n..m}>
+=cell C<**?{n..m}>
 
 =cell Match at least R<n> and no more than R<m> times.
@@ -712 +732 @@
 Z<CHP-7-SECT-2.4>
 
-X<assertions, rules>
-X<rules;assertions>
+X<assertions, regexes>
+X<regexes;assertions>
 In general, an assertion simply states that some condition or state is
 true and the match fails when that assertion is false. Many different
 constructs with many different purposes use assertion syntax. 
 
-X<variable interpolation in rules>
+X<variable interpolation in regexes>
 X<rules;variable interpolation>
-Assertions match named and anonymous rules, arrays or hashes containing
-anonymous rules, and subroutines or closures that return anonymous
-rules. You have to enclose a variable in assertion delimiters to get it
+Assertions match named and anonymous regexes, arrays or hashes containing
+anonymous regexes, and subroutines or closures that return anonymous
+regexes. You have to enclose a variable in assertion delimiters to get it
 to interpolate as an anonymous rule or rules. A bare scalar in a pattern
 interpolates as a literal string, while a scalar variable in assertion
@@ -977 +997 @@
 =row 
 
-=cell C<:W>
-
-=cell 
-
-=cell Turn off intelligent whitespace matching (return to default).
-
-=row 
-
 =cell 
 
@@ -1059 +1071 @@
 =row 
 
-=cell 
-
-=cell C<:p5>
+=cell C<:P5>
+
+=cell C<:Perl5>
 
 =cell The pattern uses Perl 5 regex syntax.
@@ -1242 +1254 @@
 Hypothetical variables are a powerful way of building up data structures
 from within a match. Ordinary captures with C<()> store the result of
-the captures in C<$1>, C<$2>, etc. The values stored in these variables
+the captures in C<$0>, C<$1>, etc. The values stored in these variables