8.119 overload (Perl in a Nutshell)

8.119 overload

Lets you substitute class methods or your own subroutines for standard Perl operators. For example, the code:

package Number;
use overload
    "+"  => \add,
    "*=" => "muas";

declares function

add

for addition and method


muas

in the Number class (or one of its base classes) for the assignment form

*=

of multiplication.

Arguments to use overload are key/value pairs, where the key is the operation being overloaded, and the value is the function or method that is to be substituted. Legal values are values permitted inside a &{ ... } call, so a subroutine name, a subroutine reference, or an anonymous subroutine are all legal. Legal keys (overloadable operations) are:

Type	Operations
Arithmetic	`+ - * / % ** << >> x .` `+= -= = /= %= *= <<= >>= x= .=`
Comparison	`< <= > >= == != <=>` `lt le gt ge eq ne cmp`
Bit and unary	`% ^ \| neg ! ~`
Increment, decrement	`++ -`
Transcendental	`atan2 cos sin exp abs log sqrt`
Boolean, string, numeric conversion	`bool` `""` `0+`
Special	`nomethod fallback =`

The functions specified with the use overload directive are typically called with three arguments. If the corresponding operation is binary, then the first two arguments are the two arguments of the operation. However, the first argument should always be an object in the package, so in some cases, the order of the arguments will be interchanged before the method is called. The third argument provides information on the order and can have these values:

false (0 ): The order of arguments is as in the current operation.
true (1 ): The arguments are reversed.
undefined: The current operation is an assignment variant, but the usual function is called instead.

Unary operations are considered binary operations with the second argument undefined.

The special nomethod key should be followed by a reference to a function of four parameters and called when the overloading mechanism cannot find a method for some operation. The first three arguments are the arguments for the corresponding method if it were found; the fourth argument is the symbol corresponding to the missing method. If several methods are tried, the last one is used.

For example, 1-$a can be equivalent to:

&nomethodMethod($a, 1, 1, "-")

if the pair


"nomethod"

=>


"nomethodMethod"

was specified in the


use overload

directive.

The special fallback key governs what to do if a method for a particular operation is not found. There are three possible cases, depending on the value associated with the fallback key:

undefined: Tries to use a substituted method. If that fails, it tries to call the method specified for nomethod ; if that also fails, an exception is raised.
true: The same as undefined, but no exception is raised. Instead, Perl silently reverts to non-overloaded operation.
defined, but false: Tries to call the method specified for nomethod ; if that fails, an exception is raised.

The overload module provides the following public functions: