Describe smart match and switch changes in perldelta

diff --git a/pod/perl5110delta.pod b/pod/perl5110delta.pod
index e96a64d..4e9d97b 100644 (file)
--- a/pod/perl5110delta.pod
+++ b/pod/perl5110delta.pod
@@ -9,6 +9,99 @@ development releases.
 
 =head1 Incompatible Changes
 
+=head2 Switch statement changes
+
+The handling of complex expressions by the C<given>/C<when> switch
+statement has been enhanced. There are three new cases where C<when> now
+inteprets its argument as a boolean, instead of an expression to be used
+in a smart match:
+
+=over 4
+
+=item file tests
+
+File tests that return a boolean value (that excludes C<-s>, C<-M>, C<-A>,
+and C<-C>):
+
+    when (-f $file) { say "$file is a file" }
+
+=item flip-flop operators
+
+The C<..> and C<...> flip-flop operators are evaluated in boolean context,
+following their usual semantics; see L<perlop/"Range Operators">.
+
+=item defined-or operator
+
+A compound expression involving the defined-or operator, as in
+C<when (expr1 // expr2)>, will be treated as boolean if the first
+expression is boolean. (This just extends the existing rule that applies
+to the regular or operator, as in C<when (expr1 || expr2)>.)
+
+=back
+
+The next paragraph details more changes brought to the semantics to
+the smart match operator, that naturally also modify the behaviour
+of the switch statements where smart matching is implicitly used.
+
+=head2 Smart match changes
+
+=head3 Changes to type-based dispatch
+
+The smart match operator C<~~> is no longer commutative. The behaviour of
+a smart match now depends primarily on the type of its right hand
+argument. While the general backwards compatibility is maintained,
+several changes must be noted:
+
+=over 4
+
+=item *
+
+Code references with an empty prototype are no longer treated specially.
+They are passed an argument like the other code references (even if they
+choose to ignore it).
+
+=item *
+
+C<%hash ~~ sub {}> and C<@array ~~ sub {}> now test that the subroutine
+returns a true value for each key of the hash (resp. element of the
+array), instead of passing the whole hash or array as a reference to
+the subroutine.
+
+=item *
+
+C<undef ~~ %hash> is always false (since C<undef> can't be a key in a
+hash). No implicit conversion to C<""> is done (as was the case in perl
+5.10.0).
+
+=item *
+
+C<$scalar ~~ @array> now always distributes the smart match across the
+elements of the array. It's true if one element in @array verifies
+C<$scalar ~~ $element>. This is a generalization of the old behaviour
+that tested whether the array contained the scalar.
+
+=back
+
+The full dispatch table for the smart match operator is given in
+L<perlsyn/"Smart matching in detail">.
+
+=head3 Smart match and overloading
+
+According to the rule of dispatch based on the rightmost argument type,
+when an object overloading C<~~> appears on the right side of the
+operator, the overload routine will always be called (with a 3rd argument
+set to a true value, see L<overload>.) However, when the object will
+appear on the left, the overload routine will be called only when the
+rightmost argument is a scalar. This way distributivity of smart match
+across arrays is not broken, as well as the other behaviours with complex
+types (coderefs, hashes, regexes). Thus, writers of overloading routines
+for smart match need to worry only with comparing against a scalar, and
+possibly with stringification overloading; the other cases will be
+automatically handled consistently.
+
+C<~~> will now refuse to work on objects that do not overload it (in order
+to avoid relying on the object's underlying structure).
+
 =head1 Core Enhancements
 
 =head1 The C<overloading> pragma