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 => '& &= | |= ^ ^= &. &.= |. |.= ^. ^.=',
12 unary => "neg ! ~ ~.",
14 func => "atan2 cos sin exp abs log sqrt int",
15 conversion => 'bool "" 0+ qr',
18 dereferencing => '${} @{} %{} &{} *{}',
20 special => 'nomethod fallback =',
24 @ops_seen{ map split(/ /), values %ops } = ();
32 *{$package . "::(("} = \&nil; # Make it findable via fetchmethod.
34 if ($_ eq 'fallback') {
35 for my $sym (*{$package . "::()"}) {
36 *$sym = \&nil; # Make it findable via fetchmethod.
40 warnings::warnif("overload arg '$_' is invalid")
41 unless exists $ops_seen{$_};
44 $ {$package . "::(" . $_} = $sub;
47 #print STDERR "Setting '$ {'package'}::\cO$_' to \\&'$sub'.\n";
48 *{$package . "::(" . $_} = \&{ $sub };
54 $package = (caller())[0];
55 # *{$package . "::OVERLOAD"} = \&OVERLOAD;
57 $package->overload::OVERLOAD(@_);
61 $package = (caller())[0];
63 *{$package . "::(("} = \&nil;
65 warnings::warnif("overload arg '$_' is invalid")
66 unless exists $ops_seen{$_};
67 delete $ {$package . "::"}{$_ eq 'fallback' ? '()' : "(" .$_};
73 $package = ref $package if ref $package;
74 mycan ($package, '()') || mycan ($package, '((');
79 return undef unless $globref;
80 my $sub = \&{*$globref};
82 return $sub if $sub != \&nil;
83 return shift->can($ {*$globref});
86 sub OverloadedStringify {
88 $package = ref $package if ref $package;
90 ov_method mycan($package, '(""'), $package
91 or ov_method mycan($package, '(0+'), $package
92 or ov_method mycan($package, '(bool'), $package
93 or ov_method mycan($package, '(nomethod'), $package;
101 require Scalar::Util;
102 $package = Scalar::Util::blessed($package);
103 return undef if !defined $package;
105 #my $meth = $package->can('(' . shift);
106 ov_method mycan($package, '(' . shift), $package;
107 #return $meth if $meth ne \&nil;
108 #return $ {*{$meth}};
118 sub mycan { # Real can would leave stubs.
119 my ($package, $meth) = @_;
125 my $mro = mro::get_linear_isa($package);
126 foreach my $p (@$mro) {
127 my $fqmeth = $p . q{::} . $meth;
128 return \*{$fqmeth} if defined &{$fqmeth};
135 'integer' => 0x1000, # HINT_NEW_INTEGER
136 'float' => 0x2000, # HINT_NEW_FLOAT
137 'binary' => 0x4000, # HINT_NEW_BINARY
138 'q' => 0x8000, # HINT_NEW_STRING
139 'qr' => 0x10000, # HINT_NEW_RE
142 use warnings::register;
144 # Arguments: what, sub
147 warnings::warnif ("Odd number of arguments for overload::constant");
150 elsif (!exists $constants {$_ [0]}) {
151 warnings::warnif ("'$_[0]' is not an overloadable type");
153 elsif (!ref $_ [1] || "$_[1]" !~ /(^|=)CODE\(0x[0-9a-f]+\)$/) {
154 # Can't use C<ref $_[1] eq "CODE"> above as code references can be
155 # blessed, and C<ref> would return the package the ref is blessed into.
156 if (warnings::enabled) {
157 $_ [1] = "undef" unless defined $_ [1];
158 warnings::warn ("'$_[1]' is not a code reference");
163 $^H |= $constants{$_[0]};
169 sub remove_constant {
170 # Arguments: what, sub
173 $^H &= ~ $constants{$_[0]};
184 overload - Package for overloading Perl operations
197 $a = SomeThing->new( 57 );
200 if (overload::Overloaded $b) {...}
202 $strval = overload::StrVal $b;
206 This pragma allows overloading of Perl's operators for a class.
207 To overload built-in functions, see L<perlsub/Overriding Built-in Functions> instead.
213 Arguments of the C<use overload> directive are (key, value) pairs.
214 For the full set of legal keys, see L</Overloadable Operations> below.
216 Operator implementations (the values) can be subroutines,
217 references to subroutines, or anonymous subroutines
218 - in other words, anything legal inside a C<&{ ... }> call.
219 Values specified as strings are interpreted as method names.
226 '""' => sub { ...; };
228 declares that subtraction is to be implemented by method C<minus()>
229 in the class C<Number> (or one of its base classes),
230 and that the function C<Number::muas()> is to be used for the
231 assignment form of multiplication, C<*=>.
232 It also defines an anonymous subroutine to implement stringification:
233 this is called whenever an object blessed into the package C<Number>
234 is used in a string context (this subroutine might, for example,
235 return the number as a Roman numeral).
237 =head3 Calling Conventions and Magic Autogeneration
239 The following sample implementation of C<minus()> (which assumes
240 that C<Number> objects are simply blessed references to scalars)
241 illustrates the calling conventions:
245 my ($self, $other, $swap) = @_;
246 my $result = $$self - $other; # *
247 $result = -$result if $swap;
248 ref $result ? $result : bless \$result;
250 # * may recurse once - see table below
252 Three arguments are passed to all subroutines specified in the
253 C<use overload> directive (with exceptions - see below, particularly
256 The first of these is the operand providing the overloaded
257 operator implementation -
258 in this case, the object whose C<minus()> method is being called.
260 The second argument is the other operand, or C<undef> in the
261 case of a unary operator.
263 The third argument is set to TRUE if (and only if) the two
264 operands have been swapped. Perl may do this to ensure that the
265 first argument (C<$self>) is an object implementing the overloaded
266 operation, in line with general object calling conventions.
267 For example, if C<$x> and C<$y> are C<Number>s:
269 operation | generates a call to
270 ============|======================
271 $x - $y | minus($x, $y, '')
272 $x - 7 | minus($x, 7, '')
273 7 - $x | minus($x, 7, 1)
275 Perl may also use C<minus()> to implement other operators which
276 have not been specified in the C<use overload> directive,
277 according to the rules for L</Magic Autogeneration> described later.
278 For example, the C<use overload> above declared no subroutine
279 for any of the operators C<-->, C<neg> (the overload key for
280 unary minus), or C<-=>. Thus
282 operation | generates a call to
283 ============|======================
284 -$x | minus($x, 0, 1)
285 $x-- | minus($x, 1, undef)
286 $x -= 3 | minus($x, 3, undef)
289 where autogeneration results in the method for a standard
290 operator which does not change either of its operands, such
291 as C<->, being used to implement an operator which changes
292 the operand ("mutators": here, C<--> and C<-=>),
293 Perl passes undef as the third argument.
294 This still evaluates as FALSE, consistent with the fact that
295 the operands have not been swapped, but gives the subroutine
296 a chance to alter its behaviour in these cases.
298 In all the above examples, C<minus()> is required
299 only to return the result of the subtraction:
300 Perl takes care of the assignment to $x.
301 In fact, such methods should I<not> modify their operands,
302 even if C<undef> is passed as the third argument
303 (see L</Overloadable Operations>).
305 The same is not true of implementations of C<++> and C<-->:
306 these are expected to modify their operand.
307 An appropriate implementation of C<--> might look like
309 use overload '--' => "decr",
311 sub decr { --${$_[0]}; }
313 If the "bitwise" feature is enabled (see L<feature>), a fifth
314 TRUE argument is passed to subroutines handling C<&>, C<|>, C<^> and C<~>.
315 This indicates that the caller is expecting numeric behaviour. The fourth
316 argument will be C<undef>, as that position (C<$_[3]>) is reserved for use
319 =head3 Mathemagic, Mutators, and Copy Constructors
321 The term 'mathemagic' describes the overloaded implementation
322 of mathematical operators.
323 Mathemagical operations raise an issue.
329 If C<$a> and C<$b> are scalars then after these statements
333 An object, however, is a reference to blessed data, so if
334 C<$a> and C<$b> are objects then the assignment C<$a = $b>
335 copies only the reference, leaving C<$a> and C<$b> referring
336 to the same object data.
337 One might therefore expect the operation C<--$a> to decrement
338 C<$b> as well as C<$a>.
339 However, this would not be consistent with how we expect the
340 mathematical operators to work.
342 Perl resolves this dilemma by transparently calling a copy
343 constructor before calling a method defined to implement
344 a mutator (C<-->, C<+=>, and so on.).
345 In the above example, when Perl reaches the decrement
346 statement, it makes a copy of the object data in C<$a> and
347 assigns to C<$a> a reference to the copied data.
348 Only then does it call C<decr()>, which alters the copied
349 data, leaving C<$b> unchanged.
350 Thus the object metaphor is preserved as far as possible,
351 while mathemagical operations still work according to the
354 Note: the preceding paragraph describes what happens when
355 Perl autogenerates the copy constructor for an object based
357 For other cases, see L</Copy Constructor>.
359 =head2 Overloadable Operations
361 The complete list of keys that can be specified in the C<use overload>
362 directive are given, separated by spaces, in the values of the
363 hash C<%overload::ops>:
365 with_assign => '+ - * / % ** << >> x .',
366 assign => '+= -= *= /= %= **= <<= >>= x= .=',
367 num_comparison => '< <= > >= == !=',
368 '3way_comparison'=> '<=> cmp',
369 str_comparison => 'lt le gt ge eq ne',
370 binary => '& &= | |= ^ ^= &. &.= |. |.= ^. ^.=',
371 unary => 'neg ! ~ ~.',
373 func => 'atan2 cos sin exp abs log sqrt int',
374 conversion => 'bool "" 0+ qr',
377 dereferencing => '${} @{} %{} &{} *{}',
379 special => 'nomethod fallback ='
381 Most of the overloadable operators map one-to-one to these keys.
382 Exceptions, including additional overloadable operations not
383 apparent from this hash, are included in the notes which follow.
384 This list is subject to growth over time.
386 A warning is issued if an attempt is made to register an operator not found
393 The operator C<not> is not a valid key for C<use overload>.
394 However, if the operator C<!> is overloaded then the same
395 implementation will be used for C<not>
396 (since the two operators differ only in precedence).
400 The key C<neg> is used for unary minus to disambiguate it from
405 Assuming they are to behave analogously to Perl's C<++> and C<-->,
406 overloaded implementations of these operators are required to
407 mutate their operands.
409 No distinction is made between prefix and postfix forms of the
410 increment and decrement operators: these differ only in the
411 point at which Perl calls the associated subroutine when
412 evaluating an expression.
414 =item * I<Assignments>
416 += -= *= /= %= **= <<= >>= x= .=
419 Simple assignment is not overloadable (the C<'='> key is used
420 for the L</Copy Constructor>).
421 Perl does have a way to make assignments to an object do whatever
422 you want, but this involves using tie(), not overload -
423 see L<perlfunc/tie> and the L</COOKBOOK> examples below.
425 The subroutine for the assignment variant of an operator is
426 required only to return the result of the operation.
427 It is permitted to change the value of its operand
428 (this is safe because Perl calls the copy constructor first),
429 but this is optional since Perl assigns the returned value to
430 the left-hand operand anyway.
432 An object that overloads an assignment operator does so only in
433 respect of assignments to that object.
434 In other words, Perl never calls the corresponding methods with
435 the third argument (the "swap" argument) set to TRUE.
436 For example, the operation
440 cannot lead to C<$b>'s implementation of C<*=> being called,
441 even if C<$a> is a scalar.
442 (It can, however, generate a call to C<$b>'s method for C<*>).
444 =item * I<Non-mutators with a mutator variant>
446 + - * / % ** << >> x .
449 As described L<above|"Calling Conventions and Magic Autogeneration">,
450 Perl may call methods for operators like C<+> and C<&> in the course
451 of implementing missing operations like C<++>, C<+=>, and C<&=>.
452 While these methods may detect this usage by testing the definedness
453 of the third argument, they should in all cases avoid changing their
455 This is because Perl does not call the copy constructor before
456 invoking these methods.
460 Traditionally, the Perl function C<int> rounds to 0
461 (see L<perlfunc/int>), and so for floating-point-like types one
462 should follow the same semantic.
464 =item * I<String, numeric, boolean, and regexp conversions>
468 These conversions are invoked according to context as necessary.
469 For example, the subroutine for C<'""'> (stringify) may be used
470 where the overloaded object is passed as an argument to C<print>,
471 and that for C<'bool'> where it is tested in the condition of a flow
472 control statement (like C<while>) or the ternary C<?:> operation.
474 Of course, in contexts like, for example, C<$obj + 1>, Perl will
475 invoke C<$obj>'s implementation of C<+> rather than (in this
476 example) converting C<$obj> to a number using the numify method
477 C<'0+'> (an exception to this is when no method has been provided
478 for C<'+'> and L</fallback> is set to TRUE).
480 The subroutines for C<'""'>, C<'0+'>, and C<'bool'> can return
481 any arbitrary Perl value.
482 If the corresponding operation for this value is overloaded too,
483 the operation will be called again with this value.
485 As a special case if the overload returns the object itself then it will
486 be used directly. An overloaded conversion returning the object is
487 probably a bug, because you're likely to get something that looks like
488 C<YourPackage=HASH(0x8172b34)>.
492 The subroutine for C<'qr'> is used wherever the object is
493 interpolated into or used as a regexp, including when it
494 appears on the RHS of a C<=~> or C<!~> operator.
496 C<qr> must return a compiled regexp, or a ref to a compiled regexp
497 (such as C<qr//> returns), and any further overloading on the return
498 value will be ignored.
502 If C<E<lt>E<gt>> is overloaded then the same implementation is used
503 for both the I<read-filehandle> syntax C<E<lt>$varE<gt>> and
504 I<globbing> syntax C<E<lt>${var}E<gt>>.
506 =item * I<File tests>
508 The key C<'-X'> is used to specify a subroutine to handle all the
509 filetest operators (C<-f>, C<-x>, and so on: see L<perlfunc/-X> for
511 it is not possible to overload any filetest operator individually.
512 To distinguish them, the letter following the '-' is passed as the
513 second argument (that is, in the slot that for binary operators
514 is used to pass the second operand).
516 Calling an overloaded filetest operator does not affect the stat value
517 associated with the special filehandle C<_>. It still refers to the
518 result of the last C<stat>, C<lstat> or unoverloaded filetest.
520 This overload was introduced in Perl 5.12.
524 The key C<"~~"> allows you to override the smart matching logic used by
525 the C<~~> operator and the switch construct (C<given>/C<when>). See
526 L<perlsyn/Switch Statements> and L<feature>.
528 Unusually, the overloaded implementation of the smart match operator
529 does not get full control of the smart match behaviour.
530 In particular, in the following code:
533 use overload '~~' => 'match';
535 my $obj = Foo->new();
538 the smart match does I<not> invoke the method call like this:
540 $obj->match([1,2,3],0);
542 rather, the smart match distributive rule takes precedence, so $obj is
543 smart matched against each array element in turn until a match is found,
544 so you may see between one and three of these calls instead:
550 Consult the match table in L<perlop/"Smartmatch Operator"> for
551 details of when overloading is invoked.
553 =item * I<Dereferencing>
557 If these operators are not explicitly overloaded then they
558 work in the normal way, yielding the underlying scalar,
559 array, or whatever stores the object data (or the appropriate
560 error message if the dereference operator doesn't match it).
561 Defining a catch-all C<'nomethod'> (see L<below|/nomethod>)
562 makes no difference to this as the catch-all function will
563 not be called to implement a missing dereference operator.
565 If a dereference operator is overloaded then it must return a
566 I<reference> of the appropriate type (for example, the
567 subroutine for key C<'${}'> should return a reference to a
568 scalar, not a scalar), or another object which overloads the
569 operator: that is, the subroutine only determines what is
570 dereferenced and the actual dereferencing is left to Perl.
571 As a special case, if the subroutine returns the object itself
572 then it will not be called again - avoiding infinite recursion.
578 See L</Special Keys for C<use overload>>.
582 =head2 Magic Autogeneration
584 If a method for an operation is not found then Perl tries to
585 autogenerate a substitute implementation from the operations
586 that have been defined.
588 Note: the behaviour described in this section can be disabled
589 by setting C<fallback> to FALSE (see L</fallback>).
591 In the following tables, numbers indicate priority.
592 For example, the table below states that,
593 if no implementation for C<'!'> has been defined then Perl will
594 implement it using C<'bool'> (that is, by inverting the value
595 returned by the method for C<'bool'>);
596 if boolean conversion is also unimplemented then Perl will
597 use C<'0+'> or, failing that, C<'""'>.
599 operator | can be autogenerated from
602 =========|==========================
616 Note: The iterator (C<'E<lt>E<gt>'>) and file test (C<'-X'>)
617 operators work as normal: if the operand is not a blessed glob or
618 IO reference then it is converted to a string (using the method
619 for C<'""'>, C<'0+'>, or C<'bool'>) to be interpreted as a glob
622 operator | can be autogenerated from
625 =========|==========================
629 abs | a1 a2 b1 b2 [*]
637 * one from [a1, a2] and one from [b1, b2]
639 Just as numeric comparisons can be autogenerated from the method
640 for C<< '<=>' >>, string comparisons can be autogenerated from
643 operators | can be autogenerated from
644 ====================|===========================
645 lt gt le ge eq ne | cmp
647 Similarly, autogeneration for keys C<'+='> and C<'++'> is analogous
648 to C<'-='> and C<'--'> above:
650 operator | can be autogenerated from
653 =========|==========================
657 And other assignment variations are analogous to
658 C<'+='> and C<'-='> (and similar to C<'.='> and C<'x='> above):
660 operator || *= /= %= **= <<= >>= &= ^= |= &.= ^.= |.=
661 -------------------||-------------------------------------------
662 autogenerated from || * / % ** << >> & ^ | &. ^. |.
664 Note also that the copy constructor (key C<'='>) may be
665 autogenerated, but only for objects based on scalars.
666 See L</Copy Constructor>.
668 =head3 Minimal Set of Overloaded Operations
670 Since some operations can be automatically generated from others, there is
671 a minimal set of operations that need to be overloaded in order to have
672 the complete set of overloaded operations at one's disposal.
673 Of course, the autogenerated operations may not do exactly what the user
674 expects. The minimal set is:
679 atan2 cos sin exp log sqrt int
683 Of the conversions, only one of string, boolean or numeric is
684 needed because each can be generated from either of the other two.
686 =head2 Special Keys for C<use overload>
690 The C<'nomethod'> key is used to specify a catch-all function to
691 be called for any operator that is not individually overloaded.
692 The specified function will be passed four parameters.
693 The first three arguments coincide with those that would have been
694 passed to the corresponding method if it had been defined.
695 The fourth argument is the C<use overload> key for that missing
696 method. If the "bitwise" feature is enabled (see L<feature>),
697 a fifth TRUE argument is passed to subroutines handling C<&>, C<|>, C<^> and C<~> to indicate that the caller is expecting numeric behaviour.
699 For example, if C<$a> is an object blessed into a package declaring
701 use overload 'nomethod' => 'catch_all', # ...
707 could (unless a method is specifically declared for the key
708 C<'+'>) result in a call
710 catch_all($a, 3, 1, '+')
712 See L</How Perl Chooses an Operator Implementation>.
716 The value assigned to the key C<'fallback'> tells Perl how hard
717 it should try to find an alternative way to implement a missing
722 =item * defined, but FALSE
724 use overload "fallback" => 0, # ... ;
726 This disables L</Magic Autogeneration>.
730 In the default case where no value is explicitly assigned to
731 C<fallback>, magic autogeneration is enabled.
735 The same as for C<undef>, but if a missing operator cannot be
736 autogenerated then, instead of issuing an error message, Perl
737 is allowed to revert to what it would have done for that
738 operator if there had been no C<use overload> directive.
740 Note: in most cases, particularly the L</Copy Constructor>,
741 this is unlikely to be appropriate behaviour.
745 See L</How Perl Chooses an Operator Implementation>.
747 =head3 Copy Constructor
749 As mentioned L<above|"Mathemagic, Mutators, and Copy Constructors">,
750 this operation is called when a mutator is applied to a reference
751 that shares its object with some other reference.
752 For example, if C<$b> is mathemagical, and C<'++'> is overloaded
753 with C<'incr'>, and C<'='> is overloaded with C<'clone'>, then the
757 # ... (other code which does not modify $a or $b) ...
760 would be executed in a manner equivalent to
764 $b = $b->clone(undef, "");
773 The subroutine for C<'='> does not overload the Perl assignment
774 operator: it is used only to allow mutators to work as described
775 here. (See L</Assignments> above.)
779 As for other operations, the subroutine implementing '=' is passed
780 three arguments, though the last two are always C<undef> and C<''>.
784 The copy constructor is called only before a call to a function
785 declared to implement a mutator, for example, if C<++$b;> in the
786 code above is effected via a method declared for key C<'++'>
787 (or 'nomethod', passed C<'++'> as the fourth argument) or, by
788 autogeneration, C<'+='>.
789 It is not called if the increment operation is effected by a call
790 to the method for C<'+'> since, in the equivalent code,
795 the data referred to by C<$a> is unchanged by the assignment to
796 C<$b> of a reference to new object data.
800 The copy constructor is not called if Perl determines that it is
801 unnecessary because there is no other reference to the data being
806 If C<'fallback'> is undefined or TRUE then a copy constructor
807 can be autogenerated, but only for objects based on scalars.
808 In other cases it needs to be defined explicitly.
809 Where an object's data is stored as, for example, an array of
810 scalars, the following might be appropriate:
812 use overload '=' => sub { bless [ @{$_[0]} ] }, # ...
816 If C<'fallback'> is TRUE and no copy constructor is defined then,
817 for objects not based on scalars, Perl may silently fall back on
818 simple assignment - that is, assignment of the object reference.
819 In effect, this disables the copy constructor mechanism since
820 no new copy of the object data is created.
821 This is almost certainly not what you want.
822 (It is, however, consistent: for example, Perl's fallback for the
823 C<++> operator is to increment the reference itself.)
827 =head2 How Perl Chooses an Operator Implementation
829 Which is checked first, C<nomethod> or C<fallback>?
830 If the two operands of an operator are of different types and
831 both overload the operator, which implementation is used?
832 The following are the precedence rules:
838 If the first operand has declared a subroutine to overload the
839 operator then use that implementation.
843 Otherwise, if fallback is TRUE or undefined for the
844 first operand then see if the
845 L<rules for autogeneration|"Magic Autogeneration">
846 allows another of its operators to be used instead.
850 Unless the operator is an assignment (C<+=>, C<-=>, etc.),
851 repeat step (1) in respect of the second operand.
855 Repeat Step (2) in respect of the second operand.
859 If the first operand has a "nomethod" method then use that.
863 If the second operand has a "nomethod" method then use that.
867 If C<fallback> is TRUE for both operands
868 then perform the usual operation for the operator,
869 treating the operands as numbers, strings, or booleans
870 as appropriate for the operator (see note).
874 Nothing worked - die.
878 Where there is only one operand (or only one operand with
879 overloading) the checks in respect of the other operand above are
882 There are exceptions to the above rules for dereference operations
883 (which, if Step 1 fails, always fall back to the normal, built-in
884 implementations - see Dereferencing), and for C<~~> (which has its
885 own set of rules - see C<Matching> under L</Overloadable Operations>
888 Note on Step 7: some operators have a different semantic depending
889 on the type of their operands.
890 As there is no way to instruct Perl to treat the operands as, e.g.,
891 numbers instead of strings, the result here may not be what you
893 See L</BUGS AND PITFALLS>.
895 =head2 Losing Overloading
897 The restriction for the comparison operation is that even if, for example,
898 C<cmp> should return a blessed reference, the autogenerated C<lt>
899 function will produce only a standard logical value based on the
900 numerical value of the result of C<cmp>. In particular, a working
901 numeric conversion is needed in this case (possibly expressed in terms of
904 Similarly, C<.=> and C<x=> operators lose their mathemagical properties
905 if the string conversion substitution is applied.
907 When you chop() a mathemagical object it is promoted to a string and its
908 mathemagical properties are lost. The same can happen with other
911 =head2 Inheritance and Overloading
913 Overloading respects inheritance via the @ISA hierarchy.
914 Inheritance interacts with overloading in two ways.
918 =item Method names in the C<use overload> directive
922 use overload key => value;
924 is a string, it is interpreted as a method name - which may
925 (in the usual way) be inherited from another class.
927 =item Overloading of an operation is inherited by derived classes
929 Any class derived from an overloaded class is also overloaded
930 and inherits its operator implementations.
931 If the same operator is overloaded in more than one ancestor
932 then the implementation is determined by the usual inheritance
935 For example, if C<A> inherits from C<B> and C<C> (in that order),
936 C<B> overloads C<+> with C<\&D::plus_sub>, and C<C> overloads
937 C<+> by C<"plus_meth">, then the subroutine C<D::plus_sub> will
938 be called to implement operation C<+> for an object in package C<A>.
942 Note that in Perl version prior to 5.18 inheritance of the C<fallback> key
943 was not governed by the above rules. The value of C<fallback> in the first
944 overloaded ancestor was used. This was fixed in 5.18 to follow the usual
945 rules of inheritance.
947 =head2 Run-time Overloading
949 Since all C<use> directives are executed at compile-time, the only way to
950 change overloading during run-time is to
952 eval 'use overload "+" => \&addmethod';
956 eval 'no overload "+", "--", "<="';
958 though the use of these constructs during run-time is questionable.
960 =head2 Public Functions
962 Package C<overload.pm> provides the following public functions:
966 =item overload::StrVal(arg)
968 Gives the string value of C<arg> as in the
969 absence of stringify overloading. If you
970 are using this to get the address of a reference (useful for checking if two
971 references point to the same thing) then you may be better off using
972 C<Scalar::Util::refaddr()>, which is faster.
974 =item overload::Overloaded(arg)
976 Returns true if C<arg> is subject to overloading of some operations.
978 =item overload::Method(obj,op)
980 Returns C<undef> or a reference to the method that implements C<op>.
984 =head2 Overloading Constants
986 For some applications, the Perl parser mangles constants too much.
987 It is possible to hook into this process via C<overload::constant()>
988 and C<overload::remove_constant()> functions.
990 These functions take a hash as an argument. The recognized keys of this hash
997 to overload integer constants,
1001 to overload floating point constants,
1005 to overload octal and hexadecimal constants,
1009 to overload C<q>-quoted strings, constant pieces of C<qq>- and C<qx>-quoted
1010 strings and here-documents,
1014 to overload constant pieces of regular expressions.
1018 The corresponding values are references to functions which take three arguments:
1019 the first one is the I<initial> string form of the constant, the second one
1020 is how Perl interprets this constant, the third one is how the constant is used.
1021 Note that the initial string form does not
1022 contain string delimiters, and has backslashes in backslash-delimiter
1023 combinations stripped (thus the value of delimiter is not relevant for
1024 processing of this string). The return value of this function is how this
1025 constant is going to be interpreted by Perl. The third argument is undefined
1026 unless for overloaded C<q>- and C<qr>- constants, it is C<q> in single-quote
1027 context (comes from strings, regular expressions, and single-quote HERE
1028 documents), it is C<tr> for arguments of C<tr>/C<y> operators,
1029 it is C<s> for right-hand side of C<s>-operator, and it is C<qq> otherwise.
1031 Since an expression C<"ab$cd,,"> is just a shortcut for C<'ab' . $cd . ',,'>,
1032 it is expected that overloaded constant strings are equipped with reasonable
1033 overloaded catenation operator, otherwise absurd results will result.
1034 Similarly, negative numbers are considered as negations of positive constants.
1036 Note that it is probably meaningless to call the functions overload::constant()
1037 and overload::remove_constant() from anywhere but import() and unimport() methods.
1038 From these methods they may be called as
1043 die "unknown import: @_" unless @_ == 1 and $_[0] eq ':constant';
1044 overload::constant integer => sub {Math::BigInt->new(shift)};
1047 =head1 IMPLEMENTATION
1049 What follows is subject to change RSN.
1051 The table of methods for all operations is cached in magic for the
1052 symbol table hash for the package. The cache is invalidated during
1053 processing of C<use overload>, C<no overload>, new function
1054 definitions, and changes in @ISA.
1056 (Every SVish thing has a magic queue, and magic is an entry in that
1057 queue. This is how a single variable may participate in multiple
1058 forms of magic simultaneously. For instance, environment variables
1059 regularly have two forms at once: their %ENV magic and their taint
1060 magic. However, the magic which implements overloading is applied to
1061 the stashes, which are rarely used directly, thus should not slow down
1064 If a package uses overload, it carries a special flag. This flag is also
1065 set when new functions are defined or @ISA is modified. There will be a
1066 slight speed penalty on the very first operation thereafter that supports
1067 overloading, while the overload tables are updated. If there is no
1068 overloading present, the flag is turned off. Thus the only speed penalty
1069 thereafter is the checking of this flag.
1071 It is expected that arguments to methods that are not explicitly supposed
1072 to be changed are constant (but this is not enforced).
1076 Please add examples to what follows!
1078 =head2 Two-face Scalars
1080 Put this in F<two_face.pm> in your Perl library directory:
1082 package two_face; # Scalars with separate string and
1084 sub new { my $p = shift; bless [@_], $p }
1085 use overload '""' => \&str, '0+' => \&num, fallback => 1;
1086 sub num {shift->[1]}
1087 sub str {shift->[0]}
1092 my $seven = two_face->new("vii", 7);
1093 printf "seven=$seven, seven=%d, eight=%d\n", $seven, $seven+1;
1094 print "seven contains 'i'\n" if $seven =~ /i/;
1096 (The second line creates a scalar which has both a string value, and a
1097 numeric value.) This prints:
1099 seven=vii, seven=7, eight=8
1102 =head2 Two-face References
1104 Suppose you want to create an object which is accessible as both an
1105 array reference and a hash reference.
1108 use overload '%{}' => \&gethash, '@{}' => sub { $ {shift()} };
1116 tie %h, ref $self, $self;
1120 sub TIEHASH { my $p = shift; bless \ shift, $p }
1123 $fields{$_} = $i++ foreach qw{zero one two three};
1125 my $self = ${shift()};
1126 my $key = $fields{shift()};
1127 defined $key or die "Out of band access";
1128 $$self->[$key] = shift;
1131 my $self = ${shift()};
1132 my $key = $fields{shift()};
1133 defined $key or die "Out of band access";
1137 Now one can access an object using both the array and hash syntax:
1139 my $bar = two_refs->new(3,4,5,6);
1141 $bar->{two} == 11 or die 'bad hash fetch';
1143 Note several important features of this example. First of all, the
1144 I<actual> type of $bar is a scalar reference, and we do not overload
1145 the scalar dereference. Thus we can get the I<actual> non-overloaded
1146 contents of $bar by just using C<$$bar> (what we do in functions which
1147 overload dereference). Similarly, the object returned by the
1148 TIEHASH() method is a scalar reference.
1150 Second, we create a new tied hash each time the hash syntax is used.
1151 This allows us not to worry about a possibility of a reference loop,
1152 which would lead to a memory leak.
1154 Both these problems can be cured. Say, if we want to overload hash
1155 dereference on a reference to an object which is I<implemented> as a
1156 hash itself, the only problem one has to circumvent is how to access
1157 this I<actual> hash (as opposed to the I<virtual> hash exhibited by the
1158 overloaded dereference operator). Here is one possible fetching routine:
1161 my ($self, $key) = (shift, shift);
1162 my $class = ref $self;
1163 bless $self, 'overload::dummy'; # Disable overloading of %{}
1164 my $out = $self->{$key};
1165 bless $self, $class; # Restore overloading
1169 To remove creation of the tied hash on each access, one may an extra
1170 level of indirection which allows a non-circular structure of references:
1173 use overload '%{}' => sub { ${shift()}->[1] },
1174 '@{}' => sub { ${shift()}->[0] };
1180 bless \ [$a, \%h], $p;
1185 tie %h, ref $self, $self;
1189 sub TIEHASH { my $p = shift; bless \ shift, $p }
1192 $fields{$_} = $i++ foreach qw{zero one two three};
1195 my $key = $fields{shift()};
1196 defined $key or die "Out of band access";
1201 my $key = $fields{shift()};
1202 defined $key or die "Out of band access";
1206 Now if $baz is overloaded like this, then C<$baz> is a reference to a
1207 reference to the intermediate array, which keeps a reference to an
1208 actual array, and the access hash. The tie()ing object for the access
1209 hash is a reference to a reference to the actual array, so
1215 There are no loops of references.
1219 Both "objects" which are blessed into the class C<two_refs1> are
1220 references to a reference to an array, thus references to a I<scalar>.
1221 Thus the accessor expression C<$$foo-E<gt>[$ind]> involves no
1222 overloaded operations.
1226 =head2 Symbolic Calculator
1228 Put this in F<symbolic.pm> in your Perl library directory:
1230 package symbolic; # Primitive symbolic calculator
1231 use overload nomethod => \&wrap;
1233 sub new { shift; bless ['n', @_] }
1235 my ($obj, $other, $inv, $meth) = @_;
1236 ($obj, $other) = ($other, $obj) if $inv;
1237 bless [$meth, $obj, $other];
1240 This module is very unusual as overloaded modules go: it does not
1241 provide any usual overloaded operators, instead it provides an
1242 implementation for L</C<nomethod>>. In this example the C<nomethod>
1243 subroutine returns an object which encapsulates operations done over
1244 the objects: C<< symbolic->new(3) >> contains C<['n', 3]>, C<< 2 +
1245 symbolic->new(3) >> contains C<['+', 2, ['n', 3]]>.
1247 Here is an example of the script which "calculates" the side of
1248 circumscribed octagon using the above package:
1251 my $iter = 1; # 2**($iter+2) = 8
1252 my $side = symbolic->new(1);
1256 $side = (sqrt(1 + $side**2) - 1)/$side;
1260 The value of $side is
1262 ['/', ['-', ['sqrt', ['+', 1, ['**', ['n', 1], 2]],
1263 undef], 1], ['n', 1]]
1265 Note that while we obtained this value using a nice little script,
1266 there is no simple way to I<use> this value. In fact this value may
1267 be inspected in debugger (see L<perldebug>), but only if
1268 C<bareStringify> B<O>ption is set, and not via C<p> command.
1270 If one attempts to print this value, then the overloaded operator
1271 C<""> will be called, which will call C<nomethod> operator. The
1272 result of this operator will be stringified again, but this result is
1273 again of type C<symbolic>, which will lead to an infinite loop.
1275 Add a pretty-printer method to the module F<symbolic.pm>:
1278 my ($meth, $a, $b) = @{+shift};
1279 $a = 'u' unless defined $a;
1280 $b = 'u' unless defined $b;
1281 $a = $a->pretty if ref $a;
1282 $b = $b->pretty if ref $b;
1286 Now one can finish the script by
1288 print "side = ", $side->pretty, "\n";
1290 The method C<pretty> is doing object-to-string conversion, so it
1291 is natural to overload the operator C<""> using this method. However,
1292 inside such a method it is not necessary to pretty-print the
1293 I<components> $a and $b of an object. In the above subroutine
1294 C<"[$meth $a $b]"> is a catenation of some strings and components $a
1295 and $b. If these components use overloading, the catenation operator
1296 will look for an overloaded operator C<.>; if not present, it will
1297 look for an overloaded operator C<"">. Thus it is enough to use
1299 use overload nomethod => \&wrap, '""' => \&str;
1301 my ($meth, $a, $b) = @{+shift};
1302 $a = 'u' unless defined $a;
1303 $b = 'u' unless defined $b;
1307 Now one can change the last line of the script to
1309 print "side = $side\n";
1313 side = [/ [- [sqrt [+ 1 [** [n 1 u] 2]] u] 1] [n 1 u]]
1315 and one can inspect the value in debugger using all the possible
1318 Something is still amiss: consider the loop variable $cnt of the
1319 script. It was a number, not an object. We cannot make this value of
1320 type C<symbolic>, since then the loop will not terminate.
1322 Indeed, to terminate the cycle, the $cnt should become false.
1323 However, the operator C<bool> for checking falsity is overloaded (this
1324 time via overloaded C<"">), and returns a long string, thus any object
1325 of type C<symbolic> is true. To overcome this, we need a way to
1326 compare an object to 0. In fact, it is easier to write a numeric
1329 Here is the text of F<symbolic.pm> with such a routine added (and
1330 slightly modified str()):
1332 package symbolic; # Primitive symbolic calculator
1334 nomethod => \&wrap, '""' => \&str, '0+' => \#
1336 sub new { shift; bless ['n', @_] }
1338 my ($obj, $other, $inv, $meth) = @_;
1339 ($obj, $other) = ($other, $obj) if $inv;
1340 bless [$meth, $obj, $other];
1343 my ($meth, $a, $b) = @{+shift};
1344 $a = 'u' unless defined $a;
1351 my %subr = ( n => sub {$_[0]},
1352 sqrt => sub {sqrt $_[0]},
1353 '-' => sub {shift() - shift()},
1354 '+' => sub {shift() + shift()},
1355 '/' => sub {shift() / shift()},
1356 '*' => sub {shift() * shift()},
1357 '**' => sub {shift() ** shift()},
1360 my ($meth, $a, $b) = @{+shift};
1361 my $subr = $subr{$meth}
1362 or die "Do not know how to ($meth) in symbolic";
1363 $a = $a->num if ref $a eq __PACKAGE__;
1364 $b = $b->num if ref $b eq __PACKAGE__;
1368 All the work of numeric conversion is done in %subr and num(). Of
1369 course, %subr is not complete, it contains only operators used in the
1370 example below. Here is the extra-credit question: why do we need an
1371 explicit recursion in num()? (Answer is at the end of this section.)
1373 Use this module like this:
1376 my $iter = symbolic->new(2); # 16-gon
1377 my $side = symbolic->new(1);
1381 $cnt = $cnt - 1; # Mutator '--' not implemented
1382 $side = (sqrt(1 + $side**2) - 1)/$side;
1384 printf "%s=%f\n", $side, $side;
1385 printf "pi=%f\n", $side*(2**($iter+2));
1387 It prints (without so many line breaks)
1389 [/ [- [sqrt [+ 1 [** [/ [- [sqrt [+ 1 [** [n 1] 2]]] 1]
1391 [/ [- [sqrt [+ 1 [** [n 1] 2]]] 1] [n 1]]]=0.198912
1394 The above module is very primitive. It does not implement
1395 mutator methods (C<++>, C<-=> and so on), does not do deep copying
1396 (not required without mutators!), and implements only those arithmetic
1397 operations which are used in the example.
1399 To implement most arithmetic operations is easy; one should just use
1400 the tables of operations, and change the code which fills %subr to
1402 my %subr = ( 'n' => sub {$_[0]} );
1403 foreach my $op (split " ", $overload::ops{with_assign}) {
1404 $subr{$op} = $subr{"$op="} = eval "sub {shift() $op shift()}";
1406 my @bins = qw(binary 3way_comparison num_comparison str_comparison);
1407 foreach my $op (split " ", "@overload::ops{ @bins }") {
1408 $subr{$op} = eval "sub {shift() $op shift()}";
1410 foreach my $op (split " ", "@overload::ops{qw(unary func)}") {
1411 print "defining '$op'\n";
1412 $subr{$op} = eval "sub {$op shift()}";
1415 Since subroutines implementing assignment operators are not required
1416 to modify their operands (see L</Overloadable Operations> above),
1417 we do not need anything special to make C<+=> and friends work,
1418 besides adding these operators to %subr and defining a copy
1419 constructor (needed since Perl has no way to know that the
1420 implementation of C<'+='> does not mutate the argument -
1421 see L</Copy Constructor>).
1423 To implement a copy constructor, add C<< '=' => \&cpy >> to C<use overload>
1424 line, and code (this code assumes that mutators change things one level
1425 deep only, so recursive copying is not needed):
1429 bless [@$self], ref $self;
1432 To make C<++> and C<--> work, we need to implement actual mutators,
1433 either directly, or in C<nomethod>. We continue to do things inside
1434 C<nomethod>, thus add
1436 if ($meth eq '++' or $meth eq '--') {
1437 @$obj = ($meth, (bless [@$obj]), 1); # Avoid circular reference
1441 after the first line of wrap(). This is not a most effective
1442 implementation, one may consider
1444 sub inc { $_[0] = bless ['++', shift, 1]; }
1448 As a final remark, note that one can fill %subr by
1450 my %subr = ( 'n' => sub {$_[0]} );
1451 foreach my $op (split " ", $overload::ops{with_assign}) {
1452 $subr{$op} = $subr{"$op="} = eval "sub {shift() $op shift()}";
1454 my @bins = qw(binary 3way_comparison num_comparison str_comparison);
1455 foreach my $op (split " ", "@overload::ops{ @bins }") {
1456 $subr{$op} = eval "sub {shift() $op shift()}";
1458 foreach my $op (split " ", "@overload::ops{qw(unary func)}") {
1459 $subr{$op} = eval "sub {$op shift()}";
1461 $subr{'++'} = $subr{'+'};
1462 $subr{'--'} = $subr{'-'};
1464 This finishes implementation of a primitive symbolic calculator in
1465 50 lines of Perl code. Since the numeric values of subexpressions
1466 are not cached, the calculator is very slow.
1468 Here is the answer for the exercise: In the case of str(), we need no
1469 explicit recursion since the overloaded C<.>-operator will fall back
1470 to an existing overloaded operator C<"">. Overloaded arithmetic
1471 operators I<do not> fall back to numeric conversion if C<fallback> is
1472 not explicitly requested. Thus without an explicit recursion num()
1473 would convert C<['+', $a, $b]> to C<$a + $b>, which would just rebuild
1474 the argument of num().
1476 If you wonder why defaults for conversion are different for str() and
1477 num(), note how easy it was to write the symbolic calculator. This
1478 simplicity is due to an appropriate choice of defaults. One extra
1479 note: due to the explicit recursion num() is more fragile than sym():
1480 we need to explicitly check for the type of $a and $b. If components
1481 $a and $b happen to be of some related type, this may lead to problems.
1483 =head2 I<Really> Symbolic Calculator
1485 One may wonder why we call the above calculator symbolic. The reason
1486 is that the actual calculation of the value of expression is postponed
1487 until the value is I<used>.
1489 To see it in action, add a method
1494 @$obj->[0,1] = ('=', shift);
1497 to the package C<symbolic>. After this change one can do
1499 my $a = symbolic->new(3);
1500 my $b = symbolic->new(4);
1501 my $c = sqrt($a**2 + $b**2);
1503 and the numeric value of $c becomes 5. However, after calling
1505 $a->STORE(12); $b->STORE(5);
1507 the numeric value of $c becomes 13. There is no doubt now that the module
1508 symbolic provides a I<symbolic> calculator indeed.
1510 To hide the rough edges under the hood, provide a tie()d interface to the
1511 package C<symbolic>. Add methods
1513 sub TIESCALAR { my $pack = shift; $pack->new(@_) }
1515 sub nop { } # Around a bug
1517 (the bug, fixed in Perl 5.14, is described in L<"BUGS">). One can use this
1520 tie $a, 'symbolic', 3;
1521 tie $b, 'symbolic', 4;
1522 $a->nop; $b->nop; # Around a bug
1524 my $c = sqrt($a**2 + $b**2);
1526 Now numeric value of $c is 5. After C<$a = 12; $b = 5> the numeric value
1527 of $c becomes 13. To insulate the user of the module add a method
1529 sub vars { my $p = shift; tie($_, $p), $_->nop foreach @_; }
1534 symbolic->vars($a, $b);
1535 my $c = sqrt($a**2 + $b**2);
1538 printf "c5 %s=%f\n", $c, $c;
1541 printf "c13 %s=%f\n", $c, $c;
1543 shows that the numeric value of $c follows changes to the values of $a
1548 Ilya Zakharevich E<lt>F<ilya@math.mps.ohio-state.edu>E<gt>.
1552 The C<overloading> pragma can be used to enable or disable overloaded
1553 operations within a lexical scope - see L<overloading>.
1557 When Perl is run with the B<-Do> switch or its equivalent, overloading
1558 induces diagnostic messages.
1560 Using the C<m> command of Perl debugger (see L<perldebug>) one can
1561 deduce which operations are overloaded (and which ancestor triggers
1562 this overloading). Say, if C<eq> is overloaded, then the method C<(eq>
1563 is shown by debugger. The method C<()> corresponds to the C<fallback>
1564 key (in fact a presence of this method shows that this package has
1565 overloading enabled, and it is what is used by the C<Overloaded>
1566 function of module C<overload>).
1568 The module might issue the following warnings:
1572 =item Odd number of arguments for overload::constant
1574 (W) The call to overload::constant contained an odd number of arguments.
1575 The arguments should come in pairs.
1577 =item '%s' is not an overloadable type
1579 (W) You tried to overload a constant type the overload package is unaware of.
1581 =item '%s' is not a code reference
1583 (W) The second (fourth, sixth, ...) argument of overload::constant needs
1584 to be a code reference. Either an anonymous subroutine, or a reference
1587 =item overload arg '%s' is invalid
1589 (W) C<use overload> was passed an argument it did not
1590 recognize. Did you mistype an operator?
1594 =head1 BUGS AND PITFALLS
1600 A pitfall when fallback is TRUE and Perl resorts to a built-in
1601 implementation of an operator is that some operators have more
1602 than one semantic, for example C<|>:
1604 use overload '0+' => sub { $_[0]->{n}; },
1606 my $x = bless { n => 4 }, "main";
1607 my $y = bless { n => 8 }, "main";
1608 print $x | $y, "\n";
1610 You might expect this to output "12".
1611 In fact, it prints "<": the ASCII result of treating "|"
1612 as a bitwise string operator - that is, the result of treating
1613 the operands as the strings "4" and "8" rather than numbers.
1614 The fact that numify (C<0+>) is implemented but stringify
1615 (C<"">) isn't makes no difference since the latter is simply
1616 autogenerated from the former.
1618 The only way to change this is to provide your own subroutine
1623 Magic autogeneration increases the potential for inadvertently
1624 creating self-referential structures.
1625 Currently Perl will not free self-referential
1626 structures until cycles are explicitly broken.
1629 use overload '+' => 'add';
1630 sub add { bless [ \$_[0], \$_[1] ] };
1632 is asking for trouble, since
1636 will effectively become
1638 $obj = add($obj, $y, undef);
1640 with the same result as
1642 $obj = [\$obj, \$foo];
1644 Even if no I<explicit> assignment-variants of operators are present in
1645 the script, they may be generated by the optimizer.
1652 my $tmp = 'obj = ' . $obj; $tmp .= "\n";
1656 The symbol table is filled with names looking like line-noise.
1660 This bug was fixed in Perl 5.18, but may still trip you up if you are using
1663 For the purpose of inheritance every overloaded package behaves as if
1664 C<fallback> is present (possibly undefined). This may create
1665 interesting effects if some package is not overloaded, but inherits
1666 from two overloaded packages.
1670 Before Perl 5.14, the relation between overloading and tie()ing was broken.
1671 Overloading was triggered or not based on the I<previous> class of the
1674 This happened because the presence of overloading was checked
1675 too early, before any tie()d access was attempted. If the
1676 class of the value FETCH()ed from the tied variable does not
1677 change, a simple workaround for code that is to run on older Perl
1678 versions is to access the value (via C<() = $foo> or some such)
1679 immediately after tie()ing, so that after this call the I<previous> class
1680 coincides with the current one.
1684 Barewords are not covered by overloaded string constants.
1688 The range operator C<..> cannot be overloaded.