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 "builtin::refaddr()" or
699 "Scalar::Util::refaddr()", which are 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 Such a method always takes three arguments, which will be enforced
709 if it is an XS method.
710 Overloading Constants
712 For some applications, the Perl parser mangles constants too much. It
713 is possible to hook into this process via "overload::constant()" and
714 "overload::remove_constant()" functions.
715 These functions take a hash as an argument. The recognized keys of
717 this hash are:
718 integer to overload integer constants,
720 float to overload floating point constants,
722 binary to overload octal and hexadecimal constants,
724 q to overload "q"-quoted strings, constant pieces of "qq"- and
726 "qx"-quoted strings and here-documents,
727 qr to overload constant pieces of regular expressions.
729 The corresponding values are references to functions which take three
731 arguments: the first one is the initial string form of the constant,
732 the second one is how Perl interprets this constant, the third one is
733 how the constant is used. Note that the initial string form does not
734 contain string delimiters, and has backslashes in backslash-delimiter
735 combinations stripped (thus the value of delimiter is not relevant for
736 processing of this string). The return value of this function is how
737 this constant is going to be interpreted by Perl. The third argument
738 is undefined unless for overloaded "q"- and "qr"- constants, it is "q"
739 in single-quote context (comes from strings, regular expressions, and
740 single-quote HERE documents), it is "tr" for arguments of "tr"/"y"
741 operators, it is "s" for right-hand side of "s"-operator, and it is
742 "qq" otherwise.
743 Since an expression "ab$cd,," is just a shortcut for 'ab' . $cd . ',,',
745 it is expected that overloaded constant strings are equipped with
746 reasonable overloaded catenation operator, otherwise absurd results
747 will result. Similarly, negative numbers are considered as negations
748 of positive constants.
749 Note that it is probably meaningless to call the functions
751 overload::constant() and overload::remove_constant() from anywhere but
752 import() and unimport() methods. From these methods they may be called
753 as
754 sub import {
756 shift;
757 return unless @_;
758 die "unknown import: @_" unless @_ == 1 and $_[0] eq ':constant';
759 overload::constant integer => sub {Math::BigInt->new(shift)};
760 }
761
763 What follows is subject to change RSN.
764 The table of methods for all operations is cached in magic for the
766 symbol table hash for the package. The cache is invalidated during
767 processing of "use overload", "no overload", new function definitions,
768 and changes in @ISA.
769 (Every SVish thing has a magic queue, and magic is an entry in that
771 queue. This is how a single variable may participate in multiple forms
772 of magic simultaneously. For instance, environment variables regularly
773 have two forms at once: their %ENV magic and their taint magic.
774 However, the magic which implements overloading is applied to the
775 stashes, which are rarely used directly, thus should not slow down
776 Perl.)
777 If a package uses overload, it carries a special flag. This flag is
779 also set when new functions are defined or @ISA is modified. There
780 will be a slight speed penalty on the very first operation thereafter
781 that supports overloading, while the overload tables are updated. If
782 there is no overloading present, the flag is turned off. Thus the only
783 speed penalty thereafter is the checking of this flag.
784 It is expected that arguments to methods that are not explicitly
786 supposed to be changed are constant (but this is not enforced).
787
789 Please add examples to what follows!
790 Two-face Scalars
792 Put this in two_face.pm in your Perl library directory:
793 package two_face; # Scalars with separate string and
795 # numeric values.
796 sub new { my $p = shift; bless [@_], $p }
797 use overload '""' => \&str, '0+' => \&num, fallback => 1;
798 sub num {shift->[1]}
799 sub str {shift->[0]}
800 Use it as follows:
802 require two_face;
804 my $seven = two_face->new("vii", 7);
805 printf "seven=$seven, seven=%d, eight=%d\n", $seven, $seven+1;
806 print "seven contains 'i'\n" if $seven =~ /i/;
807 (The second line creates a scalar which has both a string value, and a
809 numeric value.) This prints:
810 seven=vii, seven=7, eight=8
812 seven contains 'i'
813 Two-face References
815 Suppose you want to create an object which is accessible as both an
816 array reference and a hash reference.
817 package two_refs;
819 use overload '%{}' => \&gethash, '@{}' => sub { $ {shift()} };
820 sub new {
821 my $p = shift;
822 bless \ [@_], $p;
823 }
824 sub gethash {
825 my %h;
826 my $self = shift;
827 tie %h, ref $self, $self;
828 \%h;
829 }
830 sub TIEHASH { my $p = shift; bless \ shift, $p }
832 my %fields;
833 my $i = 0;
834 $fields{$_} = $i++ foreach qw{zero one two three};
835 sub STORE {
836 my $self = ${shift()};
837 my $key = $fields{shift()};
838 defined $key or die "Out of band access";
839 $$self->[$key] = shift;
840 }
841 sub FETCH {
842 my $self = ${shift()};
843 my $key = $fields{shift()};
844 defined $key or die "Out of band access";
845 $$self->[$key];
846 }
847 Now one can access an object using both the array and hash syntax:
849 my $bar = two_refs->new(3,4,5,6);
851 $bar->[2] = 11;
852 $bar->{two} == 11 or die 'bad hash fetch';
853 Note several important features of this example. First of all, the
855 actual type of $bar is a scalar reference, and we do not overload the
856 scalar dereference. Thus we can get the actual non-overloaded contents
857 of $bar by just using $$bar (what we do in functions which overload
858 dereference). Similarly, the object returned by the TIEHASH() method
859 is a scalar reference.
860 Second, we create a new tied hash each time the hash syntax is used.
862 This allows us not to worry about a possibility of a reference loop,
863 which would lead to a memory leak.
864 Both these problems can be cured. Say, if we want to overload hash
866 dereference on a reference to an object which is implemented as a hash
867 itself, the only problem one has to circumvent is how to access this
868 actual hash (as opposed to the virtual hash exhibited by the overloaded
869 dereference operator). Here is one possible fetching routine:
870 sub access_hash {
872 my ($self, $key) = (shift, shift);
873 my $class = ref $self;
874 bless $self, 'overload::dummy'; # Disable overloading of %{}
875 my $out = $self->{$key};
876 bless $self, $class; # Restore overloading
877 $out;
878 }
879 To remove creation of the tied hash on each access, one may an extra
881 level of indirection which allows a non-circular structure of
882 references:
883 package two_refs1;
885 use overload '%{}' => sub { ${shift()}->[1] },
886 '@{}' => sub { ${shift()}->[0] };
887 sub new {
888 my $p = shift;
889 my $a = [@_];
890 my %h;
891 tie %h, $p, $a;
892 bless \ [$a, \%h], $p;
893 }
894 sub gethash {
895 my %h;
896 my $self = shift;
897 tie %h, ref $self, $self;
898 \%h;
899 }
900 sub TIEHASH { my $p = shift; bless \ shift, $p }
902 my %fields;
903 my $i = 0;
904 $fields{$_} = $i++ foreach qw{zero one two three};
905 sub STORE {
906 my $a = ${shift()};
907 my $key = $fields{shift()};
908 defined $key or die "Out of band access";
909 $a->[$key] = shift;
910 }
911 sub FETCH {
912 my $a = ${shift()};
913 my $key = $fields{shift()};
914 defined $key or die "Out of band access";
915 $a->[$key];
916 }
917 Now if $baz is overloaded like this, then $baz is a reference to a
919 reference to the intermediate array, which keeps a reference to an
920 actual array, and the access hash. The tie()ing object for the access
921 hash is a reference to a reference to the actual array, so
922 • There are no loops of references.
924 • Both "objects" which are blessed into the class "two_refs1" are
926 references to a reference to an array, thus references to a scalar.
927 Thus the accessor expression "$$foo->[$ind]" involves no overloaded
928 operations.
929 Symbolic Calculator
931 Put this in symbolic.pm in your Perl library directory:
932 package symbolic; # Primitive symbolic calculator
934 use overload nomethod => \&wrap;
935 sub new { shift; bless ['n', @_] }
937 sub wrap {
938 my ($obj, $other, $inv, $meth) = @_;
939 ($obj, $other) = ($other, $obj) if $inv;
940 bless [$meth, $obj, $other];
941 }
942 This module is very unusual as overloaded modules go: it does not
944 provide any usual overloaded operators, instead it provides an
945 implementation for "nomethod". In this example the "nomethod"
946 subroutine returns an object which encapsulates operations done over
947 the objects: "symbolic->new(3)" contains "['n', 3]", "2 +
948 symbolic->new(3)" contains "['+', 2, ['n', 3]]".
949 Here is an example of the script which "calculates" the side of
951 circumscribed octagon using the above package:
952 require symbolic;
954 my $iter = 1; # 2**($iter+2) = 8
955 my $side = symbolic->new(1);
956 my $cnt = $iter;
957 while ($cnt--) {
959 $side = (sqrt(1 + $side**2) - 1)/$side;
960 }
961 print "OK\n";
962 The value of $side is
964 ['/', ['-', ['sqrt', ['+', 1, ['**', ['n', 1], 2]],
966 undef], 1], ['n', 1]]
967 Note that while we obtained this value using a nice little script,
969 there is no simple way to use this value. In fact this value may be
970 inspected in debugger (see perldebug), but only if "bareStringify"
971 Option is set, and not via "p" command.
972 If one attempts to print this value, then the overloaded operator ""
974 will be called, which will call "nomethod" operator. The result of
975 this operator will be stringified again, but this result is again of
976 type "symbolic", which will lead to an infinite loop.
977 Add a pretty-printer method to the module symbolic.pm:
979 sub pretty {
981 my ($meth, $a, $b) = @{+shift};
982 $a = 'u' unless defined $a;
983 $b = 'u' unless defined $b;
984 $a = $a->pretty if ref $a;
985 $b = $b->pretty if ref $b;
986 "[$meth $a $b]";
987 }
988 Now one can finish the script by
990 print "side = ", $side->pretty, "\n";
992 The method "pretty" is doing object-to-string conversion, so it is
994 natural to overload the operator "" using this method. However, inside
995 such a method it is not necessary to pretty-print the components $a and
996 $b of an object. In the above subroutine "[$meth $a $b]" is a
997 catenation of some strings and components $a and $b. If these
998 components use overloading, the catenation operator will look for an
999 overloaded operator "."; if not present, it will look for an overloaded
1000 operator "". Thus it is enough to use
1001 use overload nomethod => \&wrap, '""' => \&str;
1003 sub str {
1004 my ($meth, $a, $b) = @{+shift};
1005 $a = 'u' unless defined $a;
1006 $b = 'u' unless defined $b;
1007 "[$meth $a $b]";
1008 }
1009 Now one can change the last line of the script to
1011 print "side = $side\n";
1013 which outputs
1015 side = [/ [- [sqrt [+ 1 [** [n 1 u] 2]] u] 1] [n 1 u]]
1017 and one can inspect the value in debugger using all the possible
1019 methods.
1020 Something is still amiss: consider the loop variable $cnt of the
1022 script. It was a number, not an object. We cannot make this value of
1023 type "symbolic", since then the loop will not terminate.
1024 Indeed, to terminate the cycle, the $cnt should become false. However,
1026 the operator "bool" for checking falsity is overloaded (this time via
1027 overloaded ""), and returns a long string, thus any object of type
1028 "symbolic" is true. To overcome this, we need a way to compare an
1029 object to 0. In fact, it is easier to write a numeric conversion
1030 routine.
1031 Here is the text of symbolic.pm with such a routine added (and slightly
1033 modified str()):
1034 package symbolic; # Primitive symbolic calculator
1036 use overload
1037 nomethod => \&wrap, '""' => \&str, '0+' => \#
1038 sub new { shift; bless ['n', @_] }
1040 sub wrap {
1041 my ($obj, $other, $inv, $meth) = @_;
1042 ($obj, $other) = ($other, $obj) if $inv;
1043 bless [$meth, $obj, $other];
1044 }
1045 sub str {
1046 my ($meth, $a, $b) = @{+shift};
1047 $a = 'u' unless defined $a;
1048 if (defined $b) {
1049 "[$meth $a $b]";
1050 } else {
1051 "[$meth $a]";
1052 }
1053 }
1054 my %subr = ( n => sub {$_[0]},
1055 sqrt => sub {sqrt $_[0]},
1056 '-' => sub {shift() - shift()},
1057 '+' => sub {shift() + shift()},
1058 '/' => sub {shift() / shift()},
1059 '*' => sub {shift() * shift()},
1060 '**' => sub {shift() ** shift()},
1061 );
1062 sub num {
1063 my ($meth, $a, $b) = @{+shift};
1064 my $subr = $subr{$meth}
1065 or die "Do not know how to ($meth) in symbolic";
1066 $a = $a->num if ref $a eq __PACKAGE__;
1067 $b = $b->num if ref $b eq __PACKAGE__;
1068 $subr->($a,$b);
1069 }
1070 All the work of numeric conversion is done in %subr and num(). Of
1072 course, %subr is not complete, it contains only operators used in the
1073 example below. Here is the extra-credit question: why do we need an
1074 explicit recursion in num()? (Answer is at the end of this section.)
1075 Use this module like this:
1077 require symbolic;
1079 my $iter = symbolic->new(2); # 16-gon
1080 my $side = symbolic->new(1);
1081 my $cnt = $iter;
1082 while ($cnt) {
1084 $cnt = $cnt - 1; # Mutator '--' not implemented
1085 $side = (sqrt(1 + $side**2) - 1)/$side;
1086 }
1087 printf "%s=%f\n", $side, $side;
1088 printf "pi=%f\n", $side*(2**($iter+2));
1089 It prints (without so many line breaks)
1091 [/ [- [sqrt [+ 1 [** [/ [- [sqrt [+ 1 [** [n 1] 2]]] 1]
1093 [n 1]] 2]]] 1]
1094 [/ [- [sqrt [+ 1 [** [n 1] 2]]] 1] [n 1]]]=0.198912
1095 pi=3.182598
1096 The above module is very primitive. It does not implement mutator
1098 methods ("++", "-=" and so on), does not do deep copying (not required
1099 without mutators!), and implements only those arithmetic operations
1100 which are used in the example.
1101 To implement most arithmetic operations is easy; one should just use
1103 the tables of operations, and change the code which fills %subr to
1104 my %subr = ( 'n' => sub {$_[0]} );
1106 foreach my $op (split " ", $overload::ops{with_assign}) {
1107 $subr{$op} = $subr{"$op="} = eval "sub {shift() $op shift()}";
1108 }
1109 my @bins = qw(binary 3way_comparison num_comparison str_comparison);
1110 foreach my $op (split " ", "@overload::ops{ @bins }") {
1111 $subr{$op} = eval "sub {shift() $op shift()}";
1112 }
1113 foreach my $op (split " ", "@overload::ops{qw(unary func)}") {
1114 print "defining '$op'\n";
1115 $subr{$op} = eval "sub {$op shift()}";
1116 }
1117 Since subroutines implementing assignment operators are not required to
1119 modify their operands (see "Overloadable Operations" above), we do not
1120 need anything special to make "+=" and friends work, besides adding
1121 these operators to %subr and defining a copy constructor (needed since
1122 Perl has no way to know that the implementation of '+=' does not mutate
1123 the argument - see "Copy Constructor").
1124 To implement a copy constructor, add "'=' => \&cpy" to "use overload"
1126 line, and code (this code assumes that mutators change things one level
1127 deep only, so recursive copying is not needed):
1128 sub cpy {
1130 my $self = shift;
1131 bless [@$self], ref $self;
1132 }
1133 To make "++" and "--" work, we need to implement actual mutators,
1135 either directly, or in "nomethod". We continue to do things inside
1136 "nomethod", thus add
1137 if ($meth eq '++' or $meth eq '--') {
1139 @$obj = ($meth, (bless [@$obj]), 1); # Avoid circular reference
1140 return $obj;
1141 }
1142 after the first line of wrap(). This is not a most effective
1144 implementation, one may consider
1145 sub inc { $_[0] = bless ['++', shift, 1]; }
1147 instead.
1149 As a final remark, note that one can fill %subr by
1151 my %subr = ( 'n' => sub {$_[0]} );
1153 foreach my $op (split " ", $overload::ops{with_assign}) {
1154 $subr{$op} = $subr{"$op="} = eval "sub {shift() $op shift()}";
1155 }
1156 my @bins = qw(binary 3way_comparison num_comparison str_comparison);
1157 foreach my $op (split " ", "@overload::ops{ @bins }") {
1158 $subr{$op} = eval "sub {shift() $op shift()}";
1159 }
1160 foreach my $op (split " ", "@overload::ops{qw(unary func)}") {
1161 $subr{$op} = eval "sub {$op shift()}";
1162 }
1163 $subr{'++'} = $subr{'+'};
1164 $subr{'--'} = $subr{'-'};
1165 This finishes implementation of a primitive symbolic calculator in 50
1167 lines of Perl code. Since the numeric values of subexpressions are not
1168 cached, the calculator is very slow.
1169 Here is the answer for the exercise: In the case of str(), we need no
1171 explicit recursion since the overloaded "."-operator will fall back to
1172 an existing overloaded operator "". Overloaded arithmetic operators do
1173 not fall back to numeric conversion if "fallback" is not explicitly
1174 requested. Thus without an explicit recursion num() would convert
1175 "['+', $a, $b]" to "$a + $b", which would just rebuild the argument of
1176 num().
1177 If you wonder why defaults for conversion are different for str() and
1179 num(), note how easy it was to write the symbolic calculator. This
1180 simplicity is due to an appropriate choice of defaults. One extra
1181 note: due to the explicit recursion num() is more fragile than sym():
1182 we need to explicitly check for the type of $a and $b. If components
1183 $a and $b happen to be of some related type, this may lead to problems.
1184 Really Symbolic Calculator
1186 One may wonder why we call the above calculator symbolic. The reason
1187 is that the actual calculation of the value of expression is postponed
1188 until the value is used.
1189 To see it in action, add a method
1191 sub STORE {
1193 my $obj = shift;
1194 $#$obj = 1;
1195 @$obj->[0,1] = ('=', shift);
1196 }
1197 to the package "symbolic". After this change one can do
1199 my $a = symbolic->new(3);
1201 my $b = symbolic->new(4);
1202 my $c = sqrt($a**2 + $b**2);
1203 and the numeric value of $c becomes 5. However, after calling
1205 $a->STORE(12); $b->STORE(5);
1207 the numeric value of $c becomes 13. There is no doubt now that the
1209 module symbolic provides a symbolic calculator indeed.
1210 To hide the rough edges under the hood, provide a tie()d interface to
1212 the package "symbolic". Add methods
1213 sub TIESCALAR { my $pack = shift; $pack->new(@_) }
1215 sub FETCH { shift }
1216 sub nop { } # Around a bug
1217 (the bug, fixed in Perl 5.14, is described in "BUGS"). One can use
1219 this new interface as
1220 tie $a, 'symbolic', 3;
1222 tie $b, 'symbolic', 4;
1223 $a->nop; $b->nop; # Around a bug
1224 my $c = sqrt($a**2 + $b**2);
1226 Now numeric value of $c is 5. After "$a = 12; $b = 5" the numeric
1228 value of $c becomes 13. To insulate the user of the module add a
1229 method
1230 sub vars { my $p = shift; tie($_, $p), $_->nop foreach @_; }
1232 Now
1234 my ($a, $b);
1236 symbolic->vars($a, $b);
1237 my $c = sqrt($a**2 + $b**2);
1238 $a = 3; $b = 4;
1240 printf "c5 %s=%f\n", $c, $c;
1241 $a = 12; $b = 5;
1243 printf "c13 %s=%f\n", $c, $c;
1244 shows that the numeric value of $c follows changes to the values of $a
1246 and $b.
1247
1249 Ilya Zakharevich <ilya@math.mps.ohio-state.edu>.
1250
1252 The "overloading" pragma can be used to enable or disable overloaded
1253 operations within a lexical scope - see overloading.
1254
1256 When Perl is run with the -Do switch or its equivalent, overloading
1257 induces diagnostic messages.
1258 Using the "m" command of Perl debugger (see perldebug) one can deduce
1260 which operations are overloaded (and which ancestor triggers this
1261 overloading). Say, if "eq" is overloaded, then the method "(eq" is
1262 shown by debugger. The method "()" corresponds to the "fallback" key
1263 (in fact a presence of this method shows that this package has
1264 overloading enabled, and it is what is used by the "Overloaded"
1265 function of module "overload").
1266 The module might issue the following warnings:
1268 Odd number of arguments for overload::constant
1270 (W) The call to overload::constant contained an odd number of
1271 arguments. The arguments should come in pairs.
1272 '%s' is not an overloadable type
1274 (W) You tried to overload a constant type the overload package is
1275 unaware of.
1276 '%s' is not a code reference
1278 (W) The second (fourth, sixth, ...) argument of overload::constant
1279 needs to be a code reference. Either an anonymous subroutine, or a
1280 reference to a subroutine.
1281 overload arg '%s' is invalid
1283 (W) "use overload" was passed an argument it did not recognize.
1284 Did you mistype an operator?
1285
1287 • A pitfall when fallback is TRUE and Perl resorts to a built-in
1288 implementation of an operator is that some operators have more than
1289 one semantic, for example "|":
1290 use overload '0+' => sub { $_[0]->{n}; },
1292 fallback => 1;
1293 my $x = bless { n => 4 }, "main";
1294 my $y = bless { n => 8 }, "main";
1295 print $x | $y, "\n";
1296 You might expect this to output "12". In fact, it prints "<": the
1298 ASCII result of treating "|" as a bitwise string operator - that
1299 is, the result of treating the operands as the strings "4" and "8"
1300 rather than numbers. The fact that numify ("0+") is implemented
1301 but stringify ("") isn't makes no difference since the latter is
1302 simply autogenerated from the former.
1303 The only way to change this is to provide your own subroutine for
1305 '|'.
1306 • Magic autogeneration increases the potential for inadvertently
1308 creating self-referential structures. Currently Perl will not free
1309 self-referential structures until cycles are explicitly broken.
1310 For example,
1311 use overload '+' => 'add';
1313 sub add { bless [ \$_[0], \$_[1] ] };
1314 is asking for trouble, since
1316 $obj += $y;
1318 will effectively become
1320 $obj = add($obj, $y, undef);
1322 with the same result as
1324 $obj = [\$obj, \$foo];
1326 Even if no explicit assignment-variants of operators are present in
1328 the script, they may be generated by the optimizer. For example,
1329 "obj = $obj\n"
1331 may be optimized to
1333 my $tmp = 'obj = ' . $obj; $tmp .= "\n";
1335 • The symbol table is filled with names looking like line-noise.
1337 • This bug was fixed in Perl 5.18, but may still trip you up if you
1339 are using older versions:
1340 For the purpose of inheritance every overloaded package behaves as
1342 if "fallback" is present (possibly undefined). This may create
1343 interesting effects if some package is not overloaded, but inherits
1344 from two overloaded packages.
1345 • Before Perl 5.14, the relation between overloading and tie()ing was
1347 broken. Overloading was triggered or not based on the previous
1348 class of the tie()d variable.
1349 This happened because the presence of overloading was checked too
1351 early, before any tie()d access was attempted. If the class of the
1352 value FETCH()ed from the tied variable does not change, a simple
1353 workaround for code that is to run on older Perl versions is to
1354 access the value (via "() = $foo" or some such) immediately after
1355 tie()ing, so that after this call the previous class coincides with
1356 the current one.
1357 • Barewords are not covered by overloaded string constants.
1359 • The range operator ".." cannot be overloaded.
1361perl v5.36.0 2022-08-30 overload(3pm)