NAME

perlovl - perl overloading semantics

SYNOPSIS

        package SomeThing;

        %OVERLOAD = (
            '+' => \&myadd,
            '-' => \&mysub,
            # etc
        );

DESCRIPTION

CAVEAT SCRIPTOR Overloading of operators is a subject not to be taken lightly, and has such

{ package Number; %OVERLOAD=("+" => \&add, "*=" => "muas"); } declares function &Number::add for addition and assignment (+=) form of addition, and &Number::muas for assignment form of multiplication. The subroutine &add will be called if the first argument of addition is a reference to the package Number, or first argument is not an object from a package with defined magic addition, but the second is a reference to a Number. These functions are called with the third argument that specifies in which of the described above cases the function is called. If this argument is true, then this method was found for the second argument of addition/multiplication. However, in accordance with general principle, the first argument of the method should be an object of the package. Thus in this case function &add will be called with inverted order of the first two arguments. However, if the addition is commutative, we can ignore the third argument. As a special case the third argument is undef if &add is called in an assignment formula like `$a+=7;'. Writer of the package can use this knowledge to optimize the algorithm, but in general this is not necesary. 

            If $OVERLOAD{"+="} corresponds to a defined subroutine, this
    function will be called for the assignment form of addition instead of
    $OVERLOAD{"+"}. 

            The following keys of %OVERLOAD are recognized:

      "+","+=",  "-", "-=",  "*", "*=",  "/", "/=",  "%", "%=",  "**", "**=",
      "<<", "<<=",  ">>", ">>=", "x", "x=", ".", ".=",

      "<", "<=",  ">", ">=",  "==", "!=",  "<=>", "cmp",
      "lt", "le",  "gt", "ge",  "eq", "ne",

      "&", "^",  "|", "neg",  "!", "~",

      "++", "--",

      "atan2", "cos",  "sin", "exp", "abs",  "log", "sqrt",

      "bool",   "\"\"", "0+", "nomethod", "fallback", "=",
the first group corresponds to the above description, the second and third behave similarly, but has no assignment form. The forth and fifth groups are unary operators, they are called as binary operators with undef second argument. The increment and decrement functions do not know whether they are called in preincrement or in postincrement context. The key "neg" corresponds to unary minus The last group consists of three conversion functions (to boolean, string and number), of substitution failure report function of a special key "fallback" that specifies what to do if anything else fails and of a copy constructor. If $OVERLOAD{"fallback"} is undefined, then the described above algorithm of substitution works and some trivial conversions also work: 0) $a=+$b can use $OVERLOAD{"+"} method if $OVERLOAD{"+="} is not defined; 1) string, numeric and boolean conversion are similarly calculated in terms of one another if not all of them are defined; 2) ++$a operation can be expressed in terms of $a+=1 or $a+1, $a-- in terms of $a-=1 and $a-1; 3) abs($a) can be expressed in terms of $a<0 and unary minus or 0-$a. 4) unary minus can be expressed in terms of subtraction. 5) concatenation is expressed in terms of string conversion. 6) comparison operations can be expressed in terms of its "spaceship" counterpart: <, >, <=, >=, ==, != in terms of <=>; lt, gt, le, ge, eq, ne in terms of cmp. 7) copy operator can be expressed in terms of assignment of dereferenced value, if this value is scalar and not a reference.

The restriction for comparison operation is that even if, say, `cmp' returns a blessed reference, the generated `lt' function will generate only a standard logical value, based on the numerical value of the result of `cmp'. In particular, a working numeric conversion is needed (possibly expressed in terms of other conversions). Similarly, .= and x= operators switch off magicalness if the string conversion substitution is applied. 
            If a method is not found, but $OVERLOAD{"nomethod"} is
    a valid subroutine, it is called with the described above arguments
    and the forth argument that gives the key of %OVERLOAD that
    corresponds to the missing method (is several methods are tried, the
    last one is used). Say, 1-$a can be equivalent to
            &{ $Pack::OVERLOAD{"nomethod"} }($a,1,1,"-").
    If there is no $OVERLOAD{"nomethod"}, the program
    die's.

            If $OVERLOAD{"fallback"} is defined but false, no
    substitution at all is tried. In the case of failure
    $OVERLOAD{"nomethod"} is still called, if this failes, program dies.

            If $OVERLOAD{"fallback"} is true, the above substitutions are
    tried, including $OVERLOAD{"nomethod"}, but if this fails, the
    normal Perl evaluation supersedes (possibly with user-defined
    conversions from objects) without warnings.

            When sort is called without explicit method, it uses 'cmp'
    method for comparison of magical objects.

            When you chop a magical object, it becomes promoted to string
    first, and magicalness is lost. The same can happen with other
    operations as well (?).

            The '=' (copying) operation is special, since it should return
    not the blessed reference, but a freshly made copy of dereferenced
    copy. This operation is called in the situation like 
            $a=$b; $a++;
    to make change to $a and not to change $b. It is executed during $a++,
    (so before this $$a coincides with $$b),
    and only if ++ is expressed via  $OPERATOR{'++'} or $OPERATOR{'+='}
    (if it expressed via '+', i.e., as
            $a=$b; $a=$a+1;
    $$a and $$b do not appear as lvalues).
Implementation: ~~~~~~~~~~~~~~~

The table of methods for all the operations is cached as a magic for the symbol table hash for the package. It is rechecked for changes of %OVERLOAD and @ISA only during bless'ing, so actually if it is changed dynamically, you need an additional fake blessing to update the table. In fact if no %OVERLOAD is defined, there is no check at all the packages, so most programs should not suffer measurable performance penalties during bless'ing. If an object belongs to a package with %OVERLOAD, it carries a special flag. Thus the only speed penalty during arithmetic operations without overload is the check of this flag. There is no size penalty for data if there is no %OVERLOAD. The copying like $a=$b is shallow, however a deep copying is carried out before any operation that can imply an assignment to the object $b (or $a) refers to, like $b++. It is expected that the arguments to methods that are not explicitely supposed to be changed are constant (but this is not enforced).