PL_inf/PL_nan need different export with C++
[perl.git] / lib / overload.pm
1 package overload;
2
3 our $VERSION = '1.27';
4
5 %ops = (
6     with_assign         => "+ - * / % ** << >> x .",
7     assign              => "+= -= *= /= %= **= <<= >>= x= .=",
8     num_comparison      => "< <= >  >= == !=",
9     '3way_comparison'   => "<=> cmp",
10     str_comparison      => "lt le gt ge eq ne",
11     binary              => '& &= | |= ^ ^= &. &.= |. |.= ^. ^.=',
12     unary               => "neg ! ~ ~.",
13     mutators            => '++ --',
14     func                => "atan2 cos sin exp abs log sqrt int",
15     conversion          => 'bool "" 0+ qr',
16     iterators           => '<>',
17     filetest            => "-X",
18     dereferencing       => '${} @{} %{} &{} *{}',
19     matching            => '~~',
20     special             => 'nomethod fallback =',
21 );
22
23 my %ops_seen;
24 @ops_seen{ map split(/ /), values %ops } = ();
25
26 sub nil {}
27
28 sub OVERLOAD {
29   $package = shift;
30   my %arg = @_;
31   my $sub;
32   *{$package . "::(("} = \&nil; # Make it findable via fetchmethod.
33   for (keys %arg) {
34     if ($_ eq 'fallback') {
35       for my $sym (*{$package . "::()"}) {
36         *$sym = \&nil; # Make it findable via fetchmethod.
37         $$sym = $arg{$_};
38       }
39     } else {
40       warnings::warnif("overload arg '$_' is invalid")
41         unless exists $ops_seen{$_};
42       $sub = $arg{$_};
43       if (not ref $sub) {
44         $ {$package . "::(" . $_} = $sub;
45         $sub = \&nil;
46       }
47       #print STDERR "Setting '$ {'package'}::\cO$_' to \\&'$sub'.\n";
48       *{$package . "::(" . $_} = \&{ $sub };
49     }
50   }
51 }
52
53 sub import {
54   $package = (caller())[0];
55   # *{$package . "::OVERLOAD"} = \&OVERLOAD;
56   shift;
57   $package->overload::OVERLOAD(@_);
58 }
59
60 sub unimport {
61   $package = (caller())[0];
62   shift;
63   *{$package . "::(("} = \&nil;
64   for (@_) {
65       warnings::warnif("overload arg '$_' is invalid")
66         unless $ops_seen{$_};
67       delete $ {$package . "::"}{$_ eq 'fallback' ? '()' : "(" .$_};
68   }
69 }
70
71 sub Overloaded {
72   my $package = shift;
73   $package = ref $package if ref $package;
74   mycan ($package, '()') || mycan ($package, '((');
75 }
76
77 sub ov_method {
78   my $globref = shift;
79   return undef unless $globref;
80   my $sub = \&{*$globref};
81   no overloading;
82   return $sub if $sub != \&nil;
83   return shift->can($ {*$globref});
84 }
85
86 sub OverloadedStringify {
87   my $package = shift;
88   $package = ref $package if ref $package;
89   #$package->can('(""')
90   ov_method mycan($package, '(""'), $package
91     or ov_method mycan($package, '(0+'), $package
92     or ov_method mycan($package, '(bool'), $package
93     or ov_method mycan($package, '(nomethod'), $package;
94 }
95
96 sub Method {
97   my $package = shift;
98   if(ref $package) {
99     local $@;
100     local $!;
101     require Scalar::Util;
102     $package = Scalar::Util::blessed($package);
103     return undef if !defined $package;
104   }
105   #my $meth = $package->can('(' . shift);
106   ov_method mycan($package, '(' . shift), $package;
107   #return $meth if $meth ne \&nil;
108   #return $ {*{$meth}};
109 }
110
111 sub AddrRef {
112   no overloading;
113   "$_[0]";
114 }
115
116 *StrVal = *AddrRef;
117
118 sub mycan {                             # Real can would leave stubs.
119   my ($package, $meth) = @_;
120
121   local $@;
122   local $!;
123   require mro;
124
125   my $mro = mro::get_linear_isa($package);
126   foreach my $p (@$mro) {
127     my $fqmeth = $p . q{::} . $meth;
128     return \*{$fqmeth} if defined &{$fqmeth};
129   }
130
131   return undef;
132 }
133
134 %constants = (
135               'integer'   =>  0x1000, # HINT_NEW_INTEGER
136               'float'     =>  0x2000, # HINT_NEW_FLOAT
137               'binary'    =>  0x4000, # HINT_NEW_BINARY
138               'q'         =>  0x8000, # HINT_NEW_STRING
139               'qr'        => 0x10000, # HINT_NEW_RE
140              );
141
142 use warnings::register;
143 sub constant {
144   # Arguments: what, sub
145   while (@_) {
146     if (@_ == 1) {
147         warnings::warnif ("Odd number of arguments for overload::constant");
148         last;
149     }
150     elsif (!exists $constants {$_ [0]}) {
151         warnings::warnif ("'$_[0]' is not an overloadable type");
152     }
153     elsif (!ref $_ [1] || "$_[1]" !~ /(^|=)CODE\(0x[0-9a-f]+\)$/) {
154         # Can't use C<ref $_[1] eq "CODE"> above as code references can be
155         # blessed, and C<ref> would return the package the ref is blessed into.
156         if (warnings::enabled) {
157             $_ [1] = "undef" unless defined $_ [1];
158             warnings::warn ("'$_[1]' is not a code reference");
159         }
160     }
161     else {
162         $^H{$_[0]} = $_[1];
163         $^H |= $constants{$_[0]};
164     }
165     shift, shift;
166   }
167 }
168
169 sub remove_constant {
170   # Arguments: what, sub
171   while (@_) {
172     delete $^H{$_[0]};
173     $^H &= ~ $constants{$_[0]};
174     shift, shift;
175   }
176 }
177
178 1;
179
180 __END__
181
182 =head1 NAME
183
184 overload - Package for overloading Perl operations
185
186 =head1 SYNOPSIS
187
188     package SomeThing;
189
190     use overload
191         '+' => \&myadd,
192         '-' => \&mysub;
193         # etc
194     ...
195
196     package main;
197     $a = SomeThing->new( 57 );
198     $b = 5 + $a;
199     ...
200     if (overload::Overloaded $b) {...}
201     ...
202     $strval = overload::StrVal $b;
203
204 =head1 DESCRIPTION
205
206 This pragma allows overloading of Perl's operators for a class.
207 To overload built-in functions, see L<perlsub/Overriding Built-in Functions> instead.
208
209 =head2 Fundamentals
210
211 =head3 Declaration
212
213 Arguments of the C<use overload> directive are (key, value) pairs.
214 For the full set of legal keys, see L<Overloadable Operations> below.
215
216 Operator implementations (the values) can be subroutines,
217 references to subroutines, or anonymous subroutines
218 - in other words, anything legal inside a C<&{ ... }> call.
219 Values specified as strings are interpreted as method names.
220 Thus
221
222     package Number;
223     use overload
224         "-" => "minus",
225         "*=" => \&muas,
226         '""' => sub { ...; };
227
228 declares that subtraction is to be implemented by method C<minus()>
229 in the class C<Number> (or one of its base classes),
230 and that the function C<Number::muas()> is to be used for the
231 assignment form of multiplication, C<*=>.
232 It also defines an anonymous subroutine to implement stringification:
233 this is called whenever an object blessed into the package C<Number>
234 is used in a string context (this subroutine might, for example,
235 return the number as a Roman numeral).
236
237 =head3 Calling Conventions and Magic Autogeneration
238
239 The following sample implementation of C<minus()> (which assumes
240 that C<Number> objects are simply blessed references to scalars)
241 illustrates the calling conventions:
242
243     package Number;
244     sub minus {
245         my ($self, $other, $swap) = @_;
246         my $result = $$self - $other;         # *
247         $result = -$result if $swap;
248         ref $result ? $result : bless \$result;
249     }
250     # * may recurse once - see table below
251
252 Three arguments are passed to all subroutines specified in the
253 C<use overload> directive (with exceptions - see below, particularly
254 L</nomethod>).
255
256 The first of these is the operand providing the overloaded
257 operator implementation -
258 in this case, the object whose C<minus()> method is being called.
259
260 The second argument is the other operand, or C<undef> in the
261 case of a unary operator.
262
263 The third argument is set to TRUE if (and only if) the two
264 operands have been swapped.  Perl may do this to ensure that the
265 first argument (C<$self>) is an object implementing the overloaded
266 operation, in line with general object calling conventions.
267 For example, if C<$x> and C<$y> are C<Number>s:
268
269     operation   |   generates a call to
270     ============|======================
271     $x - $y     |   minus($x, $y, '')
272     $x - 7      |   minus($x, 7, '')
273     7 - $x      |   minus($x, 7, 1)
274
275 Perl may also use C<minus()> to implement other operators which
276 have not been specified in the C<use overload> directive,
277 according to the rules for L<Magic Autogeneration> described later.
278 For example, the C<use overload> above declared no subroutine
279 for any of the operators C<-->, C<neg> (the overload key for
280 unary minus), or C<-=>.  Thus
281
282     operation   |   generates a call to
283     ============|======================
284     -$x         |   minus($x, 0, 1)
285     $x--        |   minus($x, 1, undef)
286     $x -= 3     |   minus($x, 3, undef)
287
288 Note the C<undef>s:
289 where autogeneration results in the method for a standard
290 operator which does not change either of its operands, such
291 as C<->, being used to implement an operator which changes
292 the operand ("mutators": here, C<--> and C<-=>),
293 Perl passes undef as the third argument.
294 This still evaluates as FALSE, consistent with the fact that
295 the operands have not been swapped, but gives the subroutine
296 a chance to alter its behaviour in these cases.
297
298 In all the above examples, C<minus()> is required
299 only to return the result of the subtraction:
300 Perl takes care of the assignment to $x.
301 In fact, such methods should I<not> modify their operands,
302 even if C<undef> is passed as the third argument
303 (see L<Overloadable Operations>).
304
305 The same is not true of implementations of C<++> and C<-->:
306 these are expected to modify their operand.
307 An appropriate implementation of C<--> might look like
308
309     use overload '--' => "decr",
310         # ...
311     sub decr { --${$_[0]}; }
312
313 If the experimental "bitwise" feature is enabled (see L<feature>), a fifth
314 TRUE argument is passed to subroutines handling C<&>, C<|>, C<^> and C<~>.
315 This indicates that the caller is expecting numeric behaviour.  The fourth
316 argument will be C<undef>, as that position (C<$_[3]>) is reserved for use
317 by L</nomethod>.
318
319 =head3 Mathemagic, Mutators, and Copy Constructors
320
321 The term 'mathemagic' describes the overloaded implementation
322 of mathematical operators.
323 Mathemagical operations raise an issue.
324 Consider the code:
325
326     $a = $b;
327     --$a;
328
329 If C<$a> and C<$b> are scalars then after these statements
330
331     $a == $b - 1
332
333 An object, however, is a reference to blessed data, so if
334 C<$a> and C<$b> are objects then the assignment C<$a = $b>
335 copies only the reference, leaving C<$a> and C<$b> referring
336 to the same object data.
337 One might therefore expect the operation C<--$a> to decrement
338 C<$b> as well as C<$a>.
339 However, this would not be consistent with how we expect the
340 mathematical operators to work.
341
342 Perl resolves this dilemma by transparently calling a copy
343 constructor before calling a method defined to implement
344 a mutator (C<-->, C<+=>, and so on.).
345 In the above example, when Perl reaches the decrement
346 statement, it makes a copy of the object data in C<$a> and
347 assigns to C<$a> a reference to the copied data.
348 Only then does it call C<decr()>, which alters the copied
349 data, leaving C<$b> unchanged.
350 Thus the object metaphor is preserved as far as possible,
351 while mathemagical operations still work according to the
352 arithmetic metaphor.
353
354 Note: the preceding paragraph describes what happens when
355 Perl autogenerates the copy constructor for an object based
356 on a scalar.
357 For other cases, see L<Copy Constructor>.
358
359 =head2 Overloadable Operations
360
361 The complete list of keys that can be specified in the C<use overload>
362 directive are given, separated by spaces, in the values of the
363 hash C<%overload::ops>:
364
365  with_assign      => '+ - * / % ** << >> x .',
366  assign           => '+= -= *= /= %= **= <<= >>= x= .=',
367  num_comparison   => '< <= > >= == !=',
368  '3way_comparison'=> '<=> cmp',
369  str_comparison   => 'lt le gt ge eq ne',
370  binary           => '& &= | |= ^ ^= &. &.= |. |.= ^. ^.=',
371  unary            => 'neg ! ~ ~.',
372  mutators         => '++ --',
373  func             => 'atan2 cos sin exp abs log sqrt int',
374  conversion       => 'bool "" 0+ qr',
375  iterators        => '<>',
376  filetest         => '-X',
377  dereferencing    => '${} @{} %{} &{} *{}',
378  matching         => '~~',
379  special          => 'nomethod fallback ='
380
381 Most of the overloadable operators map one-to-one to these keys.
382 Exceptions, including additional overloadable operations not
383 apparent from this hash, are included in the notes which follow.
384 This list is subject to growth over time.
385
386 A warning is issued if an attempt is made to register an operator not found
387 above.
388
389 =over 5
390
391 =item * C<not>
392
393 The operator C<not> is not a valid key for C<use overload>.
394 However, if the operator C<!> is overloaded then the same
395 implementation will be used for C<not>
396 (since the two operators differ only in precedence).
397
398 =item * C<neg>
399
400 The key C<neg> is used for unary minus to disambiguate it from
401 binary C<->.
402
403 =item * C<++>, C<-->
404
405 Assuming they are to behave analogously to Perl's C<++> and C<-->,
406 overloaded implementations of these operators are required to
407 mutate their operands.
408
409 No distinction is made between prefix and postfix forms of the
410 increment and decrement operators: these differ only in the
411 point at which Perl calls the associated subroutine when
412 evaluating an expression.
413
414 =item * I<Assignments>
415
416     +=  -=  *=  /=  %=  **=  <<=  >>=  x=  .=
417     &=  |=  ^=  &.=  |.=  ^.=
418
419 Simple assignment is not overloadable (the C<'='> key is used
420 for the L<Copy Constructor>).
421 Perl does have a way to make assignments to an object do whatever
422 you want, but this involves using tie(), not overload -
423 see L<perlfunc/tie> and the L</COOKBOOK> examples below.
424
425 The subroutine for the assignment variant of an operator is
426 required only to return the result of the operation.
427 It is permitted to change the value of its operand
428 (this is safe because Perl calls the copy constructor first),
429 but this is optional since Perl assigns the returned value to
430 the left-hand operand anyway.
431
432 An object that overloads an assignment operator does so only in
433 respect of assignments to that object.
434 In other words, Perl never calls the corresponding methods with
435 the third argument (the "swap" argument) set to TRUE.
436 For example, the operation
437
438     $a *= $b
439
440 cannot lead to C<$b>'s implementation of C<*=> being called,
441 even if C<$a> is a scalar.
442 (It can, however, generate a call to C<$b>'s method for C<*>).
443
444 =item * I<Non-mutators with a mutator variant>
445
446      +  -  *  /  %  **  <<  >>  x  .
447      &  |  ^  &.  |.  ^.
448
449 As described L<above|"Calling Conventions and Magic Autogeneration">,
450 Perl may call methods for operators like C<+> and C<&> in the course
451 of implementing missing operations like C<++>, C<+=>, and C<&=>.
452 While these methods may detect this usage by testing the definedness
453 of the third argument, they should in all cases avoid changing their
454 operands.
455 This is because Perl does not call the copy constructor before
456 invoking these methods.
457
458 =item * C<int>
459
460 Traditionally, the Perl function C<int> rounds to 0
461 (see L<perlfunc/int>), and so for floating-point-like types one
462 should follow the same semantic.
463
464 =item * I<String, numeric, boolean, and regexp conversions>
465
466     ""  0+  bool
467
468 These conversions are invoked according to context as necessary.
469 For example, the subroutine for C<'""'> (stringify) may be used
470 where the overloaded object is passed as an argument to C<print>,
471 and that for C<'bool'> where it is tested in the condition of a flow
472 control statement (like C<while>) or the ternary C<?:> operation.
473
474 Of course, in contexts like, for example, C<$obj + 1>, Perl will
475 invoke C<$obj>'s implementation of C<+> rather than (in this
476 example) converting C<$obj> to a number using the numify method
477 C<'0+'> (an exception to this is when no method has been provided
478 for C<'+'> and L</fallback> is set to TRUE).
479
480 The subroutines for C<'""'>, C<'0+'>, and C<'bool'> can return
481 any arbitrary Perl value.
482 If the corresponding operation for this value is overloaded too,
483 the operation will be called again with this value.
484
485 As a special case if the overload returns the object itself then it will
486 be used directly.  An overloaded conversion returning the object is
487 probably a bug, because you're likely to get something that looks like
488 C<YourPackage=HASH(0x8172b34)>.
489
490     qr
491
492 The subroutine for C<'qr'> is used wherever the object is
493 interpolated into or used as a regexp, including when it
494 appears on the RHS of a C<=~> or C<!~> operator.
495
496 C<qr> must return a compiled regexp, or a ref to a compiled regexp
497 (such as C<qr//> returns), and any further overloading on the return
498 value will be ignored.
499
500 =item * I<Iteration>
501
502 If C<E<lt>E<gt>> is overloaded then the same implementation is used
503 for both the I<read-filehandle> syntax C<E<lt>$varE<gt>> and
504 I<globbing> syntax C<E<lt>${var}E<gt>>.
505
506 =item * I<File tests>
507
508 The key C<'-X'> is used to specify a subroutine to handle all the
509 filetest operators (C<-f>, C<-x>, and so on: see L<perlfunc/-X> for
510 the full list);
511 it is not possible to overload any filetest operator individually.
512 To distinguish them, the letter following the '-' is passed as the
513 second argument (that is, in the slot that for binary operators
514 is used to pass the second operand).
515
516 Calling an overloaded filetest operator does not affect the stat value
517 associated with the special filehandle C<_>.  It still refers to the
518 result of the last C<stat>, C<lstat> or unoverloaded filetest.
519
520 This overload was introduced in Perl 5.12.
521
522 =item * I<Matching>
523
524 The key C<"~~"> allows you to override the smart matching logic used by
525 the C<~~> operator and the switch construct (C<given>/C<when>).  See
526 L<perlsyn/Switch Statements> and L<feature>.
527
528 Unusually, the overloaded implementation of the smart match operator
529 does not get full control of the smart match behaviour.
530 In particular, in the following code:
531
532     package Foo;
533     use overload '~~' => 'match';
534
535     my $obj =  Foo->new();
536     $obj ~~ [ 1,2,3 ];
537
538 the smart match does I<not> invoke the method call like this:
539
540     $obj->match([1,2,3],0);
541
542 rather, the smart match distributive rule takes precedence, so $obj is
543 smart matched against each array element in turn until a match is found,
544 so you may see between one and three of these calls instead:
545
546     $obj->match(1,0);
547     $obj->match(2,0);
548     $obj->match(3,0);
549
550 Consult the match table in  L<perlop/"Smartmatch Operator"> for
551 details of when overloading is invoked.
552
553 =item * I<Dereferencing>
554
555     ${}  @{}  %{}  &{}  *{}
556
557 If these operators are not explicitly overloaded then they
558 work in the normal way, yielding the underlying scalar,
559 array, or whatever stores the object data (or the appropriate
560 error message if the dereference operator doesn't match it).
561 Defining a catch-all C<'nomethod'> (see L<below|/nomethod>)
562 makes no difference to this as the catch-all function will
563 not be called to implement a missing dereference operator.
564
565 If a dereference operator is overloaded then it must return a
566 I<reference> of the appropriate type (for example, the
567 subroutine for key C<'${}'> should return a reference to a
568 scalar, not a scalar), or another object which overloads the
569 operator: that is, the subroutine only determines what is
570 dereferenced and the actual dereferencing is left to Perl.
571 As a special case, if the subroutine returns the object itself
572 then it will not be called again - avoiding infinite recursion.
573
574 =item * I<Special>
575
576     nomethod  fallback  =
577
578 See L<Special Keys for C<use overload>>.
579
580 =back
581
582 =head2 Magic Autogeneration
583
584 If a method for an operation is not found then Perl tries to
585 autogenerate a substitute implementation from the operations
586 that have been defined.
587
588 Note: the behaviour described in this section can be disabled
589 by setting C<fallback> to FALSE (see L</fallback>).
590
591 In the following tables, numbers indicate priority.
592 For example, the table below states that,
593 if no implementation for C<'!'> has been defined then Perl will
594 implement it using C<'bool'> (that is, by inverting the value
595 returned by the method for C<'bool'>);
596 if boolean conversion is also unimplemented then Perl will
597 use C<'0+'> or, failing that, C<'""'>.
598
599     operator | can be autogenerated from
600              |
601              | 0+   ""   bool   .   x
602     =========|==========================
603        0+    |       1     2
604        ""    |  1          2
605        bool  |  1    2
606        int   |  1    2     3
607        !     |  2    3     1
608        qr    |  2    1     3
609        .     |  2    1     3
610        x     |  2    1     3
611        .=    |  3    2     4    1
612        x=    |  3    2     4        1
613        <>    |  2    1     3
614        -X    |  2    1     3
615
616 Note: The iterator (C<'E<lt>E<gt>'>) and file test (C<'-X'>)
617 operators work as normal: if the operand is not a blessed glob or
618 IO reference then it is converted to a string (using the method
619 for C<'""'>, C<'0+'>, or C<'bool'>) to be interpreted as a glob
620 or filename.
621
622     operator | can be autogenerated from
623              |
624              |  <   <=>   neg   -=    -
625     =========|==========================
626        neg   |                        1
627        -=    |                        1
628        --    |                   1    2
629        abs   | a1    a2    b1        b2    [*]
630        <     |        1
631        <=    |        1
632        >     |        1
633        >=    |        1
634        ==    |        1
635        !=    |        1
636
637     * one from [a1, a2] and one from [b1, b2]
638
639 Just as numeric comparisons can be autogenerated from the method
640 for C<< '<=>' >>, string comparisons can be autogenerated from
641 that for C<'cmp'>:
642
643      operators          |  can be autogenerated from
644     ====================|===========================
645      lt gt le ge eq ne  |  cmp
646
647 Similarly, autogeneration for keys C<'+='> and C<'++'> is analogous
648 to C<'-='> and C<'--'> above:
649
650     operator | can be autogenerated from
651              |
652              |  +=    +
653     =========|==========================
654         +=   |        1
655         ++   |   1    2
656
657 And other assignment variations are analogous to
658 C<'+='> and C<'-='> (and similar to C<'.='> and C<'x='> above):
659
660               operator ||  *= /= %= **= <<= >>= &= ^= |= &.= ^.= |.=
661     -------------------||-------------------------------------------
662     autogenerated from ||  *  /  %  **  <<  >>  &  ^  |  &.  ^.  |.
663
664 Note also that the copy constructor (key C<'='>) may be
665 autogenerated, but only for objects based on scalars.
666 See L<Copy Constructor>.
667
668 =head3 Minimal Set of Overloaded Operations
669
670 Since some operations can be automatically generated from others, there is
671 a minimal set of operations that need to be overloaded in order to have
672 the complete set of overloaded operations at one's disposal.
673 Of course, the autogenerated operations may not do exactly what the user
674 expects.  The minimal set is:
675
676     + - * / % ** << >> x
677     <=> cmp
678     & | ^ ~ &. |. ^. ~.
679     atan2 cos sin exp log sqrt int
680     "" 0+ bool
681     ~~
682
683 Of the conversions, only one of string, boolean or numeric is
684 needed because each can be generated from either of the other two.
685
686 =head2 Special Keys for C<use overload>
687
688 =head3 C<nomethod>
689
690 The C<'nomethod'> key is used to specify a catch-all function to
691 be called for any operator that is not individually overloaded.
692 The specified function will be passed four parameters.
693 The first three arguments coincide with those that would have been
694 passed to the corresponding method if it had been defined.
695 The fourth argument is the C<use overload> key for that missing
696 method.  If the experimental "bitwise" feature is enabled (see L<feature>),
697 a fifth TRUE argument is passed to subroutines handling C<&>, C<|>, C<^> and C<~> to indicate that the caller is expecting numeric behaviour.
698
699 For example, if C<$a> is an object blessed into a package declaring
700
701     use overload 'nomethod' => 'catch_all', # ...
702
703 then the operation
704
705     3 + $a
706
707 could (unless a method is specifically declared for the key
708 C<'+'>) result in a call
709
710     catch_all($a, 3, 1, '+')
711
712 See L<How Perl Chooses an Operator Implementation>.
713
714 =head3 C<fallback>
715
716 The value assigned to the key C<'fallback'> tells Perl how hard
717 it should try to find an alternative way to implement a missing
718 operator.
719
720 =over
721
722 =item * defined, but FALSE
723
724     use overload "fallback" => 0, # ... ;
725
726 This disables L<Magic Autogeneration>.
727
728 =item * C<undef>
729
730 In the default case where no value is explicitly assigned to
731 C<fallback>, magic autogeneration is enabled.
732
733 =item * TRUE
734
735 The same as for C<undef>, but if a missing operator cannot be
736 autogenerated then, instead of issuing an error message, Perl
737 is allowed to revert to what it would have done for that
738 operator if there had been no C<use overload> directive.
739
740 Note: in most cases, particularly the L<Copy Constructor>,
741 this is unlikely to be appropriate behaviour.
742
743 =back
744
745 See L<How Perl Chooses an Operator Implementation>.
746
747 =head3 Copy Constructor
748
749 As mentioned L<above|"Mathemagic, Mutators, and Copy Constructors">,
750 this operation is called when a mutator is applied to a reference
751 that shares its object with some other reference.
752 For example, if C<$b> is mathemagical, and C<'++'> is overloaded
753 with C<'incr'>, and C<'='> is overloaded with C<'clone'>, then the
754 code
755
756     $a = $b;
757     # ... (other code which does not modify $a or $b) ...
758     ++$b;
759
760 would be executed in a manner equivalent to
761
762     $a = $b;
763     # ...
764     $b = $b->clone(undef, "");
765     $b->incr(undef, "");
766
767 Note:
768
769 =over
770
771 =item *
772
773 The subroutine for C<'='> does not overload the Perl assignment
774 operator: it is used only to allow mutators to work as described
775 here.  (See L</Assignments> above.)
776
777 =item *
778
779 As for other operations, the subroutine implementing '=' is passed
780 three arguments, though the last two are always C<undef> and C<''>.
781
782 =item *
783
784 The copy constructor is called only before a call to a function
785 declared to implement a mutator, for example, if C<++$b;> in the
786 code above is effected via a method declared for key C<'++'>
787 (or 'nomethod', passed C<'++'> as the fourth argument) or, by
788 autogeneration, C<'+='>.
789 It is not called if the increment operation is effected by a call
790 to the method for C<'+'> since, in the equivalent code,
791
792     $a = $b;
793     $b = $b + 1;
794
795 the data referred to by C<$a> is unchanged by the assignment to
796 C<$b> of a reference to new object data.
797
798 =item *
799
800 The copy constructor is not called if Perl determines that it is
801 unnecessary because there is no other reference to the data being
802 modified.
803
804 =item *
805
806 If C<'fallback'> is undefined or TRUE then a copy constructor
807 can be autogenerated, but only for objects based on scalars.
808 In other cases it needs to be defined explicitly.
809 Where an object's data is stored as, for example, an array of
810 scalars, the following might be appropriate:
811
812     use overload '=' => sub { bless [ @{$_[0]} ] },  # ...
813
814 =item *
815
816 If C<'fallback'> is TRUE and no copy constructor is defined then,
817 for objects not based on scalars, Perl may silently fall back on
818 simple assignment - that is, assignment of the object reference.
819 In effect, this disables the copy constructor mechanism since
820 no new copy of the object data is created.
821 This is almost certainly not what you want.
822 (It is, however, consistent: for example, Perl's fallback for the
823 C<++> operator is to increment the reference itself.)
824
825 =back
826
827 =head2 How Perl Chooses an Operator Implementation
828
829 Which is checked first, C<nomethod> or C<fallback>?
830 If the two operands of an operator are of different types and
831 both overload the operator, which implementation is used?
832 The following are the precedence rules:
833
834 =over
835
836 =item 1.
837
838 If the first operand has declared a subroutine to overload the
839 operator then use that implementation.
840
841 =item 2.
842
843 Otherwise, if fallback is TRUE or undefined for the
844 first operand then see if the
845 L<rules for autogeneration|"Magic Autogeneration">
846 allows another of its operators to be used instead.
847
848 =item 3.
849
850 Unless the operator is an assignment (C<+=>, C<-=>, etc.),
851 repeat step (1) in respect of the second operand.
852
853 =item 4.
854
855 Repeat Step (2) in respect of the second operand.
856
857 =item 5.
858
859 If the first operand has a "nomethod" method then use that.
860
861 =item 6.
862
863 If the second operand has a "nomethod" method then use that.
864
865 =item 7.
866
867 If C<fallback> is TRUE for both operands
868 then perform the usual operation for the operator,
869 treating the operands as numbers, strings, or booleans
870 as appropriate for the operator (see note).
871
872 =item 8.
873
874 Nothing worked - die.
875
876 =back
877
878 Where there is only one operand (or only one operand with
879 overloading) the checks in respect of the other operand above are
880 skipped.
881
882 There are exceptions to the above rules for dereference operations
883 (which, if Step 1 fails, always fall back to the normal, built-in
884 implementations - see Dereferencing), and for C<~~> (which has its
885 own set of rules - see C<Matching> under L</Overloadable Operations>
886 above).
887
888 Note on Step 7: some operators have a different semantic depending
889 on the type of their operands.
890 As there is no way to instruct Perl to treat the operands as, e.g.,
891 numbers instead of strings, the result here may not be what you
892 expect.
893 See L<BUGS AND PITFALLS>.
894
895 =head2 Losing Overloading
896
897 The restriction for the comparison operation is that even if, for example,
898 C<cmp> should return a blessed reference, the autogenerated C<lt>
899 function will produce only a standard logical value based on the
900 numerical value of the result of C<cmp>.  In particular, a working
901 numeric conversion is needed in this case (possibly expressed in terms of
902 other conversions).
903
904 Similarly, C<.=>  and C<x=> operators lose their mathemagical properties
905 if the string conversion substitution is applied.
906
907 When you chop() a mathemagical object it is promoted to a string and its
908 mathemagical properties are lost.  The same can happen with other
909 operations as well.
910
911 =head2 Inheritance and Overloading
912
913 Overloading respects inheritance via the @ISA hierarchy.
914 Inheritance interacts with overloading in two ways.
915
916 =over
917
918 =item Method names in the C<use overload> directive
919
920 If C<value> in
921
922   use overload key => value;
923
924 is a string, it is interpreted as a method name - which may
925 (in the usual way) be inherited from another class.
926
927 =item Overloading of an operation is inherited by derived classes
928
929 Any class derived from an overloaded class is also overloaded
930 and inherits its operator implementations.
931 If the same operator is overloaded in more than one ancestor
932 then the implementation is determined by the usual inheritance
933 rules.
934
935 For example, if C<A> inherits from C<B> and C<C> (in that order),
936 C<B> overloads C<+> with C<\&D::plus_sub>, and C<C> overloads
937 C<+> by C<"plus_meth">, then the subroutine C<D::plus_sub> will
938 be called to implement operation C<+> for an object in package C<A>.
939
940 =back
941
942 Note that in Perl version prior to 5.18 inheritance of the C<fallback> key
943 was not governed by the above rules.  The value of C<fallback> in the first 
944 overloaded ancestor was used.  This was fixed in 5.18 to follow the usual
945 rules of inheritance.
946
947 =head2 Run-time Overloading
948
949 Since all C<use> directives are executed at compile-time, the only way to
950 change overloading during run-time is to
951
952     eval 'use overload "+" => \&addmethod';
953
954 You can also use
955
956     eval 'no overload "+", "--", "<="';
957
958 though the use of these constructs during run-time is questionable.
959
960 =head2 Public Functions
961
962 Package C<overload.pm> provides the following public functions:
963
964 =over 5
965
966 =item overload::StrVal(arg)
967
968 Gives the string value of C<arg> as in the
969 absence of stringify overloading.  If you
970 are using this to get the address of a reference (useful for checking if two
971 references point to the same thing) then you may be better off using
972 C<Scalar::Util::refaddr()>, which is faster.
973
974 =item overload::Overloaded(arg)
975
976 Returns true if C<arg> is subject to overloading of some operations.
977
978 =item overload::Method(obj,op)
979
980 Returns C<undef> or a reference to the method that implements C<op>.
981
982 =back
983
984 =head2 Overloading Constants
985
986 For some applications, the Perl parser mangles constants too much.
987 It is possible to hook into this process via C<overload::constant()>
988 and C<overload::remove_constant()> functions.
989
990 These functions take a hash as an argument.  The recognized keys of this hash
991 are:
992
993 =over 8
994
995 =item integer
996
997 to overload integer constants,
998
999 =item float
1000
1001 to overload floating point constants,
1002
1003 =item binary
1004
1005 to overload octal and hexadecimal constants,
1006
1007 =item q
1008
1009 to overload C<q>-quoted strings, constant pieces of C<qq>- and C<qx>-quoted
1010 strings and here-documents,
1011
1012 =item qr
1013
1014 to overload constant pieces of regular expressions.
1015
1016 =back
1017
1018 The corresponding values are references to functions which take three arguments:
1019 the first one is the I<initial> string form of the constant, the second one
1020 is how Perl interprets this constant, the third one is how the constant is used.
1021 Note that the initial string form does not
1022 contain string delimiters, and has backslashes in backslash-delimiter
1023 combinations stripped (thus the value of delimiter is not relevant for
1024 processing of this string).  The return value of this function is how this
1025 constant is going to be interpreted by Perl.  The third argument is undefined
1026 unless for overloaded C<q>- and C<qr>- constants, it is C<q> in single-quote
1027 context (comes from strings, regular expressions, and single-quote HERE
1028 documents), it is C<tr> for arguments of C<tr>/C<y> operators,
1029 it is C<s> for right-hand side of C<s>-operator, and it is C<qq> otherwise.
1030
1031 Since an expression C<"ab$cd,,"> is just a shortcut for C<'ab' . $cd . ',,'>,
1032 it is expected that overloaded constant strings are equipped with reasonable
1033 overloaded catenation operator, otherwise absurd results will result.
1034 Similarly, negative numbers are considered as negations of positive constants.
1035
1036 Note that it is probably meaningless to call the functions overload::constant()
1037 and overload::remove_constant() from anywhere but import() and unimport() methods.
1038 From these methods they may be called as
1039
1040     sub import {
1041        shift;
1042        return unless @_;
1043        die "unknown import: @_" unless @_ == 1 and $_[0] eq ':constant';
1044        overload::constant integer => sub {Math::BigInt->new(shift)};
1045     }
1046
1047 =head1 IMPLEMENTATION
1048
1049 What follows is subject to change RSN.
1050
1051 The table of methods for all operations is cached in magic for the
1052 symbol table hash for the package.  The cache is invalidated during
1053 processing of C<use overload>, C<no overload>, new function
1054 definitions, and changes in @ISA.
1055
1056 (Every SVish thing has a magic queue, and magic is an entry in that
1057 queue.  This is how a single variable may participate in multiple
1058 forms of magic simultaneously.  For instance, environment variables
1059 regularly have two forms at once: their %ENV magic and their taint
1060 magic.  However, the magic which implements overloading is applied to
1061 the stashes, which are rarely used directly, thus should not slow down
1062 Perl.)
1063
1064 If a package uses overload, it carries a special flag.  This flag is also
1065 set when new functions are defined or @ISA is modified.  There will be a
1066 slight speed penalty on the very first operation thereafter that supports
1067 overloading, while the overload tables are updated.  If there is no
1068 overloading present, the flag is turned off.  Thus the only speed penalty
1069 thereafter is the checking of this flag.
1070
1071 It is expected that arguments to methods that are not explicitly supposed
1072 to be changed are constant (but this is not enforced).
1073
1074 =head1 COOKBOOK
1075
1076 Please add examples to what follows!
1077
1078 =head2 Two-face Scalars
1079
1080 Put this in F<two_face.pm> in your Perl library directory:
1081
1082   package two_face;             # Scalars with separate string and
1083                                 # numeric values.
1084   sub new { my $p = shift; bless [@_], $p }
1085   use overload '""' => \&str, '0+' => \&num, fallback => 1;
1086   sub num {shift->[1]}
1087   sub str {shift->[0]}
1088
1089 Use it as follows:
1090
1091   require two_face;
1092   my $seven = two_face->new("vii", 7);
1093   printf "seven=$seven, seven=%d, eight=%d\n", $seven, $seven+1;
1094   print "seven contains 'i'\n" if $seven =~ /i/;
1095
1096 (The second line creates a scalar which has both a string value, and a
1097 numeric value.)  This prints:
1098
1099   seven=vii, seven=7, eight=8
1100   seven contains 'i'
1101
1102 =head2 Two-face References
1103
1104 Suppose you want to create an object which is accessible as both an
1105 array reference and a hash reference.
1106
1107   package two_refs;
1108   use overload '%{}' => \&gethash, '@{}' => sub { $ {shift()} };
1109   sub new {
1110     my $p = shift;
1111     bless \ [@_], $p;
1112   }
1113   sub gethash {
1114     my %h;
1115     my $self = shift;
1116     tie %h, ref $self, $self;
1117     \%h;
1118   }
1119
1120   sub TIEHASH { my $p = shift; bless \ shift, $p }
1121   my %fields;
1122   my $i = 0;
1123   $fields{$_} = $i++ foreach qw{zero one two three};
1124   sub STORE {
1125     my $self = ${shift()};
1126     my $key = $fields{shift()};
1127     defined $key or die "Out of band access";
1128     $$self->[$key] = shift;
1129   }
1130   sub FETCH {
1131     my $self = ${shift()};
1132     my $key = $fields{shift()};
1133     defined $key or die "Out of band access";
1134     $$self->[$key];
1135   }
1136
1137 Now one can access an object using both the array and hash syntax:
1138
1139   my $bar = two_refs->new(3,4,5,6);
1140   $bar->[2] = 11;
1141   $bar->{two} == 11 or die 'bad hash fetch';
1142
1143 Note several important features of this example.  First of all, the
1144 I<actual> type of $bar is a scalar reference, and we do not overload
1145 the scalar dereference.  Thus we can get the I<actual> non-overloaded
1146 contents of $bar by just using C<$$bar> (what we do in functions which
1147 overload dereference).  Similarly, the object returned by the
1148 TIEHASH() method is a scalar reference.
1149
1150 Second, we create a new tied hash each time the hash syntax is used.
1151 This allows us not to worry about a possibility of a reference loop,
1152 which would lead to a memory leak.
1153
1154 Both these problems can be cured.  Say, if we want to overload hash
1155 dereference on a reference to an object which is I<implemented> as a
1156 hash itself, the only problem one has to circumvent is how to access
1157 this I<actual> hash (as opposed to the I<virtual> hash exhibited by the
1158 overloaded dereference operator).  Here is one possible fetching routine:
1159
1160   sub access_hash {
1161     my ($self, $key) = (shift, shift);
1162     my $class = ref $self;
1163     bless $self, 'overload::dummy'; # Disable overloading of %{}
1164     my $out = $self->{$key};
1165     bless $self, $class;        # Restore overloading
1166     $out;
1167   }
1168
1169 To remove creation of the tied hash on each access, one may an extra
1170 level of indirection which allows a non-circular structure of references:
1171
1172   package two_refs1;
1173   use overload '%{}' => sub { ${shift()}->[1] },
1174                '@{}' => sub { ${shift()}->[0] };
1175   sub new {
1176     my $p = shift;
1177     my $a = [@_];
1178     my %h;
1179     tie %h, $p, $a;
1180     bless \ [$a, \%h], $p;
1181   }
1182   sub gethash {
1183     my %h;
1184     my $self = shift;
1185     tie %h, ref $self, $self;
1186     \%h;
1187   }
1188
1189   sub TIEHASH { my $p = shift; bless \ shift, $p }
1190   my %fields;
1191   my $i = 0;
1192   $fields{$_} = $i++ foreach qw{zero one two three};
1193   sub STORE {
1194     my $a = ${shift()};
1195     my $key = $fields{shift()};
1196     defined $key or die "Out of band access";
1197     $a->[$key] = shift;
1198   }
1199   sub FETCH {
1200     my $a = ${shift()};
1201     my $key = $fields{shift()};
1202     defined $key or die "Out of band access";
1203     $a->[$key];
1204   }
1205
1206 Now if $baz is overloaded like this, then C<$baz> is a reference to a
1207 reference to the intermediate array, which keeps a reference to an
1208 actual array, and the access hash.  The tie()ing object for the access
1209 hash is a reference to a reference to the actual array, so
1210
1211 =over
1212
1213 =item *
1214
1215 There are no loops of references.
1216
1217 =item *
1218
1219 Both "objects" which are blessed into the class C<two_refs1> are
1220 references to a reference to an array, thus references to a I<scalar>.
1221 Thus the accessor expression C<$$foo-E<gt>[$ind]> involves no
1222 overloaded operations.
1223
1224 =back
1225
1226 =head2 Symbolic Calculator
1227
1228 Put this in F<symbolic.pm> in your Perl library directory:
1229
1230   package symbolic;             # Primitive symbolic calculator
1231   use overload nomethod => \&wrap;
1232
1233   sub new { shift; bless ['n', @_] }
1234   sub wrap {
1235     my ($obj, $other, $inv, $meth) = @_;
1236     ($obj, $other) = ($other, $obj) if $inv;
1237     bless [$meth, $obj, $other];
1238   }
1239
1240 This module is very unusual as overloaded modules go: it does not
1241 provide any usual overloaded operators, instead it provides an
1242 implementation for L</C<nomethod>>.  In this example the C<nomethod>
1243 subroutine returns an object which encapsulates operations done over
1244 the objects: C<< symbolic->new(3) >> contains C<['n', 3]>, C<< 2 +
1245 symbolic->new(3) >> contains C<['+', 2, ['n', 3]]>.
1246
1247 Here is an example of the script which "calculates" the side of
1248 circumscribed octagon using the above package:
1249
1250   require symbolic;
1251   my $iter = 1;                 # 2**($iter+2) = 8
1252   my $side = symbolic->new(1);
1253   my $cnt = $iter;
1254
1255   while ($cnt--) {
1256     $side = (sqrt(1 + $side**2) - 1)/$side;
1257   }
1258   print "OK\n";
1259
1260 The value of $side is
1261
1262   ['/', ['-', ['sqrt', ['+', 1, ['**', ['n', 1], 2]],
1263                        undef], 1], ['n', 1]]
1264
1265 Note that while we obtained this value using a nice little script,
1266 there is no simple way to I<use> this value.  In fact this value may
1267 be inspected in debugger (see L<perldebug>), but only if
1268 C<bareStringify> B<O>ption is set, and not via C<p> command.
1269
1270 If one attempts to print this value, then the overloaded operator
1271 C<""> will be called, which will call C<nomethod> operator.  The
1272 result of this operator will be stringified again, but this result is
1273 again of type C<symbolic>, which will lead to an infinite loop.
1274
1275 Add a pretty-printer method to the module F<symbolic.pm>:
1276
1277   sub pretty {
1278     my ($meth, $a, $b) = @{+shift};
1279     $a = 'u' unless defined $a;
1280     $b = 'u' unless defined $b;
1281     $a = $a->pretty if ref $a;
1282     $b = $b->pretty if ref $b;
1283     "[$meth $a $b]";
1284   }
1285
1286 Now one can finish the script by
1287
1288   print "side = ", $side->pretty, "\n";
1289
1290 The method C<pretty> is doing object-to-string conversion, so it
1291 is natural to overload the operator C<""> using this method.  However,
1292 inside such a method it is not necessary to pretty-print the
1293 I<components> $a and $b of an object.  In the above subroutine
1294 C<"[$meth $a $b]"> is a catenation of some strings and components $a
1295 and $b.  If these components use overloading, the catenation operator
1296 will look for an overloaded operator C<.>; if not present, it will
1297 look for an overloaded operator C<"">.  Thus it is enough to use
1298
1299   use overload nomethod => \&wrap, '""' => \&str;
1300   sub str {
1301     my ($meth, $a, $b) = @{+shift};
1302     $a = 'u' unless defined $a;
1303     $b = 'u' unless defined $b;
1304     "[$meth $a $b]";
1305   }
1306
1307 Now one can change the last line of the script to
1308
1309   print "side = $side\n";
1310
1311 which outputs
1312
1313   side = [/ [- [sqrt [+ 1 [** [n 1 u] 2]] u] 1] [n 1 u]]
1314
1315 and one can inspect the value in debugger using all the possible
1316 methods.
1317
1318 Something is still amiss: consider the loop variable $cnt of the
1319 script.  It was a number, not an object.  We cannot make this value of
1320 type C<symbolic>, since then the loop will not terminate.
1321
1322 Indeed, to terminate the cycle, the $cnt should become false.
1323 However, the operator C<bool> for checking falsity is overloaded (this
1324 time via overloaded C<"">), and returns a long string, thus any object
1325 of type C<symbolic> is true.  To overcome this, we need a way to
1326 compare an object to 0.  In fact, it is easier to write a numeric
1327 conversion routine.
1328
1329 Here is the text of F<symbolic.pm> with such a routine added (and
1330 slightly modified str()):
1331
1332   package symbolic;             # Primitive symbolic calculator
1333   use overload
1334     nomethod => \&wrap, '""' => \&str, '0+' => \&num;
1335
1336   sub new { shift; bless ['n', @_] }
1337   sub wrap {
1338     my ($obj, $other, $inv, $meth) = @_;
1339     ($obj, $other) = ($other, $obj) if $inv;
1340     bless [$meth, $obj, $other];
1341   }
1342   sub str {
1343     my ($meth, $a, $b) = @{+shift};
1344     $a = 'u' unless defined $a;
1345     if (defined $b) {
1346       "[$meth $a $b]";
1347     } else {
1348       "[$meth $a]";
1349     }
1350   }
1351   my %subr = ( n => sub {$_[0]},
1352                sqrt => sub {sqrt $_[0]},
1353                '-' => sub {shift() - shift()},
1354                '+' => sub {shift() + shift()},
1355                '/' => sub {shift() / shift()},
1356                '*' => sub {shift() * shift()},
1357                '**' => sub {shift() ** shift()},
1358              );
1359   sub num {
1360     my ($meth, $a, $b) = @{+shift};
1361     my $subr = $subr{$meth}
1362       or die "Do not know how to ($meth) in symbolic";
1363     $a = $a->num if ref $a eq __PACKAGE__;
1364     $b = $b->num if ref $b eq __PACKAGE__;
1365     $subr->($a,$b);
1366   }
1367
1368 All the work of numeric conversion is done in %subr and num().  Of
1369 course, %subr is not complete, it contains only operators used in the
1370 example below.  Here is the extra-credit question: why do we need an
1371 explicit recursion in num()?  (Answer is at the end of this section.)
1372
1373 Use this module like this:
1374
1375   require symbolic;
1376   my $iter = symbolic->new(2);  # 16-gon
1377   my $side = symbolic->new(1);
1378   my $cnt = $iter;
1379
1380   while ($cnt) {
1381     $cnt = $cnt - 1;            # Mutator '--' not implemented
1382     $side = (sqrt(1 + $side**2) - 1)/$side;
1383   }
1384   printf "%s=%f\n", $side, $side;
1385   printf "pi=%f\n", $side*(2**($iter+2));
1386
1387 It prints (without so many line breaks)
1388
1389   [/ [- [sqrt [+ 1 [** [/ [- [sqrt [+ 1 [** [n 1] 2]]] 1]
1390                           [n 1]] 2]]] 1]
1391      [/ [- [sqrt [+ 1 [** [n 1] 2]]] 1] [n 1]]]=0.198912
1392   pi=3.182598
1393
1394 The above module is very primitive.  It does not implement
1395 mutator methods (C<++>, C<-=> and so on), does not do deep copying
1396 (not required without mutators!), and implements only those arithmetic
1397 operations which are used in the example.
1398
1399 To implement most arithmetic operations is easy; one should just use
1400 the tables of operations, and change the code which fills %subr to
1401
1402   my %subr = ( 'n' => sub {$_[0]} );
1403   foreach my $op (split " ", $overload::ops{with_assign}) {
1404     $subr{$op} = $subr{"$op="} = eval "sub {shift() $op shift()}";
1405   }
1406   my @bins = qw(binary 3way_comparison num_comparison str_comparison);
1407   foreach my $op (split " ", "@overload::ops{ @bins }") {
1408     $subr{$op} = eval "sub {shift() $op shift()}";
1409   }
1410   foreach my $op (split " ", "@overload::ops{qw(unary func)}") {
1411     print "defining '$op'\n";
1412     $subr{$op} = eval "sub {$op shift()}";
1413   }
1414
1415 Since subroutines implementing assignment operators are not required
1416 to modify their operands (see L<Overloadable Operations> above),
1417 we do not need anything special to make C<+=> and friends work,
1418 besides adding these operators to %subr and defining a copy
1419 constructor (needed since Perl has no way to know that the
1420 implementation of C<'+='> does not mutate the argument -
1421 see L<Copy Constructor>).
1422
1423 To implement a copy constructor, add C<< '=' => \&cpy >> to C<use overload>
1424 line, and code (this code assumes that mutators change things one level
1425 deep only, so recursive copying is not needed):
1426
1427   sub cpy {
1428     my $self = shift;
1429     bless [@$self], ref $self;
1430   }
1431
1432 To make C<++> and C<--> work, we need to implement actual mutators,
1433 either directly, or in C<nomethod>.  We continue to do things inside
1434 C<nomethod>, thus add
1435
1436     if ($meth eq '++' or $meth eq '--') {
1437       @$obj = ($meth, (bless [@$obj]), 1); # Avoid circular reference
1438       return $obj;
1439     }
1440
1441 after the first line of wrap().  This is not a most effective
1442 implementation, one may consider
1443
1444   sub inc { $_[0] = bless ['++', shift, 1]; }
1445
1446 instead.
1447
1448 As a final remark, note that one can fill %subr by
1449
1450   my %subr = ( 'n' => sub {$_[0]} );
1451   foreach my $op (split " ", $overload::ops{with_assign}) {
1452     $subr{$op} = $subr{"$op="} = eval "sub {shift() $op shift()}";
1453   }
1454   my @bins = qw(binary 3way_comparison num_comparison str_comparison);
1455   foreach my $op (split " ", "@overload::ops{ @bins }") {
1456     $subr{$op} = eval "sub {shift() $op shift()}";
1457   }
1458   foreach my $op (split " ", "@overload::ops{qw(unary func)}") {
1459     $subr{$op} = eval "sub {$op shift()}";
1460   }
1461   $subr{'++'} = $subr{'+'};
1462   $subr{'--'} = $subr{'-'};
1463
1464 This finishes implementation of a primitive symbolic calculator in
1465 50 lines of Perl code.  Since the numeric values of subexpressions
1466 are not cached, the calculator is very slow.
1467
1468 Here is the answer for the exercise: In the case of str(), we need no
1469 explicit recursion since the overloaded C<.>-operator will fall back
1470 to an existing overloaded operator C<"">.  Overloaded arithmetic
1471 operators I<do not> fall back to numeric conversion if C<fallback> is
1472 not explicitly requested.  Thus without an explicit recursion num()
1473 would convert C<['+', $a, $b]> to C<$a + $b>, which would just rebuild
1474 the argument of num().
1475
1476 If you wonder why defaults for conversion are different for str() and
1477 num(), note how easy it was to write the symbolic calculator.  This
1478 simplicity is due to an appropriate choice of defaults.  One extra
1479 note: due to the explicit recursion num() is more fragile than sym():
1480 we need to explicitly check for the type of $a and $b.  If components
1481 $a and $b happen to be of some related type, this may lead to problems.
1482
1483 =head2 I<Really> Symbolic Calculator
1484
1485 One may wonder why we call the above calculator symbolic.  The reason
1486 is that the actual calculation of the value of expression is postponed
1487 until the value is I<used>.
1488
1489 To see it in action, add a method
1490
1491   sub STORE {
1492     my $obj = shift;
1493     $#$obj = 1;
1494     @$obj->[0,1] = ('=', shift);
1495   }
1496
1497 to the package C<symbolic>.  After this change one can do
1498
1499   my $a = symbolic->new(3);
1500   my $b = symbolic->new(4);
1501   my $c = sqrt($a**2 + $b**2);
1502
1503 and the numeric value of $c becomes 5.  However, after calling
1504
1505   $a->STORE(12);  $b->STORE(5);
1506
1507 the numeric value of $c becomes 13.  There is no doubt now that the module
1508 symbolic provides a I<symbolic> calculator indeed.
1509
1510 To hide the rough edges under the hood, provide a tie()d interface to the
1511 package C<symbolic>.  Add methods
1512
1513   sub TIESCALAR { my $pack = shift; $pack->new(@_) }
1514   sub FETCH { shift }
1515   sub nop {  }          # Around a bug
1516
1517 (the bug, fixed in Perl 5.14, is described in L<"BUGS">).  One can use this
1518 new interface as
1519
1520   tie $a, 'symbolic', 3;
1521   tie $b, 'symbolic', 4;
1522   $a->nop;  $b->nop;    # Around a bug
1523
1524   my $c = sqrt($a**2 + $b**2);
1525
1526 Now numeric value of $c is 5.  After C<$a = 12; $b = 5> the numeric value
1527 of $c becomes 13.  To insulate the user of the module add a method
1528
1529   sub vars { my $p = shift; tie($_, $p), $_->nop foreach @_; }
1530
1531 Now
1532
1533   my ($a, $b);
1534   symbolic->vars($a, $b);
1535   my $c = sqrt($a**2 + $b**2);
1536
1537   $a = 3; $b = 4;
1538   printf "c5  %s=%f\n", $c, $c;
1539
1540   $a = 12; $b = 5;
1541   printf "c13  %s=%f\n", $c, $c;
1542
1543 shows that the numeric value of $c follows changes to the values of $a
1544 and $b.
1545
1546 =head1 AUTHOR
1547
1548 Ilya Zakharevich E<lt>F<ilya@math.mps.ohio-state.edu>E<gt>.
1549
1550 =head1 SEE ALSO
1551
1552 The C<overloading> pragma can be used to enable or disable overloaded
1553 operations within a lexical scope - see L<overloading>.
1554
1555 =head1 DIAGNOSTICS
1556
1557 When Perl is run with the B<-Do> switch or its equivalent, overloading
1558 induces diagnostic messages.
1559
1560 Using the C<m> command of Perl debugger (see L<perldebug>) one can
1561 deduce which operations are overloaded (and which ancestor triggers
1562 this overloading).  Say, if C<eq> is overloaded, then the method C<(eq>
1563 is shown by debugger.  The method C<()> corresponds to the C<fallback>
1564 key (in fact a presence of this method shows that this package has
1565 overloading enabled, and it is what is used by the C<Overloaded>
1566 function of module C<overload>).
1567
1568 The module might issue the following warnings:
1569
1570 =over 4
1571
1572 =item Odd number of arguments for overload::constant
1573
1574 (W) The call to overload::constant contained an odd number of arguments.
1575 The arguments should come in pairs.
1576
1577 =item '%s' is not an overloadable type
1578
1579 (W) You tried to overload a constant type the overload package is unaware of.
1580
1581 =item '%s' is not a code reference
1582
1583 (W) The second (fourth, sixth, ...) argument of overload::constant needs
1584 to be a code reference.  Either an anonymous subroutine, or a reference
1585 to a subroutine.
1586
1587 =item overload arg '%s' is invalid
1588
1589 (W) C<use overload> was passed an argument it did not
1590 recognize.  Did you mistype an operator?
1591
1592 =back
1593
1594 =head1 BUGS AND PITFALLS
1595
1596 =over
1597
1598 =item *
1599
1600 A pitfall when fallback is TRUE and Perl resorts to a built-in
1601 implementation of an operator is that some operators have more
1602 than one semantic, for example C<|>:
1603
1604         use overload '0+' => sub { $_[0]->{n}; },
1605             fallback => 1;
1606         my $x = bless { n => 4 }, "main";
1607         my $y = bless { n => 8 }, "main";
1608         print $x | $y, "\n";
1609
1610 You might expect this to output "12".
1611 In fact, it prints "<": the ASCII result of treating "|"
1612 as a bitwise string operator - that is, the result of treating
1613 the operands as the strings "4" and "8" rather than numbers.
1614 The fact that numify (C<0+>) is implemented but stringify
1615 (C<"">) isn't makes no difference since the latter is simply
1616 autogenerated from the former.
1617
1618 The only way to change this is to provide your own subroutine
1619 for C<'|'>.
1620
1621 =item *
1622
1623 Magic autogeneration increases the potential for inadvertently
1624 creating self-referential structures.
1625 Currently Perl will not free self-referential
1626 structures until cycles are explicitly broken.
1627 For example,
1628
1629     use overload '+' => 'add';
1630     sub add { bless [ \$_[0], \$_[1] ] };
1631
1632 is asking for trouble, since
1633
1634     $obj += $y;
1635
1636 will effectively become
1637
1638     $obj = add($obj, $y, undef);
1639
1640 with the same result as
1641
1642     $obj = [\$obj, \$foo];
1643
1644 Even if no I<explicit> assignment-variants of operators are present in
1645 the script, they may be generated by the optimizer.
1646 For example,
1647
1648     "obj = $obj\n"
1649
1650 may be optimized to
1651
1652     my $tmp = 'obj = ' . $obj;  $tmp .= "\n";
1653
1654 =item *
1655
1656 The symbol table is filled with names looking like line-noise.
1657
1658 =item *
1659
1660 This bug was fixed in Perl 5.18, but may still trip you up if you are using
1661 older versions:
1662
1663 For the purpose of inheritance every overloaded package behaves as if
1664 C<fallback> is present (possibly undefined).  This may create
1665 interesting effects if some package is not overloaded, but inherits
1666 from two overloaded packages.
1667
1668 =item *
1669
1670 Before Perl 5.14, the relation between overloading and tie()ing was broken.
1671 Overloading was triggered or not based on the I<previous> class of the
1672 tie()d variable.
1673
1674 This happened because the presence of overloading was checked
1675 too early, before any tie()d access was attempted.  If the
1676 class of the value FETCH()ed from the tied variable does not
1677 change, a simple workaround for code that is to run on older Perl
1678 versions is to access the value (via C<() = $foo> or some such)
1679 immediately after tie()ing, so that after this call the I<previous> class
1680 coincides with the current one.
1681
1682 =item *
1683
1684 Barewords are not covered by overloaded string constants.
1685
1686 =item *
1687
1688 The range operator C<..> cannot be overloaded.
1689
1690 =back
1691
1692 =cut
1693