1overload(3pm)          Perl Programmers Reference Guide          overload(3pm)
2
3
4

NAME

6       overload - Package for overloading Perl operations
7

SYNOPSIS

9           package SomeThing;
10
11           use overload
12               '+' => \&myadd,
13               '-' => \&mysub;
14               # etc
15           ...
16
17           package main;
18           $a = SomeThing->new( 57 );
19           $b = 5 + $a;
20           ...
21           if (overload::Overloaded $b) {...}
22           ...
23           $strval = overload::StrVal $b;
24

DESCRIPTION

26       This pragma allows overloading of Perl's operators for a class.  To
27       overload built-in functions, see "Overriding Built-in Functions" in
28       perlsub instead.
29
30   Fundamentals
31       Declaration
32
33       Arguments of the "use overload" directive are (key, value) pairs.  For
34       the full set of legal keys, see "Overloadable Operations" below.
35
36       Operator implementations (the values) can be subroutines, references to
37       subroutines, or anonymous subroutines - in other words, anything legal
38       inside a "&{ ... }" call.  Values specified as strings are interpreted
39       as method names.  Thus
40
41           package Number;
42           use overload
43               "-" => "minus",
44               "*=" => \&muas,
45               '""' => sub { ...; };
46
47       declares that subtraction is to be implemented by method "minus()" in
48       the class "Number" (or one of its base classes), and that the function
49       "Number::muas()" is to be used for the assignment form of
50       multiplication, "*=".  It also defines an anonymous subroutine to
51       implement stringification: this is called whenever an object blessed
52       into the package "Number" is used in a string context (this subroutine
53       might, for example, return the number as a Roman numeral).
54
55       Calling Conventions and Magic Autogeneration
56
57       The following sample implementation of "minus()" (which assumes that
58       "Number" objects are simply blessed references to scalars) illustrates
59       the calling conventions:
60
61           package Number;
62           sub minus {
63               my ($self, $other, $swap) = @_;
64               my $result = $$self - $other;         # *
65               $result = -$result if $swap;
66               ref $result ? $result : bless \$result;
67           }
68           # * may recurse once - see table below
69
70       Three arguments are passed to all subroutines specified in the "use
71       overload" directive (with exceptions - see below, particularly
72       "nomethod").
73
74       The first of these is the operand providing the overloaded operator
75       implementation - in this case, the object whose "minus()" method is
76       being called.
77
78       The second argument is the other operand, or "undef" in the case of a
79       unary operator.
80
81       The third argument is set to TRUE if (and only if) the two operands
82       have been swapped.  Perl may do this to ensure that the first argument
83       ($self) is an object implementing the overloaded operation, in line
84       with general object calling conventions.  For example, if $x and $y are
85       "Number"s:
86
87           operation   |   generates a call to
88           ============|======================
89           $x - $y     |   minus($x, $y, '')
90           $x - 7      |   minus($x, 7, '')
91           7 - $x      |   minus($x, 7, 1)
92
93       Perl may also use "minus()" to implement other operators which have not
94       been specified in the "use overload" directive, according to the rules
95       for "Magic Autogeneration" described later.  For example, the "use
96       overload" above declared no subroutine for any of the operators "--",
97       "neg" (the overload key for unary minus), or "-=".  Thus
98
99           operation   |   generates a call to
100           ============|======================
101           -$x         |   minus($x, 0, 1)
102           $x--        |   minus($x, 1, undef)
103           $x -= 3     |   minus($x, 3, undef)
104
105       Note the "undef"s: where autogeneration results in the method for a
106       standard operator which does not change either of its operands, such as
107       "-", being used to implement an operator which changes the operand
108       ("mutators": here, "--" and "-="), Perl passes undef as the third
109       argument.  This still evaluates as FALSE, consistent with the fact that
110       the operands have not been swapped, but gives the subroutine a chance
111       to alter its behaviour in these cases.
112
113       In all the above examples, "minus()" is required only to return the
114       result of the subtraction: Perl takes care of the assignment to $x.  In
115       fact, such methods should not modify their operands, even if "undef" is
116       passed as the third argument (see "Overloadable Operations").
117
118       The same is not true of implementations of "++" and "--": these are
119       expected to modify their operand.  An appropriate implementation of
120       "--" might look like
121
122           use overload '--' => "decr",
123               # ...
124           sub decr { --${$_[0]}; }
125
126       If the "bitwise" feature is enabled (see feature), a fifth TRUE
127       argument is passed to subroutines handling "&", "|", "^" and "~".  This
128       indicates that the caller is expecting numeric behaviour.  The fourth
129       argument will be "undef", as that position ($_[3]) is reserved for use
130       by "nomethod".
131
132       Mathemagic, Mutators, and Copy Constructors
133
134       The term 'mathemagic' describes the overloaded implementation of
135       mathematical operators.  Mathemagical operations raise an issue.
136       Consider the code:
137
138           $a = $b;
139           --$a;
140
141       If $a and $b are scalars then after these statements
142
143           $a == $b - 1
144
145       An object, however, is a reference to blessed data, so if $a and $b are
146       objects then the assignment "$a = $b" copies only the reference,
147       leaving $a and $b referring to the same object data.  One might
148       therefore expect the operation "--$a" to decrement $b as well as $a.
149       However, this would not be consistent with how we expect the
150       mathematical operators to work.
151
152       Perl resolves this dilemma by transparently calling a copy constructor
153       before calling a method defined to implement a mutator ("--", "+=", and
154       so on.).  In the above example, when Perl reaches the decrement
155       statement, it makes a copy of the object data in $a and assigns to $a a
156       reference to the copied data.  Only then does it call "decr()", which
157       alters the copied data, leaving $b unchanged.  Thus the object metaphor
158       is preserved as far as possible, while mathemagical operations still
159       work according to the arithmetic metaphor.
160
161       Note: the preceding paragraph describes what happens when Perl
162       autogenerates the copy constructor for an object based on a scalar.
163       For other cases, see "Copy Constructor".
164
165   Overloadable Operations
166       The complete list of keys that can be specified in the "use overload"
167       directive are given, separated by spaces, in the values of the hash
168       %overload::ops:
169
170        with_assign      => '+ - * / % ** << >> x .',
171        assign           => '+= -= *= /= %= **= <<= >>= x= .=',
172        num_comparison   => '< <= > >= == !=',
173        '3way_comparison'=> '<=> cmp',
174        str_comparison   => 'lt le gt ge eq ne',
175        binary           => '& &= | |= ^ ^= &. &.= |. |.= ^. ^.=',
176        unary            => 'neg ! ~ ~.',
177        mutators         => '++ --',
178        func             => 'atan2 cos sin exp abs log sqrt int',
179        conversion       => 'bool "" 0+ qr',
180        iterators        => '<>',
181        filetest         => '-X',
182        dereferencing    => '${} @{} %{} &{} *{}',
183        matching         => '~~',
184        special          => 'nomethod fallback ='
185
186       Most of the overloadable operators map one-to-one to these keys.
187       Exceptions, including additional overloadable operations not apparent
188       from this hash, are included in the notes which follow.  This list is
189       subject to growth over time.
190
191       A warning is issued if an attempt is made to register an operator not
192       found above.
193
194       ·    "not"
195
196            The operator "not" is not a valid key for "use overload".
197            However, if the operator "!" is overloaded then the same
198            implementation will be used for "not" (since the two operators
199            differ only in precedence).
200
201       ·    "neg"
202
203            The key "neg" is used for unary minus to disambiguate it from
204            binary "-".
205
206       ·    "++", "--"
207
208            Assuming they are to behave analogously to Perl's "++" and "--",
209            overloaded implementations of these operators are required to
210            mutate their operands.
211
212            No distinction is made between prefix and postfix forms of the
213            increment and decrement operators: these differ only in the point
214            at which Perl calls the associated subroutine when evaluating an
215            expression.
216
217       ·    Assignments
218
219                +=  -=  *=  /=  %=  **=  <<=  >>=  x=  .=
220                &=  |=  ^=  &.=  |.=  ^.=
221
222            Simple assignment is not overloadable (the '=' key is used for the
223            "Copy Constructor").  Perl does have a way to make assignments to
224            an object do whatever you want, but this involves using tie(), not
225            overload - see "tie" in perlfunc and the "COOKBOOK" examples
226            below.
227
228            The subroutine for the assignment variant of an operator is
229            required only to return the result of the operation.  It is
230            permitted to change the value of its operand (this is safe because
231            Perl calls the copy constructor first), but this is optional since
232            Perl assigns the returned value to the left-hand operand anyway.
233
234            An object that overloads an assignment operator does so only in
235            respect of assignments to that object.  In other words, Perl never
236            calls the corresponding methods with the third argument (the
237            "swap" argument) set to TRUE.  For example, the operation
238
239                $a *= $b
240
241            cannot lead to $b's implementation of "*=" being called, even if
242            $a is a scalar.  (It can, however, generate a call to $b's method
243            for "*").
244
245       ·    Non-mutators with a mutator variant
246
247                 +  -  *  /  %  **  <<  >>  x  .
248                 &  |  ^  &.  |.  ^.
249
250            As described above, Perl may call methods for operators like "+"
251            and "&" in the course of implementing missing operations like
252            "++", "+=", and "&=".  While these methods may detect this usage
253            by testing the definedness of the third argument, they should in
254            all cases avoid changing their operands.  This is because Perl
255            does not call the copy constructor before invoking these methods.
256
257       ·    "int"
258
259            Traditionally, the Perl function "int" rounds to 0 (see "int" in
260            perlfunc), and so for floating-point-like types one should follow
261            the same semantic.
262
263       ·    String, numeric, boolean, and regexp conversions
264
265                ""  0+  bool
266
267            These conversions are invoked according to context as necessary.
268            For example, the subroutine for '""' (stringify) may be used where
269            the overloaded object is passed as an argument to "print", and
270            that for 'bool' where it is tested in the condition of a flow
271            control statement (like "while") or the ternary "?:" operation.
272
273            Of course, in contexts like, for example, "$obj + 1", Perl will
274            invoke $obj's implementation of "+" rather than (in this example)
275            converting $obj to a number using the numify method '0+' (an
276            exception to this is when no method has been provided for '+' and
277            "fallback" is set to TRUE).
278
279            The subroutines for '""', '0+', and 'bool' can return any
280            arbitrary Perl value.  If the corresponding operation for this
281            value is overloaded too, the operation will be called again with
282            this value.
283
284            As a special case if the overload returns the object itself then
285            it will be used directly.  An overloaded conversion returning the
286            object is probably a bug, because you're likely to get something
287            that looks like "YourPackage=HASH(0x8172b34)".
288
289                qr
290
291            The subroutine for 'qr' is used wherever the object is
292            interpolated into or used as a regexp, including when it appears
293            on the RHS of a "=~" or "!~" operator.
294
295            "qr" must return a compiled regexp, or a ref to a compiled regexp
296            (such as "qr//" returns), and any further overloading on the
297            return value will be ignored.
298
299       ·    Iteration
300
301            If "<>" is overloaded then the same implementation is used for
302            both the read-filehandle syntax "<$var>" and globbing syntax
303            "<${var}>".
304
305       ·    File tests
306
307            The key '-X' is used to specify a subroutine to handle all the
308            filetest operators ("-f", "-x", and so on: see "-X" in perlfunc
309            for the full list); it is not possible to overload any filetest
310            operator individually.  To distinguish them, the letter following
311            the '-' is passed as the second argument (that is, in the slot
312            that for binary operators is used to pass the second operand).
313
314            Calling an overloaded filetest operator does not affect the stat
315            value associated with the special filehandle "_".  It still refers
316            to the result of the last "stat", "lstat" or unoverloaded
317            filetest.
318
319            This overload was introduced in Perl 5.12.
320
321       ·    Matching
322
323            The key "~~" allows you to override the smart matching logic used
324            by the "~~" operator and the switch construct ("given"/"when").
325            See "Switch Statements" in perlsyn and feature.
326
327            Unusually, the overloaded implementation of the smart match
328            operator does not get full control of the smart match behaviour.
329            In particular, in the following code:
330
331                package Foo;
332                use overload '~~' => 'match';
333
334                my $obj =  Foo->new();
335                $obj ~~ [ 1,2,3 ];
336
337            the smart match does not invoke the method call like this:
338
339                $obj->match([1,2,3],0);
340
341            rather, the smart match distributive rule takes precedence, so
342            $obj is smart matched against each array element in turn until a
343            match is found, so you may see between one and three of these
344            calls instead:
345
346                $obj->match(1,0);
347                $obj->match(2,0);
348                $obj->match(3,0);
349
350            Consult the match table in  "Smartmatch Operator" in perlop for
351            details of when overloading is invoked.
352
353       ·    Dereferencing
354
355                ${}  @{}  %{}  &{}  *{}
356
357            If these operators are not explicitly overloaded then they work in
358            the normal way, yielding the underlying scalar, array, or whatever
359            stores the object data (or the appropriate error message if the
360            dereference operator doesn't match it).  Defining a catch-all
361            'nomethod' (see below) makes no difference to this as the catch-
362            all function will not be called to implement a missing dereference
363            operator.
364
365            If a dereference operator is overloaded then it must return a
366            reference of the appropriate type (for example, the subroutine for
367            key '${}' should return a reference to a scalar, not a scalar), or
368            another object which overloads the operator: that is, the
369            subroutine only determines what is dereferenced and the actual
370            dereferencing is left to Perl.  As a special case, if the
371            subroutine returns the object itself then it will not be called
372            again - avoiding infinite recursion.
373
374       ·    Special
375
376                nomethod  fallback  =
377
378            See "Special Keys for "use overload"".
379
380   Magic Autogeneration
381       If a method for an operation is not found then Perl tries to
382       autogenerate a substitute implementation from the operations that have
383       been defined.
384
385       Note: the behaviour described in this section can be disabled by
386       setting "fallback" to FALSE (see "fallback").
387
388       In the following tables, numbers indicate priority.  For example, the
389       table below states that, if no implementation for '!' has been defined
390       then Perl will implement it using 'bool' (that is, by inverting the
391       value returned by the method for 'bool'); if boolean conversion is also
392       unimplemented then Perl will use '0+' or, failing that, '""'.
393
394           operator | can be autogenerated from
395                    |
396                    | 0+   ""   bool   .   x
397           =========|==========================
398              0+    |       1     2
399              ""    |  1          2
400              bool  |  1    2
401              int   |  1    2     3
402              !     |  2    3     1
403              qr    |  2    1     3
404              .     |  2    1     3
405              x     |  2    1     3
406              .=    |  3    2     4    1
407              x=    |  3    2     4        1
408              <>    |  2    1     3
409              -X    |  2    1     3
410
411       Note: The iterator ('<>') and file test ('-X') operators work as
412       normal: if the operand is not a blessed glob or IO reference then it is
413       converted to a string (using the method for '""', '0+', or 'bool') to
414       be interpreted as a glob or filename.
415
416           operator | can be autogenerated from
417                    |
418                    |  <   <=>   neg   -=    -
419           =========|==========================
420              neg   |                        1
421              -=    |                        1
422              --    |                   1    2
423              abs   | a1    a2    b1        b2    [*]
424              <     |        1
425              <=    |        1
426              >     |        1
427              >=    |        1
428              ==    |        1
429              !=    |        1
430
431           * one from [a1, a2] and one from [b1, b2]
432
433       Just as numeric comparisons can be autogenerated from the method for
434       '<=>', string comparisons can be autogenerated from that for 'cmp':
435
436            operators          |  can be autogenerated from
437           ====================|===========================
438            lt gt le ge eq ne  |  cmp
439
440       Similarly, autogeneration for keys '+=' and '++' is analogous to '-='
441       and '--' above:
442
443           operator | can be autogenerated from
444                    |
445                    |  +=    +
446           =========|==========================
447               +=   |        1
448               ++   |   1    2
449
450       And other assignment variations are analogous to '+=' and '-=' (and
451       similar to '.=' and 'x=' above):
452
453                     operator ||  *= /= %= **= <<= >>= &= ^= |= &.= ^.= |.=
454           -------------------||-------------------------------------------
455           autogenerated from ||  *  /  %  **  <<  >>  &  ^  |  &.  ^.  |.
456
457       Note also that the copy constructor (key '=') may be autogenerated, but
458       only for objects based on scalars.  See "Copy Constructor".
459
460       Minimal Set of Overloaded Operations
461
462       Since some operations can be automatically generated from others, there
463       is a minimal set of operations that need to be overloaded in order to
464       have the complete set of overloaded operations at one's disposal.  Of
465       course, the autogenerated operations may not do exactly what the user
466       expects.  The minimal set is:
467
468           + - * / % ** << >> x
469           <=> cmp
470           & | ^ ~ &. |. ^. ~.
471           atan2 cos sin exp log sqrt int
472           "" 0+ bool
473           ~~
474
475       Of the conversions, only one of string, boolean or numeric is needed
476       because each can be generated from either of the other two.
477
478   Special Keys for "use overload"
479       "nomethod"
480
481       The 'nomethod' key is used to specify a catch-all function to be called
482       for any operator that is not individually overloaded.  The specified
483       function will be passed four parameters.  The first three arguments
484       coincide with those that would have been passed to the corresponding
485       method if it had been defined.  The fourth argument is the "use
486       overload" key for that missing method.  If the "bitwise" feature is
487       enabled (see feature), a fifth TRUE argument is passed to subroutines
488       handling "&", "|", "^" and "~" to indicate that the caller is expecting
489       numeric behaviour.
490
491       For example, if $a is an object blessed into a package declaring
492
493           use overload 'nomethod' => 'catch_all', # ...
494
495       then the operation
496
497           3 + $a
498
499       could (unless a method is specifically declared for the key '+') result
500       in a call
501
502           catch_all($a, 3, 1, '+')
503
504       See "How Perl Chooses an Operator Implementation".
505
506       "fallback"
507
508       The value assigned to the key 'fallback' tells Perl how hard it should
509       try to find an alternative way to implement a missing operator.
510
511       ·   defined, but FALSE
512
513               use overload "fallback" => 0, # ... ;
514
515           This disables "Magic Autogeneration".
516
517       ·   "undef"
518
519           In the default case where no value is explicitly assigned to
520           "fallback", magic autogeneration is enabled.
521
522       ·   TRUE
523
524           The same as for "undef", but if a missing operator cannot be
525           autogenerated then, instead of issuing an error message, Perl is
526           allowed to revert to what it would have done for that operator if
527           there had been no "use overload" directive.
528
529           Note: in most cases, particularly the "Copy Constructor", this is
530           unlikely to be appropriate behaviour.
531
532       See "How Perl Chooses an Operator Implementation".
533
534       Copy Constructor
535
536       As mentioned above, this operation is called when a mutator is applied
537       to a reference that shares its object with some other reference.  For
538       example, if $b is mathemagical, and '++' is overloaded with 'incr', and
539       '=' is overloaded with 'clone', then the code
540
541           $a = $b;
542           # ... (other code which does not modify $a or $b) ...
543           ++$b;
544
545       would be executed in a manner equivalent to
546
547           $a = $b;
548           # ...
549           $b = $b->clone(undef, "");
550           $b->incr(undef, "");
551
552       Note:
553
554       ·   The subroutine for '=' does not overload the Perl assignment
555           operator: it is used only to allow mutators to work as described
556           here.  (See "Assignments" above.)
557
558       ·   As for other operations, the subroutine implementing '=' is passed
559           three arguments, though the last two are always "undef" and ''.
560
561       ·   The copy constructor is called only before a call to a function
562           declared to implement a mutator, for example, if "++$b;" in the
563           code above is effected via a method declared for key '++' (or
564           'nomethod', passed '++' as the fourth argument) or, by
565           autogeneration, '+='.  It is not called if the increment operation
566           is effected by a call to the method for '+' since, in the
567           equivalent code,
568
569               $a = $b;
570               $b = $b + 1;
571
572           the data referred to by $a is unchanged by the assignment to $b of
573           a reference to new object data.
574
575       ·   The copy constructor is not called if Perl determines that it is
576           unnecessary because there is no other reference to the data being
577           modified.
578
579       ·   If 'fallback' is undefined or TRUE then a copy constructor can be
580           autogenerated, but only for objects based on scalars.  In other
581           cases it needs to be defined explicitly.  Where an object's data is
582           stored as, for example, an array of scalars, the following might be
583           appropriate:
584
585               use overload '=' => sub { bless [ @{$_[0]} ] },  # ...
586
587       ·   If 'fallback' is TRUE and no copy constructor is defined then, for
588           objects not based on scalars, Perl may silently fall back on simple
589           assignment - that is, assignment of the object reference.  In
590           effect, this disables the copy constructor mechanism since no new
591           copy of the object data is created.  This is almost certainly not
592           what you want.  (It is, however, consistent: for example, Perl's
593           fallback for the "++" operator is to increment the reference
594           itself.)
595
596   How Perl Chooses an Operator Implementation
597       Which is checked first, "nomethod" or "fallback"?  If the two operands
598       of an operator are of different types and both overload the operator,
599       which implementation is used?  The following are the precedence rules:
600
601       1.  If the first operand has declared a subroutine to overload the
602           operator then use that implementation.
603
604       2.  Otherwise, if fallback is TRUE or undefined for the first operand
605           then see if the rules for autogeneration allows another of its
606           operators to be used instead.
607
608       3.  Unless the operator is an assignment ("+=", "-=", etc.), repeat
609           step (1) in respect of the second operand.
610
611       4.  Repeat Step (2) in respect of the second operand.
612
613       5.  If the first operand has a "nomethod" method then use that.
614
615       6.  If the second operand has a "nomethod" method then use that.
616
617       7.  If "fallback" is TRUE for both operands then perform the usual
618           operation for the operator, treating the operands as numbers,
619           strings, or booleans as appropriate for the operator (see note).
620
621       8.  Nothing worked - die.
622
623       Where there is only one operand (or only one operand with overloading)
624       the checks in respect of the other operand above are skipped.
625
626       There are exceptions to the above rules for dereference operations
627       (which, if Step 1 fails, always fall back to the normal, built-in
628       implementations - see Dereferencing), and for "~~" (which has its own
629       set of rules - see "Matching" under "Overloadable Operations" above).
630
631       Note on Step 7: some operators have a different semantic depending on
632       the type of their operands.  As there is no way to instruct Perl to
633       treat the operands as, e.g., numbers instead of strings, the result
634       here may not be what you expect.  See "BUGS AND PITFALLS".
635
636   Losing Overloading
637       The restriction for the comparison operation is that even if, for
638       example, "cmp" should return a blessed reference, the autogenerated
639       "lt" function will produce only a standard logical value based on the
640       numerical value of the result of "cmp".  In particular, a working
641       numeric conversion is needed in this case (possibly expressed in terms
642       of other conversions).
643
644       Similarly, ".="  and "x=" operators lose their mathemagical properties
645       if the string conversion substitution is applied.
646
647       When you chop() a mathemagical object it is promoted to a string and
648       its mathemagical properties are lost.  The same can happen with other
649       operations as well.
650
651   Inheritance and Overloading
652       Overloading respects inheritance via the @ISA hierarchy.  Inheritance
653       interacts with overloading in two ways.
654
655       Method names in the "use overload" directive
656           If "value" in
657
658             use overload key => value;
659
660           is a string, it is interpreted as a method name - which may (in the
661           usual way) be inherited from another class.
662
663       Overloading of an operation is inherited by derived classes
664           Any class derived from an overloaded class is also overloaded and
665           inherits its operator implementations.  If the same operator is
666           overloaded in more than one ancestor then the implementation is
667           determined by the usual inheritance rules.
668
669           For example, if "A" inherits from "B" and "C" (in that order), "B"
670           overloads "+" with "\&D::plus_sub", and "C" overloads "+" by
671           "plus_meth", then the subroutine "D::plus_sub" will be called to
672           implement operation "+" for an object in package "A".
673
674       Note that in Perl version prior to 5.18 inheritance of the "fallback"
675       key was not governed by the above rules.  The value of "fallback" in
676       the first overloaded ancestor was used.  This was fixed in 5.18 to
677       follow the usual rules of inheritance.
678
679   Run-time Overloading
680       Since all "use" directives are executed at compile-time, the only way
681       to change overloading during run-time is to
682
683           eval 'use overload "+" => \&addmethod';
684
685       You can also use
686
687           eval 'no overload "+", "--", "<="';
688
689       though the use of these constructs during run-time is questionable.
690
691   Public Functions
692       Package "overload.pm" provides the following public functions:
693
694       overload::StrVal(arg)
695            Gives the string value of "arg" as in the absence of stringify
696            overloading.  If you are using this to get the address of a
697            reference (useful for checking if two references point to the same
698            thing) then you may be better off using "Scalar::Util::refaddr()",
699            which is faster.
700
701       overload::Overloaded(arg)
702            Returns true if "arg" is subject to overloading of some
703            operations.
704
705       overload::Method(obj,op)
706            Returns "undef" or a reference to the method that implements "op".
707
708   Overloading Constants
709       For some applications, the Perl parser mangles constants too much.  It
710       is possible to hook into this process via "overload::constant()" and
711       "overload::remove_constant()" functions.
712
713       These functions take a hash as an argument.  The recognized keys of
714       this hash are:
715
716       integer to overload integer constants,
717
718       float   to overload floating point constants,
719
720       binary  to overload octal and hexadecimal constants,
721
722       q       to overload "q"-quoted strings, constant pieces of "qq"- and
723               "qx"-quoted strings and here-documents,
724
725       qr      to overload constant pieces of regular expressions.
726
727       The corresponding values are references to functions which take three
728       arguments: the first one is the initial string form of the constant,
729       the second one is how Perl interprets this constant, the third one is
730       how the constant is used.  Note that the initial string form does not
731       contain string delimiters, and has backslashes in backslash-delimiter
732       combinations stripped (thus the value of delimiter is not relevant for
733       processing of this string).  The return value of this function is how
734       this constant is going to be interpreted by Perl.  The third argument
735       is undefined unless for overloaded "q"- and "qr"- constants, it is "q"
736       in single-quote context (comes from strings, regular expressions, and
737       single-quote HERE documents), it is "tr" for arguments of "tr"/"y"
738       operators, it is "s" for right-hand side of "s"-operator, and it is
739       "qq" otherwise.
740
741       Since an expression "ab$cd,," is just a shortcut for 'ab' . $cd . ',,',
742       it is expected that overloaded constant strings are equipped with
743       reasonable overloaded catenation operator, otherwise absurd results
744       will result.  Similarly, negative numbers are considered as negations
745       of positive constants.
746
747       Note that it is probably meaningless to call the functions
748       overload::constant() and overload::remove_constant() from anywhere but
749       import() and unimport() methods.  From these methods they may be called
750       as
751
752           sub import {
753              shift;
754              return unless @_;
755              die "unknown import: @_" unless @_ == 1 and $_[0] eq ':constant';
756              overload::constant integer => sub {Math::BigInt->new(shift)};
757           }
758

IMPLEMENTATION

760       What follows is subject to change RSN.
761
762       The table of methods for all operations is cached in magic for the
763       symbol table hash for the package.  The cache is invalidated during
764       processing of "use overload", "no overload", new function definitions,
765       and changes in @ISA.
766
767       (Every SVish thing has a magic queue, and magic is an entry in that
768       queue.  This is how a single variable may participate in multiple forms
769       of magic simultaneously.  For instance, environment variables regularly
770       have two forms at once: their %ENV magic and their taint magic.
771       However, the magic which implements overloading is applied to the
772       stashes, which are rarely used directly, thus should not slow down
773       Perl.)
774
775       If a package uses overload, it carries a special flag.  This flag is
776       also set when new functions are defined or @ISA is modified.  There
777       will be a slight speed penalty on the very first operation thereafter
778       that supports overloading, while the overload tables are updated.  If
779       there is no overloading present, the flag is turned off.  Thus the only
780       speed penalty thereafter is the checking of this flag.
781
782       It is expected that arguments to methods that are not explicitly
783       supposed to be changed are constant (but this is not enforced).
784

COOKBOOK

786       Please add examples to what follows!
787
788   Two-face Scalars
789       Put this in two_face.pm in your Perl library directory:
790
791         package two_face;             # Scalars with separate string and
792                                       # numeric values.
793         sub new { my $p = shift; bless [@_], $p }
794         use overload '""' => \&str, '0+' => \&num, fallback => 1;
795         sub num {shift->[1]}
796         sub str {shift->[0]}
797
798       Use it as follows:
799
800         require two_face;
801         my $seven = two_face->new("vii", 7);
802         printf "seven=$seven, seven=%d, eight=%d\n", $seven, $seven+1;
803         print "seven contains 'i'\n" if $seven =~ /i/;
804
805       (The second line creates a scalar which has both a string value, and a
806       numeric value.)  This prints:
807
808         seven=vii, seven=7, eight=8
809         seven contains 'i'
810
811   Two-face References
812       Suppose you want to create an object which is accessible as both an
813       array reference and a hash reference.
814
815         package two_refs;
816         use overload '%{}' => \&gethash, '@{}' => sub { $ {shift()} };
817         sub new {
818           my $p = shift;
819           bless \ [@_], $p;
820         }
821         sub gethash {
822           my %h;
823           my $self = shift;
824           tie %h, ref $self, $self;
825           \%h;
826         }
827
828         sub TIEHASH { my $p = shift; bless \ shift, $p }
829         my %fields;
830         my $i = 0;
831         $fields{$_} = $i++ foreach qw{zero one two three};
832         sub STORE {
833           my $self = ${shift()};
834           my $key = $fields{shift()};
835           defined $key or die "Out of band access";
836           $$self->[$key] = shift;
837         }
838         sub FETCH {
839           my $self = ${shift()};
840           my $key = $fields{shift()};
841           defined $key or die "Out of band access";
842           $$self->[$key];
843         }
844
845       Now one can access an object using both the array and hash syntax:
846
847         my $bar = two_refs->new(3,4,5,6);
848         $bar->[2] = 11;
849         $bar->{two} == 11 or die 'bad hash fetch';
850
851       Note several important features of this example.  First of all, the
852       actual type of $bar is a scalar reference, and we do not overload the
853       scalar dereference.  Thus we can get the actual non-overloaded contents
854       of $bar by just using $$bar (what we do in functions which overload
855       dereference).  Similarly, the object returned by the TIEHASH() method
856       is a scalar reference.
857
858       Second, we create a new tied hash each time the hash syntax is used.
859       This allows us not to worry about a possibility of a reference loop,
860       which would lead to a memory leak.
861
862       Both these problems can be cured.  Say, if we want to overload hash
863       dereference on a reference to an object which is implemented as a hash
864       itself, the only problem one has to circumvent is how to access this
865       actual hash (as opposed to the virtual hash exhibited by the overloaded
866       dereference operator).  Here is one possible fetching routine:
867
868         sub access_hash {
869           my ($self, $key) = (shift, shift);
870           my $class = ref $self;
871           bless $self, 'overload::dummy'; # Disable overloading of %{}
872           my $out = $self->{$key};
873           bless $self, $class;        # Restore overloading
874           $out;
875         }
876
877       To remove creation of the tied hash on each access, one may an extra
878       level of indirection which allows a non-circular structure of
879       references:
880
881         package two_refs1;
882         use overload '%{}' => sub { ${shift()}->[1] },
883                      '@{}' => sub { ${shift()}->[0] };
884         sub new {
885           my $p = shift;
886           my $a = [@_];
887           my %h;
888           tie %h, $p, $a;
889           bless \ [$a, \%h], $p;
890         }
891         sub gethash {
892           my %h;
893           my $self = shift;
894           tie %h, ref $self, $self;
895           \%h;
896         }
897
898         sub TIEHASH { my $p = shift; bless \ shift, $p }
899         my %fields;
900         my $i = 0;
901         $fields{$_} = $i++ foreach qw{zero one two three};
902         sub STORE {
903           my $a = ${shift()};
904           my $key = $fields{shift()};
905           defined $key or die "Out of band access";
906           $a->[$key] = shift;
907         }
908         sub FETCH {
909           my $a = ${shift()};
910           my $key = $fields{shift()};
911           defined $key or die "Out of band access";
912           $a->[$key];
913         }
914
915       Now if $baz is overloaded like this, then $baz is a reference to a
916       reference to the intermediate array, which keeps a reference to an
917       actual array, and the access hash.  The tie()ing object for the access
918       hash is a reference to a reference to the actual array, so
919
920       ·   There are no loops of references.
921
922       ·   Both "objects" which are blessed into the class "two_refs1" are
923           references to a reference to an array, thus references to a scalar.
924           Thus the accessor expression "$$foo->[$ind]" involves no overloaded
925           operations.
926
927   Symbolic Calculator
928       Put this in symbolic.pm in your Perl library directory:
929
930         package symbolic;             # Primitive symbolic calculator
931         use overload nomethod => \&wrap;
932
933         sub new { shift; bless ['n', @_] }
934         sub wrap {
935           my ($obj, $other, $inv, $meth) = @_;
936           ($obj, $other) = ($other, $obj) if $inv;
937           bless [$meth, $obj, $other];
938         }
939
940       This module is very unusual as overloaded modules go: it does not
941       provide any usual overloaded operators, instead it provides an
942       implementation for ""nomethod"".  In this example the "nomethod"
943       subroutine returns an object which encapsulates operations done over
944       the objects: "symbolic->new(3)" contains "['n', 3]", "2 +
945       symbolic->new(3)" contains "['+', 2, ['n', 3]]".
946
947       Here is an example of the script which "calculates" the side of
948       circumscribed octagon using the above package:
949
950         require symbolic;
951         my $iter = 1;                 # 2**($iter+2) = 8
952         my $side = symbolic->new(1);
953         my $cnt = $iter;
954
955         while ($cnt--) {
956           $side = (sqrt(1 + $side**2) - 1)/$side;
957         }
958         print "OK\n";
959
960       The value of $side is
961
962         ['/', ['-', ['sqrt', ['+', 1, ['**', ['n', 1], 2]],
963                              undef], 1], ['n', 1]]
964
965       Note that while we obtained this value using a nice little script,
966       there is no simple way to use this value.  In fact this value may be
967       inspected in debugger (see perldebug), but only if "bareStringify"
968       Option is set, and not via "p" command.
969
970       If one attempts to print this value, then the overloaded operator ""
971       will be called, which will call "nomethod" operator.  The result of
972       this operator will be stringified again, but this result is again of
973       type "symbolic", which will lead to an infinite loop.
974
975       Add a pretty-printer method to the module symbolic.pm:
976
977         sub pretty {
978           my ($meth, $a, $b) = @{+shift};
979           $a = 'u' unless defined $a;
980           $b = 'u' unless defined $b;
981           $a = $a->pretty if ref $a;
982           $b = $b->pretty if ref $b;
983           "[$meth $a $b]";
984         }
985
986       Now one can finish the script by
987
988         print "side = ", $side->pretty, "\n";
989
990       The method "pretty" is doing object-to-string conversion, so it is
991       natural to overload the operator "" using this method.  However, inside
992       such a method it is not necessary to pretty-print the components $a and
993       $b of an object.  In the above subroutine "[$meth $a $b]" is a
994       catenation of some strings and components $a and $b.  If these
995       components use overloading, the catenation operator will look for an
996       overloaded operator "."; if not present, it will look for an overloaded
997       operator "".  Thus it is enough to use
998
999         use overload nomethod => \&wrap, '""' => \&str;
1000         sub str {
1001           my ($meth, $a, $b) = @{+shift};
1002           $a = 'u' unless defined $a;
1003           $b = 'u' unless defined $b;
1004           "[$meth $a $b]";
1005         }
1006
1007       Now one can change the last line of the script to
1008
1009         print "side = $side\n";
1010
1011       which outputs
1012
1013         side = [/ [- [sqrt [+ 1 [** [n 1 u] 2]] u] 1] [n 1 u]]
1014
1015       and one can inspect the value in debugger using all the possible
1016       methods.
1017
1018       Something is still amiss: consider the loop variable $cnt of the
1019       script.  It was a number, not an object.  We cannot make this value of
1020       type "symbolic", since then the loop will not terminate.
1021
1022       Indeed, to terminate the cycle, the $cnt should become false.  However,
1023       the operator "bool" for checking falsity is overloaded (this time via
1024       overloaded ""), and returns a long string, thus any object of type
1025       "symbolic" is true.  To overcome this, we need a way to compare an
1026       object to 0.  In fact, it is easier to write a numeric conversion
1027       routine.
1028
1029       Here is the text of symbolic.pm with such a routine added (and slightly
1030       modified str()):
1031
1032         package symbolic;             # Primitive symbolic calculator
1033         use overload
1034           nomethod => \&wrap, '""' => \&str, '0+' => \&num;
1035
1036         sub new { shift; bless ['n', @_] }
1037         sub wrap {
1038           my ($obj, $other, $inv, $meth) = @_;
1039           ($obj, $other) = ($other, $obj) if $inv;
1040           bless [$meth, $obj, $other];
1041         }
1042         sub str {
1043           my ($meth, $a, $b) = @{+shift};
1044           $a = 'u' unless defined $a;
1045           if (defined $b) {
1046             "[$meth $a $b]";
1047           } else {
1048             "[$meth $a]";
1049           }
1050         }
1051         my %subr = ( n => sub {$_[0]},
1052                      sqrt => sub {sqrt $_[0]},
1053                      '-' => sub {shift() - shift()},
1054                      '+' => sub {shift() + shift()},
1055                      '/' => sub {shift() / shift()},
1056                      '*' => sub {shift() * shift()},
1057                      '**' => sub {shift() ** shift()},
1058                    );
1059         sub num {
1060           my ($meth, $a, $b) = @{+shift};
1061           my $subr = $subr{$meth}
1062             or die "Do not know how to ($meth) in symbolic";
1063           $a = $a->num if ref $a eq __PACKAGE__;
1064           $b = $b->num if ref $b eq __PACKAGE__;
1065           $subr->($a,$b);
1066         }
1067
1068       All the work of numeric conversion is done in %subr and num().  Of
1069       course, %subr is not complete, it contains only operators used in the
1070       example below.  Here is the extra-credit question: why do we need an
1071       explicit recursion in num()?  (Answer is at the end of this section.)
1072
1073       Use this module like this:
1074
1075         require symbolic;
1076         my $iter = symbolic->new(2);  # 16-gon
1077         my $side = symbolic->new(1);
1078         my $cnt = $iter;
1079
1080         while ($cnt) {
1081           $cnt = $cnt - 1;            # Mutator '--' not implemented
1082           $side = (sqrt(1 + $side**2) - 1)/$side;
1083         }
1084         printf "%s=%f\n", $side, $side;
1085         printf "pi=%f\n", $side*(2**($iter+2));
1086
1087       It prints (without so many line breaks)
1088
1089         [/ [- [sqrt [+ 1 [** [/ [- [sqrt [+ 1 [** [n 1] 2]]] 1]
1090                                 [n 1]] 2]]] 1]
1091            [/ [- [sqrt [+ 1 [** [n 1] 2]]] 1] [n 1]]]=0.198912
1092         pi=3.182598
1093
1094       The above module is very primitive.  It does not implement mutator
1095       methods ("++", "-=" and so on), does not do deep copying (not required
1096       without mutators!), and implements only those arithmetic operations
1097       which are used in the example.
1098
1099       To implement most arithmetic operations is easy; one should just use
1100       the tables of operations, and change the code which fills %subr to
1101
1102         my %subr = ( 'n' => sub {$_[0]} );
1103         foreach my $op (split " ", $overload::ops{with_assign}) {
1104           $subr{$op} = $subr{"$op="} = eval "sub {shift() $op shift()}";
1105         }
1106         my @bins = qw(binary 3way_comparison num_comparison str_comparison);
1107         foreach my $op (split " ", "@overload::ops{ @bins }") {
1108           $subr{$op} = eval "sub {shift() $op shift()}";
1109         }
1110         foreach my $op (split " ", "@overload::ops{qw(unary func)}") {
1111           print "defining '$op'\n";
1112           $subr{$op} = eval "sub {$op shift()}";
1113         }
1114
1115       Since subroutines implementing assignment operators are not required to
1116       modify their operands (see "Overloadable Operations" above), we do not
1117       need anything special to make "+=" and friends work, besides adding
1118       these operators to %subr and defining a copy constructor (needed since
1119       Perl has no way to know that the implementation of '+=' does not mutate
1120       the argument - see "Copy Constructor").
1121
1122       To implement a copy constructor, add "'=' => \&cpy" to "use overload"
1123       line, and code (this code assumes that mutators change things one level
1124       deep only, so recursive copying is not needed):
1125
1126         sub cpy {
1127           my $self = shift;
1128           bless [@$self], ref $self;
1129         }
1130
1131       To make "++" and "--" work, we need to implement actual mutators,
1132       either directly, or in "nomethod".  We continue to do things inside
1133       "nomethod", thus add
1134
1135           if ($meth eq '++' or $meth eq '--') {
1136             @$obj = ($meth, (bless [@$obj]), 1); # Avoid circular reference
1137             return $obj;
1138           }
1139
1140       after the first line of wrap().  This is not a most effective
1141       implementation, one may consider
1142
1143         sub inc { $_[0] = bless ['++', shift, 1]; }
1144
1145       instead.
1146
1147       As a final remark, note that one can fill %subr by
1148
1149         my %subr = ( 'n' => sub {$_[0]} );
1150         foreach my $op (split " ", $overload::ops{with_assign}) {
1151           $subr{$op} = $subr{"$op="} = eval "sub {shift() $op shift()}";
1152         }
1153         my @bins = qw(binary 3way_comparison num_comparison str_comparison);
1154         foreach my $op (split " ", "@overload::ops{ @bins }") {
1155           $subr{$op} = eval "sub {shift() $op shift()}";
1156         }
1157         foreach my $op (split " ", "@overload::ops{qw(unary func)}") {
1158           $subr{$op} = eval "sub {$op shift()}";
1159         }
1160         $subr{'++'} = $subr{'+'};
1161         $subr{'--'} = $subr{'-'};
1162
1163       This finishes implementation of a primitive symbolic calculator in 50
1164       lines of Perl code.  Since the numeric values of subexpressions are not
1165       cached, the calculator is very slow.
1166
1167       Here is the answer for the exercise: In the case of str(), we need no
1168       explicit recursion since the overloaded "."-operator will fall back to
1169       an existing overloaded operator "".  Overloaded arithmetic operators do
1170       not fall back to numeric conversion if "fallback" is not explicitly
1171       requested.  Thus without an explicit recursion num() would convert
1172       "['+', $a, $b]" to "$a + $b", which would just rebuild the argument of
1173       num().
1174
1175       If you wonder why defaults for conversion are different for str() and
1176       num(), note how easy it was to write the symbolic calculator.  This
1177       simplicity is due to an appropriate choice of defaults.  One extra
1178       note: due to the explicit recursion num() is more fragile than sym():
1179       we need to explicitly check for the type of $a and $b.  If components
1180       $a and $b happen to be of some related type, this may lead to problems.
1181
1182   Really Symbolic Calculator
1183       One may wonder why we call the above calculator symbolic.  The reason
1184       is that the actual calculation of the value of expression is postponed
1185       until the value is used.
1186
1187       To see it in action, add a method
1188
1189         sub STORE {
1190           my $obj = shift;
1191           $#$obj = 1;
1192           @$obj->[0,1] = ('=', shift);
1193         }
1194
1195       to the package "symbolic".  After this change one can do
1196
1197         my $a = symbolic->new(3);
1198         my $b = symbolic->new(4);
1199         my $c = sqrt($a**2 + $b**2);
1200
1201       and the numeric value of $c becomes 5.  However, after calling
1202
1203         $a->STORE(12);  $b->STORE(5);
1204
1205       the numeric value of $c becomes 13.  There is no doubt now that the
1206       module symbolic provides a symbolic calculator indeed.
1207
1208       To hide the rough edges under the hood, provide a tie()d interface to
1209       the package "symbolic".  Add methods
1210
1211         sub TIESCALAR { my $pack = shift; $pack->new(@_) }
1212         sub FETCH { shift }
1213         sub nop {  }          # Around a bug
1214
1215       (the bug, fixed in Perl 5.14, is described in "BUGS").  One can use
1216       this new interface as
1217
1218         tie $a, 'symbolic', 3;
1219         tie $b, 'symbolic', 4;
1220         $a->nop;  $b->nop;    # Around a bug
1221
1222         my $c = sqrt($a**2 + $b**2);
1223
1224       Now numeric value of $c is 5.  After "$a = 12; $b = 5" the numeric
1225       value of $c becomes 13.  To insulate the user of the module add a
1226       method
1227
1228         sub vars { my $p = shift; tie($_, $p), $_->nop foreach @_; }
1229
1230       Now
1231
1232         my ($a, $b);
1233         symbolic->vars($a, $b);
1234         my $c = sqrt($a**2 + $b**2);
1235
1236         $a = 3; $b = 4;
1237         printf "c5  %s=%f\n", $c, $c;
1238
1239         $a = 12; $b = 5;
1240         printf "c13  %s=%f\n", $c, $c;
1241
1242       shows that the numeric value of $c follows changes to the values of $a
1243       and $b.
1244

AUTHOR

1246       Ilya Zakharevich <ilya@math.mps.ohio-state.edu>.
1247

SEE ALSO

1249       The "overloading" pragma can be used to enable or disable overloaded
1250       operations within a lexical scope - see overloading.
1251

DIAGNOSTICS

1253       When Perl is run with the -Do switch or its equivalent, overloading
1254       induces diagnostic messages.
1255
1256       Using the "m" command of Perl debugger (see perldebug) one can deduce
1257       which operations are overloaded (and which ancestor triggers this
1258       overloading).  Say, if "eq" is overloaded, then the method "(eq" is
1259       shown by debugger.  The method "()" corresponds to the "fallback" key
1260       (in fact a presence of this method shows that this package has
1261       overloading enabled, and it is what is used by the "Overloaded"
1262       function of module "overload").
1263
1264       The module might issue the following warnings:
1265
1266       Odd number of arguments for overload::constant
1267           (W) The call to overload::constant contained an odd number of
1268           arguments.  The arguments should come in pairs.
1269
1270       '%s' is not an overloadable type
1271           (W) You tried to overload a constant type the overload package is
1272           unaware of.
1273
1274       '%s' is not a code reference
1275           (W) The second (fourth, sixth, ...) argument of overload::constant
1276           needs to be a code reference.  Either an anonymous subroutine, or a
1277           reference to a subroutine.
1278
1279       overload arg '%s' is invalid
1280           (W) "use overload" was passed an argument it did not recognize.
1281           Did you mistype an operator?
1282

BUGS AND PITFALLS

1284       ·   A pitfall when fallback is TRUE and Perl resorts to a built-in
1285           implementation of an operator is that some operators have more than
1286           one semantic, for example "|":
1287
1288                   use overload '0+' => sub { $_[0]->{n}; },
1289                       fallback => 1;
1290                   my $x = bless { n => 4 }, "main";
1291                   my $y = bless { n => 8 }, "main";
1292                   print $x | $y, "\n";
1293
1294           You might expect this to output "12".  In fact, it prints "<": the
1295           ASCII result of treating "|" as a bitwise string operator - that
1296           is, the result of treating the operands as the strings "4" and "8"
1297           rather than numbers.  The fact that numify ("0+") is implemented
1298           but stringify ("") isn't makes no difference since the latter is
1299           simply autogenerated from the former.
1300
1301           The only way to change this is to provide your own subroutine for
1302           '|'.
1303
1304       ·   Magic autogeneration increases the potential for inadvertently
1305           creating self-referential structures.  Currently Perl will not free
1306           self-referential structures until cycles are explicitly broken.
1307           For example,
1308
1309               use overload '+' => 'add';
1310               sub add { bless [ \$_[0], \$_[1] ] };
1311
1312           is asking for trouble, since
1313
1314               $obj += $y;
1315
1316           will effectively become
1317
1318               $obj = add($obj, $y, undef);
1319
1320           with the same result as
1321
1322               $obj = [\$obj, \$foo];
1323
1324           Even if no explicit assignment-variants of operators are present in
1325           the script, they may be generated by the optimizer.  For example,
1326
1327               "obj = $obj\n"
1328
1329           may be optimized to
1330
1331               my $tmp = 'obj = ' . $obj;  $tmp .= "\n";
1332
1333       ·   The symbol table is filled with names looking like line-noise.
1334
1335       ·   This bug was fixed in Perl 5.18, but may still trip you up if you
1336           are using older versions:
1337
1338           For the purpose of inheritance every overloaded package behaves as
1339           if "fallback" is present (possibly undefined).  This may create
1340           interesting effects if some package is not overloaded, but inherits
1341           from two overloaded packages.
1342
1343       ·   Before Perl 5.14, the relation between overloading and tie()ing was
1344           broken.  Overloading was triggered or not based on the previous
1345           class of the tie()d variable.
1346
1347           This happened because the presence of overloading was checked too
1348           early, before any tie()d access was attempted.  If the class of the
1349           value FETCH()ed from the tied variable does not change, a simple
1350           workaround for code that is to run on older Perl versions is to
1351           access the value (via "() = $foo" or some such) immediately after
1352           tie()ing, so that after this call the previous class coincides with
1353           the current one.
1354
1355       ·   Barewords are not covered by overloaded string constants.
1356
1357       ·   The range operator ".." cannot be overloaded.
1358
1359
1360
1361perl v5.30.1                      2019-11-29                     overload(3pm)
Impressum