1overload(3pm) Perl Programmers Reference Guide overload(3pm)
2
3
4
6 overload - Package for overloading Perl operations
7
9 package SomeThing;
10
11 use overload
12 '+' => \&myadd,
13 '-' => \&mysub;
14 # etc
15 ...
16
17 package main;
18 $a = SomeThing->new( 57 );
19 $b = 5 + $a;
20 ...
21 if (overload::Overloaded $b) {...}
22 ...
23 $strval = overload::StrVal $b;
24
26 This pragma allows overloading of Perl's operators for a class. To
27 overload built-in functions, see "Overriding Built-in Functions" in
28 perlsub instead.
29
30 Fundamentals
31 Declaration
32
33 Arguments of the "use overload" directive are (key, value) pairs. For
34 the full set of legal keys, see "Overloadable Operations" below.
35
36 Operator implementations (the values) can be subroutines, references to
37 subroutines, or anonymous subroutines - in other words, anything legal
38 inside a "&{ ... }" call. Values specified as strings are interpreted
39 as method names. Thus
40
41 package Number;
42 use overload
43 "-" => "minus",
44 "*=" => \&muas,
45 '""' => sub { ...; };
46
47 declares that subtraction is to be implemented by method minus() in 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
55 Calling Conventions and Magic Autogeneration
56
57 The following sample implementation of minus() (which assumes that
58 "Number" objects are simply blessed references to scalars) illustrates
59 the calling conventions:
60
61 package Number;
62 sub minus {
63 my ($self, $other, $swap) = @_;
64 my $result = $$self - $other; # *
65 $result = -$result if $swap;
66 ref $result ? $result : bless \$result;
67 }
68 # * may recurse once - see table below
69
70 Three arguments are passed to all subroutines specified in the "use
71 overload" directive (with exceptions - see below, particularly
72 "nomethod").
73
74 The first of these is the operand providing the overloaded operator
75 implementation - in this case, the object whose minus() method is being
76 called.
77
78 The second argument is the other operand, or "undef" in the case of a
79 unary operator.
80
81 The third argument is set to TRUE if (and only if) the two operands
82 have been swapped. Perl may do this to ensure that the first argument
83 ($self) is an object implementing the overloaded operation, in line
84 with general object calling conventions. For example, if $x and $y are
85 "Number"s:
86
87 operation | generates a call to
88 ============|======================
89 $x - $y | minus($x, $y, '')
90 $x - 7 | minus($x, 7, '')
91 7 - $x | minus($x, 7, 1)
92
93 Perl may also use minus() to implement other operators which have not
94 been specified in the "use overload" directive, according to the rules
95 for "Magic Autogeneration" described later. For example, the "use
96 overload" above declared no subroutine for any of the operators "--",
97 "neg" (the overload key for unary minus), or "-=". Thus
98
99 operation | generates a call to
100 ============|======================
101 -$x | minus($x, 0, 1)
102 $x-- | minus($x, 1, undef)
103 $x -= 3 | minus($x, 3, undef)
104
105 Note the "undef"s: where autogeneration results in the method for a
106 standard operator which does not change either of its operands, such as
107 "-", being used to implement an operator which changes the operand
108 ("mutators": here, "--" and "-="), Perl passes undef as the third
109 argument. This still evaluates as FALSE, consistent with the fact that
110 the operands have not been swapped, but gives the subroutine a chance
111 to alter its behaviour in these cases.
112
113 In all the above examples, minus() is required only to return the
114 result of the subtraction: Perl takes care of the assignment to $x. In
115 fact, such methods should not modify their operands, even if "undef" is
116 passed as the third argument (see "Overloadable Operations").
117
118 The same is not true of implementations of "++" and "--": these are
119 expected to modify their operand. An appropriate implementation of
120 "--" might look like
121
122 use overload '--' => "decr",
123 # ...
124 sub decr { --${$_[0]}; }
125
126 If the "bitwise" feature is enabled (see feature), a fifth TRUE
127 argument is passed to subroutines handling "&", "|", "^" and "~". This
128 indicates that the caller is expecting numeric behaviour. The fourth
129 argument will be "undef", as that position ($_[3]) is reserved for use
130 by "nomethod".
131
132 Mathemagic, Mutators, and Copy Constructors
133
134 The term 'mathemagic' describes the overloaded implementation of
135 mathematical operators. Mathemagical operations raise an issue.
136 Consider the code:
137
138 $a = $b;
139 --$a;
140
141 If $a and $b are scalars then after these statements
142
143 $a == $b - 1
144
145 An object, however, is a reference to blessed data, so if $a and $b are
146 objects then the assignment "$a = $b" copies only the reference,
147 leaving $a and $b referring to the same object data. One might
148 therefore expect the operation "--$a" to decrement $b as well as $a.
149 However, this would not be consistent with how we expect the
150 mathematical operators to work.
151
152 Perl resolves this dilemma by transparently calling a copy constructor
153 before calling a method defined to implement a mutator ("--", "+=", and
154 so on.). In the above example, when Perl reaches the decrement
155 statement, it makes a copy of the object data in $a and assigns to $a a
156 reference to the copied data. Only then does it call decr(), which
157 alters the copied data, leaving $b unchanged. Thus the object metaphor
158 is preserved as far as possible, while mathemagical operations still
159 work according to the arithmetic metaphor.
160
161 Note: the preceding paragraph describes what happens when Perl
162 autogenerates the copy constructor for an object based on a scalar.
163 For other cases, see "Copy Constructor".
164
165 Overloadable Operations
166 The complete list of keys that can be specified in the "use overload"
167 directive are given, separated by spaces, in the values of the hash
168 %overload::ops:
169
170 with_assign => '+ - * / % ** << >> x .',
171 assign => '+= -= *= /= %= **= <<= >>= x= .=',
172 num_comparison => '< <= > >= == !=',
173 '3way_comparison' => '<=> cmp',
174 str_comparison => 'lt le gt ge eq ne',
175 binary => '& &= | |= ^ ^= &. &.= |. |.= ^. ^.=',
176 unary => 'neg ! ~ ~.',
177 mutators => '++ --',
178 func => 'atan2 cos sin exp abs log sqrt int',
179 conversion => 'bool "" 0+ qr',
180 iterators => '<>',
181 filetest => '-X',
182 dereferencing => '${} @{} %{} &{} *{}',
183 matching => '~~',
184 special => 'nomethod fallback =',
185
186 Most of the overloadable operators map one-to-one to these keys.
187 Exceptions, including additional overloadable operations not apparent
188 from this hash, are included in the notes which follow. This list is
189 subject to growth over time.
190
191 A warning is issued if an attempt is made to register an operator not
192 found above.
193
194 • "not"
195
196 The operator "not" is not a valid key for "use overload".
197 However, if the operator "!" is overloaded then the same
198 implementation will be used for "not" (since the two operators
199 differ only in precedence).
200
201 • "neg"
202
203 The key "neg" is used for unary minus to disambiguate it from
204 binary "-".
205
206 • "++", "--"
207
208 Assuming they are to behave analogously to Perl's "++" and "--",
209 overloaded implementations of these operators are required to
210 mutate their operands.
211
212 No distinction is made between prefix and postfix forms of the
213 increment and decrement operators: these differ only in the point
214 at which Perl calls the associated subroutine when evaluating an
215 expression.
216
217 • Assignments
218
219 += -= *= /= %= **= <<= >>= x= .=
220 &= |= ^= &.= |.= ^.=
221
222 Simple assignment is not overloadable (the '=' key is used for the
223 "Copy Constructor"). Perl does have a way to make assignments to
224 an object do whatever you want, but this involves using tie(), not
225 overload - see "tie" in perlfunc and the "COOKBOOK" examples
226 below.
227
228 The subroutine for the assignment variant of an operator is
229 required only to return the result of the operation. It is
230 permitted to change the value of its operand (this is safe because
231 Perl calls the copy constructor first), but this is optional since
232 Perl assigns the returned value to the left-hand operand anyway.
233
234 An object that overloads an assignment operator does so only in
235 respect of assignments to that object. In other words, Perl never
236 calls the corresponding methods with the third argument (the
237 "swap" argument) set to TRUE. For example, the operation
238
239 $a *= $b
240
241 cannot lead to $b's implementation of "*=" being called, even if
242 $a is a scalar. (It can, however, generate a call to $b's method
243 for "*").
244
245 • Non-mutators with a mutator variant
246
247 + - * / % ** << >> x .
248 & | ^ &. |. ^.
249
250 As described above, Perl may call methods for operators like "+"
251 and "&" in the course of implementing missing operations like
252 "++", "+=", and "&=". While these methods may detect this usage
253 by testing the definedness of the third argument, they should in
254 all cases avoid changing their operands. This is because Perl
255 does not call the copy constructor before invoking these methods.
256
257 • "int"
258
259 Traditionally, the Perl function "int" rounds to 0 (see "int" in
260 perlfunc), and so for floating-point-like types one should follow
261 the same semantic.
262
263 • String, numeric, boolean, and regexp conversions
264
265 "" 0+ bool
266
267 These conversions are invoked according to context as necessary.
268 For example, the subroutine for '""' (stringify) may be used where
269 the overloaded object is passed as an argument to "print", and
270 that for 'bool' where it is tested in the condition of a flow
271 control statement (like "while") or the ternary "?:" operation.
272
273 Of course, in contexts like, for example, "$obj + 1", Perl will
274 invoke $obj's implementation of "+" rather than (in this example)
275 converting $obj to a number using the numify method '0+' (an
276 exception to this is when no method has been provided for '+' and
277 "fallback" is set to TRUE).
278
279 The subroutines for '""', '0+', and 'bool' can return any
280 arbitrary Perl value. If the corresponding operation for this
281 value is overloaded too, the operation will be called again with
282 this value.
283
284 As a special case if the overload returns the object itself then
285 it will be used directly. An overloaded conversion returning the
286 object is probably a bug, because you're likely to get something
287 that looks like "YourPackage=HASH(0x8172b34)".
288
289 qr
290
291 The subroutine for 'qr' is used wherever the object is
292 interpolated into or used as a regexp, including when it appears
293 on the RHS of a "=~" or "!~" operator.
294
295 "qr" must return a compiled regexp, or a ref to a compiled regexp
296 (such as "qr//" returns), and any further overloading on the
297 return value will be ignored.
298
299 • Iteration
300
301 If "<>" is overloaded then the same implementation is used for
302 both the read-filehandle syntax "<$var>" and globbing syntax
303 "<${var}>".
304
305 • File tests
306
307 The key '-X' is used to specify a subroutine to handle all the
308 filetest operators ("-f", "-x", and so on: see "-X" in perlfunc
309 for the full list); it is not possible to overload any filetest
310 operator individually. To distinguish them, the letter following
311 the '-' is passed as the second argument (that is, in the slot
312 that for binary operators is used to pass the second operand).
313
314 Calling an overloaded filetest operator does not affect the stat
315 value associated with the special filehandle "_". It still refers
316 to the result of the last "stat", "lstat" or unoverloaded
317 filetest.
318
319 This overload was introduced in Perl 5.12.
320
321 • Matching
322
323 The key "~~" allows you to override the smart matching logic used
324 by the "~~" operator and the switch construct ("given"/"when").
325 See "Switch Statements" in perlsyn and feature.
326
327 Unusually, the overloaded implementation of the smart match
328 operator does not get full control of the smart match behaviour.
329 In particular, in the following code:
330
331 package Foo;
332 use overload '~~' => 'match';
333
334 my $obj = Foo->new();
335 $obj ~~ [ 1,2,3 ];
336
337 the smart match does not invoke the method call like this:
338
339 $obj->match([1,2,3],0);
340
341 rather, the smart match distributive rule takes precedence, so
342 $obj is smart matched against each array element in turn until a
343 match is found, so you may see between one and three of these
344 calls instead:
345
346 $obj->match(1,0);
347 $obj->match(2,0);
348 $obj->match(3,0);
349
350 Consult the match table in "Smartmatch Operator" in perlop for
351 details of when overloading is invoked.
352
353 • Dereferencing
354
355 ${} @{} %{} &{} *{}
356
357 If these operators are not explicitly overloaded then they work in
358 the normal way, yielding the underlying scalar, array, or whatever
359 stores the object data (or the appropriate error message if the
360 dereference operator doesn't match it). Defining a catch-all
361 'nomethod' (see below) makes no difference to this as the catch-
362 all function will not be called to implement a missing dereference
363 operator.
364
365 If a dereference operator is overloaded then it must return a
366 reference of the appropriate type (for example, the subroutine for
367 key '${}' should return a reference to a scalar, not a scalar), or
368 another object which overloads the operator: that is, the
369 subroutine only determines what is dereferenced and the actual
370 dereferencing is left to Perl. As a special case, if the
371 subroutine returns the object itself then it will not be called
372 again - avoiding infinite recursion.
373
374 • Special
375
376 nomethod fallback =
377
378 See "Special Keys for "use overload"".
379
380 Magic Autogeneration
381 If a method for an operation is not found then Perl tries to
382 autogenerate a substitute implementation from the operations that have
383 been defined.
384
385 Note: the behaviour described in this section can be disabled by
386 setting "fallback" to FALSE (see "fallback").
387
388 In the following tables, numbers indicate priority. For example, the
389 table below states that, if no implementation for '!' has been defined
390 then Perl will implement it using 'bool' (that is, by inverting the
391 value returned by the method for 'bool'); if boolean conversion is also
392 unimplemented then Perl will use '0+' or, failing that, '""'.
393
394 operator | can be autogenerated from
395 |
396 | 0+ "" bool . x
397 =========|==========================
398 0+ | 1 2
399 "" | 1 2
400 bool | 1 2
401 int | 1 2 3
402 ! | 2 3 1
403 qr | 2 1 3
404 . | 2 1 3
405 x | 2 1 3
406 .= | 3 2 4 1
407 x= | 3 2 4 1
408 <> | 2 1 3
409 -X | 2 1 3
410
411 Note: The iterator ('<>') and file test ('-X') operators work as
412 normal: if the operand is not a blessed glob or IO reference then it is
413 converted to a string (using the method for '""', '0+', or 'bool') to
414 be interpreted as a glob or filename.
415
416 operator | can be autogenerated from
417 |
418 | < <=> neg -= -
419 =========|==========================
420 neg | 1
421 -= | 1
422 -- | 1 2
423 abs | a1 a2 b1 b2 [*]
424 < | 1
425 <= | 1
426 > | 1
427 >= | 1
428 == | 1
429 != | 1
430
431 * one from [a1, a2] and one from [b1, b2]
432
433 Just as numeric comparisons can be autogenerated from the method for
434 '<=>', string comparisons can be autogenerated from that for 'cmp':
435
436 operators | can be autogenerated from
437 ====================|===========================
438 lt gt le ge eq ne | cmp
439
440 Similarly, autogeneration for keys '+=' and '++' is analogous to '-='
441 and '--' above:
442
443 operator | can be autogenerated from
444 |
445 | += +
446 =========|==========================
447 += | 1
448 ++ | 1 2
449
450 And other assignment variations are analogous to '+=' and '-=' (and
451 similar to '.=' and 'x=' above):
452
453 operator || *= /= %= **= <<= >>= &= ^= |= &.= ^.= |.=
454 -------------------||-------------------------------------------
455 autogenerated from || * / % ** << >> & ^ | &. ^. |.
456
457 Note also that the copy constructor (key '=') may be autogenerated, but
458 only for objects based on scalars. See "Copy Constructor".
459
460 Minimal Set of Overloaded Operations
461
462 Since some operations can be automatically generated from others, there
463 is a minimal set of operations that need to be overloaded in order to
464 have the complete set of overloaded operations at one's disposal. Of
465 course, the autogenerated operations may not do exactly what the user
466 expects. The minimal set is:
467
468 + - * / % ** << >> x
469 <=> cmp
470 & | ^ ~ &. |. ^. ~.
471 atan2 cos sin exp log sqrt int
472 "" 0+ bool
473 ~~
474
475 Of the conversions, only one of string, boolean or numeric is needed
476 because each can be generated from either of the other two.
477
478 Special Keys for "use overload"
479 "nomethod"
480
481 The 'nomethod' key is used to specify a catch-all function to be called
482 for any operator that is not individually overloaded. The specified
483 function will be passed four parameters. The first three arguments
484 coincide with those that would have been passed to the corresponding
485 method if it had been defined. The fourth argument is the "use
486 overload" key for that missing method. If the "bitwise" feature is
487 enabled (see feature), a fifth TRUE argument is passed to subroutines
488 handling "&", "|", "^" and "~" to indicate that the caller is expecting
489 numeric behaviour.
490
491 For example, if $a is an object blessed into a package declaring
492
493 use overload 'nomethod' => 'catch_all', # ...
494
495 then the operation
496
497 3 + $a
498
499 could (unless a method is specifically declared for the key '+') result
500 in a call
501
502 catch_all($a, 3, 1, '+')
503
504 See "How Perl Chooses an Operator Implementation".
505
506 "fallback"
507
508 The value assigned to the key 'fallback' tells Perl how hard it should
509 try to find an alternative way to implement a missing operator.
510
511 • defined, but FALSE
512
513 use overload "fallback" => 0, # ... ;
514
515 This disables "Magic Autogeneration".
516
517 • "undef"
518
519 In the default case where no value is explicitly assigned to
520 "fallback", magic autogeneration is enabled.
521
522 • TRUE
523
524 The same as for "undef", but if a missing operator cannot be
525 autogenerated then, instead of issuing an error message, Perl is
526 allowed to revert to what it would have done for that operator if
527 there had been no "use overload" directive.
528
529 Note: in most cases, particularly the "Copy Constructor", this is
530 unlikely to be appropriate behaviour.
531
532 See "How Perl Chooses an Operator Implementation".
533
534 Copy Constructor
535
536 As mentioned above, this operation is called when a mutator is applied
537 to a reference that shares its object with some other reference. For
538 example, if $b is mathemagical, and '++' is overloaded with 'incr', and
539 '=' is overloaded with 'clone', then the code
540
541 $a = $b;
542 # ... (other code which does not modify $a or $b) ...
543 ++$b;
544
545 would be executed in a manner equivalent to
546
547 $a = $b;
548 # ...
549 $b = $b->clone(undef, "");
550 $b->incr(undef, "");
551
552 Note:
553
554 • The subroutine for '=' does not overload the Perl assignment
555 operator: it is used only to allow mutators to work as described
556 here. (See "Assignments" above.)
557
558 • As for other operations, the subroutine implementing '=' is passed
559 three arguments, though the last two are always "undef" and ''.
560
561 • The copy constructor is called only before a call to a function
562 declared to implement a mutator, for example, if "++$b;" in the
563 code above is effected via a method declared for key '++' (or
564 'nomethod', passed '++' as the fourth argument) or, by
565 autogeneration, '+='. It is not called if the increment operation
566 is effected by a call to the method for '+' since, in the
567 equivalent code,
568
569 $a = $b;
570 $b = $b + 1;
571
572 the data referred to by $a is unchanged by the assignment to $b of
573 a reference to new object data.
574
575 • The copy constructor is not called if Perl determines that it is
576 unnecessary because there is no other reference to the data being
577 modified.
578
579 • If 'fallback' is undefined or TRUE then a copy constructor can be
580 autogenerated, but only for objects based on scalars. In other
581 cases it needs to be defined explicitly. Where an object's data is
582 stored as, for example, an array of scalars, the following might be
583 appropriate:
584
585 use overload '=' => sub { bless [ @{$_[0]} ] }, # ...
586
587 • If 'fallback' is TRUE and no copy constructor is defined then, for
588 objects not based on scalars, Perl may silently fall back on simple
589 assignment - that is, assignment of the object reference. In
590 effect, this disables the copy constructor mechanism since no new
591 copy of the object data is created. This is almost certainly not
592 what you want. (It is, however, consistent: for example, Perl's
593 fallback for the "++" operator is to increment the reference
594 itself.)
595
596 How Perl Chooses an Operator Implementation
597 Which is checked first, "nomethod" or "fallback"? If the two operands
598 of an operator are of different types and both overload the operator,
599 which implementation is used? The following are the precedence rules:
600
601 1. If the first operand has declared a subroutine to overload the
602 operator then use that implementation.
603
604 2. Otherwise, if fallback is TRUE or undefined for the first operand
605 then see if the rules for autogeneration allows another of its
606 operators to be used instead.
607
608 3. Unless the operator is an assignment ("+=", "-=", etc.), repeat
609 step (1) in respect of the second operand.
610
611 4. Repeat Step (2) in respect of the second operand.
612
613 5. If the first operand has a "nomethod" method then use that.
614
615 6. If the second operand has a "nomethod" method then use that.
616
617 7. If "fallback" is TRUE for both operands then perform the usual
618 operation for the operator, treating the operands as numbers,
619 strings, or booleans as appropriate for the operator (see note).
620
621 8. Nothing worked - die.
622
623 Where there is only one operand (or only one operand with overloading)
624 the checks in respect of the other operand above are skipped.
625
626 There are exceptions to the above rules for dereference operations
627 (which, if Step 1 fails, always fall back to the normal, built-in
628 implementations - see Dereferencing), and for "~~" (which has its own
629 set of rules - see "Matching" under "Overloadable Operations" above).
630
631 Note on Step 7: some operators have a different semantic depending on
632 the type of their operands. As there is no way to instruct Perl to
633 treat the operands as, e.g., numbers instead of strings, the result
634 here may not be what you expect. See "BUGS AND PITFALLS".
635
636 Losing Overloading
637 The restriction for the comparison operation is that even if, for
638 example, "cmp" should return a blessed reference, the autogenerated
639 "lt" function will produce only a standard logical value based on the
640 numerical value of the result of "cmp". In particular, a working
641 numeric conversion is needed in this case (possibly expressed in terms
642 of other conversions).
643
644 Similarly, ".=" and "x=" operators lose their mathemagical properties
645 if the string conversion substitution is applied.
646
647 When you chop() a mathemagical object it is promoted to a string and
648 its mathemagical properties are lost. The same can happen with other
649 operations as well.
650
651 Inheritance and Overloading
652 Overloading respects inheritance via the @ISA hierarchy. Inheritance
653 interacts with overloading in two ways.
654
655 Method names in the "use overload" directive
656 If "value" in
657
658 use overload key => value;
659
660 is a string, it is interpreted as a method name - which may (in the
661 usual way) be inherited from another class.
662
663 Overloading of an operation is inherited by derived classes
664 Any class derived from an overloaded class is also overloaded and
665 inherits its operator implementations. If the same operator is
666 overloaded in more than one ancestor then the implementation is
667 determined by the usual inheritance rules.
668
669 For example, if "A" inherits from "B" and "C" (in that order), "B"
670 overloads "+" with "\&D::plus_sub", and "C" overloads "+" by
671 "plus_meth", then the subroutine "D::plus_sub" will be called to
672 implement operation "+" for an object in package "A".
673
674 Note that in Perl version prior to 5.18 inheritance of the "fallback"
675 key was not governed by the above rules. The value of "fallback" in
676 the first overloaded ancestor was used. This was fixed in 5.18 to
677 follow the usual rules of inheritance.
678
679 Run-time Overloading
680 Since all "use" directives are executed at compile-time, the only way
681 to change overloading during run-time is to
682
683 eval 'use overload "+" => \&addmethod';
684
685 You can also use
686
687 eval 'no overload "+", "--", "<="';
688
689 though the use of these constructs during run-time is questionable.
690
691 Public Functions
692 Package "overload.pm" provides the following public functions:
693
694 overload::StrVal(arg)
695 Gives the string value of "arg" as in the absence of stringify
696 overloading. If you are using this to get the address of a
697 reference (useful for checking if two references point to the same
698 thing) then you may be better off using builtin::refaddr() or
699 Scalar::Util::refaddr(), which are faster.
700
701 overload::Overloaded(arg)
702 Returns true if "arg" is subject to overloading of some
703 operations.
704
705 overload::Method(obj,op)
706 Returns "undef" or a reference to the method that implements "op".
707
708 Such a method always takes three arguments, which will be enforced
709 if it is an XS method.
710
711 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
716 These functions take a hash as an argument. The recognized keys of
717 this hash are:
718
719 integer to overload integer constants,
720
721 float to overload floating point constants,
722
723 binary to overload octal and hexadecimal constants,
724
725 q to overload "q"-quoted strings, constant pieces of "qq"- and
726 "qx"-quoted strings and here-documents,
727
728 qr to overload constant pieces of regular expressions.
729
730 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
744 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
750 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
755 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
765 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
770 (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
778 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
785 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
791 Two-face Scalars
792 Put this in two_face.pm in your Perl library directory:
793
794 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
801 Use it as follows:
802
803 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
808 (The second line creates a scalar which has both a string value, and a
809 numeric value.) This prints:
810
811 seven=vii, seven=7, eight=8
812 seven contains 'i'
813
814 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
818 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
831 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
848 Now one can access an object using both the array and hash syntax:
849
850 my $bar = two_refs->new(3,4,5,6);
851 $bar->[2] = 11;
852 $bar->{two} == 11 or die 'bad hash fetch';
853
854 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
861 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
865 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
871 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
880 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
884 package two_refs1;
885 use overload
886 '%{}' => sub { ${shift()}->[1] },
887 '@{}' => sub { ${shift()}->[0] };
888
889 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
903 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
920 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
925 • There are no loops of references.
926
927 • 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
932 Symbolic Calculator
933 Put this in symbolic.pm in your Perl library directory:
934
935 package symbolic; # Primitive symbolic calculator
936 use overload nomethod => \&wrap;
937
938 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
945 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
952 Here is an example of the script which "calculates" the side of
953 circumscribed octagon using the above package:
954
955 require symbolic;
956 my $iter = 1; # 2**($iter+2) = 8
957 my $side = symbolic->new(1);
958 my $cnt = $iter;
959
960 while ($cnt--) {
961 $side = (sqrt(1 + $side**2) - 1)/$side;
962 }
963 print "OK\n";
964
965 The value of $side is
966
967 ['/', ['-', ['sqrt', ['+', 1, ['**', ['n', 1], 2]],
968 undef], 1], ['n', 1]]
969
970 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
975 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
980 Add a pretty-printer method to the module symbolic.pm:
981
982 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
991 Now one can finish the script by
992
993 print "side = ", $side->pretty, "\n";
994
995 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
1004 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
1012 Now one can change the last line of the script to
1013
1014 print "side = $side\n";
1015
1016 which outputs
1017
1018 side = [/ [- [sqrt [+ 1 [** [n 1 u] 2]] u] 1] [n 1 u]]
1019
1020 and one can inspect the value in debugger using all the possible
1021 methods.
1022
1023 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
1027 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
1034 Here is the text of symbolic.pm with such a routine added (and slightly
1035 modified str()):
1036
1037 package symbolic; # Primitive symbolic calculator
1038 use overload
1039 nomethod => \&wrap, '""' => \&str, '0+' => \#
1040
1041 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
1074 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
1079 Use this module like this:
1080
1081 require symbolic;
1082 my $iter = symbolic->new(2); # 16-gon
1083 my $side = symbolic->new(1);
1084 my $cnt = $iter;
1085
1086 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
1093 It prints (without so many line breaks)
1094
1095 [/ [- [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
1100 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
1105 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
1108 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
1121 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
1128 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
1132 sub cpy {
1133 my $self = shift;
1134 bless [@$self], ref $self;
1135 }
1136
1137 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
1141 if ($meth eq '++' or $meth eq '--') {
1142 @$obj = ($meth, (bless [@$obj]), 1); # Avoid circular reference
1143 return $obj;
1144 }
1145
1146 after the first line of wrap(). This is not a most effective
1147 implementation, one may consider
1148
1149 sub inc { $_[0] = bless ['++', shift, 1]; }
1150
1151 instead.
1152
1153 As a final remark, note that one can fill %subr by
1154
1155 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
1169 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
1173 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
1181 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
1188 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
1193 To see it in action, add a method
1194
1195 sub STORE {
1196 my $obj = shift;
1197 $#$obj = 1;
1198 @$obj->[0,1] = ('=', shift);
1199 }
1200
1201 to the package "symbolic". After this change one can do
1202
1203 my $a = symbolic->new(3);
1204 my $b = symbolic->new(4);
1205 my $c = sqrt($a**2 + $b**2);
1206
1207 and the numeric value of $c becomes 5. However, after calling
1208
1209 $a->STORE(12); $b->STORE(5);
1210
1211 the numeric value of $c becomes 13. There is no doubt now that the
1212 module symbolic provides a symbolic calculator indeed.
1213
1214 To hide the rough edges under the hood, provide a tie()d interface to
1215 the package "symbolic". Add methods
1216
1217 sub TIESCALAR { my $pack = shift; $pack->new(@_) }
1218 sub FETCH { shift }
1219 sub nop { } # Around a bug
1220
1221 (the bug, fixed in Perl 5.14, is described in "BUGS"). One can use
1222 this new interface as
1223
1224 tie $a, 'symbolic', 3;
1225 tie $b, 'symbolic', 4;
1226 $a->nop; $b->nop; # Around a bug
1227
1228 my $c = sqrt($a**2 + $b**2);
1229
1230 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
1234 sub vars { my $p = shift; tie($_, $p), $_->nop foreach @_; }
1235
1236 Now
1237
1238 my ($a, $b);
1239 symbolic->vars($a, $b);
1240 my $c = sqrt($a**2 + $b**2);
1241
1242 $a = 3; $b = 4;
1243 printf "c5 %s=%f\n", $c, $c;
1244
1245 $a = 12; $b = 5;
1246 printf "c13 %s=%f\n", $c, $c;
1247
1248 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
1262 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
1270 The module might issue the following warnings:
1271
1272 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
1276 '%s' is not an overloadable type
1277 (W) You tried to overload a constant type the overload package is
1278 unaware of.
1279
1280 '%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
1285 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
1294 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
1300 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
1307 The only way to change this is to provide your own subroutine for
1308 '|'.
1309
1310 • 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
1315 use overload '+' => 'add';
1316 sub add { bless [ \$_[0], \$_[1] ] };
1317
1318 is asking for trouble, since
1319
1320 $obj += $y;
1321
1322 will effectively become
1323
1324 $obj = add($obj, $y, undef);
1325
1326 with the same result as
1327
1328 $obj = [\$obj, \$foo];
1329
1330 Even if no explicit assignment-variants of operators are present in
1331 the script, they may be generated by the optimizer. For example,
1332
1333 "obj = $obj\n"
1334
1335 may be optimized to
1336
1337 my $tmp = 'obj = ' . $obj; $tmp .= "\n";
1338
1339 • The symbol table is filled with names looking like line-noise.
1340
1341 • This bug was fixed in Perl 5.18, but may still trip you up if you
1342 are using older versions:
1343
1344 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
1349 • 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
1353 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
1361 • Barewords are not covered by overloaded string constants.
1362
1363 • The range operator ".." cannot be overloaded.
1364
1365
1366
1367perl v5.38.2 2023-11-30 overload(3pm)