1overload(3pm) Perl Programmers Reference Guide overload(3pm)
2
6 overload - Package for overloading Perl operations
7
9 package SomeThing;
10 use overload
12 '+' => \&myadd,
13 '-' => \&mysub;
14 # etc
15 ...
16 package main;
18 $a = SomeThing->new( 57 );
19 $b = 5 + $a;
20 ...
21 if (overload::Overloaded $b) {...}
22 ...
23 $strval = overload::StrVal $b;
24
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 Fundamentals
31 Declaration
32 Arguments of the "use overload" directive are (key, value) pairs. For
34 the full set of legal keys, see "Overloadable Operations" below.
35 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 package Number;
42 use overload
43 "-" => "minus",
44 "*=" => \&muas,
45 '""' => sub { ...; };
46 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 Calling Conventions and Magic Autogeneration
56 The following sample implementation of "minus()" (which assumes that
58 "Number" objects are simply blessed references to scalars) illustrates
59 the calling conventions:
60 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 Three arguments are passed to all subroutines specified in the "use
71 overload" directive (with exceptions - see below, particularly
72 "nomethod").
73 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 The second argument is the other operand, or "undef" in the case of a
79 unary operator.
80 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 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 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 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 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 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 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 use overload '--' => "decr",
123 # ...
124 sub decr { --${$_[0]}; }
125 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 Mathemagic, Mutators, and Copy Constructors
133 The term 'mathemagic' describes the overloaded implementation of
135 mathematical operators. Mathemagical operations raise an issue.
136 Consider the code:
137 $a = $b;
139 --$a;
140 If $a and $b are scalars then after these statements
142 $a == $b - 1
144 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 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 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 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 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 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 A warning is issued if an attempt is made to register an operator not
192 found above.
193 • "not"
195 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 • "neg"
202 The key "neg" is used for unary minus to disambiguate it from
204 binary "-".
205 • "++", "--"
207 Assuming they are to behave analogously to Perl's "++" and "--",
209 overloaded implementations of these operators are required to
210 mutate their operands.
211 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 • Assignments
218 += -= *= /= %= **= <<= >>= x= .=
220 &= |= ^= &.= |.= ^.=
221 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 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 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 $a *= $b
240 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 • Non-mutators with a mutator variant
246 + - * / % ** << >> x .
248 & | ^ &. |. ^.
249 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 • "int"
258 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 • String, numeric, boolean, and regexp conversions
264 "" 0+ bool
266 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 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 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 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 qr
290 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 "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 • Iteration
300 If "<>" is overloaded then the same implementation is used for
302 both the read-filehandle syntax "<$var>" and globbing syntax
303 "<${var}>".
304 • File tests
306 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 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 This overload was introduced in Perl 5.12.
320 • Matching
322 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 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 package Foo;
332 use overload '~~' => 'match';
333 my $obj = Foo->new();
335 $obj ~~ [ 1,2,3 ];
336 the smart match does not invoke the method call like this:
338 $obj->match([1,2,3],0);
340 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 $obj->match(1,0);
347 $obj->match(2,0);
348 $obj->match(3,0);
349 Consult the match table in "Smartmatch Operator" in perlop for
351 details of when overloading is invoked.
352 • Dereferencing
354 ${} @{} %{} &{} *{}
356 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 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 • Special
375 nomethod fallback =
377 See "Special Keys for "use overload"".
379 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 Note: the behaviour described in this section can be disabled by
386 setting "fallback" to FALSE (see "fallback").
387 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 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 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 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 * one from [a1, a2] and one from [b1, b2]
432 Just as numeric comparisons can be autogenerated from the method for
434 '<=>', string comparisons can be autogenerated from that for 'cmp':
435 operators | can be autogenerated from
437 ====================|===========================
438 lt gt le ge eq ne | cmp
439 Similarly, autogeneration for keys '+=' and '++' is analogous to '-='
441 and '--' above:
442 operator | can be autogenerated from
444 |
445 | += +
446 =========|==========================
447 += | 1
448 ++ | 1 2
449 And other assignment variations are analogous to '+=' and '-=' (and
451 similar to '.=' and 'x=' above):
452 operator || *= /= %= **= <<= >>= &= ^= |= &.= ^.= |.=
454 -------------------||-------------------------------------------
455 autogenerated from || * / % ** << >> & ^ | &. ^. |.
456 Note also that the copy constructor (key '=') may be autogenerated, but
458 only for objects based on scalars. See "Copy Constructor".
459 Minimal Set of Overloaded Operations
461 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 + - * / % ** << >> x
469 <=> cmp
470 & | ^ ~ &. |. ^. ~.
471 atan2 cos sin exp log sqrt int
472 "" 0+ bool
473 ~~
474 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 Special Keys for "use overload"
479 "nomethod"
480 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 For example, if $a is an object blessed into a package declaring
492 use overload 'nomethod' => 'catch_all', # ...
494 then the operation
496 3 + $a
498 could (unless a method is specifically declared for the key '+') result
500 in a call
501 catch_all($a, 3, 1, '+')
503 See "How Perl Chooses an Operator Implementation".
505 "fallback"
507 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 • defined, but FALSE
512 use overload "fallback" => 0, # ... ;
514 This disables "Magic Autogeneration".
516 • "undef"
518 In the default case where no value is explicitly assigned to
520 "fallback", magic autogeneration is enabled.
521 • TRUE
523 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 Note: in most cases, particularly the "Copy Constructor", this is
530 unlikely to be appropriate behaviour.
531 See "How Perl Chooses an Operator Implementation".
533 Copy Constructor
535 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 $a = $b;
542 # ... (other code which does not modify $a or $b) ...
543 ++$b;
544 would be executed in a manner equivalent to
546 $a = $b;
548 # ...
549 $b = $b->clone(undef, "");
550 $b->incr(undef, "");
551 Note:
553 • 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 • As for other operations, the subroutine implementing '=' is passed
559 three arguments, though the last two are always "undef" and ''.
560 • 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 $a = $b;
570 $b = $b + 1;
571 the data referred to by $a is unchanged by the assignment to $b of
573 a reference to new object data.
574 • 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 • 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 use overload '=' => sub { bless [ @{$_[0]} ] }, # ...
586 • 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 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 1. If the first operand has declared a subroutine to overload the
602 operator then use that implementation.
603 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 3. Unless the operator is an assignment ("+=", "-=", etc.), repeat
609 step (1) in respect of the second operand.
610 4. Repeat Step (2) in respect of the second operand.
612 5. If the first operand has a "nomethod" method then use that.
614 6. If the second operand has a "nomethod" method then use that.
616 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 8. Nothing worked - die.
622 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 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 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 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 Similarly, ".=" and "x=" operators lose their mathemagical properties
645 if the string conversion substitution is applied.
646 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 Inheritance and Overloading
652 Overloading respects inheritance via the @ISA hierarchy. Inheritance
653 interacts with overloading in two ways.
654 Method names in the "use overload" directive
656 If "value" in
657 use overload key => value;
659 is a string, it is interpreted as a method name - which may (in the
661 usual way) be inherited from another class.
662 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 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 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 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 eval 'use overload "+" => \&addmethod';
684 You can also use
686 eval 'no overload "+", "--", "<="';
688 though the use of these constructs during run-time is questionable.
690 Public Functions
692 Package "overload.pm" provides the following public functions:
693 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 overload::Overloaded(arg)
702 Returns true if "arg" is subject to overloading of some
703 operations.
704 overload::Method(obj,op)
706 Returns "undef" or a reference to the method that implements "op".
707 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 These functions take a hash as an argument. The recognized keys of
714 this hash are:
715 integer to overload integer constants,
717 float to overload floating point constants,
719 binary to overload octal and hexadecimal constants,
721 q to overload "q"-quoted strings, constant pieces of "qq"- and
723 "qx"-quoted strings and here-documents,
724 qr to overload constant pieces of regular expressions.
726 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 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 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 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
760 What follows is subject to change RSN.
761 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 (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 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 It is expected that arguments to methods that are not explicitly
783 supposed to be changed are constant (but this is not enforced).
784
786 Please add examples to what follows!
787 Two-face Scalars
789 Put this in two_face.pm in your Perl library directory:
790 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 Use it as follows:
799 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 (The second line creates a scalar which has both a string value, and a
806 numeric value.) This prints:
807 seven=vii, seven=7, eight=8
809 seven contains 'i'
810 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 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 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 Now one can access an object using both the array and hash syntax:
846 my $bar = two_refs->new(3,4,5,6);
848 $bar->[2] = 11;
849 $bar->{two} == 11 or die 'bad hash fetch';
850 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 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 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 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 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 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 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 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 • There are no loops of references.
921 • 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 Symbolic Calculator
928 Put this in symbolic.pm in your Perl library directory:
929 package symbolic; # Primitive symbolic calculator
931 use overload nomethod => \&wrap;
932 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 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 Here is an example of the script which "calculates" the side of
948 circumscribed octagon using the above package:
949 require symbolic;
951 my $iter = 1; # 2**($iter+2) = 8
952 my $side = symbolic->new(1);
953 my $cnt = $iter;
954 while ($cnt--) {
956 $side = (sqrt(1 + $side**2) - 1)/$side;
957 }
958 print "OK\n";
959 The value of $side is
961 ['/', ['-', ['sqrt', ['+', 1, ['**', ['n', 1], 2]],
963 undef], 1], ['n', 1]]
964 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 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 Add a pretty-printer method to the module symbolic.pm:
976 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 Now one can finish the script by
987 print "side = ", $side->pretty, "\n";
989 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 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 Now one can change the last line of the script to
1008 print "side = $side\n";
1010 which outputs
1012 side = [/ [- [sqrt [+ 1 [** [n 1 u] 2]] u] 1] [n 1 u]]
1014 and one can inspect the value in debugger using all the possible
1016 methods.
1017 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 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 Here is the text of symbolic.pm with such a routine added (and slightly
1030 modified str()):
1031 package symbolic; # Primitive symbolic calculator
1033 use overload
1034 nomethod => \&wrap, '""' => \&str, '0+' => \#
1035 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 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 Use this module like this:
1074 require symbolic;
1076 my $iter = symbolic->new(2); # 16-gon
1077 my $side = symbolic->new(1);
1078 my $cnt = $iter;
1079 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 It prints (without so many line breaks)
1088 [/ [- [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 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 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 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 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 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 sub cpy {
1127 my $self = shift;
1128 bless [@$self], ref $self;
1129 }
1130 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 if ($meth eq '++' or $meth eq '--') {
1136 @$obj = ($meth, (bless [@$obj]), 1); # Avoid circular reference
1137 return $obj;
1138 }
1139 after the first line of wrap(). This is not a most effective
1141 implementation, one may consider
1142 sub inc { $_[0] = bless ['++', shift, 1]; }
1144 instead.
1146 As a final remark, note that one can fill %subr by
1148 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 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 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 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 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 To see it in action, add a method
1188 sub STORE {
1190 my $obj = shift;
1191 $#$obj = 1;
1192 @$obj->[0,1] = ('=', shift);
1193 }
1194 to the package "symbolic". After this change one can do
1196 my $a = symbolic->new(3);
1198 my $b = symbolic->new(4);
1199 my $c = sqrt($a**2 + $b**2);
1200 and the numeric value of $c becomes 5. However, after calling
1202 $a->STORE(12); $b->STORE(5);
1204 the numeric value of $c becomes 13. There is no doubt now that the
1206 module symbolic provides a symbolic calculator indeed.
1207 To hide the rough edges under the hood, provide a tie()d interface to
1209 the package "symbolic". Add methods
1210 sub TIESCALAR { my $pack = shift; $pack->new(@_) }
1212 sub FETCH { shift }
1213 sub nop { } # Around a bug
1214 (the bug, fixed in Perl 5.14, is described in "BUGS"). One can use
1216 this new interface as
1217 tie $a, 'symbolic', 3;
1219 tie $b, 'symbolic', 4;
1220 $a->nop; $b->nop; # Around a bug
1221 my $c = sqrt($a**2 + $b**2);
1223 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 sub vars { my $p = shift; tie($_, $p), $_->nop foreach @_; }
1229 Now
1231 my ($a, $b);
1233 symbolic->vars($a, $b);
1234 my $c = sqrt($a**2 + $b**2);
1235 $a = 3; $b = 4;
1237 printf "c5 %s=%f\n", $c, $c;
1238 $a = 12; $b = 5;
1240 printf "c13 %s=%f\n", $c, $c;
1241 shows that the numeric value of $c follows changes to the values of $a
1243 and $b.
1244
1246 Ilya Zakharevich <ilya@math.mps.ohio-state.edu>.
1247
1249 The "overloading" pragma can be used to enable or disable overloaded
1250 operations within a lexical scope - see overloading.
1251
1253 When Perl is run with the -Do switch or its equivalent, overloading
1254 induces diagnostic messages.
1255 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 The module might issue the following warnings:
1265 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 '%s' is not an overloadable type
1271 (W) You tried to overload a constant type the overload package is
1272 unaware of.
1273 '%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 overload arg '%s' is invalid
1280 (W) "use overload" was passed an argument it did not recognize.
1281 Did you mistype an operator?
1282
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 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 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 The only way to change this is to provide your own subroutine for
1302 '|'.
1303 • 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 use overload '+' => 'add';
1310 sub add { bless [ \$_[0], \$_[1] ] };
1311 is asking for trouble, since
1313 $obj += $y;
1315 will effectively become
1317 $obj = add($obj, $y, undef);
1319 with the same result as
1321 $obj = [\$obj, \$foo];
1323 Even if no explicit assignment-variants of operators are present in
1325 the script, they may be generated by the optimizer. For example,
1326 "obj = $obj\n"
1328 may be optimized to
1330 my $tmp = 'obj = ' . $obj; $tmp .= "\n";
1332 • The symbol table is filled with names looking like line-noise.
1334 • This bug was fixed in Perl 5.18, but may still trip you up if you
1336 are using older versions:
1337 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 • 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 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 • Barewords are not covered by overloaded string constants.
1356 • The range operator ".." cannot be overloaded.
1358perl v5.34.0 2021-10-18 overload(3pm)