Note changes to perlvar in perldelta

[perl5.git] / pod / perlsyn.pod

diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod
index 59f268e..18143d1 100644 (file)
--- a/pod/perlsyn.pod
+++ b/pod/perlsyn.pod
@@ -228,6 +228,9 @@ The following compound statements may be used to control flow:
     if (EXPR) BLOCK
     if (EXPR) BLOCK else BLOCK
     if (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK
+    unless (EXPR) BLOCK
+    unless (EXPR) BLOCK else BLOCK
+    unless (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK
     LABEL while (EXPR) BLOCK
     LABEL while (EXPR) BLOCK continue BLOCK
     LABEL until (EXPR) BLOCK
@@ -252,7 +255,11 @@ all do the same thing:
 The C<if> statement is straightforward.  Because BLOCKs are always
 bounded by curly brackets, there is never any ambiguity about which
 C<if> an C<else> goes with.  If you use C<unless> in place of C<if>,
-the sense of the test is reversed.
+the sense of the test is reversed. Like C<if>, C<unless> can be followed
+by C<else>. C<unless> can even be followed by one or more C<elsif>
+statements, though you may want to think twice before using that particular
+language construct, as everyone reading your code will have to think at least
+twice before they can understand what's going on.
 
 The C<while> statement executes the block as long as the expression is
 L<true|/"Truth and Falsehood">.
@@ -272,6 +279,14 @@ conditional is about to be evaluated again.  Thus it can be used to
 increment a loop variable, even when the loop has been continued via
 the C<next> statement.
 
+Extension modules can also hook into the Perl parser to define new
+kinds of compound statement.  These are introduced by a keyword which
+the extension recognises, and the syntax following the keyword is
+defined entirely by the extension.  If you are an implementor, see
+L<perlapi/PL_keyword_plugin> for the mechanism.  If you are using such
+a module, see the module's documentation for details of the syntax that
+it defines.
+
 =head2 Loop Control
 X<loop control> X<loop, control> X<next> X<last> X<redo> X<continue>
 
@@ -659,6 +674,45 @@ case to the next:
        default    { say '$foo does not contain a y' }
     }
 
+=head3 Return value
+
+When a C<given> statement is also a valid expression (e.g.
+when it's the last statement of a block), it evaluates to :
+
+=over 4
+
+=item *
+
+an empty list as soon as an explicit C<break> is encountered.
+
+=item *
+
+the value of the last evaluated expression of the successful
+C<when>/C<default> clause, if there's one.
+
+=item *
+
+the value of the last evaluated expression of the C<given> block if no
+condition is true.
+
+=back
+
+In both last cases, the last expression is evaluated in the context that
+was applied to the C<given> block.
+
+Note that, unlike C<if> and C<unless>, failed C<when> statements always
+evaluate to an empty list.
+
+    my $price = do { given ($item) {
+       when ([ 'pear', 'apple' ]) { 1 }
+       break when 'vote';      # My vote cannot be bought
+        1e10  when /Mona Lisa/;
+        'unknown';
+    } };
+
+Currently, C<given> blocks can't always be used as proper expressions. This
+may be addressed in a future version of perl.
+
 =head3 Switching in a loop
 
 Instead of using C<given()>, you can use a C<foreach()> loop.
@@ -671,7 +725,7 @@ string occurs in an array:
     }
     print "\@array contains $count copies of 'foo'\n";
 
-On exit from the C<when> block, there is an implicit C<next>.
+At the end of all C<when> blocks, there is an implicit C<next>.
 You can override that with an explicit C<last> if you're only
 interested in the first match.
 
@@ -704,12 +758,12 @@ C<grep> does not.
     Any     CodeRef   scalar sub truth          $b->($a)
 
     Hash    Hash      hash keys identical (every key is found in both hashes)
-    Array   Hash      hash slice existence     grep { exists $b->{$_} } @$a
+    Array   Hash      hash keys intersection   grep { exists $b->{$_} } @$a
     Regex   Hash      hash key grep            grep /$a/, keys %$b
     undef   Hash      always false (undef can't be a key)
     Any     Hash      hash entry existence     exists $b->{$a}
 
-    Hash    Array     hash slice existence     grep { exists $a->{$_} } @$b
+    Hash    Array     hash keys intersection   grep { exists $a->{$_} } @$b
     Array   Array     arrays are comparable[2]
     Regex   Array     array grep               grep /$a/, @$b
     undef   Array     array contains undef     grep !defined, @$b
@@ -877,7 +931,7 @@ C preprocessors: it matches the regular expression
     # example: '# line 42 "new_filename.plx"'
     /^\#   \s*
       line \s+ (\d+)   \s*
-      (?:\s("?)([^"]+)\2)? \s*
+      (?:\s("?)([^"]+)\g2)? \s*
      $/x
 
 with C<$1> being the line number for the next line, and C<$3> being