Documentation for the 'qr' overload.

[p5sagit/p5-mst-13.2.git] / lib / overload.pm

diff --git a/lib/overload.pm b/lib/overload.pm
index 7790832..e506a7c 100644 (file)
--- a/lib/overload.pm
+++ b/lib/overload.pm
@@ -1,6 +1,6 @@
 package overload;
 
-our $VERSION = '1.08';
+our $VERSION = '1.09';
 
 sub nil {}
 
@@ -9,6 +9,7 @@ sub OVERLOAD {
   my %arg = @_;
   my ($sub, $fb);
   $ {$package . "::OVERLOAD"}{dummy}++; # Register with magic by touching.
+  $fb = ${$package . "::()"}; # preserve old fallback value RT#68196
   *{$package . "::()"} = \&nil; # Make it findable via fetchmethod.
   for (keys %arg) {
     if ($_ eq 'fallback') {
@@ -134,7 +135,7 @@ sub mycan {                         # Real can would leave stubs.
         unary            => "neg ! ~",
         mutators         => '++ --',
         func             => "atan2 cos sin exp abs log sqrt int",
-        conversion       => 'bool "" 0+',
+        conversion       => 'bool "" 0+ qr',
         iterators        => '<>',
          filetest         => "-X",
         dereferencing    => '${} @{} %{} &{} *{}',
@@ -399,15 +400,20 @@ floating-point-like types one should follow the same semantic.  If
 C<int> is unavailable, it can be autogenerated using the overloading of
 C<0+>.
 
-=item * I<Boolean, string and numeric conversion>
+=item * I<Boolean, string, numeric and regexp conversion>
 
-    'bool', '""', '0+',
+    'bool', '""', '0+', 'qr'
 
-If one or two of these operations are not overloaded, the remaining ones can
-be used instead.  C<bool> is used in the flow control operators
-(like C<while>) and for the ternary C<?:> operation.  These functions can
-return any arbitrary Perl value.  If the corresponding operation for this value
-is overloaded too, that operation will be called again with this value.
+If one or two of these operations are not overloaded, the remaining ones
+can be used instead.  C<bool> is used in the flow control operators
+(like C<while>) and for the ternary C<?:> operation; C<qr> is used for
+the RHS of C<=~> and when an object is interpolated into a regexp.
+
+C<bool>, C<"">, and C<0+> can return any arbitrary Perl value.  If the
+corresponding operation for this value is overloaded too, that operation
+will be called again with this value. C<qr> must return a compiled
+regexp, or a ref to a compiled regexp (such as C<qr//> returns), and any
+further overloading on the return value will be ignored.
 
 As a special case if the overload returns the object itself then it will
 be used directly. An overloaded conversion returning the object is
@@ -455,6 +461,31 @@ The key C<"~~"> allows you to override the smart matching logic used by
 the C<~~> operator and the switch construct (C<given>/C<when>).  See
 L<perlsyn/switch> and L<feature>.
 
+Unusually, overloading of the smart match operator does not automatically
+take precedence over normal smart match behaviour. In particular, in the
+following code:
+
+    package Foo;
+    use overload '~~' => 'match';
+
+    my $obj =  Foo->new();
+    $obj ~~ [ 1,2,3 ];
+
+the smart match does I<not> invoke the method call like this:
+
+    $obj->match([1,2,3],0);
+
+rather, the smart match distributive rule takes precedence, so $obj is
+smart matched against each array element in turn until a match is found,
+so you may see between one and three of these calls instead:
+
+    $obj->match(1,0);
+    $obj->match(2,0);
+    $obj->match(3,0);
+
+Consult the match table in  L<perlsyn/"Smart matching in detail"> for
+details of when overloading is invoked.
+
 =item * I<Dereferencing>
 
     '${}', '@{}', '%{}', '&{}', '*{}'.
@@ -492,7 +523,7 @@ A computer-readable form of the above table is available in the hash
  unary           => 'neg ! ~',
  mutators        => '++ --',
  func            => 'atan2 cos sin exp abs log sqrt',
- conversion      => 'bool "" 0+',
+ conversion      => 'bool "" 0+ qr',
  iterators       => '<>',
  filetest         => '-X',
  dereferencing   => '${} @{} %{} &{} *{}',
@@ -667,8 +698,8 @@ is not defined.
 
 =item I<Conversion operations>
 
-String, numeric, and boolean conversion are calculated in terms of one
-another if not all of them are defined.
+String, numeric, boolean and regexp conversion are calculated in terms
+of one another if not all of them are defined.
 
 =item I<Increment and decrement>