lib/overload.pm

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