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 = new SomeThing 57;
19 $b=5+$a;
20 ...
21 if (overload::Overloaded $b) {...}
22 ...
23 $strval = overload::StrVal $b;
24
26 Declaration of overloaded functions
27 The compilation directive
29 package Number;
31 use overload
32 "+" => \&add,
33 "*=" => "muas";
34 declares function Number::add() for addition, and method muas() in the
36 "class" "Number" (or one of its base classes) for the assignment form
37 "*=" of multiplication.
38 Arguments of this directive come in (key, value) pairs. Legal values
40 are values legal inside a "&{ ... }" call, so the name of a subroutine,
41 a reference to a subroutine, or an anonymous subroutine will all work.
42 Note that values specified as strings are interpreted as methods, not
43 subroutines. Legal keys are listed below.
44 The subroutine "add" will be called to execute "$a+$b" if $a is a ref‐
46 erence to an object blessed into the package "Number", or if $a is not
47 an object from a package with defined mathemagic addition, but $b is a
48 reference to a "Number". It can also be called in other situations,
49 like "$a+=7", or "$a++". See "MAGIC AUTOGENERATION". (Mathemagical
50 methods refer to methods triggered by an overloaded mathematical opera‐
51 tor.)
52 Since overloading respects inheritance via the @ISA hierarchy, the
54 above declaration would also trigger overloading of "+" and "*=" in all
55 the packages which inherit from "Number".
56 Calling Conventions for Binary Operations
58 The functions specified in the "use overload ..." directive are called
60 with three (in one particular case with four, see "Last Resort") argu‐
61 ments. If the corresponding operation is binary, then the first two
62 arguments are the two arguments of the operation. However, due to gen‐
63 eral object calling conventions, the first argument should always be an
64 object in the package, so in the situation of "7+$a", the order of the
65 arguments is interchanged. It probably does not matter when implement‐
66 ing the addition method, but whether the arguments are reversed is
67 vital to the subtraction method. The method can query this information
68 by examining the third argument, which can take three different values:
69 FALSE the order of arguments is as in the current operation.
71 TRUE the arguments are reversed.
73 "undef"
75 the current operation is an assignment variant (as in "$a+=7"),
76 but the usual function is called instead. This additional
77 information can be used to generate some optimizations. Compare
78 "Calling Conventions for Mutators".
79 Calling Conventions for Unary Operations
81 Unary operation are considered binary operations with the second argu‐
83 ment being "undef". Thus the functions that overloads "{"++"}" is
84 called with arguments "($a,undef,'')" when $a++ is executed.
85 Calling Conventions for Mutators
87 Two types of mutators have different calling conventions:
89 "++" and "--"
91 The routines which implement these operators are expected to actu‐
92 ally mutate their arguments. So, assuming that $obj is a reference
93 to a number,
94 sub incr { my $n = $ {$_[0]}; ++$n; $_[0] = bless \$n}
96 is an appropriate implementation of overloaded "++". Note that
98 sub incr { ++$ {$_[0]} ; shift }
100 is OK if used with preincrement and with postincrement. (In the
102 case of postincrement a copying will be performed, see "Copy Con‐
103 structor".)
104 "x=" and other assignment versions
106 There is nothing special about these methods. They may change the
107 value of their arguments, and may leave it as is. The result is
108 going to be assigned to the value in the left-hand-side if differ‐
109 ent from this value.
110 This allows for the same method to be used as overloaded "+=" and
112 "+". Note that this is allowed, but not recommended, since by the
113 semantic of "Fallback" Perl will call the method for "+" anyway, if
114 "+=" is not overloaded.
115 Warning. Due to the presence of assignment versions of operations,
117 routines which may be called in assignment context may create self-ref‐
118 erential structures. Currently Perl will not free self-referential
119 structures until cycles are "explicitly" broken. You may get problems
120 when traversing your structures too.
121 Say,
123 use overload '+' => sub { bless [ \$_[0], \$_[1] ] };
125 is asking for trouble, since for code "$obj += $foo" the subroutine is
127 called as "$obj = add($obj, $foo, undef)", or "$obj = [\$obj, \$foo]".
128 If using such a subroutine is an important optimization, one can over‐
129 load "+=" explicitly by a non-"optimized" version, or switch to non-
130 optimized version if "not defined $_[2]" (see "Calling Conventions for
131 Binary Operations").
132 Even if no explicit assignment-variants of operators are present in the
134 script, they may be generated by the optimizer. Say, ",$obj," or ',' .
135 $obj . ',' may be both optimized to
136 my $tmp = ',' . $obj; $tmp .= ',';
138 Overloadable Operations
140 The following symbols can be specified in "use overload" directive:
142 * Arithmetic operations
144 "+", "+=", "-", "-=", "*", "*=", "/", "/=", "%", "%=",
145 "**", "**=", "<<", "<<=", ">>", ">>=", "x", "x=", ".", ".=",
146 For these operations a substituted non-assignment variant can be
148 called if the assignment variant is not available. Methods for
149 operations "+", "-", "+=", and "-=" can be called to automatically
150 generate increment and decrement methods. The operation "-" can
151 be used to autogenerate missing methods for unary minus or "abs".
152 See "MAGIC AUTOGENERATION", "Calling Conventions for Mutators" and
154 "Calling Conventions for Binary Operations") for details of these
155 substitutions.
156 * Comparison operations
158 "<", "<=", ">", ">=", "==", "!=", "<=>",
159 "lt", "le", "gt", "ge", "eq", "ne", "cmp",
160 If the corresponding "spaceship" variant is available, it can be
162 used to substitute for the missing operation. During "sort"ing
163 arrays, "cmp" is used to compare values subject to "use overload".
164 * Bit operations
166 "&", "^", "⎪", "neg", "!", "~",
167 "neg" stands for unary minus. If the method for "neg" is not
169 specified, it can be autogenerated using the method for subtrac‐
170 tion. If the method for "!" is not specified, it can be autogener‐
171 ated using the methods for "bool", or "", or "0+".
172 * Increment and decrement
174 "++", "--",
175 If undefined, addition and subtraction methods can be used
177 instead. These operations are called both in prefix and postfix
178 form.
179 * Transcendental functions
181 "atan2", "cos", "sin", "exp", "abs", "log", "sqrt", "int"
182 If "abs" is unavailable, it can be autogenerated using methods for
184 "<" or "<=>" combined with either unary minus or subtraction.
185 Note that traditionally the Perl function int rounds to 0, thus
187 for floating-point-like types one should follow the same semantic.
188 If "int" is unavailable, it can be autogenerated using the over‐
189 loading of "0+".
190 * Boolean, string and numeric conversion
192 'bool', '""', '0+',
193 If one or two of these operations are not overloaded, the remain‐
195 ing ones can be used instead. "bool" is used in the flow control
196 operators (like "while") and for the ternary "?:" operation.
197 These functions can return any arbitrary Perl value. If the cor‐
198 responding operation for this value is overloaded too, that opera‐
199 tion will be called again with this value.
200 As a special case if the overload returns the object itself then
202 it will be used directly. An overloaded conversion returning the
203 object is probably a bug, because you're likely to get something
204 that looks like "YourPackage=HASH(0x8172b34)".
205 * Iteration
207 "<>"
208 If not overloaded, the argument will be converted to a filehandle
210 or glob (which may require a stringification). The same overload‐
211 ing happens both for the read-filehandle syntax "<$var>" and glob‐
212 bing syntax "<${var}>".
213 BUGS Even in list context, the iterator is currently called only
215 once and with scalar context.
216 * Dereferencing
218 '${}', '@{}', '%{}', '&{}', '*{}'.
219 If not overloaded, the argument will be dereferenced as is, thus
221 should be of correct type. These functions should return a refer‐
222 ence of correct type, or another object with overloaded derefer‐
223 encing.
224 As a special case if the overload returns the object itself then
226 it will be used directly (provided it is the correct type).
227 The dereference operators must be specified explicitly they will
229 not be passed to "nomethod".
230 * Special
232 "nomethod", "fallback", "=",
233 see "SPECIAL SYMBOLS FOR "use overload"".
235 See "Fallback" for an explanation of when a missing method can be auto‐
237 generated.
238 A computer-readable form of the above table is available in the hash
240 %overload::ops, with values being space-separated lists of names:
241 with_assign => '+ - * / % ** << >> x .',
243 assign => '+= -= *= /= %= **= <<= >>= x= .=',
244 num_comparison => '< <= > >= == !=',
245 '3way_comparison'=> '<=> cmp',
246 str_comparison => 'lt le gt ge eq ne',
247 binary => '& ⎪ ^',
248 unary => 'neg ! ~',
249 mutators => '++ --',
250 func => 'atan2 cos sin exp abs log sqrt',
251 conversion => 'bool "" 0+',
252 iterators => '<>',
253 dereferencing => '${} @{} %{} &{} *{}',
254 special => 'nomethod fallback ='
255 Inheritance and overloading
257 Inheritance interacts with overloading in two ways.
259 Strings as values of "use overload" directive
261 If "value" in
262 use overload key => value;
264 is a string, it is interpreted as a method name.
266 Overloading of an operation is inherited by derived classes
268 Any class derived from an overloaded class is also overloaded. The
269 set of overloaded methods is the union of overloaded methods of all
270 the ancestors. If some method is overloaded in several ancestor,
271 then which description will be used is decided by the usual inheri‐
272 tance rules:
273 If "A" inherits from "B" and "C" (in this order), "B" overloads "+"
275 with "\&D::plus_sub", and "C" overloads "+" by "plus_meth", then
276 the subroutine "D::plus_sub" will be called to implement operation
277 "+" for an object in package "A".
278 Note that since the value of the "fallback" key is not a subroutine,
280 its inheritance is not governed by the above rules. In the current
281 implementation, the value of "fallback" in the first overloaded ances‐
282 tor is used, but this is accidental and subject to change.
283
285 Three keys are recognized by Perl that are not covered by the above
286 description.
287 Last Resort
289 "nomethod" should be followed by a reference to a function of four
291 parameters. If defined, it is called when the overloading mechanism
292 cannot find a method for some operation. The first three arguments of
293 this function coincide with the arguments for the corresponding method
294 if it were found, the fourth argument is the symbol corresponding to
295 the missing method. If several methods are tried, the last one is
296 used. Say, "1-$a" can be equivalent to
297 &nomethodMethod($a,1,1,"-")
299 if the pair "nomethod" => "nomethodMethod" was specified in the "use
301 overload" directive.
302 The "nomethod" mechanism is not used for the dereference operators (
304 ${} @{} %{} &{} *{} ).
305 If some operation cannot be resolved, and there is no function assigned
307 to "nomethod", then an exception will be raised via die()-- unless
308 "fallback" was specified as a key in "use overload" directive.
309 Fallback
311 The key "fallback" governs what to do if a method for a particular
313 operation is not found. Three different cases are possible depending
314 on the value of "fallback":
315 * "undef" Perl tries to use a substituted method (see "MAGIC
317 AUTOGENERATION"). If this fails, it then tries to
318 calls "nomethod" value; if missing, an exception will
319 be raised.
320 * TRUE The same as for the "undef" value, but no exception is
322 raised. Instead, it silently reverts to what it would
323 have done were there no "use overload" present.
324 * defined, but FALSE
326 No autogeneration is tried. Perl tries to call
327 "nomethod" value, and if this is missing, raises an
328 exception.
329 Note. "fallback" inheritance via @ISA is not carved in stone yet, see
331 "Inheritance and overloading".
332 Copy Constructor
334 The value for "=" is a reference to a function with three arguments,
336 i.e., it looks like the other values in "use overload". However, it
337 does not overload the Perl assignment operator. This would go against
338 Camel hair.
339 This operation is called in the situations when a mutator is applied to
341 a reference that shares its object with some other reference, such as
342 $a=$b;
344 ++$a;
345 To make this change $a and not change $b, a copy of $$a is made, and $a
347 is assigned a reference to this new object. This operation is done
348 during execution of the "++$a", and not during the assignment, (so
349 before the increment $$a coincides with $$b). This is only done if
350 "++" is expressed via a method for '++' or '+=' (or "nomethod"). Note
351 that if this operation is expressed via '+' a nonmutator, i.e., as in
352 $a=$b;
354 $a=$a+1;
355 then $a does not reference a new copy of $$a, since $$a does not appear
357 as lvalue when the above code is executed.
358 If the copy constructor is required during the execution of some muta‐
360 tor, but a method for '=' was not specified, it can be autogenerated as
361 a string copy if the object is a plain scalar.
362 Example
364 The actually executed code for
365 $a=$b;
367 Something else which does not modify $a or $b....
368 ++$a;
369 may be
371 $a=$b;
373 Something else which does not modify $a or $b....
374 $a = $a->clone(undef,"");
375 $a->incr(undef,"");
376 if $b was mathemagical, and '++' was overloaded with "\&incr", '='
378 was overloaded with "\&clone".
379 Same behaviour is triggered by "$b = $a++", which is consider a synonym
381 for "$b = $a; ++$a".
382
384 If a method for an operation is not found, and the value for "fall‐
385 back" is TRUE or undefined, Perl tries to autogenerate a substitute
386 method for the missing operation based on the defined operations.
387 Autogenerated method substitutions are possible for the following oper‐
388 ations:
389 Assignment forms of arithmetic operations
391 "$a+=$b" can use the method for "+" if the method for
392 "+=" is not defined.
393 Conversion operations
395 String, numeric, and boolean conversion are calculated
396 in terms of one another if not all of them are defined.
397 Increment and decrement
399 The "++$a" operation can be expressed in terms of
400 "$a+=1" or "$a+1", and "$a--" in terms of "$a-=1" and
401 "$a-1".
402 "abs($a)" can be expressed in terms of "$a<0" and "-$a" (or
404 "0-$a").
405 Unary minus can be expressed in terms of subtraction.
407 Negation "!" and "not" can be expressed in terms of boolean con‐
409 version, or string or numerical conversion.
410 Concatenation can be expressed in terms of string conversion.
412 Comparison operations
414 can be expressed in terms of its "spaceship" counter‐
415 part: either "<=>" or "cmp":
416 <, >, <=, >=, ==, != in terms of <=>
418 lt, gt, le, ge, eq, ne in terms of cmp
419 Iterator
421 <> in terms of builtin operations
422 Dereferencing
424 ${} @{} %{} &{} *{} in terms of builtin operations
425 Copy operator can be expressed in terms of an assignment to the
427 dereferenced value, if this value is a scalar and not a
428 reference.
429
431 The restriction for the comparison operation is that even if, for exam‐
432 ple, `"cmp"' should return a blessed reference, the autogenerated
433 `"lt"' function will produce only a standard logical value based on the
434 numerical value of the result of `"cmp"'. In particular, a working
435 numeric conversion is needed in this case (possibly expressed in terms
436 of other conversions).
437 Similarly, ".=" and "x=" operators lose their mathemagical properties
439 if the string conversion substitution is applied.
440 When you chop() a mathemagical object it is promoted to a string and
442 its mathemagical properties are lost. The same can happen with other
443 operations as well.
444
446 Since all "use" directives are executed at compile-time, the only way
447 to change overloading during run-time is to
448 eval 'use overload "+" => \&addmethod';
450 You can also use
452 eval 'no overload "+", "--", "<="';
454 though the use of these constructs during run-time is questionable.
456
458 Package "overload.pm" provides the following public functions:
459 overload::StrVal(arg)
461 Gives string value of "arg" as in absence of stringify overload‐
462 ing. If you are using this to get the address of a reference (use‐
463 ful for checking if two references point to the same thing) then
464 you may be better off using "Scalar::Util::refaddr()", which is
465 faster.
466 overload::Overloaded(arg)
468 Returns true if "arg" is subject to overloading of some opera‐
469 tions.
470 overload::Method(obj,op)
472 Returns "undef" or a reference to the method that implements "op".
473
475 For some applications, the Perl parser mangles constants too much. It
476 is possible to hook into this process via "overload::constant()" and
477 "overload::remove_constant()" functions.
478 These functions take a hash as an argument. The recognized keys of
480 this hash are:
481 integer to overload integer constants,
483 float to overload floating point constants,
485 binary to overload octal and hexadecimal constants,
487 q to overload "q"-quoted strings, constant pieces of "qq"- and
489 "qx"-quoted strings and here-documents,
490 qr to overload constant pieces of regular expressions.
492 The corresponding values are references to functions which take three
494 arguments: the first one is the initial string form of the constant,
495 the second one is how Perl interprets this constant, the third one is
496 how the constant is used. Note that the initial string form does not
497 contain string delimiters, and has backslashes in backslash-delimiter
498 combinations stripped (thus the value of delimiter is not relevant for
499 processing of this string). The return value of this function is how
500 this constant is going to be interpreted by Perl. The third argument
501 is undefined unless for overloaded "q"- and "qr"- constants, it is "q"
502 in single-quote context (comes from strings, regular expressions, and
503 single-quote HERE documents), it is "tr" for arguments of "tr"/"y"
504 operators, it is "s" for right-hand side of "s"-operator, and it is
505 "qq" otherwise.
506 Since an expression "ab$cd,," is just a shortcut for 'ab' . $cd . ',,',
508 it is expected that overloaded constant strings are equipped with rea‐
509 sonable overloaded catenation operator, otherwise absurd results will
510 result. Similarly, negative numbers are considered as negations of
511 positive constants.
512 Note that it is probably meaningless to call the functions over‐
514 load::constant() and overload::remove_constant() from anywhere but
515 import() and unimport() methods. From these methods they may be called
516 as
517 sub import {
519 shift;
520 return unless @_;
521 die "unknown import: @_" unless @_ == 1 and $_[0] eq ':constant';
522 overload::constant integer => sub {Math::BigInt->new(shift)};
523 }
524 BUGS Currently overloaded-ness of constants does not propagate into
526 "eval '...'".
527
529 What follows is subject to change RSN.
530 The table of methods for all operations is cached in magic for the sym‐
532 bol table hash for the package. The cache is invalidated during pro‐
533 cessing of "use overload", "no overload", new function definitions, and
534 changes in @ISA. However, this invalidation remains unprocessed until
535 the next "bless"ing into the package. Hence if you want to change over‐
536 loading structure dynamically, you'll need an additional (fake)
537 "bless"ing to update the table.
538 (Every SVish thing has a magic queue, and magic is an entry in that
540 queue. This is how a single variable may participate in multiple forms
541 of magic simultaneously. For instance, environment variables regularly
542 have two forms at once: their %ENV magic and their taint magic. How‐
543 ever, the magic which implements overloading is applied to the stashes,
544 which are rarely used directly, thus should not slow down Perl.)
545 If an object belongs to a package using overload, it carries a special
547 flag. Thus the only speed penalty during arithmetic operations without
548 overloading is the checking of this flag.
549 In fact, if "use overload" is not present, there is almost no overhead
551 for overloadable operations, so most programs should not suffer measur‐
552 able performance penalties. A considerable effort was made to minimize
553 the overhead when overload is used in some package, but the arguments
554 in question do not belong to packages using overload. When in doubt,
555 test your speed with "use overload" and without it. So far there have
556 been no reports of substantial speed degradation if Perl is compiled
557 with optimization turned on.
558 There is no size penalty for data if overload is not used. The only
560 size penalty if overload is used in some package is that all the pack‐
561 ages acquire a magic during the next "bless"ing into the package. This
562 magic is three-words-long for packages without overloading, and carries
563 the cache table if the package is overloaded.
564 Copying ("$a=$b") is shallow; however, a one-level-deep copying is car‐
566 ried out before any operation that can imply an assignment to the
567 object $a (or $b) refers to, like "$a++". You can override this behav‐
568 ior by defining your own copy constructor (see "Copy Constructor").
569 It is expected that arguments to methods that are not explicitly sup‐
571 posed to be changed are constant (but this is not enforced).
572
574 One may wonder why the semantic of overloaded "=" is so counter intu‐
575 itive. If it looks counter intuitive to you, you are subject to a
576 metaphor clash.
577 Here is a Perl object metaphor:
579 object is a reference to blessed data
581 and an arithmetic metaphor:
583 object is a thing by itself.
585 The main problem of overloading "=" is the fact that these metaphors
587 imply different actions on the assignment "$a = $b" if $a and $b are
588 objects. Perl-think implies that $a becomes a reference to whatever $b
589 was referencing. Arithmetic-think implies that the value of "object"
590 $a is changed to become the value of the object $b, preserving the fact
591 that $a and $b are separate entities.
592 The difference is not relevant in the absence of mutators. After a
594 Perl-way assignment an operation which mutates the data referenced by
595 $a would change the data referenced by $b too. Effectively, after "$a
596 = $b" values of $a and $b become indistinguishable.
597 On the other hand, anyone who has used algebraic notation knows the
599 expressive power of the arithmetic metaphor. Overloading works hard to
600 enable this metaphor while preserving the Perlian way as far as possi‐
601 ble. Since it is not possible to freely mix two contradicting
602 metaphors, overloading allows the arithmetic way to write things as far
603 as all the mutators are called via overloaded access only. The way it
604 is done is described in "Copy Constructor".
605 If some mutator methods are directly applied to the overloaded values,
607 one may need to explicitly unlink other values which references the
608 same value:
609 $a = new Data 23;
611 ...
612 $b = $a; # $b is "linked" to $a
613 ...
614 $a = $a->clone; # Unlink $b from $a
615 $a->increment_by(4);
616 Note that overloaded access makes this transparent:
618 $a = new Data 23;
620 $b = $a; # $b is "linked" to $a
621 $a += 4; # would unlink $b automagically
622 However, it would not make
624 $a = new Data 23;
626 $a = 4; # Now $a is a plain 4, not 'Data'
627 preserve "objectness" of $a. But Perl has a way to make assignments to
629 an object do whatever you want. It is just not the overload, but
630 tie()ing interface (see "tie" in perlfunc). Adding a FETCH() method
631 which returns the object itself, and STORE() method which changes the
632 value of the object, one can reproduce the arithmetic metaphor in its
633 completeness, at least for variables which were tie()d from the start.
634 (Note that a workaround for a bug may be needed, see "BUGS".)
636
638 Please add examples to what follows!
639 Two-face scalars
641 Put this in two_face.pm in your Perl library directory:
643 package two_face; # Scalars with separate string and
645 # numeric values.
646 sub new { my $p = shift; bless [@_], $p }
647 use overload '""' => \&str, '0+' => \&num, fallback => 1;
648 sub num {shift->[1]}
649 sub str {shift->[0]}
650 Use it as follows:
652 require two_face;
654 my $seven = new two_face ("vii", 7);
655 printf "seven=$seven, seven=%d, eight=%d\n", $seven, $seven+1;
656 print "seven contains `i'\n" if $seven =~ /i/;
657 (The second line creates a scalar which has both a string value, and a
659 numeric value.) This prints:
660 seven=vii, seven=7, eight=8
662 seven contains `i'
663 Two-face references
665 Suppose you want to create an object which is accessible as both an
667 array reference and a hash reference, similar to the pseudo-hash
668 builtin Perl type. Let's make it better than a pseudo-hash by allowing
669 index 0 to be treated as a normal element.
670 package two_refs;
672 use overload '%{}' => \&gethash, '@{}' => sub { $ {shift()} };
673 sub new {
674 my $p = shift;
675 bless \ [@_], $p;
676 }
677 sub gethash {
678 my %h;
679 my $self = shift;
680 tie %h, ref $self, $self;
681 \%h;
682 }
683 sub TIEHASH { my $p = shift; bless \ shift, $p }
685 my %fields;
686 my $i = 0;
687 $fields{$_} = $i++ foreach qw{zero one two three};
688 sub STORE {
689 my $self = ${shift()};
690 my $key = $fields{shift()};
691 defined $key or die "Out of band access";
692 $$self->[$key] = shift;
693 }
694 sub FETCH {
695 my $self = ${shift()};
696 my $key = $fields{shift()};
697 defined $key or die "Out of band access";
698 $$self->[$key];
699 }
700 Now one can access an object using both the array and hash syntax:
702 my $bar = new two_refs 3,4,5,6;
704 $bar->[2] = 11;
705 $bar->{two} == 11 or die 'bad hash fetch';
706 Note several important features of this example. First of all, the
708 actual type of $bar is a scalar reference, and we do not overload the
709 scalar dereference. Thus we can get the actual non-overloaded contents
710 of $bar by just using $$bar (what we do in functions which overload
711 dereference). Similarly, the object returned by the TIEHASH() method
712 is a scalar reference.
713 Second, we create a new tied hash each time the hash syntax is used.
715 This allows us not to worry about a possibility of a reference loop,
716 which would lead to a memory leak.
717 Both these problems can be cured. Say, if we want to overload hash
719 dereference on a reference to an object which is implemented as a hash
720 itself, the only problem one has to circumvent is how to access this
721 actual hash (as opposed to the virtual hash exhibited by the overloaded
722 dereference operator). Here is one possible fetching routine:
723 sub access_hash {
725 my ($self, $key) = (shift, shift);
726 my $class = ref $self;
727 bless $self, 'overload::dummy'; # Disable overloading of %{}
728 my $out = $self->{$key};
729 bless $self, $class; # Restore overloading
730 $out;
731 }
732 To remove creation of the tied hash on each access, one may an extra
734 level of indirection which allows a non-circular structure of refer‐
735 ences:
736 package two_refs1;
738 use overload '%{}' => sub { ${shift()}->[1] },
739 '@{}' => sub { ${shift()}->[0] };
740 sub new {
741 my $p = shift;
742 my $a = [@_];
743 my %h;
744 tie %h, $p, $a;
745 bless \ [$a, \%h], $p;
746 }
747 sub gethash {
748 my %h;
749 my $self = shift;
750 tie %h, ref $self, $self;
751 \%h;
752 }
753 sub TIEHASH { my $p = shift; bless \ shift, $p }
755 my %fields;
756 my $i = 0;
757 $fields{$_} = $i++ foreach qw{zero one two three};
758 sub STORE {
759 my $a = ${shift()};
760 my $key = $fields{shift()};
761 defined $key or die "Out of band access";
762 $a->[$key] = shift;
763 }
764 sub FETCH {
765 my $a = ${shift()};
766 my $key = $fields{shift()};
767 defined $key or die "Out of band access";
768 $a->[$key];
769 }
770 Now if $baz is overloaded like this, then $baz is a reference to a ref‐
772 erence to the intermediate array, which keeps a reference to an actual
773 array, and the access hash. The tie()ing object for the access hash is
774 a reference to a reference to the actual array, so
775 · There are no loops of references.
777 · Both "objects" which are blessed into the class "two_refs1" are
779 references to a reference to an array, thus references to a scalar.
780 Thus the accessor expression "$$foo->[$ind]" involves no overloaded
781 operations.
782 Symbolic calculator
784 Put this in symbolic.pm in your Perl library directory:
786 package symbolic; # Primitive symbolic calculator
788 use overload nomethod => \&wrap;
789 sub new { shift; bless ['n', @_] }
791 sub wrap {
792 my ($obj, $other, $inv, $meth) = @_;
793 ($obj, $other) = ($other, $obj) if $inv;
794 bless [$meth, $obj, $other];
795 }
796 This module is very unusual as overloaded modules go: it does not pro‐
798 vide any usual overloaded operators, instead it provides the "Last
799 Resort" operator "nomethod". In this example the corresponding subrou‐
800 tine returns an object which encapsulates operations done over the
801 objects: "new symbolic 3" contains "['n', 3]", "2 + new symbolic 3"
802 contains "['+', 2, ['n', 3]]".
803 Here is an example of the script which "calculates" the side of circum‐
805 scribed octagon using the above package:
806 require symbolic;
808 my $iter = 1; # 2**($iter+2) = 8
809 my $side = new symbolic 1;
810 my $cnt = $iter;
811 while ($cnt--) {
813 $side = (sqrt(1 + $side**2) - 1)/$side;
814 }
815 print "OK\n";
816 The value of $side is
818 ['/', ['-', ['sqrt', ['+', 1, ['**', ['n', 1], 2]],
820 undef], 1], ['n', 1]]
821 Note that while we obtained this value using a nice little script,
823 there is no simple way to use this value. In fact this value may be
824 inspected in debugger (see perldebug), but ony if "bareStringify"
825 Option is set, and not via "p" command.
826 If one attempts to print this value, then the overloaded operator ""
828 will be called, which will call "nomethod" operator. The result of
829 this operator will be stringified again, but this result is again of
830 type "symbolic", which will lead to an infinite loop.
831 Add a pretty-printer method to the module symbolic.pm:
833 sub pretty {
835 my ($meth, $a, $b) = @{+shift};
836 $a = 'u' unless defined $a;
837 $b = 'u' unless defined $b;
838 $a = $a->pretty if ref $a;
839 $b = $b->pretty if ref $b;
840 "[$meth $a $b]";
841 }
842 Now one can finish the script by
844 print "side = ", $side->pretty, "\n";
846 The method "pretty" is doing object-to-string conversion, so it is nat‐
848 ural to overload the operator "" using this method. However, inside
849 such a method it is not necessary to pretty-print the components $a and
850 $b of an object. In the above subroutine "[$meth $a $b]" is a catena‐
851 tion of some strings and components $a and $b. If these components use
852 overloading, the catenation operator will look for an overloaded opera‐
853 tor "."; if not present, it will look for an overloaded operator "".
854 Thus it is enough to use
855 use overload nomethod => \&wrap, '""' => \&str;
857 sub str {
858 my ($meth, $a, $b) = @{+shift};
859 $a = 'u' unless defined $a;
860 $b = 'u' unless defined $b;
861 "[$meth $a $b]";
862 }
863 Now one can change the last line of the script to
865 print "side = $side\n";
867 which outputs
869 side = [/ [- [sqrt [+ 1 [** [n 1 u] 2]] u] 1] [n 1 u]]
871 and one can inspect the value in debugger using all the possible meth‐
873 ods.
874 Something is still amiss: consider the loop variable $cnt of the
876 script. It was a number, not an object. We cannot make this value of
877 type "symbolic", since then the loop will not terminate.
878 Indeed, to terminate the cycle, the $cnt should become false. However,
880 the operator "bool" for checking falsity is overloaded (this time via
881 overloaded ""), and returns a long string, thus any object of type
882 "symbolic" is true. To overcome this, we need a way to compare an
883 object to 0. In fact, it is easier to write a numeric conversion rou‐
884 tine.
885 Here is the text of symbolic.pm with such a routine added (and slightly
887 modified str()):
888 package symbolic; # Primitive symbolic calculator
890 use overload
891 nomethod => \&wrap, '""' => \&str, '0+' => \#
892 sub new { shift; bless ['n', @_] }
894 sub wrap {
895 my ($obj, $other, $inv, $meth) = @_;
896 ($obj, $other) = ($other, $obj) if $inv;
897 bless [$meth, $obj, $other];
898 }
899 sub str {
900 my ($meth, $a, $b) = @{+shift};
901 $a = 'u' unless defined $a;
902 if (defined $b) {
903 "[$meth $a $b]";
904 } else {
905 "[$meth $a]";
906 }
907 }
908 my %subr = ( n => sub {$_[0]},
909 sqrt => sub {sqrt $_[0]},
910 '-' => sub {shift() - shift()},
911 '+' => sub {shift() + shift()},
912 '/' => sub {shift() / shift()},
913 '*' => sub {shift() * shift()},
914 '**' => sub {shift() ** shift()},
915 );
916 sub num {
917 my ($meth, $a, $b) = @{+shift};
918 my $subr = $subr{$meth}
919 or die "Do not know how to ($meth) in symbolic";
920 $a = $a->num if ref $a eq __PACKAGE__;
921 $b = $b->num if ref $b eq __PACKAGE__;
922 $subr->($a,$b);
923 }
924 All the work of numeric conversion is done in %subr and num(). Of
926 course, %subr is not complete, it contains only operators used in the
927 example below. Here is the extra-credit question: why do we need an
928 explicit recursion in num()? (Answer is at the end of this section.)
929 Use this module like this:
931 require symbolic;
933 my $iter = new symbolic 2; # 16-gon
934 my $side = new symbolic 1;
935 my $cnt = $iter;
936 while ($cnt) {
938 $cnt = $cnt - 1; # Mutator `--' not implemented
939 $side = (sqrt(1 + $side**2) - 1)/$side;
940 }
941 printf "%s=%f\n", $side, $side;
942 printf "pi=%f\n", $side*(2**($iter+2));
943 It prints (without so many line breaks)
945 [/ [- [sqrt [+ 1 [** [/ [- [sqrt [+ 1 [** [n 1] 2]]] 1]
947 [n 1]] 2]]] 1]
948 [/ [- [sqrt [+ 1 [** [n 1] 2]]] 1] [n 1]]]=0.198912
949 pi=3.182598
950 The above module is very primitive. It does not implement mutator
952 methods ("++", "-=" and so on), does not do deep copying (not required
953 without mutators!), and implements only those arithmetic operations
954 which are used in the example.
955 To implement most arithmetic operations is easy; one should just use
957 the tables of operations, and change the code which fills %subr to
958 my %subr = ( 'n' => sub {$_[0]} );
960 foreach my $op (split " ", $overload::ops{with_assign}) {
961 $subr{$op} = $subr{"$op="} = eval "sub {shift() $op shift()}";
962 }
963 my @bins = qw(binary 3way_comparison num_comparison str_comparison);
964 foreach my $op (split " ", "@overload::ops{ @bins }") {
965 $subr{$op} = eval "sub {shift() $op shift()}";
966 }
967 foreach my $op (split " ", "@overload::ops{qw(unary func)}") {
968 print "defining `$op'\n";
969 $subr{$op} = eval "sub {$op shift()}";
970 }
971 Due to "Calling Conventions for Mutators", we do not need anything spe‐
973 cial to make "+=" and friends work, except filling "+=" entry of %subr,
974 and defining a copy constructor (needed since Perl has no way to know
975 that the implementation of '+=' does not mutate the argument, compare
976 "Copy Constructor").
977 To implement a copy constructor, add "'=' => \&cpy" to "use overload"
979 line, and code (this code assumes that mutators change things one level
980 deep only, so recursive copying is not needed):
981 sub cpy {
983 my $self = shift;
984 bless [@$self], ref $self;
985 }
986 To make "++" and "--" work, we need to implement actual mutators,
988 either directly, or in "nomethod". We continue to do things inside
989 "nomethod", thus add
990 if ($meth eq '++' or $meth eq '--') {
992 @$obj = ($meth, (bless [@$obj]), 1); # Avoid circular reference
993 return $obj;
994 }
995 after the first line of wrap(). This is not a most effective implemen‐
997 tation, one may consider
998 sub inc { $_[0] = bless ['++', shift, 1]; }
1000 instead.
1002 As a final remark, note that one can fill %subr by
1004 my %subr = ( 'n' => sub {$_[0]} );
1006 foreach my $op (split " ", $overload::ops{with_assign}) {
1007 $subr{$op} = $subr{"$op="} = eval "sub {shift() $op shift()}";
1008 }
1009 my @bins = qw(binary 3way_comparison num_comparison str_comparison);
1010 foreach my $op (split " ", "@overload::ops{ @bins }") {
1011 $subr{$op} = eval "sub {shift() $op shift()}";
1012 }
1013 foreach my $op (split " ", "@overload::ops{qw(unary func)}") {
1014 $subr{$op} = eval "sub {$op shift()}";
1015 }
1016 $subr{'++'} = $subr{'+'};
1017 $subr{'--'} = $subr{'-'};
1018 This finishes implementation of a primitive symbolic calculator in 50
1020 lines of Perl code. Since the numeric values of subexpressions are not
1021 cached, the calculator is very slow.
1022 Here is the answer for the exercise: In the case of str(), we need no
1024 explicit recursion since the overloaded "."-operator will fall back to
1025 an existing overloaded operator "". Overloaded arithmetic operators do
1026 not fall back to numeric conversion if "fallback" is not explicitly
1027 requested. Thus without an explicit recursion num() would convert
1028 "['+', $a, $b]" to "$a + $b", which would just rebuild the argument of
1029 num().
1030 If you wonder why defaults for conversion are different for str() and
1032 num(), note how easy it was to write the symbolic calculator. This
1033 simplicity is due to an appropriate choice of defaults. One extra
1034 note: due to the explicit recursion num() is more fragile than sym():
1035 we need to explicitly check for the type of $a and $b. If components
1036 $a and $b happen to be of some related type, this may lead to problems.
1037 Really symbolic calculator
1039 One may wonder why we call the above calculator symbolic. The reason
1041 is that the actual calculation of the value of expression is postponed
1042 until the value is used.
1043 To see it in action, add a method
1045 sub STORE {
1047 my $obj = shift;
1048 $#$obj = 1;
1049 @$obj->[0,1] = ('=', shift);
1050 }
1051 to the package "symbolic". After this change one can do
1053 my $a = new symbolic 3;
1055 my $b = new symbolic 4;
1056 my $c = sqrt($a**2 + $b**2);
1057 and the numeric value of $c becomes 5. However, after calling
1059 $a->STORE(12); $b->STORE(5);
1061 the numeric value of $c becomes 13. There is no doubt now that the
1063 module symbolic provides a symbolic calculator indeed.
1064 To hide the rough edges under the hood, provide a tie()d interface to
1066 the package "symbolic" (compare with "Metaphor clash"). Add methods
1067 sub TIESCALAR { my $pack = shift; $pack->new(@_) }
1069 sub FETCH { shift }
1070 sub nop { } # Around a bug
1071 (the bug is described in "BUGS"). One can use this new interface as
1073 tie $a, 'symbolic', 3;
1075 tie $b, 'symbolic', 4;
1076 $a->nop; $b->nop; # Around a bug
1077 my $c = sqrt($a**2 + $b**2);
1079 Now numeric value of $c is 5. After "$a = 12; $b = 5" the numeric
1081 value of $c becomes 13. To insulate the user of the module add a
1082 method
1083 sub vars { my $p = shift; tie($_, $p), $_->nop foreach @_; }
1085 Now
1087 my ($a, $b);
1089 symbolic->vars($a, $b);
1090 my $c = sqrt($a**2 + $b**2);
1091 $a = 3; $b = 4;
1093 printf "c5 %s=%f\n", $c, $c;
1094 $a = 12; $b = 5;
1096 printf "c13 %s=%f\n", $c, $c;
1097 shows that the numeric value of $c follows changes to the values of $a
1099 and $b.
1100
1102 Ilya Zakharevich <ilya@math.mps.ohio-state.edu>.
1103
1105 When Perl is run with the -Do switch or its equivalent, overloading
1106 induces diagnostic messages.
1107 Using the "m" command of Perl debugger (see perldebug) one can deduce
1109 which operations are overloaded (and which ancestor triggers this over‐
1110 loading). Say, if "eq" is overloaded, then the method "(eq" is shown by
1111 debugger. The method "()" corresponds to the "fallback" key (in fact a
1112 presence of this method shows that this package has overloading
1113 enabled, and it is what is used by the "Overloaded" function of module
1114 "overload").
1115 The module might issue the following warnings:
1117 Odd number of arguments for overload::constant
1119 (W) The call to overload::constant contained an odd number of argu‐
1120 ments. The arguments should come in pairs.
1121 `%s' is not an overloadable type
1123 (W) You tried to overload a constant type the overload package is
1124 unaware of.
1125 `%s' is not a code reference
1127 (W) The second (fourth, sixth, ...) argument of overload::constant
1128 needs to be a code reference. Either an anonymous subroutine, or a
1129 reference to a subroutine.
1130
1132 Because it is used for overloading, the per-package hash %OVERLOAD now
1133 has a special meaning in Perl. The symbol table is filled with names
1134 looking like line-noise.
1135 For the purpose of inheritance every overloaded package behaves as if
1137 "fallback" is present (possibly undefined). This may create interesting
1138 effects if some package is not overloaded, but inherits from two over‐
1139 loaded packages.
1140 Relation between overloading and tie()ing is broken. Overloading is
1142 triggered or not basing on the previous class of tie()d value.
1143 This happens because the presence of overloading is checked too early,
1145 before any tie()d access is attempted. If the FETCH()ed class of the
1146 tie()d value does not change, a simple workaround is to access the
1147 value immediately after tie()ing, so that after this call the previous
1148 class coincides with the current one.
1149 Needed: a way to fix this without a speed penalty.
1151 Barewords are not covered by overloaded string constants.
1153 This document is confusing. There are grammos and misleading language
1155 used in places. It would seem a total rewrite is needed.
1156perl v5.8.8 2001-09-21 overload(3pm)