From: Ben Morrow <ben@morrow.me.uk>
Date: Tue, 27 Oct 2009 16:12:36 +0000 (+0000)
Subject: Documentation for the 'qr' overload.
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=7cb0cfe6b05b22a9c89198b7133aee5507599e8c;p=p5sagit%2Fp5-mst-13.2.git

Documentation for the 'qr' overload.
---

diff --git a/lib/overload.pm b/lib/overload.pm
index 8960171..e506a7c 100644
--- a/lib/overload.pm
+++ b/lib/overload.pm
@@ -135,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	  => '${} @{} %{} &{} *{}',
@@ -400,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
@@ -518,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	  => '${} @{} %{} &{} *{}',
@@ -693,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>
 
diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index 2bad617..22b30f8 100644
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -3004,6 +3004,17 @@ the string being unpacked.  See L<perlfunc/pack>.
 the string being unpacked. The string being unpacked was also invalid
 UTF-8. See L<perlfunc/pack>.
 
+=item Overloaded dereference did not return a reference
+
+(F) An object with an overloaded dereference operator was dereferenced,
+but the overloaded operation did not return a reference. See
+L<overload>.
+
+=item Overloaded qr did not return a REGEXP
+
+(F) An object with a C<qr> overload was used as part of a match, but the
+overloaded operation didn't return a compiled regexp. See L<overload>.
+
 =item %s package attribute may clash with future reserved word: %s
 
 (W reserved) A lowercase attribute name was used that had a
diff --git a/t/porting/diag.t b/t/porting/diag.t
index 9aa25d5..cdb6dba 100644
--- a/t/porting/diag.t
+++ b/t/porting/diag.t
@@ -298,7 +298,6 @@ Offset outside string
 Opening dirhandle %s also as a file
 Opening filehandle %s also as a directory
 Operator or semicolon missing before %c%s
-Overloaded dereference did not return a reference
 PERL_SIGNALS illegal: "%s"
 Perl %s required (did you mean %s?)--this is only %s, stopped
 Perl %s required--this is only %s, stopped