6 with_assign => "+ - * / % ** << >> x .",
7 assign => "+= -= *= /= %= **= <<= >>= x= .=",
8 num_comparison => "< <= > >= == !=",
9 '3way_comparison' => "<=> cmp",
10 str_comparison => "lt le gt ge eq ne",
11 binary => '& &= | |= ^ ^=',
14 func => "atan2 cos sin exp abs log sqrt int",
15 conversion => 'bool "" 0+ qr',
18 dereferencing => '${} @{} %{} &{} *{}',
20 special => 'nomethod fallback =',
24 for $category (keys %ops) {
25 $ops_seen{$_}++ for (split /\s+/, $ops{$category});
34 *{$package . "::()"} = \&nil; # Make it findable via fetchmethod.
36 if ($_ eq 'fallback') {
37 for my $sym (*{$package . "::(fallback"}) {
38 *$sym = \&nil; # Make it findable via fetchmethod.
42 warnings::warnif("overload arg '$_' is invalid")
46 $ {$package . "::(" . $_} = $sub;
49 #print STDERR "Setting '$ {'package'}::\cO$_' to \\&'$sub'.\n";
50 *{$package . "::(" . $_} = \&{ $sub };
56 $package = (caller())[0];
57 # *{$package . "::OVERLOAD"} = \&OVERLOAD;
59 $package->overload::OVERLOAD(@_);
63 $package = (caller())[0];
66 warnings::warnif("overload arg '$_' is invalid")
68 delete $ {$package . "::"}{"(" . $_};
74 $package = ref $package if ref $package;
75 mycan ($package, '()');
80 return undef unless $globref;
81 my $sub = \&{*$globref};
83 return $sub if !ref $sub or $sub != \&nil;
84 return shift->can($ {*$globref});
87 sub OverloadedStringify {
89 $package = ref $package if ref $package;
91 ov_method mycan($package, '(""'), $package
92 or ov_method mycan($package, '(0+'), $package
93 or ov_method mycan($package, '(bool'), $package
94 or ov_method mycan($package, '(nomethod'), $package;
102 require Scalar::Util;
103 $package = Scalar::Util::blessed($package);
104 return undef if !defined $package;
106 #my $meth = $package->can('(' . shift);
107 ov_method mycan($package, '(' . shift), $package;
108 #return $meth if $meth ne \&nil;
109 #return $ {*{$meth}};
119 sub mycan { # Real can would leave stubs.
120 my ($package, $meth) = @_;
126 my $mro = mro::get_linear_isa($package);
127 foreach my $p (@$mro) {
128 my $fqmeth = $p . q{::} . $meth;
129 return \*{$fqmeth} if defined &{$fqmeth};
136 'integer' => 0x1000, # HINT_NEW_INTEGER
137 'float' => 0x2000, # HINT_NEW_FLOAT
138 'binary' => 0x4000, # HINT_NEW_BINARY
139 'q' => 0x8000, # HINT_NEW_STRING
140 'qr' => 0x10000, # HINT_NEW_RE
143 use warnings::register;
145 # Arguments: what, sub
148 warnings::warnif ("Odd number of arguments for overload::constant");
151 elsif (!exists $constants {$_ [0]}) {
152 warnings::warnif ("'$_[0]' is not an overloadable type");
154 elsif (!ref $_ [1] || "$_[1]" !~ /(^|=)CODE\(0x[0-9a-f]+\)$/) {
155 # Can't use C<ref $_[1] eq "CODE"> above as code references can be
156 # blessed, and C<ref> would return the package the ref is blessed into.
157 if (warnings::enabled) {
158 $_ [1] = "undef" unless defined $_ [1];
159 warnings::warn ("'$_[1]' is not a code reference");
164 $^H |= $constants{$_[0]};
170 sub remove_constant {
171 # Arguments: what, sub
174 $^H &= ~ $constants{$_[0]};
185 overload - Package for overloading Perl operations
198 $a = SomeThing->new( 57 );
201 if (overload::Overloaded $b) {...}
203 $strval = overload::StrVal $b;
207 This pragma allows overloading of Perl's operators for a class.
208 To overload built-in functions, see L<perlsub/Overriding Built-in Functions> instead.
214 Arguments of the C<use overload> directive are (key, value) pairs.
215 For the full set of legal keys, see L<Overloadable Operations> below.
217 Operator implementations (the values) can be subroutines,
218 references to subroutines, or anonymous subroutines
219 - in other words, anything legal inside a C<&{ ... }> call.
220 Values specified as strings are interpreted as method names.
227 '""' => sub { ...; };
229 declares that subtraction is to be implemented by method C<minus()>
230 in the class C<Number> (or one of its base classes),
231 and that the function C<Number::muas()> is to be used for the
232 assignment form of multiplication, C<*=>.
233 It also defines an anonymous subroutine to implement stringification:
234 this is called whenever an object blessed into the package C<Number>
235 is used in a string context (this subroutine might, for example,
236 return the number as a Roman numeral).
238 =head3 Calling Conventions and Magic Autogeneration
240 The following sample implementation of C<minus()> (which assumes
241 that C<Number> objects are simply blessed references to scalars)
242 illustrates the calling conventions:
246 my ($self, $other, $swap) = @_;
247 my $result = $$self - $other; # *
248 $result = -$result if $swap;
249 ref $result ? $result : bless \$result;
251 # * may recurse once - see table below
253 Three arguments are passed to all subroutines specified in the
254 C<use overload> directive (with one exception - see L</nomethod>).
255 The first of these is the operand providing the overloaded
256 operator implementation -
257 in this case, the object whose C<minus()> method is being called.
259 The second argument is the other operand, or C<undef> in the
260 case of a unary operator.
262 The third argument is set to TRUE if (and only if) the two
263 operands have been swapped. Perl may do this to ensure that the
264 first argument (C<$self>) is an object implementing the overloaded
265 operation, in line with general object calling conventions.
266 For example, if C<$x> and C<$y> are C<Number>s:
268 operation | generates a call to
269 ============|======================
270 $x - $y | minus($x, $y, '')
271 $x - 7 | minus($x, 7, '')
272 7 - $x | minus($x, 7, 1)
274 Perl may also use C<minus()> to implement other operators which
275 have not been specified in the C<use overload> directive,
276 according to the rules for L<Magic Autogeneration> described later.
277 For example, the C<use overload> above declared no subroutine
278 for any of the operators C<-->, C<neg> (the overload key for
279 unary minus), or C<-=>. Thus
281 operation | generates a call to
282 ============|======================
283 -$x | minus($x, 0, 1)
284 $x-- | minus($x, 1, undef)
285 $x -= 3 | minus($x, 3, undef)
288 where autogeneration results in the method for a standard
289 operator which does not change either of its operands, such
290 as C<->, being used to implement an operator which changes
291 the operand ("mutators": here, C<--> and C<-=>),
292 Perl passes undef as the third argument.
293 This still evaluates as FALSE, consistent with the fact that
294 the operands have not been swapped, but gives the subroutine
295 a chance to alter its behaviour in these cases.
297 In all the above examples, C<minus()> is required
298 only to return the result of the subtraction:
299 Perl takes care of the assignment to $x.
300 In fact, such methods should I<not> modify their operands,
301 even if C<undef> is passed as the third argument
302 (see L<Overloadable Operations>).
304 The same is not true of implementations of C<++> and C<-->:
305 these are expected to modify their operand.
306 An appropriate implementation of C<--> might look like
308 use overload '--' => "decr",
310 sub decr { --${$_[0]}; }
312 =head3 Mathemagic, Mutators, and Copy Constructors
314 The term 'mathemagic' describes the overloaded implementation
315 of mathematical operators.
316 Mathemagical operations raise an issue.
322 If C<$a> and C<$b> are scalars then after these statements
326 An object, however, is a reference to blessed data, so if
327 C<$a> and C<$b> are objects then the assignment C<$a = $b>
328 copies only the reference, leaving C<$a> and C<$b> referring
329 to the same object data.
330 One might therefore expect the operation C<--$a> to decrement
331 C<$b> as well as C<$a>.
332 However, this would not be consistent with how we expect the
333 mathematical operators to work.
335 Perl resolves this dilemma by transparently calling a copy
336 constructor before calling a method defined to implement
337 a mutator (C<-->, C<+=>, and so on.).
338 In the above example, when Perl reaches the decrement
339 statement, it makes a copy of the object data in C<$a> and
340 assigns to C<$a> a reference to the copied data.
341 Only then does it call C<decr()>, which alters the copied
342 data, leaving C<$b> unchanged.
343 Thus the object metaphor is preserved as far as possible,
344 while mathemagical operations still work according to the
347 Note: the preceding paragraph describes what happens when
348 Perl autogenerates the copy constructor for an object based
350 For other cases, see L<Copy Constructor>.
352 =head2 Overloadable Operations
354 The complete list of keys that can be specified in the C<use overload>
355 directive are given, separated by spaces, in the values of the
356 hash C<%overload::ops>:
358 with_assign => '+ - * / % ** << >> x .',
359 assign => '+= -= *= /= %= **= <<= >>= x= .=',
360 num_comparison => '< <= > >= == !=',
361 '3way_comparison'=> '<=> cmp',
362 str_comparison => 'lt le gt ge eq ne',
363 binary => '& &= | |= ^ ^=',
366 func => 'atan2 cos sin exp abs log sqrt int',
367 conversion => 'bool "" 0+ qr',
370 dereferencing => '${} @{} %{} &{} *{}',
372 special => 'nomethod fallback ='
374 Most of the overloadable operators map one-to-one to these keys.
375 Exceptions, including additional overloadable operations not
376 apparent from this hash, are included in the notes which follow.
378 A warning is issued if an attempt is made to register an operator not found
385 The operator C<not> is not a valid key for C<use overload>.
386 However, if the operator C<!> is overloaded then the same
387 implementation will be used for C<not>
388 (since the two operators differ only in precedence).
392 The key C<neg> is used for unary minus to disambiguate it from
397 Assuming they are to behave analogously to Perl's C<++> and C<-->,
398 overloaded implementations of these operators are required to
399 mutate their operands.
401 No distinction is made between prefix and postfix forms of the
402 increment and decrement operators: these differ only in the
403 point at which Perl calls the associated subroutine when
404 evaluating an expression.
406 =item * I<Assignments>
408 += -= *= /= %= **= <<= >>= x= .=
411 Simple assignment is not overloadable (the C<'='> key is used
412 for the L<Copy Constructor>).
413 Perl does have a way to make assignments to an object do whatever
414 you want, but this involves using tie(), not overload -
415 see L<perlfunc/tie> and the L</COOKBOOK> examples below.
417 The subroutine for the assignment variant of an operator is
418 required only to return the result of the operation.
419 It is permitted to change the value of its operand
420 (this is safe because Perl calls the copy constructor first),
421 but this is optional since Perl assigns the returned value to
422 the left-hand operand anyway.
424 An object that overloads an assignment operator does so only in
425 respect of assignments to that object.
426 In other words, Perl never calls the corresponding methods with
427 the third argument (the "swap" argument) set to TRUE.
428 For example, the operation
432 cannot lead to C<$b>'s implementation of C<*=> being called,
433 even if C<$a> is a scalar.
434 (It can, however, generate a call to C<$b>'s method for C<*>).
436 =item * I<Non-mutators with a mutator variant>
438 + - * / % ** << >> x .
441 As described L<above|"Calling Conventions and Magic Autogeneration">,
442 Perl may call methods for operators like C<+> and C<&> in the course
443 of implementing missing operations like C<++>, C<+=>, and C<&=>.
444 While these methods may detect this usage by testing the definedness
445 of the third argument, they should in all cases avoid changing their
447 This is because Perl does not call the copy constructor before
448 invoking these methods.
452 Traditionally, the Perl function C<int> rounds to 0
453 (see L<perlfunc/int>), and so for floating-point-like types one
454 should follow the same semantic.
456 =item * I<String, numeric, boolean, and regexp conversions>
460 These conversions are invoked according to context as necessary.
461 For example, the subroutine for C<'""'> (stringify) may be used
462 where the overloaded object is passed as an argument to C<print>,
463 and that for C<'bool'> where it is tested in the condition of a flow
464 control statement (like C<while>) or the ternary C<?:> operation.
466 Of course, in contexts like, for example, C<$obj + 1>, Perl will
467 invoke C<$obj>'s implementation of C<+> rather than (in this
468 example) converting C<$obj> to a number using the numify method
469 C<'0+'> (an exception to this is when no method has been provided
470 for C<'+'> and L</fallback> is set to TRUE).
472 The subroutines for C<'""'>, C<'0+'>, and C<'bool'> can return
473 any arbitrary Perl value.
474 If the corresponding operation for this value is overloaded too,
475 the operation will be called again with this value.
477 As a special case if the overload returns the object itself then it will
478 be used directly. An overloaded conversion returning the object is
479 probably a bug, because you're likely to get something that looks like
480 C<YourPackage=HASH(0x8172b34)>.
484 The subroutine for C<'qr'> is used wherever the object is
485 interpolated into or used as a regexp, including when it
486 appears on the RHS of a C<=~> or C<!~> operator.
488 C<qr> must return a compiled regexp, or a ref to a compiled regexp
489 (such as C<qr//> returns), and any further overloading on the return
490 value will be ignored.
494 If C<E<lt>E<gt>> is overloaded then the same implementation is used
495 for both the I<read-filehandle> syntax C<E<lt>$varE<gt>> and
496 I<globbing> syntax C<E<lt>${var}E<gt>>.
498 B<BUGS> Even in list context, the iterator is currently called only
499 once and with scalar context.
501 =item * I<File tests>
503 The key C<'-X'> is used to specify a subroutine to handle all the
504 filetest operators (C<-f>, C<-x>, and so on: see L<perlfunc/-X> for
506 it is not possible to overload any filetest operator individually.
507 To distinguish them, the letter following the '-' is passed as the
508 second argument (that is, in the slot that for binary operators
509 is used to pass the second operand).
511 Calling an overloaded filetest operator does not affect the stat value
512 associated with the special filehandle C<_>. It still refers to the
513 result of the last C<stat>, C<lstat> or unoverloaded filetest.
515 This overload was introduced in Perl 5.12.
519 The key C<"~~"> allows you to override the smart matching logic used by
520 the C<~~> operator and the switch construct (C<given>/C<when>). See
521 L<perlsyn/Switch Statements> and L<feature>.
523 Unusually, the overloaded implementation of the smart match operator
524 does not get full control of the smart match behaviour.
525 In particular, in the following code:
528 use overload '~~' => 'match';
530 my $obj = Foo->new();
533 the smart match does I<not> invoke the method call like this:
535 $obj->match([1,2,3],0);
537 rather, the smart match distributive rule takes precedence, so $obj is
538 smart matched against each array element in turn until a match is found,
539 so you may see between one and three of these calls instead:
545 Consult the match table in L<perlop/"Smartmatch Operator"> for
546 details of when overloading is invoked.
548 =item * I<Dereferencing>
552 If these operators are not explicitly overloaded then they
553 work in the normal way, yielding the underlying scalar,
554 array, or whatever stores the object data (or the appropriate
555 error message if the dereference operator doesn't match it).
556 Defining a catch-all C<'nomethod'> (see L<below|/nomethod>)
557 makes no difference to this as the catch-all function will
558 not be called to implement a missing dereference operator.
560 If a dereference operator is overloaded then it must return a
561 I<reference> of the appropriate type (for example, the
562 subroutine for key C<'${}'> should return a reference to a
563 scalar, not a scalar), or another object which overloads the
564 operator: that is, the subroutine only determines what is
565 dereferenced and the actual dereferencing is left to Perl.
566 As a special case, if the subroutine returns the object itself
567 then it will not be called again - avoiding infinite recursion.
573 See L<Special Keys for C<use overload>>.
577 =head2 Magic Autogeneration
579 If a method for an operation is not found then Perl tries to
580 autogenerate a substitute implementation from the operations
581 that have been defined.
583 Note: the behaviour described in this section can be disabled
584 by setting C<fallback> to FALSE (see L</fallback>).
586 In the following tables, numbers indicate priority.
587 For example, the table below states that,
588 if no implementation for C<'!'> has been defined then Perl will
589 implement it using C<'bool'> (that is, by inverting the value
590 returned by the method for C<'bool'>);
591 if boolean conversion is also unimplemented then Perl will
592 use C<'0+'> or, failing that, C<'""'>.
594 operator | can be autogenerated from
597 =========|==========================
611 Note: The iterator (C<'E<lt>E<gt>'>) and file test (C<'-X'>)
612 operators work as normal: if the operand is not a blessed glob or
613 IO reference then it is converted to a string (using the method
614 for C<'""'>, C<'0+'>, or C<'bool'>) to be interpreted as a glob
617 operator | can be autogenerated from
620 =========|==========================
624 abs | a1 a2 b1 b2 [*]
632 * one from [a1, a2] and one from [b1, b2]
634 Just as numeric comparisons can be autogenerated from the method
635 for C<< '<=>' >>, string comparisons can be autogenerated from
638 operators | can be autogenerated from
639 ====================|===========================
640 lt gt le ge eq ne | cmp
642 Similarly, autogeneration for keys C<'+='> and C<'++'> is analogous
643 to C<'-='> and C<'--'> above:
645 operator | can be autogenerated from
648 =========|==========================
652 And other assignment variations are analogous to
653 C<'+='> and C<'-='> (and similar to C<'.='> and C<'x='> above):
655 operator || *= /= %= **= <<= >>= &= ^= |=
656 -------------------||--------------------------------
657 autogenerated from || * / % ** << >> & ^ |
659 Note also that the copy constructor (key C<'='>) may be
660 autogenerated, but only for objects based on scalars.
661 See L<Copy Constructor>.
663 =head3 Minimal Set of Overloaded Operations
665 Since some operations can be automatically generated from others, there is
666 a minimal set of operations that need to be overloaded in order to have
667 the complete set of overloaded operations at one's disposal.
668 Of course, the autogenerated operations may not do exactly what the user
669 expects. The minimal set is:
674 atan2 cos sin exp log sqrt int
678 Of the conversions, only one of string, boolean or numeric is
679 needed because each can be generated from either of the other two.
681 =head2 Special Keys for C<use overload>
685 The C<'nomethod'> key is used to specify a catch-all function to
686 be called for any operator that is not individually overloaded.
687 The specified function will be passed four parameters.
688 The first three arguments coincide with those that would have been
689 passed to the corresponding method if it had been defined.
690 The fourth argument is the C<use overload> key for that missing
693 For example, if C<$a> is an object blessed into a package declaring
695 use overload 'nomethod' => 'catch_all', # ...
701 could (unless a method is specifically declared for the key
702 C<'+'>) result in a call
704 catch_all($a, 3, 1, '+')
706 See L<How Perl Chooses an Operator Implementation>.
710 The value assigned to the key C<'fallback'> tells Perl how hard
711 it should try to find an alternative way to implement a missing
716 =item * defined, but FALSE
718 use overload "fallback" => 0, # ... ;
720 This disables L<Magic Autogeneration>.
724 In the default case where no value is explicitly assigned to
725 C<fallback>, magic autogeneration is enabled.
729 The same as for C<undef>, but if a missing operator cannot be
730 autogenerated then, instead of issuing an error message, Perl
731 is allowed to revert to what it would have done for that
732 operator if there had been no C<use overload> directive.
734 Note: in most cases, particularly the L<Copy Constructor>,
735 this is unlikely to be appropriate behaviour.
739 See L<How Perl Chooses an Operator Implementation>.
741 =head3 Copy Constructor
743 As mentioned L<above|"Mathemagic, Mutators, and Copy Constructors">,
744 this operation is called when a mutator is applied to a reference
745 that shares its object with some other reference.
746 For example, if C<$b> is mathemagical, and C<'++'> is overloaded
747 with C<'incr'>, and C<'='> is overloaded with C<'clone'>, then the
751 # ... (other code which does not modify $a or $b) ...
754 would be executed in a manner equivalent to
758 $b = $b->clone(undef, "");
767 The subroutine for C<'='> does not overload the Perl assignment
768 operator: it is used only to allow mutators to work as described
769 here. (See L</Assignments> above.)
773 As for other operations, the subroutine implementing '=' is passed
774 three arguments, though the last two are always C<undef> and C<''>.
778 The copy constructor is called only before a call to a function
779 declared to implement a mutator, for example, if C<++$b;> in the
780 code above is effected via a method declared for key C<'++'>
781 (or 'nomethod', passed C<'++'> as the fourth argument) or, by
782 autogeneration, C<'+='>.
783 It is not called if the increment operation is effected by a call
784 to the method for C<'+'> since, in the equivalent code,
789 the data referred to by C<$a> is unchanged by the assignment to
790 C<$b> of a reference to new object data.
794 The copy constructor is not called if Perl determines that it is
795 unnecessary because there is no other reference to the data being
800 If C<'fallback'> is undefined or TRUE then a copy constructor
801 can be autogenerated, but only for objects based on scalars.
802 In other cases it needs to be defined explicitly.
803 Where an object's data is stored as, for example, an array of
804 scalars, the following might be appropriate:
806 use overload '=' => sub { bless [ @{$_[0]} ] }, # ...
810 If C<'fallback'> is TRUE and no copy constructor is defined then,
811 for objects not based on scalars, Perl may silently fall back on
812 simple assignment - that is, assignment of the object reference.
813 In effect, this disables the copy constructor mechanism since
814 no new copy of the object data is created.
815 This is almost certainly not what you want.
816 (It is, however, consistent: for example, Perl's fallback for the
817 C<++> operator is to increment the reference itself.)
821 =head2 How Perl Chooses an Operator Implementation
823 Which is checked first, C<nomethod> or C<fallback>?
824 If the two operands of an operator are of different types and
825 both overload the operator, which implementation is used?
826 The following are the precedence rules:
832 If the first operand has declared a subroutine to overload the
833 operator then use that implementation.
837 Otherwise, if fallback is TRUE or undefined for the
838 first operand then see if the
839 L<rules for autogeneration|"Magic Autogeneration">
840 allows another of its operators to be used instead.
844 Unless the operator is an assignment (C<+=>, C<-=>, etc.),
845 repeat step (1) in respect of the second operand.
849 Repeat Step (2) in respect of the second operand.
853 If the first operand has a "nomethod" method then use that.
857 If the second operand has a "nomethod" method then use that.
861 If C<fallback> is TRUE for both operands
862 then perform the usual operation for the operator,
863 treating the operands as numbers, strings, or booleans
864 as appropriate for the operator (see note).
868 Nothing worked - die.
872 Where there is only one operand (or only one operand with
873 overloading) the checks in respect of the other operand above are
876 There are exceptions to the above rules for dereference operations
877 (which, if Step 1 fails, always fall back to the normal, built-in
878 implementations - see Dereferencing), and for C<~~> (which has its
879 own set of rules - see C<Matching> under L</Overloadable Operations>
882 Note on Step 7: some operators have a different semantic depending
883 on the type of their operands.
884 As there is no way to instruct Perl to treat the operands as, e.g.,
885 numbers instead of strings, the result here may not be what you
887 See L<BUGS AND PITFALLS>.
889 =head2 Losing Overloading
891 The restriction for the comparison operation is that even if, for example,
892 C<cmp> should return a blessed reference, the autogenerated C<lt>
893 function will produce only a standard logical value based on the
894 numerical value of the result of C<cmp>. In particular, a working
895 numeric conversion is needed in this case (possibly expressed in terms of
898 Similarly, C<.=> and C<x=> operators lose their mathemagical properties
899 if the string conversion substitution is applied.
901 When you chop() a mathemagical object it is promoted to a string and its
902 mathemagical properties are lost. The same can happen with other
905 =head2 Inheritance and Overloading
907 Overloading respects inheritance via the @ISA hierarchy.
908 Inheritance interacts with overloading in two ways.
912 =item Method names in the C<use overload> directive
916 use overload key => value;
918 is a string, it is interpreted as a method name - which may
919 (in the usual way) be inherited from another class.
921 =item Overloading of an operation is inherited by derived classes
923 Any class derived from an overloaded class is also overloaded
924 and inherits its operator implementations.
925 If the same operator is overloaded in more than one ancestor
926 then the implementation is determined by the usual inheritance
929 For example, if C<A> inherits from C<B> and C<C> (in that order),
930 C<B> overloads C<+> with C<\&D::plus_sub>, and C<C> overloads
931 C<+> by C<"plus_meth">, then the subroutine C<D::plus_sub> will
932 be called to implement operation C<+> for an object in package C<A>.
936 Note that in Perl version prior to 5.18 inheritance of the C<fallback> key
937 was not governed by the above rules. The value of C<fallback> in the first
938 overloaded ancestor was used. This was fixed in 5.18 to follow the usual
939 rules of inheritance.
941 =head2 Run-time Overloading
943 Since all C<use> directives are executed at compile-time, the only way to
944 change overloading during run-time is to
946 eval 'use overload "+" => \&addmethod';
950 eval 'no overload "+", "--", "<="';
952 though the use of these constructs during run-time is questionable.
954 =head2 Public Functions
956 Package C<overload.pm> provides the following public functions:
960 =item overload::StrVal(arg)
962 Gives the string value of C<arg> as in the
963 absence of stringify overloading. If you
964 are using this to get the address of a reference (useful for checking if two
965 references point to the same thing) then you may be better off using
966 C<Scalar::Util::refaddr()>, which is faster.
968 =item overload::Overloaded(arg)
970 Returns true if C<arg> is subject to overloading of some operations.
972 =item overload::Method(obj,op)
974 Returns C<undef> or a reference to the method that implements C<op>.
978 =head2 Overloading Constants
980 For some applications, the Perl parser mangles constants too much.
981 It is possible to hook into this process via C<overload::constant()>
982 and C<overload::remove_constant()> functions.
984 These functions take a hash as an argument. The recognized keys of this hash
991 to overload integer constants,
995 to overload floating point constants,
999 to overload octal and hexadecimal constants,
1003 to overload C<q>-quoted strings, constant pieces of C<qq>- and C<qx>-quoted
1004 strings and here-documents,
1008 to overload constant pieces of regular expressions.
1012 The corresponding values are references to functions which take three arguments:
1013 the first one is the I<initial> string form of the constant, the second one
1014 is how Perl interprets this constant, the third one is how the constant is used.
1015 Note that the initial string form does not
1016 contain string delimiters, and has backslashes in backslash-delimiter
1017 combinations stripped (thus the value of delimiter is not relevant for
1018 processing of this string). The return value of this function is how this
1019 constant is going to be interpreted by Perl. The third argument is undefined
1020 unless for overloaded C<q>- and C<qr>- constants, it is C<q> in single-quote
1021 context (comes from strings, regular expressions, and single-quote HERE
1022 documents), it is C<tr> for arguments of C<tr>/C<y> operators,
1023 it is C<s> for right-hand side of C<s>-operator, and it is C<qq> otherwise.
1025 Since an expression C<"ab$cd,,"> is just a shortcut for C<'ab' . $cd . ',,'>,
1026 it is expected that overloaded constant strings are equipped with reasonable
1027 overloaded catenation operator, otherwise absurd results will result.
1028 Similarly, negative numbers are considered as negations of positive constants.
1030 Note that it is probably meaningless to call the functions overload::constant()
1031 and overload::remove_constant() from anywhere but import() and unimport() methods.
1032 From these methods they may be called as
1037 die "unknown import: @_" unless @_ == 1 and $_[0] eq ':constant';
1038 overload::constant integer => sub {Math::BigInt->new(shift)};
1041 =head1 IMPLEMENTATION
1043 What follows is subject to change RSN.
1045 The table of methods for all operations is cached in magic for the
1046 symbol table hash for the package. The cache is invalidated during
1047 processing of C<use overload>, C<no overload>, new function
1048 definitions, and changes in @ISA.
1050 (Every SVish thing has a magic queue, and magic is an entry in that
1051 queue. This is how a single variable may participate in multiple
1052 forms of magic simultaneously. For instance, environment variables
1053 regularly have two forms at once: their %ENV magic and their taint
1054 magic. However, the magic which implements overloading is applied to
1055 the stashes, which are rarely used directly, thus should not slow down
1058 If a package uses overload, it carries a special flag. This flag is also
1059 set when new function are defined or @ISA is modified. There will be a
1060 slight speed penalty on the very first operation thereafter that supports
1061 overloading, while the overload tables are updated. If there is no
1062 overloading present, the flag is turned off. Thus the only speed penalty
1063 thereafter is the checking of this flag.
1065 It is expected that arguments to methods that are not explicitly supposed
1066 to be changed are constant (but this is not enforced).
1070 Please add examples to what follows!
1072 =head2 Two-face Scalars
1074 Put this in F<two_face.pm> in your Perl library directory:
1076 package two_face; # Scalars with separate string and
1078 sub new { my $p = shift; bless [@_], $p }
1079 use overload '""' => \&str, '0+' => \&num, fallback => 1;
1080 sub num {shift->[1]}
1081 sub str {shift->[0]}
1086 my $seven = two_face->new("vii", 7);
1087 printf "seven=$seven, seven=%d, eight=%d\n", $seven, $seven+1;
1088 print "seven contains 'i'\n" if $seven =~ /i/;
1090 (The second line creates a scalar which has both a string value, and a
1091 numeric value.) This prints:
1093 seven=vii, seven=7, eight=8
1096 =head2 Two-face References
1098 Suppose you want to create an object which is accessible as both an
1099 array reference and a hash reference.
1102 use overload '%{}' => \&gethash, '@{}' => sub { $ {shift()} };
1110 tie %h, ref $self, $self;
1114 sub TIEHASH { my $p = shift; bless \ shift, $p }
1117 $fields{$_} = $i++ foreach qw{zero one two three};
1119 my $self = ${shift()};
1120 my $key = $fields{shift()};
1121 defined $key or die "Out of band access";
1122 $$self->[$key] = shift;
1125 my $self = ${shift()};
1126 my $key = $fields{shift()};
1127 defined $key or die "Out of band access";
1131 Now one can access an object using both the array and hash syntax:
1133 my $bar = two_refs->new(3,4,5,6);
1135 $bar->{two} == 11 or die 'bad hash fetch';
1137 Note several important features of this example. First of all, the
1138 I<actual> type of $bar is a scalar reference, and we do not overload
1139 the scalar dereference. Thus we can get the I<actual> non-overloaded
1140 contents of $bar by just using C<$$bar> (what we do in functions which
1141 overload dereference). Similarly, the object returned by the
1142 TIEHASH() method is a scalar reference.
1144 Second, we create a new tied hash each time the hash syntax is used.
1145 This allows us not to worry about a possibility of a reference loop,
1146 which would lead to a memory leak.
1148 Both these problems can be cured. Say, if we want to overload hash
1149 dereference on a reference to an object which is I<implemented> as a
1150 hash itself, the only problem one has to circumvent is how to access
1151 this I<actual> hash (as opposed to the I<virtual> hash exhibited by the
1152 overloaded dereference operator). Here is one possible fetching routine:
1155 my ($self, $key) = (shift, shift);
1156 my $class = ref $self;
1157 bless $self, 'overload::dummy'; # Disable overloading of %{}
1158 my $out = $self->{$key};
1159 bless $self, $class; # Restore overloading
1163 To remove creation of the tied hash on each access, one may an extra
1164 level of indirection which allows a non-circular structure of references:
1167 use overload '%{}' => sub { ${shift()}->[1] },
1168 '@{}' => sub { ${shift()}->[0] };
1174 bless \ [$a, \%h], $p;
1179 tie %h, ref $self, $self;
1183 sub TIEHASH { my $p = shift; bless \ shift, $p }
1186 $fields{$_} = $i++ foreach qw{zero one two three};
1189 my $key = $fields{shift()};
1190 defined $key or die "Out of band access";
1195 my $key = $fields{shift()};
1196 defined $key or die "Out of band access";
1200 Now if $baz is overloaded like this, then C<$baz> is a reference to a
1201 reference to the intermediate array, which keeps a reference to an
1202 actual array, and the access hash. The tie()ing object for the access
1203 hash is a reference to a reference to the actual array, so
1209 There are no loops of references.
1213 Both "objects" which are blessed into the class C<two_refs1> are
1214 references to a reference to an array, thus references to a I<scalar>.
1215 Thus the accessor expression C<$$foo-E<gt>[$ind]> involves no
1216 overloaded operations.
1220 =head2 Symbolic Calculator
1222 Put this in F<symbolic.pm> in your Perl library directory:
1224 package symbolic; # Primitive symbolic calculator
1225 use overload nomethod => \&wrap;
1227 sub new { shift; bless ['n', @_] }
1229 my ($obj, $other, $inv, $meth) = @_;
1230 ($obj, $other) = ($other, $obj) if $inv;
1231 bless [$meth, $obj, $other];
1234 This module is very unusual as overloaded modules go: it does not
1235 provide any usual overloaded operators, instead it provides an
1236 implementation for L<C<nomethod>>. In this example the C<nomethod>
1237 subroutine returns an object which encapsulates operations done over
1238 the objects: C<< symbolic->new(3) >> contains C<['n', 3]>, C<< 2 +
1239 symbolic->new(3) >> contains C<['+', 2, ['n', 3]]>.
1241 Here is an example of the script which "calculates" the side of
1242 circumscribed octagon using the above package:
1245 my $iter = 1; # 2**($iter+2) = 8
1246 my $side = symbolic->new(1);
1250 $side = (sqrt(1 + $side**2) - 1)/$side;
1254 The value of $side is
1256 ['/', ['-', ['sqrt', ['+', 1, ['**', ['n', 1], 2]],
1257 undef], 1], ['n', 1]]
1259 Note that while we obtained this value using a nice little script,
1260 there is no simple way to I<use> this value. In fact this value may
1261 be inspected in debugger (see L<perldebug>), but only if
1262 C<bareStringify> B<O>ption is set, and not via C<p> command.
1264 If one attempts to print this value, then the overloaded operator
1265 C<""> will be called, which will call C<nomethod> operator. The
1266 result of this operator will be stringified again, but this result is
1267 again of type C<symbolic>, which will lead to an infinite loop.
1269 Add a pretty-printer method to the module F<symbolic.pm>:
1272 my ($meth, $a, $b) = @{+shift};
1273 $a = 'u' unless defined $a;
1274 $b = 'u' unless defined $b;
1275 $a = $a->pretty if ref $a;
1276 $b = $b->pretty if ref $b;
1280 Now one can finish the script by
1282 print "side = ", $side->pretty, "\n";
1284 The method C<pretty> is doing object-to-string conversion, so it
1285 is natural to overload the operator C<""> using this method. However,
1286 inside such a method it is not necessary to pretty-print the
1287 I<components> $a and $b of an object. In the above subroutine
1288 C<"[$meth $a $b]"> is a catenation of some strings and components $a
1289 and $b. If these components use overloading, the catenation operator
1290 will look for an overloaded operator C<.>; if not present, it will
1291 look for an overloaded operator C<"">. Thus it is enough to use
1293 use overload nomethod => \&wrap, '""' => \&str;
1295 my ($meth, $a, $b) = @{+shift};
1296 $a = 'u' unless defined $a;
1297 $b = 'u' unless defined $b;
1301 Now one can change the last line of the script to
1303 print "side = $side\n";
1307 side = [/ [- [sqrt [+ 1 [** [n 1 u] 2]] u] 1] [n 1 u]]
1309 and one can inspect the value in debugger using all the possible
1312 Something is still amiss: consider the loop variable $cnt of the
1313 script. It was a number, not an object. We cannot make this value of
1314 type C<symbolic>, since then the loop will not terminate.
1316 Indeed, to terminate the cycle, the $cnt should become false.
1317 However, the operator C<bool> for checking falsity is overloaded (this
1318 time via overloaded C<"">), and returns a long string, thus any object
1319 of type C<symbolic> is true. To overcome this, we need a way to
1320 compare an object to 0. In fact, it is easier to write a numeric
1323 Here is the text of F<symbolic.pm> with such a routine added (and
1324 slightly modified str()):
1326 package symbolic; # Primitive symbolic calculator
1328 nomethod => \&wrap, '""' => \&str, '0+' => \#
1330 sub new { shift; bless ['n', @_] }
1332 my ($obj, $other, $inv, $meth) = @_;
1333 ($obj, $other) = ($other, $obj) if $inv;
1334 bless [$meth, $obj, $other];
1337 my ($meth, $a, $b) = @{+shift};
1338 $a = 'u' unless defined $a;
1345 my %subr = ( n => sub {$_[0]},
1346 sqrt => sub {sqrt $_[0]},
1347 '-' => sub {shift() - shift()},
1348 '+' => sub {shift() + shift()},
1349 '/' => sub {shift() / shift()},
1350 '*' => sub {shift() * shift()},
1351 '**' => sub {shift() ** shift()},
1354 my ($meth, $a, $b) = @{+shift};
1355 my $subr = $subr{$meth}
1356 or die "Do not know how to ($meth) in symbolic";
1357 $a = $a->num if ref $a eq __PACKAGE__;
1358 $b = $b->num if ref $b eq __PACKAGE__;
1362 All the work of numeric conversion is done in %subr and num(). Of
1363 course, %subr is not complete, it contains only operators used in the
1364 example below. Here is the extra-credit question: why do we need an
1365 explicit recursion in num()? (Answer is at the end of this section.)
1367 Use this module like this:
1370 my $iter = symbolic->new(2); # 16-gon
1371 my $side = symbolic->new(1);
1375 $cnt = $cnt - 1; # Mutator '--' not implemented
1376 $side = (sqrt(1 + $side**2) - 1)/$side;
1378 printf "%s=%f\n", $side, $side;
1379 printf "pi=%f\n", $side*(2**($iter+2));
1381 It prints (without so many line breaks)
1383 [/ [- [sqrt [+ 1 [** [/ [- [sqrt [+ 1 [** [n 1] 2]]] 1]
1385 [/ [- [sqrt [+ 1 [** [n 1] 2]]] 1] [n 1]]]=0.198912
1388 The above module is very primitive. It does not implement
1389 mutator methods (C<++>, C<-=> and so on), does not do deep copying
1390 (not required without mutators!), and implements only those arithmetic
1391 operations which are used in the example.
1393 To implement most arithmetic operations is easy; one should just use
1394 the tables of operations, and change the code which fills %subr to
1396 my %subr = ( 'n' => sub {$_[0]} );
1397 foreach my $op (split " ", $overload::ops{with_assign}) {
1398 $subr{$op} = $subr{"$op="} = eval "sub {shift() $op shift()}";
1400 my @bins = qw(binary 3way_comparison num_comparison str_comparison);
1401 foreach my $op (split " ", "@overload::ops{ @bins }") {
1402 $subr{$op} = eval "sub {shift() $op shift()}";
1404 foreach my $op (split " ", "@overload::ops{qw(unary func)}") {
1405 print "defining '$op'\n";
1406 $subr{$op} = eval "sub {$op shift()}";
1409 Since subroutines implementing assignment operators are not required
1410 to modify their operands (see L<Overloadable Operations> above),
1411 we do not need anything special to make C<+=> and friends work,
1412 besides adding these operators to %subr and defining a copy
1413 constructor (needed since Perl has no way to know that the
1414 implementation of C<'+='> does not mutate the argument -
1415 see L<Copy Constructor>).
1417 To implement a copy constructor, add C<< '=' => \&cpy >> to C<use overload>
1418 line, and code (this code assumes that mutators change things one level
1419 deep only, so recursive copying is not needed):
1423 bless [@$self], ref $self;
1426 To make C<++> and C<--> work, we need to implement actual mutators,
1427 either directly, or in C<nomethod>. We continue to do things inside
1428 C<nomethod>, thus add
1430 if ($meth eq '++' or $meth eq '--') {
1431 @$obj = ($meth, (bless [@$obj]), 1); # Avoid circular reference
1435 after the first line of wrap(). This is not a most effective
1436 implementation, one may consider
1438 sub inc { $_[0] = bless ['++', shift, 1]; }
1442 As a final remark, note that one can fill %subr by
1444 my %subr = ( 'n' => sub {$_[0]} );
1445 foreach my $op (split " ", $overload::ops{with_assign}) {
1446 $subr{$op} = $subr{"$op="} = eval "sub {shift() $op shift()}";
1448 my @bins = qw(binary 3way_comparison num_comparison str_comparison);
1449 foreach my $op (split " ", "@overload::ops{ @bins }") {
1450 $subr{$op} = eval "sub {shift() $op shift()}";
1452 foreach my $op (split " ", "@overload::ops{qw(unary func)}") {
1453 $subr{$op} = eval "sub {$op shift()}";
1455 $subr{'++'} = $subr{'+'};
1456 $subr{'--'} = $subr{'-'};
1458 This finishes implementation of a primitive symbolic calculator in
1459 50 lines of Perl code. Since the numeric values of subexpressions
1460 are not cached, the calculator is very slow.
1462 Here is the answer for the exercise: In the case of str(), we need no
1463 explicit recursion since the overloaded C<.>-operator will fall back
1464 to an existing overloaded operator C<"">. Overloaded arithmetic
1465 operators I<do not> fall back to numeric conversion if C<fallback> is
1466 not explicitly requested. Thus without an explicit recursion num()
1467 would convert C<['+', $a, $b]> to C<$a + $b>, which would just rebuild
1468 the argument of num().
1470 If you wonder why defaults for conversion are different for str() and
1471 num(), note how easy it was to write the symbolic calculator. This
1472 simplicity is due to an appropriate choice of defaults. One extra
1473 note: due to the explicit recursion num() is more fragile than sym():
1474 we need to explicitly check for the type of $a and $b. If components
1475 $a and $b happen to be of some related type, this may lead to problems.
1477 =head2 I<Really> Symbolic Calculator
1479 One may wonder why we call the above calculator symbolic. The reason
1480 is that the actual calculation of the value of expression is postponed
1481 until the value is I<used>.
1483 To see it in action, add a method
1488 @$obj->[0,1] = ('=', shift);
1491 to the package C<symbolic>. After this change one can do
1493 my $a = symbolic->new(3);
1494 my $b = symbolic->new(4);
1495 my $c = sqrt($a**2 + $b**2);
1497 and the numeric value of $c becomes 5. However, after calling
1499 $a->STORE(12); $b->STORE(5);
1501 the numeric value of $c becomes 13. There is no doubt now that the module
1502 symbolic provides a I<symbolic> calculator indeed.
1504 To hide the rough edges under the hood, provide a tie()d interface to the
1505 package C<symbolic>. Add methods
1507 sub TIESCALAR { my $pack = shift; $pack->new(@_) }
1509 sub nop { } # Around a bug
1511 (the bug, fixed in Perl 5.14, is described in L<"BUGS">). One can use this
1514 tie $a, 'symbolic', 3;
1515 tie $b, 'symbolic', 4;
1516 $a->nop; $b->nop; # Around a bug
1518 my $c = sqrt($a**2 + $b**2);
1520 Now numeric value of $c is 5. After C<$a = 12; $b = 5> the numeric value
1521 of $c becomes 13. To insulate the user of the module add a method
1523 sub vars { my $p = shift; tie($_, $p), $_->nop foreach @_; }
1528 symbolic->vars($a, $b);
1529 my $c = sqrt($a**2 + $b**2);
1532 printf "c5 %s=%f\n", $c, $c;
1535 printf "c13 %s=%f\n", $c, $c;
1537 shows that the numeric value of $c follows changes to the values of $a
1542 Ilya Zakharevich E<lt>F<ilya@math.mps.ohio-state.edu>E<gt>.
1546 The C<overloading> pragma can be used to enable or disable overloaded
1547 operations within a lexical scope - see L<overloading>.
1551 When Perl is run with the B<-Do> switch or its equivalent, overloading
1552 induces diagnostic messages.
1554 Using the C<m> command of Perl debugger (see L<perldebug>) one can
1555 deduce which operations are overloaded (and which ancestor triggers
1556 this overloading). Say, if C<eq> is overloaded, then the method C<(eq>
1557 is shown by debugger. The method C<()> corresponds to the C<fallback>
1558 key (in fact a presence of this method shows that this package has
1559 overloading enabled, and it is what is used by the C<Overloaded>
1560 function of module C<overload>).
1562 The module might issue the following warnings:
1566 =item Odd number of arguments for overload::constant
1568 (W) The call to overload::constant contained an odd number of arguments.
1569 The arguments should come in pairs.
1571 =item '%s' is not an overloadable type
1573 (W) You tried to overload a constant type the overload package is unaware of.
1575 =item '%s' is not a code reference
1577 (W) The second (fourth, sixth, ...) argument of overload::constant needs
1578 to be a code reference. Either an anonymous subroutine, or a reference
1581 =item overload arg '%s' is invalid
1583 (W) C<use overload> was passed an argument it did not
1584 recognize. Did you mistype an operator?
1588 =head1 BUGS AND PITFALLS
1594 A pitfall when fallback is TRUE and Perl resorts to a built-in
1595 implementation of an operator is that some operators have more
1596 than one semantic, for example C<|>:
1598 use overload '0+' => sub { $_[0]->{n}; },
1600 my $x = bless { n => 4 }, "main";
1601 my $y = bless { n => 8 }, "main";
1602 print $x | $y, "\n";
1604 You might expect this to output "12".
1605 In fact, it prints "<": the ASCII result of treating "|"
1606 as a bitwise string operator - that is, the result of treating
1607 the operands as the strings "4" and "8" rather than numbers.
1608 The fact that numify (C<0+>) is implemented but stringify
1609 (C<"">) isn't makes no difference since the latter is simply
1610 autogenerated from the former.
1612 The only way to change this is to provide your own subroutine
1617 Magic autogeneration increases the potential for inadvertently
1618 creating self-referential structures.
1619 Currently Perl will not free self-referential
1620 structures until cycles are explicitly broken.
1623 use overload '+' => 'add';
1624 sub add { bless [ \$_[0], \$_[1] ] };
1626 is asking for trouble, since
1630 will effectively become
1632 $obj = add($obj, $y, undef);
1634 with the same result as
1636 $obj = [\$obj, \$foo];
1638 Even if no I<explicit> assignment-variants of operators are present in
1639 the script, they may be generated by the optimizer.
1646 my $tmp = 'obj = ' . $obj; $tmp .= "\n";
1650 The symbol table is filled with names looking like line-noise.
1654 This bug was fixed in Perl 5.18, but may still trip you up if you are using
1657 For the purpose of inheritance every overloaded package behaves as if
1658 C<fallback> is present (possibly undefined). This may create
1659 interesting effects if some package is not overloaded, but inherits
1660 from two overloaded packages.
1664 Before Perl 5.14, the relation between overloading and tie()ing was broken.
1665 Overloading was triggered or not based on the I<previous> class of the
1668 This happened because the presence of overloading was checked
1669 too early, before any tie()d access was attempted. If the
1670 class of the value FETCH()ed from the tied variable does not
1671 change, a simple workaround for code that is to run on older Perl
1672 versions is to access the value (via C<() = $foo> or some such)
1673 immediately after tie()ing, so that after this call the I<previous> class
1674 coincides with the current one.
1678 Barewords are not covered by overloaded string constants.