Add a note in perl5131delta about given return values

And tweak its documentation.

2 files changed, 28 insertions, 8 deletions

diff --git a/pod/perl5131delta.pod b/pod/perl5131delta.pod
index cfcd3d4a2a..db47d6f17f 100644
--- a/pod/perl5131delta.pod
+++ b/pod/perl5131delta.pod
@@ -44,6 +44,23 @@ The new local array used to be made tied too, which was fairly pointless,
 and has now been fixed. This fix could however potentially cause a change
 in behaviour of some code.
 
+=head2 C<given> return values
+
+Starting from this release, C<given> blocks returns the last evaluated
+expression, or an empty list if the block was exited by C<break>. Thus you
+can now write:
+
+    my $type = do {
+     given ($num) {
+      break     when undef;
+      'integer' when /^[+-]?[0-9]+$/;
+      'float'   when /^[+-]?[0-9]+(?:\.[0-9]+)?$/;
+      'unknown';
+     }
+    };
+
+See L<perlsyn/Return value> for details.
+
 =head1 Core Enhancements
 
 XXX New core language features go here. Summarise user-visible core language
diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod
index 3a65b4e9d0..29db5dafd5 100644
--- a/pod/perlsyn.pod
+++ b/pod/perlsyn.pod
@@ -677,28 +677,31 @@ case to the next:
 =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 :
+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.
+an empty list as soon as an explicit C<break> is encountered.
 
 =item *
 
-The value of the last evaluated expression of the successful
+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.
+the value of the last evaluated expression of the C<given> block if no
+condition is true.
 
 =back
 
-Note that, unlike C<if> and C<unless>, both C<when> and C<default> always
-themselves return an empty list.
+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 }
@@ -707,7 +710,7 @@ themselves return an empty list.
         'unknown';
     } };
 
-C<given> blocks can't currently be used as proper expressions. This
+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