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