home *** CD-ROM | disk | FTP | other *** search
- <!-- $RCSfile$$Revision$$Date$ -->
- <!-- $Log$ -->
- <HTML>
- <TITLE> PERLOVL </TITLE>
- <h2>NAME </h2>
- perlovl - perl overloading semantics
- <p><h2>SYNOPSIS</h2>
- <pre>
- package SomeThing;
- </pre>
- <pre>
- %OVERLOAD = (
- '+' => \&myadd,
- '-' => \&mysub,
- # etc
- );
- ...
- </pre>
- <pre>
- package main;
- $a = new SomeThing 57;
- $b=5+$a;
- </pre>
- <h2>CAVEAT SCRIPTOR</h2>
- 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.
- <p><h2>DESCRIPTION</h2>
- <h3>Declaration of overloaded functions</h3>
- <pre>
- package Number;
- %OVERLOAD = (
- "+" => \&add,
- "*=" => "muas"
- );
- </pre>
- declares function Number::add() for addition, and method muas() in
- the "class" <B>Number</B> (or one of its base classes)
- for the assignment form <B>*=</B> of multiplication. Legal values of this
- hash array are values legal inside <B>&{ ... }</B> call, so the name of a
- subroutine, a reference to a subroutine, or an anonymous subroutine
- will all work.
- <p>The subroutine <B>$OVERLOAD{"+"}</B> will be called to execute <B>$a+$b</B> if $a
- is a reference to an object blessed into the package <B>Number</B>, or $a is
- not an object from a package with defined mathemagic addition, but $b is a
- reference to a <B>Number</B>. It can be called also in other situations, like
- <B>$a+=7</B>, or <B>$a++</B>. See MAGIC AUTOGENERATION. (Mathemagical
- methods refer to methods triggered by an overloaded mathematical
- operator.)
- <p><h3>Calling Conventions for Binary Operations</h3>
- The functions in <B>values %OVERLOAD</B> are called with three (in one
- particular case with four, see 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 <B>7+$a</B>, 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:
- <p>
- <dl>
- <dt><B>FALSE</B>
- <dd>
- the order of arguments is as in the current operation.
- <p></dd>
- <dt><B>TRUE</B>
- <dd>
- the arguments are reversed.
- <p></dd>
- <dt><B><A HREF="perlfunc.html#perlfunc_258">undef</A> </B>
- <dd>
- the current operation is an assignment variant (as in
- <B>$a+=7</B>), but the usual function is called instead. This additional
- information can be used to generate some optimizations.
- <p></dd>
-
- </dl>
-
- <h3>Calling Conventions for Unary Operations</h3>
- Unary operation are considered binary operations with the second
- argument being
- <A HREF="perlfunc.html#perlfunc_258">undef</A>
- . Thus <B>$OVERLOAD{"++"}</B> is called with
- arguments <B>($a,undef,'')</B> when $a++ is executed.
- <p><h3>Overloadable Operations</h3>
- The following keys of %OVERLOAD are recognized:
- <p>
- <dl>
-
- <dt><b><A NAME="perlcall_39">* <I>Arithmetic operations</I></A></b>
- <pre>
- "+", "+=", "-", "-=", "*", "*=", "/", "/=", "%", "%=",
- "**", "**=", "<<", "<<=", >>", >>=", "x", "x=", ".", ".=",
- </pre>
- <dd>
- For these operations a substituted non-assignment variant can be called if
- the assignment variant is not available. Methods for operations "<B>+</B>",
- "<B>-</B>", "<B>+=</B>", and "<B>-=</B>" can be called to automatically generate
- increment and decrement methods. The operations "<B>-</B>" can be used to
- autogenerate missing methods for unary minus or
- <A HREF="perlfunc.html#perlfunc_72">abs</A>
- .
- <p></dd>
- <dt><B>* <I>Comparison operations</I></B>
- <pre>
- "<", "<=", ">", ">=", "==", "!=", "<=>",
- "lt", "le", "gt", "ge", "eq", "ne", "cmp",
- </pre>
- <dd>
- If the corresponding "spaceship" variant is available, it can be
- used to substitute for the missing operation. During
- <A HREF="perlfunc.html#perlfunc_234">sort</A>
- ing
- arrays, <B>cmp</B> is used to compare values subject to %OVERLOAD.
- <p></dd>
- <dt><B>* <I>Bit operations</I></B>
- <pre>
- "&", "^", "|", "neg", "!", "~",
- </pre>
- <dd>
- "<B>neg</B>" stands for unary minus. If the method for <B>neg</B> is not
- specified, it can be autogenerated using on the method for subtraction.
- <p></dd>
- <dt><B>* <I>Increment and decrement</I></B>
- <pre>
- "++", "--",
- </pre>
- <dd>
- If undefined, addition and subtraction methods can be
- used instead. These operations are called both in prefix and
- postfix form.
- <p></dd>
- <dt><B>* <I>Transcendental functions</I></B>
- <pre>
- "atan2", "cos", "sin", "exp", "abs", "log", "sqrt",
- </pre>
- <dd>
- If
- <A HREF="perlfunc.html#perlfunc_72">abs</A>
- is unavailable, it can be autogenerated using methods
- for "<" or "<=>" combined with either unary minus or subtraction.
- <p></dd>
- <dt><B>* <I>Boolean, string and numeric conversion</I></B>
- <pre>
- "bool", "\"\"", "0+",
- </pre>
- <dd>
- If one or two of these operations are unavailable, the remaining ones can
- be used instead. <B>bool</B> is used in the flow control operators
- (like <B>while</B>) and for the ternary "<B>?:</B>" 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.
- <p></dd>
- <dt><B>* <I>Special</I></B>
- <pre>
- "nomethod", "fallback", "=",
- </pre>
- <dd>
- see SPECIAL KEYS OF %OVERLOAD.
- <p></dd>
-
- </dl>
-
- See "Fallback" for an explanation of when a missing method can be autogenerated.
- <p><h2>SPECIAL KEYS OF %OVERLOAD</h2>
- Three keys are recognized by Perl that are not covered by the above
- description.
- <p><h3>Last Resort</h3>
- <B>$OVERLOAD{"nomethod"}</B> 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, <B>1-$a</B>
- can be equivalent to
- <p><pre>
- &{ $Pack::OVERLOAD{"nomethod"} }($a,1,1,"-").
- </pre>
- If some operation cannot be resolved, and there is no
- <B>$OVERLOAD{"nomethod"}</B>, then an exception will be raised
- via die() -- unless <B>$OVERLOAD{"fallback"}</B> is true.
- <p><h3>Fallback </h3>
- <B>$OVERLOAD{"fallback"}</B> governs what to do if a method for a particular
- operation is not found. Three different cases are possible depending on
- value of <B>$OVERLOAD{"fallback"}</B>:
- <p>
- <dl>
- <dt><B>* <A HREF="perlfunc.html#perlfunc_258">undef</A> </B>
- <dd>
- Perl tries to use a
- substituted method (see MAGIC AUTOGENERATION). If this fails, it
- then tries to calls <B>$OVERLOAD{"nomethod"}</B>; if missing, an exception
- will be raised.
- <p></dd>
- <dt><B>* TRUE</B>
- <dd>
- The same as for the
- <A HREF="perlfunc.html#perlfunc_258">undef</A>
- value, but no exception is raised. Instead,
- it silently reverts to what it would have done were there no %OVERLOAD is
- present.
- <p></dd>
- <dt><B>* defined, but FALSE</B>
- <dd>
- No autogeneration is tried. Perl tries to call
- <B>$OVERLOAD{"nomethod"}</B>, and if this is missing, raises an exception.
- <p></dd>
-
- </dl>
-
- <h3>Copy Constructor</h3>
- <B>$OVERLOAD{"="}</B> 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 "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
- <p><pre>
- $a=$b;
- $a++;
- </pre>
- To make this change to $a and not to change $b, a freshly made copy of
- <B>$$a</B> is made, and $a is assigned a reference to this object. This
- operation is executed during <B>$a++</B>, (so before this <B>$$a</B> coincides
- with <B>$$b</B>), and only if <B>++</B> is expressed via <B>$OPERATOR{'++'}</B> or
- <B>$OPERATOR{'+='}</B>. Note that if this operation is expressed via '<B>+</B>',
- i.e., as
- <p><pre>
- $a=$b;
- $a=$a+1;
- </pre>
- then <B>$$a</B> and <B>$$b</B> do not appear as lvalues.
- <p>If the copy constructor is required during execution of some mutator, but
- <B>$OPERATOR{'='}</B> is missing, it can be autogenerated as a string
- copy if an object of
- the package is a plain scalar.
- <p><h2>MAGIC AUTOGENERATION</h2>
- If a method for an operation is not found, and <B>$OVERLOAD{"fallback"}</B> 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:
- <p>
- <dl>
- <dt><B><I>Assignment forms of arithmetic operations</I></B>
- <dd>
- <B>$a=+$b</B> can use the <B>$OVERLOAD{"+"}</B> method if <B>$OVERLOAD{"+="}</B>
- is not defined.
- <p></dd>
- <dt><B><I>Conversion operations</I> </B>
- <dd>
- String, numeric, and boolean conversion are calculated in terms of one
- another if not all of them are defined.
- <p></dd>
- <dt><B><I>Increment and decrement</I></B>
- <dd>
- The <B>++$a</B> operation can be expressed in terms of <B>$a+=1</B> or <B>$a+1</B>,
- and <B>$a--</B> in terms of <B>$a-=1</B> and <B>$a-1</B>.
- <p></dd>
- <dt><B><B>abs($a)</B></B>
- <dd>
- can be expressed in terms of <B>$a<0</B> and <B>-$a</B> (or <B>0-$a</B>).
- <p></dd>
- <dt><B><I>Unary minus</I></B>
- <dd>
- can be expressed in terms of subtraction.
- <p></dd>
- <dt><B><I>Concatenation</I></B>
- <dd>
- can be expressed in terms of string conversion.
- <p></dd>
- <dt><B><I>Comparison operations</I> </B>
- <dd>
- can be expressed in terms of its "spaceship" counterpart: either
- <B><=></B> or <B>cmp</B>:
-
- <, >, <=, >=, ==, != in terms of <=>
- lt, gt, le, ge, eq, ne in terms of cmp
- <p></dd>
- <dt><B><I>Copy operator</I></B>
- <dd>
- can be expressed in terms of assignment to the dereferenced value, if this
- value is scalar but not a reference.
- <p></dd>
-
- </dl>
-
- <h2>WARNING</h2>
- The restriction for the comparison operation is that even if, for example,
- `<B>cmp</B>' should return a blessed reference, the autogenerated `<B>lt</B>'
- function will produce only a standard logical value based on the
- numerical value of the result of `<B>cmp</B>'. In particular, a working
- numeric conversion is needed in this case (possibly expressed in terms of
- other conversions).
- <p>Similarly, <B>.=</B> and <B>x=</B> operators lose their mathemagical properties
- if the string conversion substitution is applied.
- <p>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.
- <p><h2>IMPLEMENTATION</h2>
- 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
- <A HREF="perlfunc.html#perlfunc_78">bless</A>
- ing; so if it is changed
- dynamically, you'll need an additional fake
- <A HREF="perlfunc.html#perlfunc_78">bless</A>
- ing to update the
- table.
- <p>(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.)
- <p>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.
- <p>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.
- <p>There is no size penalty for data if there is no %OVERLOAD.
- <p>The copying like <B>$a=$b</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>$b++</B>. You can override this
- behavior by defining your copy constructor (see "Copy Constructor").
- <p>It is expected that arguments to methods that are not explicitly supposed
- to be changed are constant (but this is not enforced).
- <p><h2>AUTHOR</h2>
- Ilya Zakharevich <<I>ilya@math.mps.ohio-state.edu</I>>.
- <p><h2>DIAGNOSTICS</h2>
- When Perl is run with the <B>-Do</B> switch or its equivalent, overloading
- induces diagnostic messages.
- <p><h2>BUGS</h2>
- Because it's used for overloading, the per-package associative array
- %OVERLOAD now has a special meaning in Perl.
- <p>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.
- <p>As shipped, %OVERLOAD is not inherited via the @ISA tree. A patch for
- this is available from the author.
- <p>This document is confusing.<p>