home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
BURKS 2
/
BURKS_AUG97.ISO
/
SLAKWARE
/
D12
/
PERL1.TGZ
/
perl1.tar
/
usr
/
lib
/
perl5
/
overload.pm
< prev
next >
Wrap
Text File
|
1996-06-28
|
14KB
|
490 lines
package overload;
sub OVERLOAD {
$package = shift;
my %arg = @_;
my $hash = \%{$package . "::OVERLOAD"};
for (keys %arg) {
$hash->{$_} = $arg{$_};
}
}
sub import {
$package = (caller())[0];
# *{$package . "::OVERLOAD"} = \&OVERLOAD;
shift;
$package->overload::OVERLOAD(@_);
}
sub unimport {
$package = (caller())[0];
my $hash = \%{$package . "::OVERLOAD"};
shift;
for (@_) {
delete $hash->{$_};
}
}
sub Overloaded {
defined ($package = ref $_[0]) and defined %{$package . "::OVERLOAD"};
}
sub OverloadedStringify {
defined ($package = ref $_[0]) and
defined %{$package . "::OVERLOAD"} and
exists $ {$package . "::OVERLOAD"}{'""'} and
defined &{$ {$package . "::OVERLOAD"}{'""'}};
}
sub Method {
defined ($package = ref $_[0]) and
defined %{$package . "::OVERLOAD"} and
$ {$package . "::OVERLOAD"}{$_[1]};
}
sub AddrRef {
$package = ref $_[0];
bless $_[0], Overload::Fake; # Non-overloaded package
my $str = "$_[0]";
bless $_[0], $package; # Back
$str;
}
sub StrVal {
(OverloadedStringify) ?
(AddrRef) :
"$_[0]";
}
1;
__END__
=head1 NAME
overload - Package for overloading perl operations
=head1 SYNOPSIS
package SomeThing;
use overload
'+' => \&myadd,
'-' => \&mysub;
# etc
...
package main;
$a = new SomeThing 57;
$b=5+$a;
...
if (overload::Overloaded $b) {...}
...
$strval = overload::StrVal $b;
=head1 CAVEAT SCRIPTOR
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.
=head1 DESCRIPTION
=head2 Declaration of overloaded functions
The compilation directive
package Number;
use overload
"+" => \&add,
"*=" => "muas";
declares function Number::add() for addition, and method muas() in
the "class" C<Number> (or one of its base classes)
for the assignment form C<*=> of multiplication.
Arguments of this directive come in (key, value) pairs. Legal values
are values legal inside a C<&{ ... }> call, so the name of a subroutine,
a reference to a subroutine, or an anonymous subroutine will all work.
Legal keys are listed below.
The subroutine C<add> will be called to execute C<$a+$b> if $a
is a reference to an object blessed into the package C<Number>, or if $a is
not an object from a package with defined mathemagic addition, but $b is a
reference to a C<Number>. It can also be called in other situations, like
C<$a+=7>, or C<$a++>. See L<MAGIC AUTOGENERATION>. (Mathemagical
methods refer to methods triggered by an overloaded mathematical
operator.)
=head2 Calling Conventions for Binary Operations
The functions specified in the C<use overload ...> directive are called
with three (in one particular case with four, see L<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 always be
an object in the package, so in the situation of C<7+$a>, the
order of the arguments is interchanged. It probably does not matter
when implementing the addition method, but whether the arguments
are reversed is vital to the subtraction method. The method can
query this information by examining the third argument, which can take
three different values:
=over 7
=item FALSE
the order of arguments is as in the current operation.
=item TRUE
the arguments are reversed.
=item C<undef>
the current operation is an assignment variant (as in
C<$a+=7>), but the usual function is called instead. This additional
information can be used to generate some optimizations.
=back
=head2 Calling Conventions for Unary Operations
Unary operation are considered binary operations with the second
argument being C<undef>. Thus the functions that overloads C<{"++"}>
is called with arguments C<($a,undef,'')> when $a++ is executed.
=head2 Overloadable Operations
The following symbols can be specified in C<use overload>:
=over 5
=item * I<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 "C<+>",
"C<->", "C<+=>", and "C<-=>" can be called to automatically generate
increment and decrement methods. The operation "C<->" can be used to
autogenerate missing methods for unary minus or C<abs>.
=item * I<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 C<sort>ing
arrays, C<cmp> is used to compare values subject to C<use overload>.
=item * I<Bit operations>
"&", "^", "|", "neg", "!", "~",
"C<neg>" stands for unary minus. If the method for C<neg> is not
specified, it can be autogenerated using the method for subtraction.
=item * I<Increment and decrement>
"++", "--",
If undefined, addition and subtraction methods can be
used instead. These operations are called both in prefix and
postfix form.
=item * I<Transcendental functions>
"atan2", "cos", "sin", "exp", "abs", "log", "sqrt",
If C<abs> is unavailable, it can be autogenerated using methods
for "<" or "<=>" combined with either unary minus or subtraction.
=item * I<Boolean, string and numeric conversion>
"bool", "\"\"", "0+",
If one or two of these operations are unavailable, the remaining ones can
be used instead. C<bool> is used in the flow control operators
(like C<while>) and for the ternary "C<?:>" 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.
=item * I<Special>
"nomethod", "fallback", "=",
see L<SPECIAL SYMBOLS FOR C<use overload>>.
=back
See L<"Fallback"> for an explanation of when a missing method can be autogenerated.
=head1 SPECIAL SYMBOLS FOR C<use overload>
Three keys are recognized by Perl that are not covered by the above
description.
=head2 Last Resort
C<"nomethod"> 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, C<1-$a> can be equivalent to
&nomethodMethod($a,1,1,"-")
if the pair C<"nomethod" =E<gt> "nomethodMethod"> was specified in the
C<use overload> directive.
If some operation cannot be resolved, and there is no function
assigned to C<"nomethod">, then an exception will be raised via die()--
unless C<"fallback"> was specified as a key in C<use overload> directive.
=head2 Fallback
The key C<"fallback"> governs what to do if a method for a particular
operation is not found. Three different cases are possible depending on
the value of C<"fallback">:
=over 16
=item * C<undef>
Perl tries to use a
substituted method (see L<MAGIC AUTOGENERATION>). If this fails, it
then tries to calls C<"nomethod"> value; if missing, an exception
will be raised.
=item * TRUE
The same as for the C<undef> value, but no exception is raised. Instead,
it silently reverts to what it would have done were there no C<use overload>
present.
=item * defined, but FALSE
No autogeneration is tried. Perl tries to call
C<"nomethod"> value, and if this is missing, raises an exception.
=back
=head2 Copy Constructor
The value for C<"="> is a reference to a function with three
arguments, i.e., it looks like the other values in C<use
overload>. However, it does not overload the Perl assignment
operator. This would go against Camel hair.
This operation is called in the situations when a mutator is applied
to a ref