lib/overload.pm

   1 package overload;
   2
   3 sub nil {}
   4
   5 sub OVERLOAD {
   6   $package = shift;
   7   my %arg = @_;
   8   my ($sub, $fb);
   9   $ {$package . "::OVERLOAD"}{dummy}++; # Register with magic by touching.
  10   *{$package . "::()"} = \&nil; # Make it findable via fetchmethod.
  11   for (keys %arg) {
  12     if ($_ eq 'fallback') {
  13       $fb = $arg{$_};
  14     } else {
  15       $sub = $arg{$_};
  16       if (not ref $sub and $sub !~ /::/) {
  17         $ {$package . "::(" . $_} = $sub;
  18         $sub = \&nil;
  19       }
  20       #print STDERR "Setting `$ {'package'}::\cO$_' to \\&`$sub'.\n";
  21       *{$package . "::(" . $_} = \&{ $sub };
  22     }
  23   }
  24   ${$package . "::()"} = $fb; # Make it findable too (fallback only).
  25 }
  26
  27 sub import {
  28   $package = (caller())[0];
  29   # *{$package . "::OVERLOAD"} = \&OVERLOAD;
  30   shift;
  31   $package->overload::OVERLOAD(@_);
  32 }
  33
  34 sub unimport {
  35   $package = (caller())[0];
  36   ${$package . "::OVERLOAD"}{dummy}++; # Upgrade the table
  37   shift;
  38   for (@_) {
  39     if ($_ eq 'fallback') {
  40       undef $ {$package . "::()"};
  41     } else {
  42       delete $ {$package . "::"}{"(" . $_};
  43     }
  44   }
  45 }
  46
  47 sub Overloaded {
  48   my $package = shift;
  49   $package = ref $package if ref $package;
  50   $package->can('()');
  51 }
  52
  53 sub ov_method {
  54   my $globref = shift;
  55   return undef unless $globref;
  56   my $sub = \&{*$globref};
  57   return $sub if $sub ne \&nil;
  58   return shift->can($ {*$globref});
  59 }
  60
  61 sub OverloadedStringify {
  62   my $package = shift;
  63   $package = ref $package if ref $package;
  64   #$package->can('(""')
  65   ov_method mycan($package, '(""'), $package
  66     or ov_method mycan($package, '(0+'), $package
  67     or ov_method mycan($package, '(bool'), $package
  68     or ov_method mycan($package, '(nomethod'), $package;
  69 }
  70
  71 sub Method {
  72   my $package = shift;
  73   $package = ref $package if ref $package;
  74   #my $meth = $package->can('(' . shift);
  75   ov_method mycan($package, '(' . shift), $package;
  76   #return $meth if $meth ne \&nil;
  77   #return $ {*{$meth}};
  78 }
  79
  80 sub AddrRef {
  81   my $package = ref $_[0];
  82   return "$_[0]" unless $package;
  83   bless $_[0], overload::Fake;  # Non-overloaded package
  84   my $str = "$_[0]";
  85   bless $_[0], $package;        # Back
  86   $package . substr $str, index $str, '=';
  87 }
  88
  89 sub StrVal {
  90   (OverloadedStringify($_[0])) ?
  91     (AddrRef(shift)) :
  92     "$_[0]";
  93 }
  94
  95 sub mycan {                             # Real can would leave stubs.
  96   my ($package, $meth) = @_;
  97   return \*{$package . "::$meth"} if defined &{$package . "::$meth"};
  98   my $p;
  99   foreach $p (@{$package . "::ISA"}) {
 100     my $out = mycan($p, $meth);
 101     return $out if $out;
 102   }
 103   return undef;
 104 }
 105
 106 %constants = (
 107               'integer'   =>  0x1000,
 108               'float'     =>  0x2000,
 109               'binary'    =>  0x4000,
 110               'q'         =>  0x8000,
 111               'qr'        => 0x10000,
 112              );
 113
 114 %ops = ( with_assign      => "+ - * / % ** << >> x .",
 115          assign           => "+= -= *= /= %= **= <<= >>= x= .=",
 116          str_comparison   => "< <= >  >= == !=",
 117          '3way_comparison'=> "<=> cmp",
 118          num_comparison   => "lt le gt ge eq ne",
 119          binary           => "& | ^",
 120          unary            => "neg ! ~",
 121          mutators         => '++ --',
 122          func             => "atan2 cos sin exp abs log sqrt",
 123          conversion       => 'bool "" 0+',
 124          iterators        => '<>',
 125          dereferencing    => '${} @{} %{} &{} *{}',
 126          special          => 'nomethod fallback =');
 127
 128 sub constant {
 129   # Arguments: what, sub
 130   while (@_) {
 131     $^H{$_[0]} = $_[1];
 132     $^H |= $constants{$_[0]} | 0x20000;
 133     shift, shift;
 134   }
 135 }
 136
 137 sub remove_constant {
 138   # Arguments: what, sub
 139   while (@_) {
 140     delete $^H{$_[0]};
 141     $^H &= ~ $constants{$_[0]};
 142     shift, shift;
 143   }
 144 }
 145
 146 1;
 147
 148 __END__
 149
 150 =head1 NAME
 151
 152 overload - Package for overloading perl operations
 153
 154 =head1 SYNOPSIS
 155
 156     package SomeThing;
 157
 158     use overload
 159         '+' => \&myadd,
 160         '-' => \&mysub;
 161         # etc
 162     ...
 163
 164     package main;
 165     $a = new SomeThing 57;
 166     $b=5+$a;
 167     ...
 168     if (overload::Overloaded $b) {...}
 169     ...
 170     $strval = overload::StrVal $b;
 171
 172 =head1 CAVEAT SCRIPTOR
 173
 174 Overloading of operators is a subject not to be taken lightly.
 175 Neither its precise implementation, syntax, nor semantics are
 176 100% endorsed by Larry Wall.  So any of these may be changed
 177 at some point in the future.
 178
 179 =head1 DESCRIPTION
 180
 181 =head2 Declaration of overloaded functions
 182
 183 The compilation directive
 184
 185     package Number;
 186     use overload
 187         "+" => \&add,
 188         "*=" => "muas";
 189
 190 declares function Number::add() for addition, and method muas() in
 191 the "class" C<Number> (or one of its base classes)
 192 for the assignment form C<*=> of multiplication.
 193
 194 Arguments of this directive come in (key, value) pairs.  Legal values
 195 are values legal inside a C<&{ ... }> call, so the name of a
 196 subroutine, a reference to a subroutine, or an anonymous subroutine
 197 will all work.  Note that values specified as strings are
 198 interpreted as methods, not subroutines.  Legal keys are listed below.
 199
 200 The subroutine C<add> will be called to execute C<$a+$b> if $a
 201 is a reference to an object blessed into the package C<Number>, or if $a is
 202 not an object from a package with defined mathemagic addition, but $b is a
 203 reference to a C<Number>.  It can also be called in other situations, like
 204 C<$a+=7>, or C<$a++>.  See L<MAGIC AUTOGENERATION>.  (Mathemagical
 205 methods refer to methods triggered by an overloaded mathematical
 206 operator.)
 207
 208 Since overloading respects inheritance via the @ISA hierarchy, the
 209 above declaration would also trigger overloading of C<+> and C<*=> in
 210 all the packages which inherit from C<Number>.
 211
 212 =head2 Calling Conventions for Binary Operations
 213
 214 The functions specified in the C<use overload ...> directive are called
 215 with three (in one particular case with four, see L<Last Resort>)
 216 arguments.  If the corresponding operation is binary, then the first
 217 two arguments are the two arguments of the operation.  However, due to
 218 general object calling conventions, the first argument should always be
 219 an object in the package, so in the situation of C<7+$a>, the
 220 order of the arguments is interchanged.  It probably does not matter
 221 when implementing the addition method, but whether the arguments
 222 are reversed is vital to the subtraction method.  The method can
 223 query this information by examining the third argument, which can take
 224 three different values:
 225
 226 =over 7
 227
 228 =item FALSE
 229
 230 the order of arguments is as in the current operation.
 231
 232 =item TRUE
 233
 234 the arguments are reversed.
 235
 236 =item C<undef>
 237
 238 the current operation is an assignment variant (as in
 239 C<$a+=7>), but the usual function is called instead.  This additional
 240 information can be used to generate some optimizations.  Compare
 241 L<Calling Conventions for Mutators>.
 242
 243 =back
 244
 245 =head2 Calling Conventions for Unary Operations
 246
 247 Unary operation are considered binary operations with the second
 248 argument being C<undef>.  Thus the functions that overloads C<{"++"}>
 249 is called with arguments C<($a,undef,'')> when $a++ is executed.
 250
 251 =head2 Calling Conventions for Mutators
 252
 253 Two types of mutators have different calling conventions:
 254
 255 =over
 256
 257 =item C<++> and C<-->
 258
 259 The routines which implement these operators are expected to actually
 260 I<mutate> their arguments.  So, assuming that $obj is a reference to a
 261 number,
 262
 263   sub incr { my $n = $ {$_[0]}; ++$n; $_[0] = bless \$n}
 264
 265 is an appropriate implementation of overloaded C<++>.  Note that
 266
 267   sub incr { ++$ {$_[0]} ; shift }
 268
 269 is OK if used with preincrement and with postincrement. (In the case
 270 of postincrement a copying will be performed, see L<Copy Constructor>.)
 271
 272 =item C<x=> and other assignment versions
 273
 274 There is nothing special about these methods.  They may change the
 275 value of their arguments, and may leave it as is.  The result is going
 276 to be assigned to the value in the left-hand-side if different from
 277 this value.
 278
 279 This allows for the same method to be used as averloaded C<+=> and
 280 C<+>.  Note that this is I<allowed>, but not recommended, since by the
 281 semantic of L<"Fallback"> Perl will call the method for C<+> anyway,
 282 if C<+=> is not overloaded.
 283
 284 =back
 285
 286 B<Warning.>  Due to the presense of assignment versions of operations,
 287 routines which may be called in assignment context may create
 288 self-referencial structures.  Currently Perl will not free self-referential
 289 structures until cycles are C<explicitly> broken.  You may get problems
 290 when traversing your structures too.
 291
 292 Say,
 293
 294   use overload '+' => sub { bless [ \$_[0], \$_[1] ] };
 295
 296 is asking for trouble, since for code C<$obj += $foo> the subroutine
 297 is called as C<$obj = add($obj, $foo, undef)>, or C<$obj = [\$obj,
 298 \$foo]>.  If using such a subroutine is an important optimization, one
 299 can overload C<+=> explicitly by a non-"optimized" version, or switch
 300 to non-optimized version if C<not defined $_[2]> (see
 301 L<Calling Conventions for Binary Operations>).
 302
 303 Even if no I<explicit> assignment-variants of operators are present in
 304 the script, they may be generated by the optimizer.  Say, C<",$obj,"> or
 305 C<',' . $obj . ','> may be both optimized to
 306
 307   my $tmp = ',' . $obj;    $tmp .= ',';
 308
 309 =head2 Overloadable Operations
 310
 311 The following symbols can be specified in C<use overload> directive:
 312
 313 =over 5
 314
 315 =item * I<Arithmetic operations>
 316
 317     "+", "+=", "-", "-=", "*", "*=", "/", "/=", "%", "%=",
 318     "**", "**=", "<<", "<<=", ">>", ">>=", "x", "x=", ".", ".=",
 319
 320 For these operations a substituted non-assignment variant can be called if
 321 the assignment variant is not available.  Methods for operations "C<+>",
 322 "C<->", "C<+=>", and "C<-=>" can be called to automatically generate
 323 increment and decrement methods.  The operation "C<->" can be used to
 324 autogenerate missing methods for unary minus or C<abs>.
 325
 326 See L<"MAGIC AUTOGENERATION">, L<"Calling Conventions for Mutators"> and
 327 L<"Calling Conventions for Binary Operations">) for details of these
 328 substitutions.
 329
 330 =item * I<Comparison operations>
 331
 332     "<",  "<=", ">",  ">=", "==", "!=", "<=>",
 333     "lt", "le", "gt", "ge", "eq", "ne", "cmp",
 334
 335 If the corresponding "spaceship" variant is available, it can be
 336 used to substitute for the missing operation.  During C<sort>ing
 337 arrays, C<cmp> is used to compare values subject to C<use overload>.
 338
 339 =item * I<Bit operations>
 340
 341     "&", "^", "|", "neg", "!", "~",
 342
 343 "C<neg>" stands for unary minus.  If the method for C<neg> is not
 344 specified, it can be autogenerated using the method for
 345 subtraction. If the method for "C<!>" is not specified, it can be
 346 autogenerated using the methods for "C<bool>", or "C<\"\">", or "C<0+>".
 347
 348 =item * I<Increment and decrement>
 349
 350     "++", "--",
 351
 352 If undefined, addition and subtraction methods can be
 353 used instead.  These operations are called both in prefix and
 354 postfix form.
 355
 356 =item * I<Transcendental functions>
 357
 358     "atan2", "cos", "sin", "exp", "abs", "log", "sqrt",
 359
 360 If C<abs> is unavailable, it can be autogenerated using methods
 361 for "E<lt>" or "E<lt>=E<gt>" combined with either unary minus or subtraction.
 362
 363 =item * I<Boolean, string and numeric conversion>
 364
 365     "bool", "\"\"", "0+",
 366
 367 If one or two of these operations are not overloaded, the remaining ones can
 368 be used instead.  C<bool> is used in the flow control operators
 369 (like C<while>) and for the ternary "C<?:>" operation.  These functions can
 370 return any arbitrary Perl value.  If the corresponding operation for this value
 371 is overloaded too, that operation will be called again with this value.
 372
 373 =item * I<Iteration>
 374
 375     "<>"
 376
 377 If not overloaded, the argument will be converted to a filehandle or
 378 glob (which may require a stringification).  The same overloading
 379 happens both for the I<read-filehandle> syntax C<E<lt>$varE<gt>> and
 380 I<globbing> syntax C<E<lt>${var}E<gt>>.
 381
 382 =item * I<Dereferencing>
 383
 384     '${}', '@{}', '%{}', '&{}', '*{}'.
 385
 386 If not overloaded, the argument will be dereferenced I<as is>, thus
 387 should be of correct type.  These functions should return a reference
 388 of correct type, or another object with overloaded dereferencing.
 389
 390 =item * I<Special>
 391
 392     "nomethod", "fallback", "=",
 393
 394 see L<SPECIAL SYMBOLS FOR C<use overload>>.
 395
 396 =back
 397
 398 See L<"Fallback"> for an explanation of when a missing method can be
 399 autogenerated.
 400
 401 A computer-readable form of the above table is available in the hash
 402 %overload::ops, with values being space-separated lists of names:
 403
 404  with_assign      => '+ - * / % ** << >> x .',
 405  assign           => '+= -= *= /= %= **= <<= >>= x= .=',
 406  str_comparison   => '< <= > >= == !=',
 407  '3way_comparison'=> '<=> cmp',
 408  num_comparison   => 'lt le gt ge eq ne',
 409  binary           => '& | ^',
 410  unary            => 'neg ! ~',
 411  mutators         => '++ --',
 412  func             => 'atan2 cos sin exp abs log sqrt',
 413  conversion       => 'bool "" 0+',
 414  iterators        => '<>',
 415  dereferencing    => '${} @{} %{} &{} *{}',
 416  special          => 'nomethod fallback ='
 417
 418 =head2 Inheritance and overloading
 419
 420 Inheritance interacts with overloading in two ways.
 421
 422 =over
 423
 424 =item Strings as values of C<use overload> directive
 425
 426 If C<value> in
 427
 428   use overload key => value;
 429
 430 is a string, it is interpreted as a method name.
 431
 432 =item Overloading of an operation is inherited by derived classes
 433
 434 Any class derived from an overloaded class is also overloaded.  The
 435 set of overloaded methods is the union of overloaded methods of all
 436 the ancestors. If some method is overloaded in several ancestor, then
 437 which description will be used is decided by the usual inheritance
 438 rules:
 439
 440 If C<A> inherits from C<B> and C<C> (in this order), C<B> overloads
 441 C<+> with C<\&D::plus_sub>, and C<C> overloads C<+> by C<"plus_meth">,
 442 then the subroutine C<D::plus_sub> will be called to implement
 443 operation C<+> for an object in package C<A>.
 444
 445 =back
 446
 447 Note that since the value of the C<fallback> key is not a subroutine,
 448 its inheritance is not governed by the above rules.  In the current
 449 implementation, the value of C<fallback> in the first overloaded
 450 ancestor is used, but this is accidental and subject to change.
 451
 452 =head1 SPECIAL SYMBOLS FOR C<use overload>
 453
 454 Three keys are recognized by Perl that are not covered by the above
 455 description.
 456
 457 =head2 Last Resort
 458
 459 C<"nomethod"> should be followed by a reference to a function of four
 460 parameters.  If defined, it is called when the overloading mechanism
 461 cannot find a method for some operation.  The first three arguments of
 462 this function coincide with the arguments for the corresponding method if
 463 it were found, the fourth argument is the symbol
 464 corresponding to the missing method.  If several methods are tried,
 465 the last one is used.  Say, C<1-$a> can be equivalent to
 466
 467         &nomethodMethod($a,1,1,"-")
 468
 469 if the pair C<"nomethod" =E<gt> "nomethodMethod"> was specified in the
 470 C<use overload> directive.
 471
 472 If some operation cannot be resolved, and there is no function
 473 assigned to C<"nomethod">, then an exception will be raised via die()--
 474 unless C<"fallback"> was specified as a key in C<use overload> directive.
 475
 476 =head2 Fallback
 477
 478 The key C<"fallback"> governs what to do if a method for a particular
 479 operation is not found.  Three different cases are possible depending on
 480 the value of C<"fallback">:
 481
 482 =over 16
 483
 484 =item * C<undef>
 485
 486 Perl tries to use a
 487 substituted method (see L<MAGIC AUTOGENERATION>).  If this fails, it
 488 then tries to calls C<"nomethod"> value; if missing, an exception
 489 will be raised.
 490
 491 =item * TRUE
 492
 493 The same as for the C<undef> value, but no exception is raised.  Instead,
 494 it silently reverts to what it would have done were there no C<use overload>
 495 present.
 496
 497 =item * defined, but FALSE
 498
 499 No autogeneration is tried.  Perl tries to call
 500 C<"nomethod"> value, and if this is missing, raises an exception.
 501
 502 =back
 503
 504 B<Note.> C<"fallback"> inheritance via @ISA is not carved in stone
 505 yet, see L<"Inheritance and overloading">.
 506
 507 =head2 Copy Constructor
 508
 509 The value for C<"="> is a reference to a function with three
 510 arguments, i.e., it looks like the other values in C<use
 511 overload>. However, it does not overload the Perl assignment
 512 operator. This would go against Camel hair.
 513
 514 This operation is called in the situations when a mutator is applied
 515 to a reference that shares its object with some other reference, such
 516 as
 517
 518         $a=$b;
 519         ++$a;
 520
 521 To make this change $a and not change $b, a copy of C<$$a> is made,
 522 and $a is assigned a reference to this new object.  This operation is
 523 done during execution of the C<++$a>, and not during the assignment,
 524 (so before the increment C<$$a> coincides with C<$$b>).  This is only
 525 done if C<++> is expressed via a method for C<'++'> or C<'+='> (or
 526 C<nomethod>).  Note that if this operation is expressed via C<'+'>
 527 a nonmutator, i.e., as in
 528
 529         $a=$b;
 530         $a=$a+1;
 531
 532 then C<$a> does not reference a new copy of C<$$a>, since $$a does not
 533 appear as lvalue when the above code is executed.
 534
 535 If the copy constructor is required during the execution of some mutator,
 536 but a method for C<'='> was not specified, it can be autogenerated as a
 537 string copy if the object is a plain scalar.
 538
 539 =over 5
 540
 541 =item B<Example>
 542
 543 The actually executed code for
 544
 545         $a=$b;
 546         Something else which does not modify $a or $b....
 547         ++$a;
 548
 549 may be
 550
 551         $a=$b;
 552         Something else which does not modify $a or $b....
 553         $a = $a->clone(undef,"");
 554         $a->incr(undef,"");
 555
 556 if $b was mathemagical, and C<'++'> was overloaded with C<\&incr>,
 557 C<'='> was overloaded with C<\&clone>.
 558
 559 =back
 560
 561 Same behaviour is triggered by C<$b = $a++>, which is consider a synonim for
 562 C<$b = $a; ++$a>.
 563
 564 =head1 MAGIC AUTOGENERATION
 565
 566 If a method for an operation is not found, and the value for  C<"fallback"> is
 567 TRUE or undefined, Perl tries to autogenerate a substitute method for
 568 the missing operation based on the defined operations.  Autogenerated method
 569 substitutions are possible for the following operations:
 570
 571 =over 16
 572
 573 =item I<Assignment forms of arithmetic operations>
 574
 575 C<$a+=$b> can use the method for C<"+"> if the method for C<"+=">
 576 is not defined.
 577
 578 =item I<Conversion operations>
 579
 580 String, numeric, and boolean conversion are calculated in terms of one
 581 another if not all of them are defined.
 582
 583 =item I<Increment and decrement>
 584
 585 The C<++$a> operation can be expressed in terms of C<$a+=1> or C<$a+1>,
 586 and C<$a--> in terms of C<$a-=1> and C<$a-1>.
 587
 588 =item C<abs($a)>
 589
 590 can be expressed in terms of C<$aE<lt>0> and C<-$a> (or C<0-$a>).
 591
 592 =item I<Unary minus>
 593
 594 can be expressed in terms of subtraction.
 595
 596 =item I<Negation>
 597
 598 C<!> and C<not> can be expressed in terms of boolean conversion, or
 599 string or numerical conversion.
 600
 601 =item I<Concatenation>
 602
 603 can be expressed in terms of string conversion.
 604
 605 =item I<Comparison operations>
 606
 607 can be expressed in terms of its "spaceship" counterpart: either
 608 C<E<lt>=E<gt>> or C<cmp>:
 609
 610     <, >, <=, >=, ==, !=        in terms of <=>
 611     lt, gt, le, ge, eq, ne      in terms of cmp
 612
 613 =item I<Iterator>
 614
 615     <>                          in terms of builtin operations
 616
 617 =item I<Dereferencing>
 618
 619     ${} @{} %{} &{} *{}         in terms of builtin operations
 620
 621 =item I<Copy operator>
 622
 623 can be expressed in terms of an assignment to the dereferenced value, if this
 624 value is a scalar and not a reference.
 625
 626 =back
 627
 628 =head1 Losing overloading
 629
 630 The restriction for the comparison operation is that even if, for example,
 631 `C<cmp>' should return a blessed reference, the autogenerated `C<lt>'
 632 function will produce only a standard logical value based on the
 633 numerical value of the result of `C<cmp>'.  In particular, a working
 634 numeric conversion is needed in this case (possibly expressed in terms of
 635 other conversions).
 636
 637 Similarly, C<.=>  and C<x=> operators lose their mathemagical properties
 638 if the string conversion substitution is applied.
 639
 640 When you chop() a mathemagical object it is promoted to a string and its
 641 mathemagical properties are lost.  The same can happen with other
 642 operations as well.
 643
 644 =head1 Run-time Overloading
 645
 646 Since all C<use> directives are executed at compile-time, the only way to
 647 change overloading during run-time is to
 648
 649     eval 'use overload "+" => \&addmethod';
 650
 651 You can also use
 652
 653     eval 'no overload "+", "--", "<="';
 654
 655 though the use of these constructs during run-time is questionable.
 656
 657 =head1 Public functions
 658
 659 Package C<overload.pm> provides the following public functions:
 660
 661 =over 5
 662
 663 =item overload::StrVal(arg)
 664
 665 Gives string value of C<arg> as in absence of stringify overloading.
 666
 667 =item overload::Overloaded(arg)
 668
 669 Returns true if C<arg> is subject to overloading of some operations.
 670
 671 =item overload::Method(obj,op)
 672
 673 Returns C<undef> or a reference to the method that implements C<op>.
 674
 675 =back
 676
 677 =head1 Overloading constants
 678
 679 For some application Perl parser mangles constants too much.  It is possible
 680 to hook into this process via overload::constant() and overload::remove_constant()
 681 functions.
 682
 683 These functions take a hash as an argument.  The recognized keys of this hash
 684 are
 685
 686 =over 8
 687
 688 =item integer
 689
 690 to overload integer constants,
 691
 692 =item float
 693
 694 to overload floating point constants,
 695
 696 =item binary
 697
 698 to overload octal and hexadecimal constants,
 699
 700 =item q
 701
 702 to overload C<q>-quoted strings, constant pieces of C<qq>- and C<qx>-quoted
 703 strings and here-documents,
 704
 705 =item qr
 706
 707 to overload constant pieces of regular expressions.
 708
 709 =back
 710
 711 The corresponding values are references to functions which take three arguments:
 712 the first one is the I<initial> string form of the constant, the second one
 713 is how Perl interprets this constant, the third one is how the constant is used.
 714 Note that the initial string form does not
 715 contain string delimiters, and has backslashes in backslash-delimiter
 716 combinations stripped (thus the value of delimiter is not relevant for
 717 processing of this string).  The return value of this function is how this
 718 constant is going to be interpreted by Perl.  The third argument is undefined
 719 unless for overloaded C<q>- and C<qr>- constants, it is C<q> in single-quote
 720 context (comes from strings, regular expressions, and single-quote HERE
 721 documents), it is C<tr> for arguments of C<tr>/C<y> operators,
 722 it is C<s> for right-hand side of C<s>-operator, and it is C<qq> otherwise.
 723
 724 Since an expression C<"ab$cd,,"> is just a shortcut for C<'ab' . $cd . ',,'>,
 725 it is expected that overloaded constant strings are equipped with reasonable
 726 overloaded catenation operator, otherwise absurd results will result.
 727 Similarly, negative numbers are considered as negations of positive constants.
 728
 729 Note that it is probably meaningless to call the functions overload::constant()
 730 and overload::remove_constant() from anywhere but import() and unimport() methods.
 731 From these methods they may be called as
 732
 733         sub import {
 734           shift;
 735           return unless @_;
 736           die "unknown import: @_" unless @_ == 1 and $_[0] eq ':constant';
 737           overload::constant integer => sub {Math::BigInt->new(shift)};
 738         }
 739
 740 B<BUGS> Currently overloaded-ness of constants does not propagate
 741 into C<eval '...'>.
 742
 743 =head1 IMPLEMENTATION
 744
 745 What follows is subject to change RSN.
 746
 747 The table of methods for all operations is cached in magic for the
 748 symbol table hash for the package.  The cache is invalidated during
 749 processing of C<use overload>, C<no overload>, new function
 750 definitions, and changes in @ISA. However, this invalidation remains
 751 unprocessed until the next C<bless>ing into the package. Hence if you
 752 want to change overloading structure dynamically, you'll need an
 753 additional (fake) C<bless>ing to update the table.
 754
 755 (Every SVish thing has a magic queue, and magic is an entry in that
 756 queue.  This is how a single variable may participate in multiple
 757 forms of magic simultaneously.  For instance, environment variables
 758 regularly have two forms at once: their %ENV magic and their taint
 759 magic. However, the magic which implements overloading is applied to
 760 the stashes, which are rarely used directly, thus should not slow down
 761 Perl.)
 762
 763 If an object belongs to a package using overload, it carries a special
 764 flag.  Thus the only speed penalty during arithmetic operations without
 765 overloading is the checking of this flag.
 766
 767 In fact, if C<use overload> is not present, there is almost no overhead
 768 for overloadable operations, so most programs should not suffer
 769 measurable performance penalties.  A considerable effort was made to
 770 minimize the overhead when overload is used in some package, but the
 771 arguments in question do not belong to packages using overload.  When
 772 in doubt, test your speed with C<use overload> and without it.  So far
 773 there have been no reports of substantial speed degradation if Perl is
 774 compiled with optimization turned on.
 775
 776 There is no size penalty for data if overload is not used. The only
 777 size penalty if overload is used in some package is that I<all> the
 778 packages acquire a magic during the next C<bless>ing into the
 779 package. This magic is three-words-long for packages without
 780 overloading, and carries the cache tabel if the package is overloaded.
 781
 782 Copying (C<$a=$b>) is shallow; however, a one-level-deep copying is
 783 carried out before any operation that can imply an assignment to the
 784 object $a (or $b) refers to, like C<$a++>.  You can override this
 785 behavior by defining your own copy constructor (see L<"Copy Constructor">).
 786
 787 It is expected that arguments to methods that are not explicitly supposed
 788 to be changed are constant (but this is not enforced).
 789
 790 =head1 Metaphor clash
 791
 792 One may wonder why the semantic of overloaded C<=> is so counterintuive.
 793 If it I<looks> counterintuive to you, you are subject to a metaphor
 794 clash.
 795
 796 Here is a Perl object metaphor:
 797
 798 I<  object is a reference to blessed data>
 799
 800 and an arithmetic metaphor:
 801
 802 I<  object is a thing by itself>.
 803
 804 The I<main> problem of overloading C<=> is the fact that these metaphors
 805 imply different actions on the assignment C<$a = $b> if $a and $b are
 806 objects.  Perl-think implies that $a becomes a reference to whatever
 807 $b was referencing.  Arithmetic-think implies that the value of "object"
 808 $a is changed to become the value of the object $b, preserving the fact
 809 that $a and $b are separate entities.
 810
 811 The difference is not relevant in the absence of mutators.  After
 812 a Perl-way assignment an operation which mutates the data referenced by $a
 813 would change the data referenced by $b too.  Effectively, after
 814 C<$a = $b> values of $a and $b become I<indistinguishable>.
 815
 816 On the other hand, anyone who has used algebraic notation knows the
 817 expressive power of the arithmetic metaphor.  Overloading works hard
 818 to enable this metaphor while preserving the Perlian way as far as
 819 possible.  Since it is not not possible to freely mix two contradicting
 820 metaphors, overloading allows the arithmetic way to write things I<as
 821 far as all the mutators are called via overloaded access only>.  The
 822 way it is done is described in L<Copy Constructor>.
 823
 824 If some mutator methods are directly applied to the overloaded values,
 825 one may need to I<explicitly unlink> other values which references the
 826 same value:
 827
 828     $a = new Data 23;
 829     ...
 830     $b = $a;            # $b is "linked" to $a
 831     ...
 832     $a = $a->clone;     # Unlink $b from $a
 833     $a->increment_by(4);
 834
 835 Note that overloaded access makes this transparent:
 836
 837     $a = new Data 23;
 838     $b = $a;            # $b is "linked" to $a
 839     $a += 4;            # would unlink $b automagically
 840
 841 However, it would not make
 842
 843     $a = new Data 23;
 844     $a = 4;             # Now $a is a plain 4, not 'Data'
 845
 846 preserve "objectness" of $a.  But Perl I<has> a way to make assignments
 847 to an object do whatever you want.  It is just not the overload, but
 848 tie()ing interface (see L<perlfunc/tie>).  Adding a FETCH() method
 849 which returns the object itself, and STORE() method which changes the
 850 value of the object, one can reproduce the arithmetic metaphor in its
 851 completeness, at least for variables which were tie()d from the start.
 852
 853 (Note that a workaround for a bug may be needed, see L<"BUGS">.)
 854
 855 =head1 Cookbook
 856
 857 Please add examples to what follows!
 858
 859 =head2 Two-face scalars
 860
 861 Put this in F<two_face.pm> in your Perl library directory:
 862
 863   package two_face;             # Scalars with separate string and
 864                                 # numeric values.
 865   sub new { my $p = shift; bless [@_], $p }
 866   use overload '""' => \&str, '0+' => \&num, fallback => 1;
 867   sub num {shift->[1]}
 868   sub str {shift->[0]}
 869
 870 Use it as follows:
 871
 872   require two_face;
 873   my $seven = new two_face ("vii", 7);
 874   printf "seven=$seven, seven=%d, eight=%d\n", $seven, $seven+1;
 875   print "seven contains `i'\n" if $seven =~ /i/;
 876
 877 (The second line creates a scalar which has both a string value, and a
 878 numeric value.)  This prints:
 879
 880   seven=vii, seven=7, eight=8
 881   seven contains `i'
 882
 883 =head2 Two-face references
 884
 885 Suppose you want to create an object which is accessible as both an
 886 array reference, and a hash reference, similar to the builtin
 887 L<array-accessible-as-a-hash|perlref/"Pseudo-hashes: Using an array as
 888 a hash"> builtin Perl type.  Let us make it better than the builtin
 889 type, there will be no restriction that you cannot use the index 0 of
 890 your array.
 891
 892   package two_refs;
 893   use overload '%{}' => \&gethash, '@{}' => sub { $ {shift()} };
 894   sub new {
 895     my $p = shift;
 896     bless \ [@_], $p;
 897   }
 898   sub gethash {
 899     my %h;
 900     my $self = shift;
 901     tie %h, ref $self, $self;
 902     \%h;
 903   }
 904
 905   sub TIEHASH { my $p = shift; bless \ shift, $p }
 906   my %fields;
 907   my $i = 0;
 908   $fields{$_} = $i++ foreach qw{zero one two three};
 909   sub STORE {
 910     my $self = ${shift()};
 911     my $key = $fields{shift()};
 912     defined $key or die "Out of band access";
 913     $$self->[$key] = shift;
 914   }
 915   sub FETCH {
 916     my $self = ${shift()};
 917     my $key = $fields{shift()};
 918     defined $key or die "Out of band access";
 919     $$self->[$key];
 920   }
 921
 922 Now one can access an object using both the array and hash syntax:
 923
 924   my $bar = new two_refs 3,4,5,6;
 925   $bar->[2] = 11;
 926   $bar->{two} == 11 or die 'bad hash fetch';
 927
 928 Note several important features of this example.  First of all, the
 929 I<actual> type of $bar is a scalar reference, and we do not overload
 930 the scalar dereference.  Thus we can get the I<actual> non-overloaded
 931 contents of $bar by just using C<$$bar> (what we do in functions which
 932 overload dereference).  Similarly, the object returned by the
 933 TIEHASH() method is a scalar reference.
 934
 935 Second, we create a new tied hash each time the hash syntax is used.
 936 This allows us not to worry about a possibility of a reference loop,
 937 would would lead to a memory leak.
 938
 939 Both these problems can be cured.  Say, if we want to overload hash
 940 dereference on a reference to an object which is I<implemented> as a
 941 hash itself, the only problem one has to circumvent is how to access
 942 this I<actual> hash (as opposed to the I<virtual> exhibited by
 943 overloaded dereference operator).  Here is one possible fetching routine:
 944
 945   sub access_hash {
 946     my ($self, $key) = (shift, shift);
 947     my $class = ref $self;
 948     bless $self, 'overload::dummy'; # Disable overloading of %{}
 949     my $out = $self->{$key};
 950     bless $self, $class;        # Restore overloading
 951     $out;
 952   }
 953
 954 To move creation of the tied hash on each access, one may an extra
 955 level of indirection which allows a non-circular structure of references:
 956
 957   package two_refs1;
 958   use overload '%{}' => sub { ${shift()}->[1] },
 959                '@{}' => sub { ${shift()}->[0] };
 960   sub new {
 961     my $p = shift;
 962     my $a = [@_];
 963     my %h;
 964     tie %h, $p, $a;
 965     bless \ [$a, \%h], $p;
 966   }
 967   sub gethash {
 968     my %h;
 969     my $self = shift;
 970     tie %h, ref $self, $self;
 971     \%h;
 972   }
 973
 974   sub TIEHASH { my $p = shift; bless \ shift, $p }
 975   my %fields;
 976   my $i = 0;
 977   $fields{$_} = $i++ foreach qw{zero one two three};
 978   sub STORE {
 979     my $a = ${shift()};
 980     my $key = $fields{shift()};
 981     defined $key or die "Out of band access";
 982     $a->[$key] = shift;
 983   }
 984   sub FETCH {
 985     my $a = ${shift()};
 986     my $key = $fields{shift()};
 987     defined $key or die "Out of band access";
 988     $a->[$key];
 989   }
 990
 991 Now if $baz is overloaded like this, then C<$bar> is a reference to a
 992 reference to the intermediate array, which keeps a reference to an
 993 actual array, and the access hash.  The tie()ing object for the access
 994 hash is also a reference to a reference to the actual array, so
 995
 996 =over
 997
 998 =item *
 999
1000 There are no loops of references.
1001
1002 =item *
1003
1004 Both "objects" which are blessed into the class C<two_refs1> are
1005 references to a reference to an array, thus references to a I<scalar>.
1006 Thus the accessor expression C<$$foo-E<gt>[$ind]> involves no
1007 overloaded operations.
1008
1009 =back
1010
1011 =head2 Symbolic calculator
1012
1013 Put this in F<symbolic.pm> in your Perl library directory:
1014
1015   package symbolic;             # Primitive symbolic calculator
1016   use overload nomethod => \&wrap;
1017
1018   sub new { shift; bless ['n', @_] }
1019   sub wrap {
1020     my ($obj, $other, $inv, $meth) = @_;
1021     ($obj, $other) = ($other, $obj) if $inv;
1022     bless [$meth, $obj, $other];
1023   }
1024
1025 This module is very unusual as overloaded modules go: it does not
1026 provide any usual overloaded operators, instead it provides the L<Last
1027 Resort> operator C<nomethod>.  In this example the corresponding
1028 subroutine returns an object which encupsulates operations done over
1029 the objects: C<new symbolic 3> contains C<['n', 3]>, C<2 + new
1030 symbolic 3> contains C<['+', 2, ['n', 3]]>.
1031
1032 Here is an example of the script which "calculates" the side of
1033 circumscribed octagon using the above package:
1034
1035   require symbolic;
1036   my $iter = 1;                 # 2**($iter+2) = 8
1037   my $side = new symbolic 1;
1038   my $cnt = $iter;
1039
1040   while ($cnt--) {
1041     $side = (sqrt(1 + $side**2) - 1)/$side;
1042   }
1043   print "OK\n";
1044
1045 The value of $side is
1046
1047   ['/', ['-', ['sqrt', ['+', 1, ['**', ['n', 1], 2]],
1048                        undef], 1], ['n', 1]]
1049
1050 Note that while we obtained this value using a nice little script,
1051 there is no simple way to I<use> this value.  In fact this value may
1052 be inspected in debugger (see L<perldebug>), but ony if
1053 C<bareStringify> B<O>ption is set, and not via C<p> command.
1054
1055 If one attempts to print this value, then the overloaded operator
1056 C<""> will be called, which will call C<nomethod> operator.  The
1057 result of this operator will be stringified again, but this result is
1058 again of type C<symbolic>, which will lead to an infinite loop.
1059
1060 Add a pretty-printer method to the module F<symbolic.pm>:
1061
1062   sub pretty {
1063     my ($meth, $a, $b) = @{+shift};
1064     $a = 'u' unless defined $a;
1065     $b = 'u' unless defined $b;
1066     $a = $a->pretty if ref $a;
1067     $b = $b->pretty if ref $b;
1068     "[$meth $a $b]";
1069   }
1070
1071 Now one can finish the script by
1072
1073   print "side = ", $side->pretty, "\n";
1074
1075 The method C<pretty> is doing object-to-string conversion, so it
1076 is natural to overload the operator C<""> using this method.  However,
1077 inside such a method it is not necessary to pretty-print the
1078 I<components> $a and $b of an object.  In the above subroutine
1079 C<"[$meth $a $b]"> is a catenation of some strings and components $a
1080 and $b.  If these components use overloading, the catenation operator
1081 will look for an overloaded operator C<.>, if not present, it will
1082 look for an overloaded operator C<"">.  Thus it is enough to use
1083
1084   use overload nomethod => \&wrap, '""' => \&str;
1085   sub str {
1086     my ($meth, $a, $b) = @{+shift};
1087     $a = 'u' unless defined $a;
1088     $b = 'u' unless defined $b;
1089     "[$meth $a $b]";
1090   }
1091
1092 Now one can change the last line of the script to
1093
1094   print "side = $side\n";
1095
1096 which outputs
1097
1098   side = [/ [- [sqrt [+ 1 [** [n 1 u] 2]] u] 1] [n 1 u]]
1099
1100 and one can inspect the value in debugger using all the possible
1101 methods.
1102
1103 Something is is still amiss: consider the loop variable $cnt of the
1104 script.  It was a number, not an object.  We cannot make this value of
1105 type C<symbolic>, since then the loop will not terminate.
1106
1107 Indeed, to terminate the cycle, the $cnt should become false.
1108 However, the operator C<bool> for checking falsity is overloaded (this
1109 time via overloaded C<"">), and returns a long string, thus any object
1110 of type C<symbolic> is true.  To overcome this, we need a way to
1111 compare an object to 0.  In fact, it is easier to write a numeric
1112 conversion routine.
1113
1114 Here is the text of F<symbolic.pm> with such a routine added (and
1115 slightly modifed str()):
1116
1117   package symbolic;             # Primitive symbolic calculator
1118   use overload
1119     nomethod => \&wrap, '""' => \&str, '0+' => \&num;
1120
1121   sub new { shift; bless ['n', @_] }
1122   sub wrap {
1123     my ($obj, $other, $inv, $meth) = @_;
1124     ($obj, $other) = ($other, $obj) if $inv;
1125     bless [$meth, $obj, $other];
1126   }
1127   sub str {
1128     my ($meth, $a, $b) = @{+shift};
1129     $a = 'u' unless defined $a;
1130     if (defined $b) {
1131       "[$meth $a $b]";
1132     } else {
1133       "[$meth $a]";
1134     }
1135   }
1136   my %subr = ( n => sub {$_[0]},
1137                sqrt => sub {sqrt $_[0]},
1138                '-' => sub {shift() - shift()},
1139                '+' => sub {shift() + shift()},
1140                '/' => sub {shift() / shift()},
1141                '*' => sub {shift() * shift()},
1142                '**' => sub {shift() ** shift()},
1143              );
1144   sub num {
1145     my ($meth, $a, $b) = @{+shift};
1146     my $subr = $subr{$meth}
1147       or die "Do not know how to ($meth) in symbolic";
1148     $a = $a->num if ref $a eq __PACKAGE__;
1149     $b = $b->num if ref $b eq __PACKAGE__;
1150     $subr->($a,$b);
1151   }
1152
1153 All the work of numeric conversion is done in %subr and num().  Of
1154 course, %subr is not complete, it contains only operators used in teh
1155 example below.  Here is the extra-credit question: why do we need an
1156 explicit recursion in num()?  (Answer is at the end of this section.)
1157
1158 Use this module like this:
1159
1160   require symbolic;
1161   my $iter = new symbolic 2;    # 16-gon
1162   my $side = new symbolic 1;
1163   my $cnt = $iter;
1164
1165   while ($cnt) {
1166     $cnt = $cnt - 1;            # Mutator `--' not implemented
1167     $side = (sqrt(1 + $side**2) - 1)/$side;
1168   }
1169   printf "%s=%f\n", $side, $side;
1170   printf "pi=%f\n", $side*(2**($iter+2));
1171
1172 It prints (without so many line breaks)
1173
1174   [/ [- [sqrt [+ 1 [** [/ [- [sqrt [+ 1 [** [n 1] 2]]] 1]
1175                           [n 1]] 2]]] 1]
1176      [/ [- [sqrt [+ 1 [** [n 1] 2]]] 1] [n 1]]]=0.198912
1177   pi=3.182598
1178
1179 The above module is very primitive.  It does not implement
1180 mutator methods (C<++>, C<-=> and so on), does not do deep copying
1181 (not required without mutators!), and implements only those arithmetic
1182 operations which are used in the example.
1183
1184 To implement most arithmetic operattions is easy, one should just use
1185 the tables of operations, and change the code which fills %subr to
1186
1187   my %subr = ( 'n' => sub {$_[0]} );
1188   foreach my $op (split " ", $overload::ops{with_assign}) {
1189     $subr{$op} = $subr{"$op="} = eval "sub {shift() $op shift()}";
1190   }
1191   my @bins = qw(binary 3way_comparison num_comparison str_comparison);
1192   foreach my $op (split " ", "@overload::ops{ @bins }") {
1193     $subr{$op} = eval "sub {shift() $op shift()}";
1194   }
1195   foreach my $op (split " ", "@overload::ops{qw(unary func)}") {
1196     print "defining `$op'\n";
1197     $subr{$op} = eval "sub {$op shift()}";
1198   }
1199
1200 Due to L<Calling Conventions for Mutators>, we do not need anything
1201 special to make C<+=> and friends work, except filling C<+=> entry of
1202 %subr, and defining a copy constructor (needed since Perl has no
1203 way to know that the implementation of C<'+='> does not mutate
1204 the argument, compare L<Copy Constructor>).
1205
1206 To implement a copy constructor, add C<'=' => \&cpy> to C<use overload>
1207 line, and code (this code assumes that mutators change things one level
1208 deep only, so recursive copying is not needed):
1209
1210   sub cpy {
1211     my $self = shift;
1212     bless [@$self], ref $self;
1213   }
1214
1215 To make C<++> and C<--> work, we need to implement actual mutators,
1216 either directly, or in C<nomethod>.  We continue to do things inside
1217 C<nomethod>, thus add
1218
1219     if ($meth eq '++' or $meth eq '--') {
1220       @$obj = ($meth, (bless [@$obj]), 1); # Avoid circular reference
1221       return $obj;
1222     }
1223
1224 after the first line of wrap().  This is not a most effective
1225 implementation, one may consider
1226
1227   sub inc { $_[0] = bless ['++', shift, 1]; }
1228
1229 instead.
1230
1231 As a final remark, note that one can fill %subr by
1232
1233   my %subr = ( 'n' => sub {$_[0]} );
1234   foreach my $op (split " ", $overload::ops{with_assign}) {
1235     $subr{$op} = $subr{"$op="} = eval "sub {shift() $op shift()}";
1236   }
1237   my @bins = qw(binary 3way_comparison num_comparison str_comparison);
1238   foreach my $op (split " ", "@overload::ops{ @bins }") {
1239     $subr{$op} = eval "sub {shift() $op shift()}";
1240   }
1241   foreach my $op (split " ", "@overload::ops{qw(unary func)}") {
1242     $subr{$op} = eval "sub {$op shift()}";
1243   }
1244   $subr{'++'} = $subr{'+'};
1245   $subr{'--'} = $subr{'-'};
1246
1247 This finishes implementation of a primitive symbolic calculator in
1248 50 lines of Perl code.  Since the numeric values of subexpressions
1249 are not cached, the calculator is very slow.
1250
1251 Here is the answer for the exercise: In the case of str(), we need no
1252 explicit recursion since the overloaded C<.>-operator will fall back
1253 to an existing overloaded operator C<"">.  Overloaded arithmetic
1254 operators I<do not> fall back to numeric conversion if C<fallback> is
1255 not explicitly requested.  Thus without an explicit recursion num()
1256 would convert C<['+', $a, $b]> to C<$a + $b>, which would just rebuild
1257 the argument of num().
1258
1259 If you wonder why defaults for conversion are different for str() and
1260 num(), note how easy it was to write the symbolic calculator.  This
1261 simplicity is due to an appropriate choice of defaults.  One extra
1262 note: due to teh explicit recursion num() is more fragile than sym():
1263 we need to explicitly check for the type of $a and $b.  If componets
1264 $a and $b happen to be of some related type, this may lead to problems.
1265
1266 =head2 I<Really> symbolic calculator
1267
1268 One may wonder why we call the above calculator symbolic.  The reason
1269 is that the actual calculation of the value of expression is postponed
1270 until the value is I<used>.
1271
1272 To see it in action, add a method
1273
1274   sub STORE {
1275     my $obj = shift;
1276     $#$obj = 1;
1277     @$obj->[0,1] = ('=', shift);
1278   }
1279
1280 to the package C<symbolic>.  After this change one can do
1281
1282   my $a = new symbolic 3;
1283   my $b = new symbolic 4;
1284   my $c = sqrt($a**2 + $b**2);
1285
1286 and the numeric value of $c becomes 5.  However, after calling
1287
1288   $a->STORE(12);  $b->STORE(5);
1289
1290 the numeric value of $c becomes 13.  There is no doubt now that the module
1291 symbolic provides a I<symbolic> calculator indeed.
1292
1293 To hide the rough edges under the hood, provide a tie()d interface to the
1294 package C<symbolic> (compare with L<Metaphor clash>).  Add methods
1295
1296   sub TIESCALAR { my $pack = shift; $pack->new(@_) }
1297   sub FETCH { shift }
1298   sub nop {  }          # Around a bug
1299
1300 (the bug is described in L<"BUGS">).  One can use this new interface as
1301
1302   tie $a, 'symbolic', 3;
1303   tie $b, 'symbolic', 4;
1304   $a->nop;  $b->nop;    # Around a bug
1305
1306   my $c = sqrt($a**2 + $b**2);
1307
1308 Now numeric value of $c is 5.  After C<$a = 12; $b = 5> the numeric value
1309 of $c becomes 13.  To insulate the user of the module add a method
1310
1311   sub vars { my $p = shift; tie($_, $p), $_->nop foreach @_; }
1312
1313 Now
1314
1315   my ($a, $b);
1316   symbolic->vars($a, $b);
1317   my $c = sqrt($a**2 + $b**2);
1318
1319   $a = 3; $b = 4;
1320   printf "c5  %s=%f\n", $c, $c;
1321
1322   $a = 12; $b = 5;
1323   printf "c13  %s=%f\n", $c, $c;
1324
1325 shows that the numeric value of $c follows changes to the values of $a
1326 and $b.
1327
1328 =head1 AUTHOR
1329
1330 Ilya Zakharevich E<lt>F<ilya@math.mps.ohio-state.edu>E<gt>.
1331
1332 =head1 DIAGNOSTICS
1333
1334 When Perl is run with the B<-Do> switch or its equivalent, overloading
1335 induces diagnostic messages.
1336
1337 Using the C<m> command of Perl debugger (see L<perldebug>) one can
1338 deduce which operations are overloaded (and which ancestor triggers
1339 this overloading). Say, if C<eq> is overloaded, then the method C<(eq>
1340 is shown by debugger. The method C<()> corresponds to the C<fallback>
1341 key (in fact a presence of this method shows that this package has
1342 overloading enabled, and it is what is used by the C<Overloaded>
1343 function of module C<overload>).
1344
1345 =head1 BUGS
1346
1347 Because it is used for overloading, the per-package hash %OVERLOAD now
1348 has a special meaning in Perl. The symbol table is filled with names
1349 looking like line-noise.
1350
1351 For the purpose of inheritance every overloaded package behaves as if
1352 C<fallback> is present (possibly undefined). This may create
1353 interesting effects if some package is not overloaded, but inherits
1354 from two overloaded packages.
1355
1356 Relation between overloading and tie()ing is broken.  Overloading is
1357 triggered or not basing on the I<previous> class of tie()d value.
1358
1359 This happens because the presence of overloading is checked too early,
1360 before any tie()d access is attempted.  If the FETCH()ed class of the
1361 tie()d value does not change, a simple workaround is to access the value
1362 immediately after tie()ing, so that after this call the I<previous> class
1363 coincides with the current one.
1364
1365 B<Needed:> a way to fix this without a speed penalty.
1366
1367 Barewords are not covered by overloaded string constants.
1368
1369 This document is confusing.  There are grammos and misleading language
1370 used in places.  It would seem a total rewrite is needed.
1371
1372 =cut
1373