X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlsyn.pod;h=4e1bc0a8a7b9ca62b24bb1d3dcda1cff90f8313f;hb=93592fd5aeec89ac25994a493ef54e1d7a572d65;hp=2ba30d84c4f9757d9f9943e042919402da7d76d2;hpb=c6ebb5120dc80740c6aa629eb475e186a4fa19f8;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod
index 2ba30d8..4e1bc0a 100644
--- a/pod/perlsyn.pod
+++ b/pod/perlsyn.pod
@@ -272,6 +272,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>
 
@@ -568,8 +576,10 @@ is exactly equivalent to
 
 	when($_ ~~ $foo)
 
-In fact C<when(EXPR)> is treated as an implicit smart match most of the
-time. The exceptions are that when EXPR is:
+Most of the time, C<when(EXPR)> is treated as an implicit smart match of
+C<$_>, i.e. C<$_ ~~ EXPR>. (See L</"Smart matching in detail"> for more
+information on smart matching.) But when EXPR is one of the below
+exceptional cases, it is used directly as a boolean:
 
 =over 4
 
@@ -633,16 +643,13 @@ you want. For example you could write:
     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
+or hash as the argument to C<given>, it is turned into a
 reference. So C<given(@foo)> is the same as C<given(\@foo)>,
 for example.
 
 C<default> behaves exactly like C<when(1 == 1)>, which is
 to say that it always matches.
 
-See L</"Smart matching in detail"> for more information
-on smart matching.
-
 =head3 Breaking out
 
 You can use the C<break> keyword to break out of the enclosing
@@ -672,7 +679,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.
 
@@ -690,6 +697,10 @@ implicitly dereferences any non-blessed hash or array ref, so the "Hash"
 and "Array" entries apply in those cases. (For blessed references, the
 "Object" entries apply.)
 
+Note that the "Matching Code" column is not always an exact rendition.  For
+example, the smart match operator short-circuits whenever possible, but
+C<grep> does not.
+
     $a      $b        Type of Match Implied    Matching Code
     ======  =====     =====================    =============
     Any     undef     undefined                !defined $a
@@ -701,12 +712,12 @@ and "Array" entries apply in those cases. (For blessed references, the
     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
@@ -720,6 +731,7 @@ and "Array" entries apply in those cases. (For blessed references, the
     Object  Any       invokes ~~ overloading on $object, or falls back:
     Any     Num       numeric equality         $a == $b
     Num     numish[4] numeric equality         $a == $b
+    undef   Any       undefined                !defined($b)
     Any     Any       string equality          $a eq $b
 
  1 - empty hashes or arrays will match.
@@ -728,20 +740,26 @@ and "Array" entries apply in those cases. (For blessed references, the
  3 - If a circular reference is found, we fall back to referential equality.
  4 - either a real number, or a string that looks like a number
 
-The "matching code" doesn't represent the I<real> matching code,
-of course: it's just there to explain the intended meaning. Unlike
-C<grep>, the smart match operator will short-circuit whenever it can.
-
 =head3 Custom matching via overloading
 
 You can change the way that an object is matched by overloading
-the C<~~> operator. This trumps the usual smart match semantics.
-See L<overload>.
+the C<~~> operator. This may alter the usual smart match semantics.
 
 It should be noted that C<~~> will refuse to work on objects that
 don't overload it (in order to avoid relying on the object's
 underlying structure).
 
+Note also that smart match's matching rules take precedence over
+overloading, so if C<$obj> has smart match overloading, then
+
+    $obj ~~ X
+
+will not automatically invoke the overload method with X as an argument;
+instead the table above is consulted as normal, and based in the type of X,
+overloading may or may not be invoked.
+
+See L<overload>.
+
 =head3 Differences from Perl 6
 
 The Perl 5 smart match and C<given>/C<when> constructs are not