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 the
48 class "Number" (or one of its base classes), and that the function
49 Number::muas() is to be used for the assignment form of multiplication,
50 "*=". It also defines an anonymous subroutine to implement
51 stringification: this is called whenever an object blessed into the
52 package "Number" is used in a string context (this subroutine might,
53 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 being
76 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
886 '%{}' => sub { ${shift()}->[1] },
887 '@{}' => sub { ${shift()}->[0] };
888 sub new {
890 my $p = shift;
891 my $a = [@_];
892 my %h;
893 tie %h, $p, $a;
894 bless \ [$a, \%h], $p;
895 }
896 sub gethash {
897 my %h;
898 my $self = shift;
899 tie %h, ref $self, $self;
900 \%h;
901 }
902 sub TIEHASH { my $p = shift; bless \ shift, $p }
904 my %fields;
905 my $i = 0;
906 $fields{$_} = $i++ foreach qw{zero one two three};
907 sub STORE {
908 my $a = ${shift()};
909 my $key = $fields{shift()};
910 defined $key or die "Out of band access";
911 $a->[$key] = shift;
912 }
913 sub FETCH {
914 my $a = ${shift()};
915 my $key = $fields{shift()};
916 defined $key or die "Out of band access";
917 $a->[$key];
918 }
919 Now if $baz is overloaded like this, then $baz is a reference to a
921 reference to the intermediate array, which keeps a reference to an
922 actual array, and the access hash. The tie()ing object for the access
923 hash is a reference to a reference to the actual array, so
924 • There are no loops of references.
926 • Both "objects" which are blessed into the class "two_refs1" are
928 references to a reference to an array, thus references to a scalar.
929 Thus the accessor expression "$$foo->[$ind]" involves no overloaded
930 operations.
931 Symbolic Calculator
933 Put this in symbolic.pm in your Perl library directory:
934 package symbolic; # Primitive symbolic calculator
936 use overload nomethod => \&wrap;
937 sub new { shift; bless ['n', @_] }
939 sub wrap {
940 my ($obj, $other, $inv, $meth) = @_;
941 ($obj, $other) = ($other, $obj) if $inv;
942 bless [$meth, $obj, $other];
943 }
944 This module is very unusual as overloaded modules go: it does not
946 provide any usual overloaded operators, instead it provides an
947 implementation for "nomethod". In this example the "nomethod"
948 subroutine returns an object which encapsulates operations done over
949 the objects: "symbolic->new(3)" contains "['n', 3]", "2 +
950 symbolic->new(3)" contains "['+', 2, ['n', 3]]".
951 Here is an example of the script which "calculates" the side of
953 circumscribed octagon using the above package:
954 require symbolic;
956 my $iter = 1; # 2**($iter+2) = 8
957 my $side = symbolic->new(1);
958 my $cnt = $iter;
959 while ($cnt--) {
961 $side = (sqrt(1 + $side**2) - 1)/$side;
962 }
963 print "OK\n";
964 The value of $side is
966 ['/', ['-', ['sqrt', ['+', 1, ['**', ['n', 1], 2]],
968 undef], 1], ['n', 1]]
969 Note that while we obtained this value using a nice little script,
971 there is no simple way to use this value. In fact this value may be
972 inspected in debugger (see perldebug), but only if "bareStringify"
973 Option is set, and not via "p" command.
974 If one attempts to print this value, then the overloaded operator ""
976 will be called, which will call "nomethod" operator. The result of
977 this operator will be stringified again, but this result is again of
978 type "symbolic", which will lead to an infinite loop.
979 Add a pretty-printer method to the module symbolic.pm:
981 sub pretty {
983 my ($meth, $a, $b) = @{+shift};
984 $a = 'u' unless defined $a;
985 $b = 'u' unless defined $b;
986 $a = $a->pretty if ref $a;
987 $b = $b->pretty if ref $b;
988 "[$meth $a $b]";
989 }
990 Now one can finish the script by
992 print "side = ", $side->pretty, "\n";
994 The method "pretty" is doing object-to-string conversion, so it is
996 natural to overload the operator "" using this method. However, inside
997 such a method it is not necessary to pretty-print the components $a and
998 $b of an object. In the above subroutine "[$meth $a $b]" is a
999 catenation of some strings and components $a and $b. If these
1000 components use overloading, the catenation operator will look for an
1001 overloaded operator "."; if not present, it will look for an overloaded
1002 operator "". Thus it is enough to use
1003 use overload nomethod => \&wrap, '""' => \&str;
1005 sub str {
1006 my ($meth, $a, $b) = @{+shift};
1007 $a = 'u' unless defined $a;
1008 $b = 'u' unless defined $b;
1009 "[$meth $a $b]";
1010 }
1011 Now one can change the last line of the script to
1013 print "side = $side\n";
1015 which outputs
1017 side = [/ [- [sqrt [+ 1 [** [n 1 u] 2]] u] 1] [n 1 u]]
1019 and one can inspect the value in debugger using all the possible
1021 methods.
1022 Something is still amiss: consider the loop variable $cnt of the
1024 script. It was a number, not an object. We cannot make this value of
1025 type "symbolic", since then the loop will not terminate.
1026 Indeed, to terminate the cycle, the $cnt should become false. However,
1028 the operator "bool" for checking falsity is overloaded (this time via
1029 overloaded ""), and returns a long string, thus any object of type
1030 "symbolic" is true. To overcome this, we need a way to compare an
1031 object to 0. In fact, it is easier to write a numeric conversion
1032 routine.
1033 Here is the text of symbolic.pm with such a routine added (and slightly
1035 modified str()):
1036 package symbolic; # Primitive symbolic calculator
1038 use overload
1039 nomethod => \&wrap, '""' => \&str, '0+' => \#
1040 sub new { shift; bless ['n', @_] }
1042 sub wrap {
1043 my ($obj, $other, $inv, $meth) = @_;
1044 ($obj, $other) = ($other, $obj) if $inv;
1045 bless [$meth, $obj, $other];
1046 }
1047 sub str {
1048 my ($meth, $a, $b) = @{+shift};
1049 $a = 'u' unless defined $a;
1050 if (defined $b) {
1051 "[$meth $a $b]";
1052 } else {
1053 "[$meth $a]";
1054 }
1055 }
1056 my %subr = (
1057 n => sub {$_[0]},
1058 sqrt => sub {sqrt $_[0]},
1059 '-' => sub {shift() - shift()},
1060 '+' => sub {shift() + shift()},
1061 '/' => sub {shift() / shift()},
1062 '*' => sub {shift() * shift()},
1063 '**' => sub {shift() ** shift()},
1064 );
1065 sub num {
1066 my ($meth, $a, $b) = @{+shift};
1067 my $subr = $subr{$meth}
1068 or die "Do not know how to ($meth) in symbolic";
1069 $a = $a->num if ref $a eq __PACKAGE__;
1070 $b = $b->num if ref $b eq __PACKAGE__;
1071 $subr->($a,$b);
1072 }
1073 All the work of numeric conversion is done in %subr and num(). Of
1075 course, %subr is not complete, it contains only operators used in the
1076 example below. Here is the extra-credit question: why do we need an
1077 explicit recursion in num()? (Answer is at the end of this section.)
1078 Use this module like this:
1080 require symbolic;
1082 my $iter = symbolic->new(2); # 16-gon
1083 my $side = symbolic->new(1);
1084 my $cnt = $iter;
1085 while ($cnt) {
1087 $cnt = $cnt - 1; # Mutator '--' not implemented
1088 $side = (sqrt(1 + $side**2) - 1)/$side;
1089 }
1090 printf "%s=%f\n", $side, $side;
1091 printf "pi=%f\n", $side*(2**($iter+2));
1092 It prints (without so many line breaks)
1094 [/ [- [sqrt [+ 1 [** [/ [- [sqrt [+ 1 [** [n 1] 2]]] 1]
1096 [n 1]] 2]]] 1]
1097 [/ [- [sqrt [+ 1 [** [n 1] 2]]] 1] [n 1]]]=0.198912
1098 pi=3.182598
1099 The above module is very primitive. It does not implement mutator
1101 methods ("++", "-=" and so on), does not do deep copying (not required
1102 without mutators!), and implements only those arithmetic operations
1103 which are used in the example.
1104 To implement most arithmetic operations is easy; one should just use
1106 the tables of operations, and change the code which fills %subr to
1107 my %subr = ( 'n' => sub {$_[0]} );
1109 foreach my $op (split " ", $overload::ops{with_assign}) {
1110 $subr{$op} = $subr{"$op="} = eval "sub {shift() $op shift()}";
1111 }
1112 my @bins = qw(binary 3way_comparison num_comparison str_comparison);
1113 foreach my $op (split " ", "@overload::ops{ @bins }") {
1114 $subr{$op} = eval "sub {shift() $op shift()}";
1115 }
1116 foreach my $op (split " ", "@overload::ops{qw(unary func)}") {
1117 print "defining '$op'\n";
1118 $subr{$op} = eval "sub {$op shift()}";
1119 }
1120 Since subroutines implementing assignment operators are not required to
1122 modify their operands (see "Overloadable Operations" above), we do not
1123 need anything special to make "+=" and friends work, besides adding
1124 these operators to %subr and defining a copy constructor (needed since
1125 Perl has no way to know that the implementation of '+=' does not mutate
1126 the argument - see "Copy Constructor").
1127 To implement a copy constructor, add "'=' => \&cpy" to "use overload"
1129 line, and code (this code assumes that mutators change things one level
1130 deep only, so recursive copying is not needed):
1131 sub cpy {
1133 my $self = shift;
1134 bless [@$self], ref $self;
1135 }
1136 To make "++" and "--" work, we need to implement actual mutators,
1138 either directly, or in "nomethod". We continue to do things inside
1139 "nomethod", thus add
1140 if ($meth eq '++' or $meth eq '--') {
1142 @$obj = ($meth, (bless [@$obj]), 1); # Avoid circular reference
1143 return $obj;
1144 }
1145 after the first line of wrap(). This is not a most effective
1147 implementation, one may consider
1148 sub inc { $_[0] = bless ['++', shift, 1]; }
1150 instead.
1152 As a final remark, note that one can fill %subr by
1154 my %subr = ( 'n' => sub {$_[0]} );
1156 foreach my $op (split " ", $overload::ops{with_assign}) {
1157 $subr{$op} = $subr{"$op="} = eval "sub {shift() $op shift()}";
1158 }
1159 my @bins = qw(binary 3way_comparison num_comparison str_comparison);
1160 foreach my $op (split " ", "@overload::ops{ @bins }") {
1161 $subr{$op} = eval "sub {shift() $op shift()}";
1162 }
1163 foreach my $op (split " ", "@overload::ops{qw(unary func)}") {
1164 $subr{$op} = eval "sub {$op shift()}";
1165 }
1166 $subr{'++'} = $subr{'+'};
1167 $subr{'--'} = $subr{'-'};
1168 This finishes implementation of a primitive symbolic calculator in 50
1170 lines of Perl code. Since the numeric values of subexpressions are not
1171 cached, the calculator is very slow.
1172 Here is the answer for the exercise: In the case of str(), we need no
1174 explicit recursion since the overloaded "."-operator will fall back to
1175 an existing overloaded operator "". Overloaded arithmetic operators do
1176 not fall back to numeric conversion if "fallback" is not explicitly
1177 requested. Thus without an explicit recursion num() would convert
1178 "['+', $a, $b]" to "$a + $b", which would just rebuild the argument of
1179 num().
1180 If you wonder why defaults for conversion are different for str() and
1182 num(), note how easy it was to write the symbolic calculator. This
1183 simplicity is due to an appropriate choice of defaults. One extra
1184 note: due to the explicit recursion num() is more fragile than sym():
1185 we need to explicitly check for the type of $a and $b. If components
1186 $a and $b happen to be of some related type, this may lead to problems.
1187 Really Symbolic Calculator
1189 One may wonder why we call the above calculator symbolic. The reason
1190 is that the actual calculation of the value of expression is postponed
1191 until the value is used.
1192 To see it in action, add a method
1194 sub STORE {
1196 my $obj = shift;
1197 $#$obj = 1;
1198 @$obj->[0,1] = ('=', shift);
1199 }
1200 to the package "symbolic". After this change one can do
1202 my $a = symbolic->new(3);
1204 my $b = symbolic->new(4);
1205 my $c = sqrt($a**2 + $b**2);
1206 and the numeric value of $c becomes 5. However, after calling
1208 $a->STORE(12); $b->STORE(5);
1210 the numeric value of $c becomes 13. There is no doubt now that the
1212 module symbolic provides a symbolic calculator indeed.
1213 To hide the rough edges under the hood, provide a tie()d interface to
1215 the package "symbolic". Add methods
1216 sub TIESCALAR { my $pack = shift; $pack->new(@_) }
1218 sub FETCH { shift }
1219 sub nop { } # Around a bug
1220 (the bug, fixed in Perl 5.14, is described in "BUGS"). One can use
1222 this new interface as
1223 tie $a, 'symbolic', 3;
1225 tie $b, 'symbolic', 4;
1226 $a->nop; $b->nop; # Around a bug
1227 my $c = sqrt($a**2 + $b**2);
1229 Now numeric value of $c is 5. After "$a = 12; $b = 5" the numeric
1231 value of $c becomes 13. To insulate the user of the module add a
1232 method
1233 sub vars { my $p = shift; tie($_, $p), $_->nop foreach @_; }
1235 Now
1237 my ($a, $b);
1239 symbolic->vars($a, $b);
1240 my $c = sqrt($a**2 + $b**2);
1241 $a = 3; $b = 4;
1243 printf "c5 %s=%f\n", $c, $c;
1244 $a = 12; $b = 5;
1246 printf "c13 %s=%f\n", $c, $c;
1247 shows that the numeric value of $c follows changes to the values of $a
1249 and $b.
1250
1252 Ilya Zakharevich <ilya@math.mps.ohio-state.edu>.
1253
1255 The "overloading" pragma can be used to enable or disable overloaded
1256 operations within a lexical scope - see overloading.
1257
1259 When Perl is run with the -Do switch or its equivalent, overloading
1260 induces diagnostic messages.
1261 Using the "m" command of Perl debugger (see perldebug) one can deduce
1263 which operations are overloaded (and which ancestor triggers this
1264 overloading). Say, if "eq" is overloaded, then the method "(eq" is
1265 shown by debugger. The method "()" corresponds to the "fallback" key
1266 (in fact a presence of this method shows that this package has
1267 overloading enabled, and it is what is used by the "Overloaded"
1268 function of module "overload").
1269 The module might issue the following warnings:
1271 Odd number of arguments for overload::constant
1273 (W) The call to overload::constant contained an odd number of
1274 arguments. The arguments should come in pairs.
1275 '%s' is not an overloadable type
1277 (W) You tried to overload a constant type the overload package is
1278 unaware of.
1279 '%s' is not a code reference
1281 (W) The second (fourth, sixth, ...) argument of overload::constant
1282 needs to be a code reference. Either an anonymous subroutine, or a
1283 reference to a subroutine.
1284 overload arg '%s' is invalid
1286 (W) "use overload" was passed an argument it did not recognize.
1287 Did you mistype an operator?
1288
1290 • A pitfall when fallback is TRUE and Perl resorts to a built-in
1291 implementation of an operator is that some operators have more than
1292 one semantic, for example "|":
1293 use overload '0+' => sub { $_[0]->{n}; },
1295 fallback => 1;
1296 my $x = bless { n => 4 }, "main";
1297 my $y = bless { n => 8 }, "main";
1298 print $x | $y, "\n";
1299 You might expect this to output "12". In fact, it prints "<": the
1301 ASCII result of treating "|" as a bitwise string operator - that
1302 is, the result of treating the operands as the strings "4" and "8"
1303 rather than numbers. The fact that numify ("0+") is implemented
1304 but stringify ("") isn't makes no difference since the latter is
1305 simply autogenerated from the former.
1306 The only way to change this is to provide your own subroutine for
1308 '|'.
1309 • Magic autogeneration increases the potential for inadvertently
1311 creating self-referential structures. Currently Perl will not free
1312 self-referential structures until cycles are explicitly broken.
1313 For example,
1314 use overload '+' => 'add';
1316 sub add { bless [ \$_[0], \$_[1] ] };
1317 is asking for trouble, since
1319 $obj += $y;
1321 will effectively become
1323 $obj = add($obj, $y, undef);
1325 with the same result as
1327 $obj = [\$obj, \$foo];
1329 Even if no explicit assignment-variants of operators are present in
1331 the script, they may be generated by the optimizer. For example,
1332 "obj = $obj\n"
1334 may be optimized to
1336 my $tmp = 'obj = ' . $obj; $tmp .= "\n";
1338 • The symbol table is filled with names looking like line-noise.
1340 • This bug was fixed in Perl 5.18, but may still trip you up if you
1342 are using older versions:
1343 For the purpose of inheritance every overloaded package behaves as
1345 if "fallback" is present (possibly undefined). This may create
1346 interesting effects if some package is not overloaded, but inherits
1347 from two overloaded packages.
1348 • Before Perl 5.14, the relation between overloading and tie()ing was
1350 broken. Overloading was triggered or not based on the previous
1351 class of the tie()d variable.
1352 This happened because the presence of overloading was checked too
1354 early, before any tie()d access was attempted. If the class of the
1355 value FETCH()ed from the tied variable does not change, a simple
1356 workaround for code that is to run on older Perl versions is to
1357 access the value (via "() = $foo" or some such) immediately after
1358 tie()ing, so that after this call the previous class coincides with
1359 the current one.
1360 • Barewords are not covered by overloaded string constants.
1362 • The range operator ".." cannot be overloaded.
1364perl v5.38.2 2023-11-30 overload(3pm)