<P>see <A HREF="#special symbols for c<use overload>">SPECIAL SYMBOLS FOR <CODE>use overload</CODE></A>.</P>
</UL>
<P>See <A HREF="#fallback">Fallback</A> for an explanation of when a missing method can be
autogenerated.</P>
<P>A computer-readable form of the above table is available in the hash
%overload::ops, with values being space-separated lists of names:</P>
<PRE>
with_assign => '+ - * / % ** << >> x .',
assign => '+= -= *= /= %= **= <<= >>= x= .=',
num_comparison => '< <= > >= == !=',
'3way_comparison'=> '<=> cmp',
str_comparison => 'lt le gt ge eq ne',
binary => '& | ^',
unary => 'neg ! ~',
mutators => '++ --',
func => 'atan2 cos sin exp abs log sqrt',
conversion => 'bool "" 0+',
iterators => '<>',
dereferencing => '${} @{} %{} &{} *{}',
special => 'nomethod fallback ='</PRE>
<P>
<H2><A NAME="inheritance and overloading">Inheritance and overloading</A></H2>
<P>Inheritance interacts with overloading in two ways.</P>
<DL>
<DT><STRONG><A NAME="item_Strings_as_values_of_use_overload_directive">Strings as values of <CODE>use overload</CODE> directive</A></STRONG><BR>
<DD>
If <CODE>value</CODE> in
<PRE>
use overload key => value;</PRE>
<P>is a string, it is interpreted as a method name.</P>
<P></P>
<DT><STRONG><A NAME="item_Overloading_of_an_operation_is_inherited_by_derive">Overloading of an operation is inherited by derived classes</A></STRONG><BR>
<DD>
Any class derived from an overloaded class is also overloaded. The
set of overloaded methods is the union of overloaded methods of all
the ancestors. If some method is overloaded in several ancestor, then
which description will be used is decided by the usual inheritance
rules:
<P>If <CODE>A</CODE> inherits from <CODE>B</CODE> and <CODE>C</CODE> (in this order), <CODE>B</CODE> overloads
<CODE>+</CODE> with <CODE>\&D::plus_sub</CODE>, and <CODE>C</CODE> overloads <CODE>+</CODE> by <CODE>"plus_meth"</CODE>,
then the subroutine <CODE>D::plus_sub</CODE> will be called to implement
operation <CODE>+</CODE> for an object in package <CODE>A</CODE>.</P>
<P></P></DL>
<P>Note that since the value of the <CODE>fallback</CODE> key is not a subroutine,
its inheritance is not governed by the above rules. In the current
implementation, the value of <CODE>fallback</CODE> in the first overloaded
ancestor is used, but this is accidental and subject to change.</P>
<P>
<HR>
<H1><A NAME="special symbols for use overload">SPECIAL SYMBOLS FOR <CODE>use overload</CODE></A></H1>
<P>Three keys are recognized by Perl that are not covered by the above
description.</P>
<P>
<H2><A NAME="last resort">Last Resort</A></H2>
<P><CODE>"nomethod"</CODE> should be followed by 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 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. Say, <CODE>1-$a</CODE> can be equivalent to</P>
<PRE>
&nomethodMethod($a,1,1,"-")</PRE>
<P>if the pair <CODE>"nomethod" => "nomethodMethod"</CODE> was specified in the
<CODE>use overload</CODE> directive.</P>
<P>If some operation cannot be resolved, and there is no function
assigned to <CODE>"nomethod"</CODE>, then an exception will be raised via die()--
unless <CODE>"fallback"</CODE> was specified as a key in <CODE>use overload</CODE> directive.</P>
<P>
<H2><A NAME="fallback">Fallback</A></H2>
<P>The key <CODE>"fallback"</CODE> governs what to do if a method for a particular
operation is not found. Three different cases are possible depending on
the value of <CODE>"fallback"</CODE>:</P>
<UL>
<LI><STRONG><CODE>undef</CODE></STRONG><BR>
Perl tries to use a
substituted method (see <A HREF="#magic autogeneration">MAGIC AUTOGENERATION</A>). If this fails, it
then tries to calls <CODE>"nomethod"</CODE> value; if missing, an exception
will be raised.
<P></P>
<LI><STRONG>TRUE</STRONG><BR>
The same as for the <A HREF="#item_undef"><CODE>undef</CODE></A> value, but no exception is raised. Instead,
it silently reverts to what it would have done were there no <CODE>use overload</CODE>
present.
<P></P>
<LI><STRONG><A NAME="item_defined%2C_but_FALSE">defined, but FALSE</A></STRONG><BR>
No autogeneration is tried. Perl tries to call
<CODE>"nomethod"</CODE> value, and if this is missing, raises an exception.
<P></P></UL>
<P><STRONG>Note.</STRONG> <CODE>"fallback"</CODE> inheritance via @ISA is not carved in stone
yet, see <A HREF="#inheritance and overloading">Inheritance and overloading</A>.</P>
to overload <A HREF="#item_q"><CODE>q</CODE></A>-quoted strings, constant pieces of <A HREF="../lib/Pod/perlfunc.html#item_qq"><CODE>qq</CODE></A>- and <A HREF="../lib/Pod/perlfunc.html#item_qx"><CODE>qx</CODE></A>-quoted
strings and here-documents,
<P></P>
<DT><STRONG><A NAME="item_qr">qr</A></STRONG><BR>
<DD>
to overload constant pieces of regular expressions.
<P></P></DL>
<P>The corresponding values are references to functions which take three arguments:
the first one is the <EM>initial</EM> string form of the constant, the second one
is how Perl interprets this constant, the third one is how the constant is used.
Note that the initial string form does not
contain string delimiters, and has backslashes in backslash-delimiter
combinations stripped (thus the value of delimiter is not relevant for
processing of this string). The return value of this function is how this
constant is going to be interpreted by Perl. The third argument is undefined
unless for overloaded <A HREF="#item_q"><CODE>q</CODE></A>- and <A HREF="#item_qr"><CODE>qr</CODE></A>- constants, it is <A HREF="#item_q"><CODE>q</CODE></A> in single-quote
context (comes from strings, regular expressions, and single-quote HERE
documents), it is <A HREF="../lib/Pod/perlfunc.html#item_tr"><CODE>tr</CODE></A> for arguments of <A HREF="../lib/Pod/perlfunc.html#item_tr"><CODE>tr</CODE></A>/<A HREF="../lib/Pod/perlfunc.html#item_y"><CODE>y</CODE></A> operators,
it is <A HREF="../lib/Pod/perlfunc.html#item_s"><CODE>s</CODE></A> for right-hand side of <A HREF="../lib/Pod/perlfunc.html#item_s"><CODE>s</CODE></A>-operator, and it is <A HREF="../lib/Pod/perlfunc.html#item_qq"><CODE>qq</CODE></A> otherwise.</P>
<P>Since an expression <CODE>"ab$cd,,"</CODE> is just a shortcut for <CODE>'ab' . $cd . ',,'</CODE>,
it is expected that overloaded constant strings are equipped with reasonable
overloaded catenation operator, otherwise absurd results will result.
Similarly, negative numbers are considered as negations of positive constants.</P>
<P>Note that it is probably meaningless to call the functions overload::constant()
and overload::remove_constant() from anywhere but <A HREF="../lib/Pod/perlfunc.html#item_import"><CODE>import()</CODE></A> and <CODE>unimport()</CODE> methods.
From these methods they may be called as</P>
<PRE>
sub import {
shift;
return unless @_;
die "unknown import: @_" unless @_ == 1 and $_[0] eq ':constant';
overload::constant integer => sub {Math::BigInt->new(shift)};
}</PRE>
<P><STRONG>BUGS</STRONG> Currently overloaded-ness of constants does not propagate
<P>Suppose you want to create an object which is accessible as both an
array reference, and a hash reference, similar to the builtin
<A HREF="../lib/Pod/perlref.html#pseudohashes: using an array as a hash">array-accessible-as-a-hash</A> builtin Perl type. Let us make it better than the builtin
type, there will be no restriction that you cannot use the index 0 of
your array.</P>
<PRE>
package two_refs;
use overload '%{}' => \&gethash, '@{}' => sub { $ {shift()} };
sub new {
my $p = shift;
bless \ [@_], $p;
}
sub gethash {
my %h;
my $self = shift;
tie %h, ref $self, $self;
\%h;
}</PRE>
<PRE>
sub TIEHASH { my $p = shift; bless \ shift, $p }
my %fields;
my $i = 0;
$fields{$_} = $i++ foreach qw{zero one two three};
sub STORE {
my $self = ${shift()};
my $key = $fields{shift()};
defined $key or die "Out of band access";
$$self->[$key] = shift;
}
sub FETCH {
my $self = ${shift()};
my $key = $fields{shift()};
defined $key or die "Out of band access";
$$self->[$key];
}</PRE>
<P>Now one can access an object using both the array and hash syntax:</P>
<PRE>
my $bar = new two_refs 3,4,5,6;
$bar->[2] = 11;
$bar->{two} == 11 or die 'bad hash fetch';</PRE>
<P>Note several important features of this example. First of all, the
<EM>actual</EM> type of $bar is a scalar reference, and we do not overload
the scalar dereference. Thus we can get the <EM>actual</EM> non-overloaded
contents of $bar by just using <CODE>$$bar</CODE> (what we do in functions which
overload dereference). Similarly, the object returned by the
<CODE>TIEHASH()</CODE> method is a scalar reference.</P>
<P>Second, we create a new tied hash each time the hash syntax is used.
This allows us not to worry about a possibility of a reference loop,
would would lead to a memory leak.</P>
<P>Both these problems can be cured. Say, if we want to overload hash
dereference on a reference to an object which is <EM>implemented</EM> as a
hash itself, the only problem one has to circumvent is how to access
this <EM>actual</EM> hash (as opposed to the <EM>virtual</EM> exhibited by
overloaded dereference operator). Here is one possible fetching routine:</P>
<PRE>
sub access_hash {
my ($self, $key) = (shift, shift);
my $class = ref $self;
bless $self, 'overload::dummy'; # Disable overloading of %{}
my $out = $self->{$key};
bless $self, $class; # Restore overloading
$out;
}</PRE>
<P>To move creation of the tied hash on each access, one may an extra
level of indirection which allows a non-circular structure of references:</P>
<PRE>
package two_refs1;
use overload '%{}' => sub { ${shift()}->[1] },
'@{}' => sub { ${shift()}->[0] };
sub new {
my $p = shift;
my $a = [@_];
my %h;
tie %h, $p, $a;
bless \ [$a, \%h], $p;
}
sub gethash {
my %h;
my $self = shift;
tie %h, ref $self, $self;
\%h;
}</PRE>
<PRE>
sub TIEHASH { my $p = shift; bless \ shift, $p }
my %fields;
my $i = 0;
$fields{$_} = $i++ foreach qw{zero one two three};
sub STORE {
my $a = ${shift()};
my $key = $fields{shift()};
defined $key or die "Out of band access";
$a->[$key] = shift;
}
sub FETCH {
my $a = ${shift()};
my $key = $fields{shift()};
defined $key or die "Out of band access";
$a->[$key];
}</PRE>
<P>Now if $baz is overloaded like this, then <CODE>$bar</CODE> is a reference to a
reference to the intermediate array, which keeps a reference to an
actual array, and the access hash. The tie()ing object for the access
hash is also a reference to a reference to the actual array, so</P>
<UL>
<LI>
There are no loops of references.
<P></P>
<LI>
Both ``objects'' which are blessed into the class <CODE>two_refs1</CODE> are
references to a reference to an array, thus references to a <EM>scalar</EM>.
Thus the accessor expression <CODE>$$foo->[$ind]</CODE> involves no
<P>Put this in <EM>symbolic.pm</EM> in your Perl library directory:</P>
<PRE>
package symbolic; # Primitive symbolic calculator
use overload nomethod => \&wrap;</PRE>
<PRE>
sub new { shift; bless ['n', @_] }
sub wrap {
my ($obj, $other, $inv, $meth) = @_;
($obj, $other) = ($other, $obj) if $inv;
bless [$meth, $obj, $other];
}</PRE>
<P>This module is very unusual as overloaded modules go: it does not
provide any usual overloaded operators, instead it provides the <A HREF="#last resort">Last Resort</A> operator <CODE>nomethod</CODE>. In this example the corresponding
subroutine returns an object which encapsulates operations done over
the objects: <CODE>new symbolic 3</CODE> contains <CODE>['n', 3]</CODE>, <CODE>2 + new
<P>When Perl is run with the <STRONG>-Do</STRONG> switch or its equivalent, overloading
induces diagnostic messages.</P>
<P>Using the <A HREF="../lib/Pod/perlfunc.html#item_m"><CODE>m</CODE></A> command of Perl debugger (see <A HREF="../lib/Pod/perldebug.html">the perldebug manpage</A>) one can
deduce which operations are overloaded (and which ancestor triggers
this overloading). Say, if <CODE>eq</CODE> is overloaded, then the method <CODE>(eq</CODE>
is shown by debugger. The method <CODE>()</CODE> corresponds to the <CODE>fallback</CODE>
key (in fact a presence of this method shows that this package has
overloading enabled, and it is what is used by the <A HREF="#item_Overloaded"><CODE>Overloaded</CODE></A>
function of module <CODE>overload</CODE>).</P>
<P>
<HR>
<H1><A NAME="bugs">BUGS</A></H1>
<P>Because it is used for overloading, the per-package hash %OVERLOAD now
has a special meaning in Perl. The symbol table is filled with names
looking like line-noise.</P>
<P>For the purpose of inheritance every overloaded package behaves as if
<CODE>fallback</CODE> is present (possibly undefined). This may create
interesting effects if some package is not overloaded, but inherits
from two overloaded packages.</P>
<P>Relation between overloading and tie()ing is broken. Overloading is
triggered or not basing on the <EM>previous</EM> class of tie()d value.</P>
<P>This happens because the presence of overloading is checked too early,
before any tie()d access is attempted. If the FETCH()ed class of the
tie()d value does not change, a simple workaround is to access the value
immediately after tie()ing, so that after this call the <EM>previous</EM> class
coincides with the current one.</P>
<P><STRONG>Needed:</STRONG> a way to fix this without a speed penalty.</P>
<P>Barewords are not covered by overloaded string constants.</P>
<P>This document is confusing. There are grammos and misleading language
used in places. It would seem a total rewrite is needed.</P>
