About Us Documentation

Contact Site Map



Man Page for PERLOVL

     perlovl - perl overloading semantics

         package SomeThing;

         %OVERLOAD = (
             '+' => myadd,
             '-' => mysub,
             # etc

         package main;
         $a = new SomeThing 57;

     Overloading of operators is a subject not to be taken
     lightly.  Neither its precise implementation, syntax, nor
     semantics are 100% endorsed by Larry Wall.  So any of these
     may be changed at some point in the future.

     Declaration of overloaded functions

         package Number;
         %OVERLOAD = (
             "+" => add,
             "*=" => "muas"

     declares function Number::add() for addition, and method
     muas() in the "class" Number (or one of its base classes)
     for the assignment form *= of multiplication.  Legal values
     of this hash array are values legal inside &{ ... } call, so
     the name of a subroutine, a reference to a subroutine, or an
     anonymous subroutine will all work.

     The subroutine $OVERLOAD{"+"} will be called to execute
     $a+$b if $a is a reference to an object blessed into the
     package Number, or $a is not an object from a package with
     defined mathemagic addition, but $b is a reference to a
     Number.  It can be called also in other situations, like
     $a+=7, or $a++.  See the section on MAGIC AUTOGENERATION.
     (Mathemagical methods refer to methods triggered by an
     overloaded mathematical operator.)

     Calling Conventions for Binary Operations

     The functions in values %OVERLOAD are called with three (in
     one particular case with four, see the section on Last
     Resort) arguments.  If the corresponding operation is
     binary, then the first two arguments are the two arguments
     of the operation.  However, due to general object calling
     conventions, the first argument should be always an object
     in the package, so in the situation of 7+$a, the order of
     arguments is interchanged.  Most probably it does not matter
     for implementation of the addition method, but whether the
     arguments  are reversed is vital for the subtraction method.
     The subroutine can query this information by examining the
     third argument, which can take three different values:

     FALSE  the order of arguments is as in the current

     TRUE   the arguments are reversed.

     undef  the current operation is an assignment variant (as in
            $a+=7), but the usual function is called instead.
            This additional information can be used to generate
            some optimizations.

     Calling Conventions for Unary Operations

     Unary operation are considered binary operations with the
     second argument being undef.  Thus $OVERLOAD{"++"} is called
     with arguments ($a,undef,'') when $a++ is executed.

     Overloadable Operations

     The following keys of %OVERLOAD are recognized:

     + Arithmetic operations

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

          For these operations a substituted non-assignment
          variant can be called if the assignment variant is not
          available.  Methods for operations "+", "-", "+=", and
          "-=" can be called to automatically generate increment
          and decrement methods.  The operations "-" can be used
          to autogenerate missing methods for unary minus or abs.

     + Comparison operations

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

          If the corresponding "spaceship" variant is available,
          it can be used to substitute for the missing operation.
          During sorting arrays, cmp is used to compare values
          subject to %OVERLOAD.

     + Bit operations

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

          "neg" stands for unary minus.  If the method for neg is
          not specified, it can be autogenerated using on the
          method for subtraction.

     + Increment and decrement

              "++", "--",

          If undefined, addition and subtraction methods can be
          used instead.  These operations are called both in
          prefix and postfix form.

     + Transcendental functions

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

          If abs is unavailable, it can be autogenerated using
          methods for "<" or "<=>" combined with either unary
          minus or subtraction.

     + Boolean, string and numeric conversion

              "bool", "

          If one or two of these operations are unavailable, the
          remaining ones can be used instead.  bool is used in
          the flow control operators (like while) and for the
          ternary "?:" operation.  These functions can return any
          arbitrary Perl value.  If the corresponding operation
          for this value is overloaded too, that operation will
          be called again with this value.

     + Special

              "nomethod", "fallback", "=",

          see the section on SPECIAL KEYS OF %OVERLOAD.

     See the section on Fallback for an explanation of when a
     missing method can be autogenerated.

     Three keys are recognized by Perl that are not covered by
     the above description.

     Last Resort

     $OVERLOAD{"nomethod"} is a reference to a function of four
     parameters.  If defined, it is called when the overloading
     mechanism cannot find a method for some operation.  The
     first three arguments of this function coincide with
     arguments for the corresponding method if it were found, the
     fourth argument is the key of %OVERLOAD corresponding to the
     missing method.  If several methods are tried, the last one
     is used.  Say, 1-$a can be equivalent to

             &{ $Pack::OVERLOAD{"nomethod"} }($a,1,1,"-").

     If some operation cannot be resolved, and there is no
     $OVERLOAD{"nomethod"}, then an exception will be raised via
     die() -- unless $OVERLOAD{"fallback"} is true.


     $OVERLOAD{"fallback"} governs what to do if a method for a
     particular operation is not found.  Three different cases
     are possible depending on value of $OVERLOAD{"fallback"}:

     + undef         Perl tries to use a substituted method (see
                     the section on MAGIC AUTOGENERATION).  If
                     this fails, it then tries to calls
                     $OVERLOAD{"nomethod"}; if missing, an
                     exception will be raised.

     + TRUE          The same as for the undef value, but no
                     exception is raised.  Instead, it silently
                     reverts to what it would have done were
                     there no %OVERLOAD is present.

     + defined, but FALSE
                     No autogeneration is tried.  Perl tries to
                     call $OVERLOAD{"nomethod"}, and if this is
                     missing, raises an exception.

     Copy Constructor

     $OVERLOAD{"="} is a reference to a function with three
     arguments, i.e., it looks like a usual value of %OVERLOAD.
     What is special about this subroutine is that it should not
     return a blessed reference into a package (as most other
     methods are expected to), but rather a freshly made copy of
     its dereferenced argument (see the section on BUGS, though).
     This operation is called in the situations when a mutator is
     applied to a reference that shares its object with some
     other reference, such as


     To make this change to $a and not to change $b, a freshly
     made copy of $$a is made, and $a is assigned a reference to
     this object.  This operation is executed during $a++, (so
     before this $$a coincides with $$b), and only if ++ is
     expressed via  $OPERATOR{'++'} or $OPERATOR{'+='}.  Note
     that if this operation is expressed via '+', i.e., as


     then $$a and $$b do not appear as lvalues.

     If the copy constructor is required during execution of some
     mutator, but $OPERATOR{'='} is missing, it can be
     autogenerated as a string copy if an object of the package
     is a plain scalar.

     If a method for an operation is not found, and
     $OVERLOAD{"fallback"} is TRUE or undefined, Perl tries to to
     autogenerate a substitute method for the missing operation
     based on defined operations.  Autogenerated method
     substitutions are possible for the following operations:

     Assignment forms of arithmetic operations
                     $a=+$b can use the $OVERLOAD{"+"} method if
                     $OVERLOAD{"+="} is not defined.

     Conversion operations
                     String, numeric, and boolean conversion are
                     calculated in terms of one another if not
                     all of them are defined.

     Increment and decrement
                     The ++$a operation can be expressed in terms
                     of $a+=1 or $a+1, and $a-- in terms of $a-=1
                     and $a-1.

     abs($a)         can be expressed in terms of $a<0 and -$a
                     (or 0-$a).

     Unary minus     can be expressed in terms of subtraction.

     Concatenation   can be expressed in terms of string

     Comparison operations
                     can be expressed in terms of its "spaceship"
                     counterpart: either  or cmp:

                         <, >, <=, >=, ==, !=      in terms of
                         lt, gt, le, ge, eq, ne    in terms of

     Copy operator   can be expressed in terms of assignment to
                     the dereferenced value, if this value is
                     scalar but not a reference.

     The restriction for the comparison operation is that even
     if, for example, `cmp' should return a blessed reference,
     the autogenerated `lt' function will produce only a standard
     logical value based on the numerical value of the result of
     `cmp'.  In particular, a working numeric conversion is
     needed in this case (possibly expressed in terms of other

     Similarly, .=  and x= operators lose their mathemagical
     properties if the string conversion substitution is applied.

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

     The table of methods for all operations is cached as a magic
     for the symbol table hash of the package.  It is rechecked
     for changes of %OVERLOAD and @ISA only during blessing; so
     if it is changed dynamically, you'll need an additional fake
     blessing to update the table.

     (Every SVish thing has a magic queue, and a magic is an
     entry in that queue.  This is how a single variable may
     participate in multiple forms of magic simultaneously.  For
     instance, environment variables regularly have two forms at
     once: their %ENV magic and their taint magic.)

     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

     In fact, if no %OVERLOAD is ever accessed, there is almost
     no overhead for overloadable operations, so most programs
     should not suffer measurable performance penalties.
     Considerable effort was made minimize overhead when
     %OVERLOAD is accessed and the current operation is
     overloadable but the arguments in question do not belong to
     packages with %OVERLOAD.  When in doubt, test your speed
     with %OVERLOAD and without it.  So far there have been no
     reports of substantial speed degradation if Perl is compiled
     with optimization turned on.

     There is no size penalty for data if there is no  %OVERLOAD.

     The copying like $a=$b is shallow; however, a one-level-deep
     copying is carried out before any operation that can imply
     an assignment to the object $b (or $a) refers to, like $b++.
     You can override this behavior by defining your copy
     constructor (see the section on Copy Constructor).

     It is expected that arguments to methods that are not
     explicitly supposed to be changed are constant (but this is
     not enforced).

     Ilya Zakharevich <ilya@math.mps.ohio-state.edu>.

     When Perl is run with the -Do switch or its equivalent,
     overloading induces diagnostic messages.

     Because it's used for overloading, the per-package
     associative array %OVERLOAD now has a special meaning in

     Although the copy constructor is specially designed to make
     overloading operations with references to an array simpler,
     as it now works it's useless for this because a subroutine
     cannot return an array in the same way as it returns a
     scalar (from the point of view of Perl internals).  Expect a
     change of interface for the copy constructor.

     As shipped, %OVERLOAD is not inherited via the @ISA tree.  A
     patch for this is available from the author.

     This document is confusing.

To return to the Ready-to-Run Software Super ReadyPak Table of Contents please press here.


Email addresses listed on this site may  NOT be used for unsolicited commercial email.

Ready-to-Run Software, Inc Privacy Statement

Portions (c)Copyright, 1996-2005 by Ready-to-Run Software, Inc
(All rights reserved.)
212 Cedar Cove
Lansing, NY 14882
Phone: 607 533 UNIX (8649)
Fax: 607 533 4002