Make given() statements return the last evaluated expression

1 files changed, 36 insertions, 0 deletions

diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod
index 4e1bc0a8a7..f90b8b376e 100644
--- a/pod/perlsyn.pod
+++ b/pod/perlsyn.pod
@@ -667,6 +667,42 @@ 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 returns :
+
+=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 was true.
+
+=back
+
+Note that, unlike C<if> and C<unless>, both C<when> and C<default> always
+themselves return 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';
+    } };
+
+C<given> blocks can't currently 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.