patch for LWP 5.05 to make it play with both 5.003 and 5.003_20 + overload patch

1 files changed, 74 insertions, 15 deletions

diff --git a/lib/overload.pm b/lib/overload.pm
index 049545995c..2bbb639d9b 100644
--- a/lib/overload.pm
+++ b/lib/overload.pm
@@ -149,9 +149,10 @@ the "class" C<Number> (or one of its base classes)
 for the assignment form C<*=> of multiplication.  
 
 Arguments of this directive come in (key, value) pairs.  Legal values
-are values legal inside a C<&{ ... }> call, so the name of a subroutine,
-a reference to a subroutine, or an anonymous subroutine will all work.
-Legal keys are listed below.
+are values legal inside a C<&{ ... }> call, so the name of a
+subroutine, a reference to a subroutine, or an anonymous subroutine
+will all work.  Note that values specified as strings are
+interpreted as methods, not subroutines.  Legal keys are listed below.
 
 The subroutine C<add> will be called to execute C<$a+$b> if $a
 is a reference to an object blessed into the package C<Number>, or if $a is
@@ -161,6 +162,10 @@ C<$a+=7>, or C<$a++>.  See L<MAGIC AUTOGENERATION>.  (Mathemagical
 methods refer to methods triggered by an overloaded mathematical
 operator.)
 
+Since overloading respects @ISA hierarchy, in fact the above
+declaration would also trigger overloading of C<+> and C<*=> in all
+the packages which inherit from C<Number>.
+
 =head2 Calling Conventions for Binary Operations
 
 The functions specified in the C<use overload ...> directive are called
@@ -269,6 +274,40 @@ see L<SPECIAL SYMBOLS FOR C<use overload>>.
 
 See L<"Fallback"> for an explanation of when a missing method can be autogenerated.
 
+=head2 Inheritance and overloading
+
+There are two ways how inheritance interacts with overloading. 
+
+=over
+
+=item Strings as values of C<use overload> directive
+
+If the value of 
+
+  use overload key => value;
+
+directive is a string, it is interpreted as a method name.
+
+=item Overloading of an operation is inherited by derived classes
+
+If any of ancestors is overloaded, so is the derived class. The set of
+overloaded methods is the union of overloaded methods of all the
+ancestors. If some method is overloaded in several ancestor, then
+which description will be used is decided by the usual inheritance
+rules: 
+
+If C<A> inherits from C<B> and C<C> (in this order), and C<B>
+overloads C<+> by C<\&D::plus_sub>, C<C> overloads C<+> by
+C<"plus_meth">, then the subroutine C<D::plus_sub> will be called to
+implement operation C<+> for an object in package C<A>.
+
+=back
+
+Note that since the value of C<fallback> key is not a subroutine, its
+inheritance is not governed by the above rules. Current implementation
+is that the value of C<fallback> in the first overloaded ancestor is
+taken, but this may be subject to change.
+
 =head1 SPECIAL SYMBOLS FOR C<use overload>
 
 Three keys are recognized by Perl that are not covered by the above
@@ -321,6 +360,9 @@ C<"nomethod"> value, and if this is missing, raises an exception.
 
 =back
 
+B<Note.> C<"fallback"> inheritance via @ISA is not carved in stone
+yet, see L<"Inheritance and overloading">.
+
 =head2 Copy Constructor
 
 The value for C<"="> is a reference to a function with three
@@ -484,16 +526,21 @@ Returns C<undef> or a reference to the method that implements C<op>.
 
 What follows is subject to change RSN.
 
-The table of methods for all operations is cached as magic in the
-symbol table hash for the package.  The table is rechecked for changes due to
-C<use overload>, C<no overload>, and @ISA only during
-C<bless>ing; so if they are changed dynamically, you'll need an
-additional fake C<bless>ing to update the table.
-
-(Every SVish thing has a magic queue, and magic is an entry in that queue.
-This is how a single variable may participate in multiple forms of magic
-simultaneously.  For instance, environment variables regularly have two
-forms at once: their %ENV magic and their taint magic.)
+The table of methods for all operations is cached in magic for the
+symbol table hash for the package.  The cache is invalidated during
+processing of C<use overload>, C<no overload>, new function
+definitions, and changes in @ISA. However, this invalidation remains
+unprocessed until the next C<bless>ing into the package. Hence if you
+want to change overloading structure dynamically, you'll need an
+additional (fake) C<bless>ing to update the table.
+
+(Every SVish thing has a magic queue, and magic is an entry in that
+queue.  This is how a single variable may participate in multiple
+forms of magic simultaneously.  For instance, environment variables
+regularly have two forms at once: their %ENV magic and their taint
+magic. However, the magic which implements overloading is applied to
+the stashes, which are rarely used directly, thus should not slow down
+Perl.)
 
 If an object belongs to a package using overload, it carries a special
 flag.  Thus the only speed penalty during arithmetic operations without
@@ -502,13 +549,17 @@ overloading is the checking of this flag.
 In fact, if C<use overload> is not present, there is almost no overhead for
 overloadable operations, so most programs should not suffer measurable
 performance penalties.  A considerable effort was made to minimize the overhead
-when overload is used and the current operation is overloadable but
+when overload is used in some package, but
 the arguments in question do not belong to packages using overload.  When
 in doubt, test your speed with C<use overload> and without it.  So far there
 have been no reports of substantial speed degradation if Perl is compiled
 with optimization turned on.
 
-There is no size penalty for data if overload is not used. 
+There is no size penalty for data if overload is not used. The only
+size penalty if overload is used in some package is that I<all> the
+packages acquire a magic during the next C<bless>ing into the
+package. This magic is three-words-long for packages without
+overloading, and carries the cache tabel if the package is overloaded.
 
 Copying (C<$a=$b>) is shallow; however, a one-level-deep copying is 
 carried out before any operation that can imply an assignment to the
@@ -527,6 +578,14 @@ Ilya Zakharevich E<lt>F<ilya@math.mps.ohio-state.edu>E<gt>.
 When Perl is run with the B<-Do> switch or its equivalent, overloading
 induces diagnostic messages.
 
+Using the C<m> command of Perl debugger (see L<perldebug>) one can
+deduce which operations are overloaded (and which ancestor triggers
+this overloading). Say, if C<eq> is overloaded, then the method C<(eq>
+is shown by debugger. The method C<()> corresponds to the C<fallback>
+key (in fact a presence of this method shows that this package has
+overloading enabled, and it is what is used by the C<Overloaded>
+function).
+
 =head1 BUGS
 
 Because it is used for overloading, the per-package associative array