Fix failing Time-Piece tests on Win32

[p5sagit/p5-mst-13.2.git] / pod / perlsyn.pod

diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod
index c10d732..28bb824 100644 (file)
--- a/pod/perlsyn.pod
+++ b/pod/perlsyn.pod
@@ -117,7 +117,7 @@ is treated as 0.
 
 =head2 Statement Modifiers
 X<statement modifier> X<modifier> X<if> X<unless> X<while>
-X<until> X<foreach> X<for>
+X<until> X<when> X<foreach> X<for>
 
 Any simple statement may optionally be followed by a I<SINGLE> modifier,
 just before the terminating semicolon (or block ending).  The possible
@@ -127,6 +127,8 @@ modifiers are:
     unless EXPR
     while EXPR
     until EXPR
+    when EXPR
+    for LIST
     foreach LIST
 
 The C<EXPR> following the modifier is referred to as the "condition".
@@ -139,6 +141,22 @@ the condition is true (i.e., if the condition is false).
     print "Basset hounds got long ears" if length $ear >= 10;
     go_outside() and play() unless $is_raining;
 
+C<when> executes the statement I<when> C<$_> smart matches C<EXPR>, and
+then either C<break>s out if it's enclosed in a C<given> scope or skips
+to the C<next> element when it lies directly inside a C<for> loop.
+See also L</"Switch statements">.
+
+    given ($something) {
+        $abc    = 1 when /^abc/;
+        $just_a = 1 when /^a/;
+        $other  = 1;
+    }
+
+    for (@names) {
+       admin($_)   when [ qw/Alice Bob/ ];
+       regular($_) when [ qw/Chris David Ellen/ ];
+    }
+
 The C<foreach> modifier is an iterator: it executes the statement once
 for each item in the LIST (with C<$_> aliased to each item in turn).
 
@@ -555,32 +573,30 @@ is exactly equivalent to
 
        when($_ ~~ $foo)
 
-(though you need to enable the "~~" feature before you
-can use the C<~~> operator directly). In fact C<when(EXPR)>
-is treated as an implicit smart match most of the time. The
-exceptions are that when EXPR is:
+In fact C<when(EXPR)> is treated as an implicit smart match most of the
+time. The exceptions are that when EXPR is:
 
 =over 4
 
-=item o
+=item *
 
 a subroutine or method call
 
-=item o
+=item *
 
 a regular expression match, i.e. C</REGEX/> or C<$foo =~ /REGEX/>,
 or a negated regular expression match C<$foo !~ /REGEX/>.
 
-=item o
+=item *
 
 a comparison such as C<$_ E<lt> 10> or C<$x eq "abc">
 (or of course C<$_ ~~ $c>)
 
-=item o
+=item *
 
 C<defined(...)>, C<exists(...)>, or C<eof(...)>
 
-=item o
+=item *
 
 A negated expression C<!(...)> or C<not (...)>, or a logical
 exclusive-or C<(...) xor (...)>.
@@ -609,7 +625,7 @@ is applied recursively to the first argument.
 These rules look complicated, but usually they will do what
 you want. For example you could write:
 
-    when (/^\d$/ && $_ < 75) { ... }
+    when (/^\d+$/ && $_ < 75) { ... }
 
 Another useful shortcut is that, if you use a literal array
 or hash as the argument to C<when>, it is turned into a
@@ -636,7 +652,7 @@ case to the next:
     given($foo) {
        when (/x/) { say '$foo contains an x'; continue }
        when (/y/) { say '$foo contains a y' }
-       default    { say '$foo contains neither an x nor a y' }
+       default    { say '$foo does not contain a y' }
     }
 
 =head3 Switching in a loop
@@ -676,7 +692,7 @@ order, determines the match behaviour.
     Any     Code[+]   scalar sub truth         $b->($a)
 
     Hash    Hash      hash keys identical      [sort keys %$a]~~[sort keys %$b]
-    Hash    Array     hash value slice truth   grep $_, @$a{@$b}
+    Hash    Array     hash slice existence     @$b == grep {exists $a->{$_}} @$b
     Hash    Regex     hash key grep            grep /$b/, keys %$a
     Hash    Any       hash entry existence     exists $a->{$b}
 
@@ -718,7 +734,8 @@ See L<overload>.
 The Perl 5 smart match and C<given>/C<when> constructs are not
 absolutely identical to their Perl 6 analogues. The most visible
 difference is that, in Perl 5, parentheses are required around
-the argument to C<given()> and C<when()>. Parentheses in Perl 6
+the argument to C<given()> and C<when()> (except when this last
+one is used as a statement modifier). Parentheses in Perl 6
 are always optional in a control construct such as C<if()>,
 C<while()>, or C<when()>; they can't be made optional in Perl
 5 without a great deal of potential confusion, because Perl 5