X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlsyn.pod;h=28bb824ada99bf497848e2193ec0fb33941d9a6f;hb=6e0733998eff7a098d2d21d5602f3eb2a7521e1f;hp=77ac7a9eba359487a64439d822333ae987339358;hpb=e17b7802b536212dcf45bdeeab52049ea254d916;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod
index 77ac7a9..28bb824 100644
--- 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
@@ -731,16 +748,9 @@ would parse the expression
 as though the argument to C<given> were an element of the hash
 C<%foo>, interpreting the braces as hash-element syntax.
 
-The table of smart matches is not identical to that proposed
-by the Perl 6 specification Synopsis 4. Some of the differences
-are simply a consequence of Perl 5's different data model, while
-other changes have been made to address problems with the Perl 6
-proposal. For example, the Perl 6 specification implies that
-C<$string ~~ qr/regex/> would test string equality, rather than
-doing a regular expression match. On the other hand, informal
-examples elsewhere make it clear that a regular expression
-match is the intended behaviour. Thus the Synopsis 4 smart
-match specification cannot yet be regarded as definitive.
+The table of smart matches is not identical to that proposed by the
+Perl 6 specification, mainly due to the differences between Perl 6's
+and Perl 5's data models.
 
 In Perl 6, C<when()> will always do an implicit smart match
 with its argument, whilst it is convenient in Perl 5 to