: For some reasons my patches for Overload did not make it into
: 001[a-n].
Are you referring to NETaa14099 and NETaa13769? If not, please
resend them. I must have missed them. The second patch does look a
little out of date, in that it deals with the OVERLOAD module rather
than the Overload module.
Larry
*******************************************************************************
Bug NETaa14099 NL.perl Submitted 950318
NEW defect report perl, version 5.001
1 enclosure
"possible bug with overloading"
DETECTION INFORMATION
Detection method: customer use
Detected in phase: post release
Test program name:
Hardware:
Version of OS:
Problem severity: 3
Affects project:
Need fix by:
SUBMITTER INFORMATION
Submitter: Ilya Zakharevich
Organization: math.ohio-state.edu
Phone number:
Address: ilya@vaccine
************ Problem (Added 950318 by ilya) ***********
Return-Path: owner-perl5-porters@nicoh.com
Return-Path: <owner-perl5-porters@nicoh.com>
Received: from scalpel (scalpel.netlabs.com) by netlabs.com (4.1/SMI-4.1)
id AA06036; Sat, 18 Mar 95 17:37:05 PST
Received: from netlabs.com (vaccine-eng1.netlabs.com) by scalpel (4.1/SMI-4.1)
id AA07110; Sat, 18 Mar 95 17:36:14 PST
Received: from africa.nicoh.com by netlabs.com (4.1/SMI-4.1)
id AA06033; Sat, 18 Mar 95 17:37:02 PST
Received: by africa.nicoh.com
(1.37.109.15/16.2) id AA068165870; Sat, 18 Mar 1995 20:17:50 -0500
From: ilya@math.ohio-state.edu (Ilya Zakharevich)
Message-Id: <199503190114.UAA08492@monk.mps.ohio-state.edu>
Subject: Re: possible bug with overloading
To: kelem@xilinx.com (Steve Kelem)
Date: Sat, 18 Mar 1995 20:14:01 -0500 (EST)
Cc: perl5-porters@africa.nicoh.com
In-Reply-To: <16370.795381440@castor> from "Steve Kelem" at Mar 16, 95 11:17:20 am
X-Mailer: ELM [version 2.4 PL24]
Mime-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Content-Length: 4067
Sender: owner-perl5-porters@nicoh.com
List-Name: perl5-porters
Precedence: bulk
Features: .p.PF
Steve Kelem writes:
>
> I'm having trouble with perl5.001 (with Larry's patches) on a Sparc 10
> running SunOS 4.1.3, compiled with /bin/cc.
>
> I get the message:
>
> Operation `bool': no method found,
> left argument in overloaded package DATE,
> right argument has no overloaded magic at dectest.perl line 35.
>
[deletia]
>
> Here's the file dectest.perl. (I whittled the problem down quite a bit.)
>
> ======================================================================
> #! /usr/local/src/gnu/perl5.001/perl -- # -*-Perl-*-
> require "timelocal.pl";
>
> package DATE;
> ########################################
>
> %OVERLOAD = (
> "==" => \&eq_date
> );
>
> sub new {
> local $type = shift @_;
> local ($YMD) = @_;
> local ($Y, $M, $D) = split(/\//, $YMD);
> local $self = {
> 'y' => $Y,
> 'm' => $M,
> 'd' => $D,
> 'tod' => main::timelocal(0,0,15,$D,$M-1,$Y-1900),
> 'dow' => (localtime(main::timelocal(0,0,15,$D,$M-1,$Y-1900)))[6],
> 'ymd' => sprintf("%d/%02d/%02d", $Y, $M, $D)
> };
> bless $self;
> return $self;
> }
[deletia]
> sub eq_date { # Equal for dates.
> local $type = shift @_;
> print "eq_date: ", join(', ', @_);
------------------------------------^
> local ($Date1, $Date2) = @_;
> print "$Date1->{'ymd'} ?= $Date2->{'ymd'}\n";
> return $Date1->{'ymd'} eq $Date2->{'ymd'};
> }
I'm sure you have found a bug in your script already, having a
subroutine Print near eq_date. Look what happens: the overloaded data
is a hash, so there is no obvious method to print it. So the
overloaded stringify method is called during print. There is no such
guy, so it tries numify, and, last, boolify. Then it duely reports
that there is no boolify.
If you add '""' => Print in your code, anything works like that:
1994, 1994/11/23, 23, 11, dow
1994, 1994/11/23, 23, 11, dow
eq_date: 1, 1994/11/23 ?=
1994/11/28 != 1994/11/23 is true!
I was bitten by this bug in reporter too, so I'm absolutely sure I
sent a patch for it once. But probably it was lost during gray period
when I did not know that my patches are not included in betas.
So below is unofficial unofficial patch. It also corrects minor string
length inconsistencies in printf. (However, expect more bugs in
reporter, since I remember that the patch that corrected a lot of bugs
was much longer - or was it a patch that made -Do less concise?)
Enjoy,
Ilya
*** gv.c.old Sat Mar 18 19:47:56 1995
--- gv.c Sat Mar 18 20:07:33 1995
***************
*** 1004,1013 ****
} else if (cvp && (cv=cvp[nomethod_amg])) {
notfound = 1; lr = 1;
} else {
! char tmpstr[512];
if (off==-1) off=method;
! sprintf(tmpstr,"Operation `%s': no method found,\n\tleft argument %s%.200s,\n\tright argument %s%.200s",
! ((char**)AMG_names)[off],
SvAMAGIC(left)?
"in overloaded package ":
"has no overloaded magic",
--- 1004,1013 ----
} else if (cvp && (cv=cvp[nomethod_amg])) {
notfound = 1; lr = 1;
} else {
! char tmpstr[700];
if (off==-1) off=method;
! sprintf(tmpstr,"Operation `%s': no method found,\n\tleft argument %s%.290s,\n\tright argument %s%.290s",
! ((char**)AMG_names)[method],
SvAMAGIC(left)?
"in overloaded package ":
"has no overloaded magic",
***************
*** 1030,1036 ****
}
}
if (!notfound) {
! DEBUG_o( deb("Overloaded operator `%s'%s%s%s:\n\tmethod%s found%s in package %.200s%s\n",
((char**)AMG_names)[off],
method+assignshift==off? "" :
" (initially `",
--- 1030,1036 ----
}
}
if (!notfound) {
! DEBUG_o( deb("Overloaded operator `%s'%s%s%s:\n\tmethod%s found%s in package %.256s%s\n",
((char**)AMG_names)[off],
method+assignshift==off? "" :
" (initially `",
[Mailinglist--not acked]
************ History ************
bugs 950318 000000 Submitted to NL.perl by ilya@math.ohio-state.edu (Ilya Zakharevich)
*******************************************************************************
Bug NETaa13769 NL.perl Submitted 950315
NEW defect report perl, version 5.001
1 enclosure
"Newer wraps for Overload"
DETECTION INFORMATION
Detection method: customer use
Detected in phase: post release
Test program name:
Hardware:
Version of OS:
Problem severity: 4
Affects project:
Need fix by:
SUBMITTER INFORMATION
Submitter: Ilya Zakharevich
Organization: math.ohio-state.edu
Phone number:
Address: ilya@vaccine
************ Problem (Added 950315 by ilya) ***********
Replied: Wed, 15 Mar 95 13:37:40 -0800
Replied: perl5
Return-Path: ilya@math.ohio-state.edu
Return-Path: <ilya@math.ohio-state.edu>
Received: from monk.mps.ohio-state.edu by netlabs.com (4.1/SMI-4.1)
id AA00605; Wed, 15 Mar 95 12:58:22 PST
Received: (from ilya@localhost) by monk.mps.ohio-state.edu (8.6.11/8.6.11) id PAA25698 for lwall@netlabs.com; Wed, 15 Mar 1995 15:57:22 -0500
From: ilya@math.ohio-state.edu (Ilya Zakharevich)
Message-Id: <199503152057.PAA25698@monk.mps.ohio-state.edu>
Subject: Newer wraps for Overload
To: lwall@netlabs.com (Larry Wall)
Date: Wed, 15 Mar 1995 15:57:21 -0500 (EST)
X-Mailer: ELM [version 2.4 PL24]
Mime-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Content-Length: 35109
Hi, Larry,
I did post to perl5-porters before, but here is much better wrapped
package. It encapsulates current state of affairs (and adds some
functions useful for marshalling).
I did not check 5.001 yet, but hope to see it in 5.0011.
Best wishes,
Ilya
#!/bin/sh
# This is a shell archive (produced by GNU sharutils 4.1).
# To extract the files from this archive, save it to some FILE, remove
# everything before the `!/bin/sh' line above, then type `sh FILE'.
#
# Made on 1995-03-15 15:56 EST by <ilya@monk>.
# Source directory was `/home/ilya/perl'.
#
# Existing files will *not* be overwritten unless `-c' is specified.
#
# This shar contains:
# length mode name
# ------ ---------- ------------------------------------------
# 5073 -rw-r--r-- t/op/overload.t
# 13762 -rw-r--r-- lib/Overload.pm
# 12646 -rw-r--r-- pod/perlovl.pod
#
touch -am 1231235999 $$.touch >/dev/null 2>&1
if test ! -f 1231235999 && test -f $$.touch; then
shar_touch=touch
else
shar_touch=:
echo
echo 'WARNING: not restoring timestamps. Consider getting and'
echo "installing GNU \`touch', distributed in GNU File Utilities..."
echo
fi
rm -f 1231235999 $$.touch
#
# ============= t/op/overload.t ==============
if test ! -d 't'; then
echo 'x - creating directory t'
mkdir 't'
fi
if test ! -d 't/op'; then
echo 'x - creating directory t/op'
mkdir 't/op'
fi
if test -f 't/op/overload.t' && test X"$1" != X"-c"; then
echo 'x - skipping t/op/overload.t (file already exists)'
else
echo 'x - extracting t/op/overload.t (text)'
sed 's/^X//' << 'SHAR_EOF' > 't/op/overload.t' &&
#!./perl
X
BEGIN { unshift @INC, './lib', '../lib';
X require Config; import Config;
}
X
package Oscalar;
X
%OVERLOAD = (
X # Anonymous subroutines:
'+' => sub {new Oscalar ${$_[0]}+$_[1]},
'-' => sub {new Oscalar
X $_[2]? $_[1]-${$_[0]} : ${$_[0]}-$_[1]},
'<=>' => sub {new Oscalar
X $_[2]? $_[1]-${$_[0]} : ${$_[0]}-$_[1]},
'cmp' => sub {new Oscalar
X $_[2]? ($_[1] cmp ${$_[0]}) : (${$_[0]} cmp $_[1])},
'*' => sub {new Oscalar ${$_[0]}*$_[1]},
'/' => sub {new Oscalar
X $_[2]? $_[1]/${$_[0]} :
X ${$_[0]}/$_[1]},
'%' => sub {new Oscalar
X $_[2]? $_[1]%${$_[0]} : ${$_[0]}%$_[1]},
'**' => sub {new Oscalar
X $_[2]? $_[1]**${$_[0]} : ${$_[0]}-$_[1]},
X
qw(
"" stringify
0+ numify) # Order of arguments unsignificant
);
X
sub new {
X my $foo = $_[1];
X bless \$foo;
}
X
sub stringify { "${$_[0]}" }
sub numify { 0 + "${$_[0]}" } # Not needed, additional overhead
X # comparing to direct compilation based on
X # stringify
X
package main;
X
$test = 0;
$| = 1;
print "1..",&last,"\n";
X
sub test {
X $test++; if (shift) {print "ok $test\n";1} else {print "not ok $test\n";0}
}
X
$a = new Oscalar "087";
$b= "$a";
X
test (!defined ref $b); # 1
test ($b eq $a); # 2
test ($b eq "087"); # 3
test (ref $a eq "Oscalar"); # 4
test ($a eq $a); # 5
test ($a eq "087"); # 6
X
$c = $a + 7;
X
test (ref $c eq "Oscalar"); # 7
test (!($c eq $a)); # 8
test ($c eq "94"); # 9
X
$b=$a;
X
test (ref $a eq "Oscalar"); # 10
X
$b++;
X
test (ref $b eq "Oscalar"); # 11
test ( $a eq "087"); # 12
test ( $b eq "88"); # 13
test (ref $a eq "Oscalar"); # 14
X
$c=$b;
$c-=$a;
X
test (ref $c eq "Oscalar"); # 15
test ( $a eq "087"); # 16
test ( $c eq "1"); # 17
test (ref $a eq "Oscalar"); # 18
X
$b=1;
$b+=$a;
X
test (ref $b eq "Oscalar"); # 19
test ( $a eq "087"); # 20
test ( $b eq "88"); # 21
test (ref $a eq "Oscalar"); # 22
X
$Oscalar::OVERLOAD{'++'} = sub {${$_[0]}++;$_[0]};
X
$b=$a;
X
test (ref $a eq "Oscalar"); # 23
X
$b++;
X
test (ref $b eq "Oscalar"); # 24
test ( $a eq "087"); # 25
test ( $b eq "88"); # 26
test (ref $a eq "Oscalar"); # 27
X
package Oscalar;
$dummy=bless \$dummy; # Now cache of method should be reloaded
package main;
X
$b=$a;
$b++;
X
test (ref $b eq "Oscalar"); # 28
test ( $a eq "087"); # 29
test ( $b eq "88"); # 30
test (ref $a eq "Oscalar"); # 31
X
X
$Oscalar::OVERLOAD{'++'} = sub {${$_[0]}+=2;$_[0]};
X
$b=$a;
X
test (ref $a eq "Oscalar"); # 32
X
$b++;
X
test (ref $b eq "Oscalar"); # 33
test ( $a eq "087"); # 34
test ( $b eq "88"); # 35
test (ref $a eq "Oscalar"); # 36
X
package Oscalar;
$dummy=bless \$dummy; # Now cache of method should be reloaded
package main;
X
$b++;
X
test (ref $b eq "Oscalar"); # 37
test ( $a eq "087"); # 38
test ( $b eq "90"); # 39
test (ref $a eq "Oscalar"); # 40
X
$b=$a;
$b++;
X
test (ref $b eq "Oscalar"); # 41
test ( $a eq "087"); # 42
test ( $b eq "89"); # 43
test (ref $a eq "Oscalar"); # 44
X
X
test ($b? 1:0); # 45
X
$Oscalar::OVERLOAD{'='} = sub {$copies++; package Oscalar; local $new=${$_[0]};bless \$new};
X
$b=new Oscalar "$a";
X
test (ref $b eq "Oscalar"); # 46
test ( $a eq "087"); # 47
test ( $b eq "087"); # 48
test (ref $a eq "Oscalar"); # 49
X
$b++;
X
test (ref $b eq "Oscalar"); # 50
test ( $a eq "087"); # 51
test ( $b eq "89"); # 52
test (ref $a eq "Oscalar"); # 53
test ($copies == 0); # 54
X
$b+=1;
X
test (ref $b eq "Oscalar"); # 55
test ( $a eq "087"); # 56
test ( $b eq "90"); # 57
test (ref $a eq "Oscalar"); # 58
test ($copies == 0); # 59
X
$b=$a;
$b+=1;
X
test (ref $b eq "Oscalar"); # 60
test ( $a eq "087"); # 61
test ( $b eq "88"); # 62
test (ref $a eq "Oscalar"); # 63
test ($copies == 0); # 64
X
$b=$a;
$b++;
X
test (ref $b eq "Oscalar") || print ref $b,"=ref(b)\n"; # 65
test ( $a eq "087"); # 66
test ( $b eq "89"); # 67
test (ref $a eq "Oscalar"); # 68
test ($copies == 1); # 69
X
$Oscalar::OVERLOAD{'+='} = sub {${$_[0]}+=3*$_[1];$_[0]};
$c=new Oscalar; # Cause rehash
X
$b=$a;
$b+=1;
X
test (ref $b eq "Oscalar"); # 70
test ( $a eq "087"); # 71
test ( $b eq "90"); # 72
test (ref $a eq "Oscalar"); # 73
test ($copies == 2); # 74
X
$b+=$b;
X
test (ref $b eq "Oscalar"); # 75
test ( $b eq "360"); # 76
test ($copies == 2); # 77
$b=-$b;
X
test (ref $b eq "Oscalar"); # 78
test ( $b eq "-360"); # 79
test ($copies == 2); # 80
X
$b=abs($b);
X
test (ref $b eq "Oscalar"); # 81
test ( $b eq "360"); # 82
test ($copies == 2); # 83
X
$b=abs($b);
X
test (ref $b eq "Oscalar"); # 84
test ( $b eq "360"); # 85
test ($copies == 2); # 86
X
$Oscalar::OVERLOAD{'x'} = sub {new Oscalar ($_[2]? "_.$_[1]._" x ${$_[0]}:
X "_.${$_[0]}._" x $_[1])};
X
$a=new Oscalar "yy";
$a x= 3;
test ($a eq "_.yy.__.yy.__.yy._"); # 87
X
$Oscalar::OVERLOAD{'.'} = sub {new Oscalar ($_[2]? "_.$_[1].__.${$_[0]}._":
X "_.${$_[0]}.__.$_[1]._")};
X
$a=new Oscalar "xx";
X
test ("b${a}c" eq "_._.b.__.xx._.__.c._"); # 88
X
# Here we test blessing to a package updates hash
X
delete $Oscalar::OVERLOAD{'.'};
X
test ("b${a}" eq "_.b.__.xx._"); # 89
$x="1";
bless \$x, Oscalar;
test ("b${a}c" eq "bxxc"); # 90
new Oscalar 1;
test ("b${a}c" eq "bxxc"); # 91
X
sub last {91}
SHAR_EOF
$shar_touch -am 0315154895 't/op/overload.t' &&
chmod 0644 't/op/overload.t' ||
echo 'restore of t/op/overload.t failed'
shar_count="`wc -c < 't/op/overload.t'`"
test 5073 -eq "$shar_count" ||
echo "t/op/overload.t: original size 5073, current size $shar_count"
fi
# ============= lib/Overload.pm ==============
if test ! -d 'lib'; then
echo 'x - creating directory lib'
mkdir 'lib'
fi
if test -f 'lib/Overload.pm' && test X"$1" != X"-c"; then
echo 'x - skipping lib/Overload.pm (file already exists)'
else
echo 'x - extracting lib/Overload.pm (text)'
sed 's/^X//' << 'SHAR_EOF' > 'lib/Overload.pm' &&
package Overload;
X
sub OVERLOAD {
X $package = shift;
X my %arg = @_;
X my $hash = \%{$package . "::OVERLOAD"};
X for (keys %arg) {
X $hash->{$_} = $arg{$_};
X }
}
X
sub import {
X $package = (caller())[0];
X *{$package . "::OVERLOAD"} = \&OVERLOAD;
X shift;
X $package->OVERLOAD(@_);
}
X
sub unimport {
X $package = (caller())[0];
X my $hash = \%{$package . "::OVERLOAD"};
X shift;
X for (@_) {
X delete $hash->{$_};
X }
}
X
sub Overloaded {
X defined ($package = ref $_[0]) and defined %{$package . "::OVERLOAD"};
}
X
sub OverloadedStringify {
X defined ($package = ref $_[0]) and
X defined %{$package . "::OVERLOAD"} and
X exists $ {$package . "::OVERLOAD"}{'""'} and
X defined &{$ {$package . "::OVERLOAD"}{'""'}};
}
X
sub Method {
X defined ($package = ref $_[0]) and
X defined %{$package . "::OVERLOAD"} and
X $ {$package . "::OVERLOAD"}{$_[1]};
}
X
sub AddrRef {
X $package = ref $_[0];
X bless $_[0], Overload::Fake; # Non-overloaded package
X my $str = "$_[0]";
X bless $_[0], $package; # Back
X $str;
}
X
sub StrVal {
X (OverloadedStringify) ?
X (AddrRef) :
X "$_[0]";
}
X
1;
X
__END__
X
=head1 NAME
X
C<Overload.pm> - Package for overloading of perl operations
X
=head1 SYNOPSIS
X
X package SomeThing;
X
X use Overload
X '+' => \&myadd,
X '-' => \&mysub;
X # etc
X ...
X
X package main;
X $a = new SomeThing 57;
X $b=5+$a;
X ...
X if (Overload::Overloaded $b) {...}
X ...
X $strval = Overload::StrVal $b;
X
=head1 CAVEAT SCRIPTOR
X
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.
X
=head1 DESCRIPTION
X
=head2 Declaration of overloaded functions
X
The compilation directive
X
X package Number;
X use OVERLOAD
X "+" => \&add,
X "*=" => "muas";
X
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.
X
Arguments of this directive come in (key, value) pairs. Legal values
are values legal inside 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.
X
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 $a is
not an object from a package with defined mathemagic addition, but $b is a
reference to a C<Number>. It can be called also 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.)
X
=head2 Calling Conventions for Binary Operations
X
The functions specified in 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 be
always an object in the package, so in the situation of C<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:
X
=over 7
X
=item FALSE
X
the order of arguments is as in the current operation.
X
=item TRUE
X
the arguments are reversed.
X
=item C<undef>
X
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.
X
=back
X
=head2 Calling Conventions for Unary Operations
X
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.
X
=head2 Overloadable Operations
X
The following symbols can be specified in C<use Overload>:
X
=over 5
X
=item * I<Arithmetic operations>
X
X "+", "+=", "-", "-=", "*", "*=", "/", "/=", "%", "%=",
X "**", "**=", "<<", "<<=", ">>", ">>=", "x", "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 operations "C<->" can be used to
autogenerate missing methods for unary minus or C<abs>.
X
=item * I<Comparison operations>
X
X "<", "<=", ">", ">=", "==", "!=", "<=>",
X "lt", "le", "gt", "ge", "eq", "ne", "cmp",
X
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>.
X
=item * I<Bit operations>
X
X "&", "^", "|", "neg", "!", "~",
X
"C<neg>" stands for unary minus. If the method for C<neg> is not
specified, it can be autogenerated using on the method for subtraction.
X
=item * I<Increment and decrement>
X
X "++", "--",
X
If undefined, addition and subtraction methods can be
used instead. These operations are called both in prefix and
postfix form.
X
=item * I<Transcendental functions>
X
X "atan2", "cos", "sin", "exp", "abs", "log", "sqrt",
X
If C<abs> is unavailable, it can be autogenerated using methods
for "<" or "<=>" combined with either unary minus or subtraction.
X
=item * I<Boolean, string and numeric conversion>
X
X "bool", "\"\"", "0+",
X
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.
X
=item * I<Special>
X
X "nomethod", "fallback", "=",
X
see L<SPECIAL SYMBOLS FOR C<use Overload>>.
X
=back
X
See L<"Fallback"> for an explanation of when a missing method can be autogenerated.
X
=head1 SPECIAL SYMBOLS FOR C<use Overload>
X
Three keys are recognized by Perl that are not covered by the above
description.
X
=head2 Last Resort
X
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 arguments for the corresponding method if
it were found, the fourth argument is the symbol for C<use Overload>
corresponding to the missing method. If several methods are tried,
the last one is used. Say, C<1-$a> can be equivalent to
X
X &nomethodMethod($a,1,1,"-")
X
if the pair C<"nomethod" =E<gt> "nomethodMethod"> was specified in the
C<use Overload> directive.
X
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.
X
=head2 Fallback
X
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
value of C<"fallback">:
X
=over 16
X
=item * C<undef>
X
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.
X
=item * TRUE
X
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.
X
=item * defined, but FALSE
X
No autogeneration is tried. Perl tries to call
C<"nomethod"> value, and if this is missing, raises an exception.
X
=back
X
=head2 Copy Constructor
X
Value for C<"="> is a reference to a function with three arguments,
i.e., it looks like a usual value in C<use Overload>. 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
X
X $a=$b;
X $a++;
X
To make this change to $a and not to change $b, a freshly made copy of
C<$$a> is made, and $a is assigned a reference to this object. This
operation is executed during C<$a++>, (so before this C<$$a> coincides
with C<$$b>), and only if C<++> is expressed via method for C<'++'> or
C<'+='>. Note that if this operation is expressed via C<'+'>,
i.e., as
X
X $a=$b;
X $a=$a+1;
X
then C<$$a> and C<$$b> do not appear as lvalues.
X
If the copy constructor is required during execution of some mutator,
but method for C<'='> was not specified, it can be autogenerated as a
string copy if an object of the package is a plain scalar.
X
=head1 MAGIC AUTOGENERATION
X
If a method for an operation is not found, and value for C<"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:
X
=over 16
X
=item I<Assignment forms of arithmetic operations>
X
C<$a=+$b> can use the method for C<"+"> if method for C<"+=">
is not defined.
X
=item I<Conversion operations>
X
String, numeric, and boolean conversion are calculated in terms of one
another if not all of them are defined.
X
=item I<Increment and decrement>
X
The C<++$a> operation can be expressed in terms of C<$a+=1> or C<$a+1>,
and C<$a--> in terms of C<$a-=1> and C<$a-1>.
X
=item C<abs($a)>
X
can be expressed in terms of C<$aE<lt>0> and C<-$a> (or C<0-$a>).
X
=item I<Unary minus>
X
can be expressed in terms of subtraction.
X
=item I<Concatenation>
X
can be expressed in terms of string conversion.
X
=item I<Comparison operations>
X
can be expressed in terms of its "spaceship" counterpart: either
C<E<lt>=E<gt>> or C<cmp>:
X
X <, >, <=, >=, ==, != in terms of <=>
X lt, gt, le, ge, eq, ne in terms of cmp
X
=item I<Copy operator>
X
can be expressed in terms of assignment to the dereferenced value, if this
value is scalar but not a reference.
X
=back
X
=head1 WARNING
X
The restriction for the comparison operation is that even if, for example,
`C<cmp>' should return a blessed reference, the autogenerated `C<lt>'
function will produce only a standard logical value based on the
numerical value of the result of `C<cmp>'. In particular, a working
numeric conversion is needed in this case (possibly expressed in terms of
other conversions).
X
Similarly, C<.=> and C<x=> operators lose their mathemagical properties
if the string conversion substitution is applied.
X
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.
X
=head1 Run-time Overloading
X
Since any C<use> directive is executed at compile-time, the only way to change overloading during run-time is to
X
X eval 'use Overload "+" => \&addmethod';
X
You can use also
X
X eval 'no Overload "+", "--", "<="';
X
while the utility of this construction during compile-time is questionable.
X
=head1 Public functions
X
Package C<Overload.pm> provides the following public functions:
X
=over 5
X
=item Overload::StrVal(arg)
X
Gives string value of C<arg> as in absence of stringify overloading.
X
=item Overload::Overloaded(arg)
X
Returns true if C<arg> is subject to overloading of some operations.
X
=item Overload::Method(obj,op)
X
Returns C<undef> or reference to method that implements C<op>.
X
=back
X
=head1 IMPLEMENTATION
X
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 due to
C<use Overload>, C<no Overload>, and @ISA only during
C<bless>ing; so if it is changed dynamically, you'll need an
additional fake C<bless>ing to update the table.
X
(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.)
X
If an object belongs to a package using Overload, it carries a special
flag. Thus the only speed penalty during arithmetic operations without
overload is the check of this flag.
X
In fact, if C<use Overload> is not present, 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 used, the current operation is overloadable but
the arguments in question do not belong to packages using Overload. When
in doubt, test your speed with C<use Overload> and without it. So far there
have been no reports of substantial speed degradation if Perl is compiled
with optimization turned on.
X
There is no size penalty for data if Overload is not used.
X
The copying like C<$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 C<$b++>. You can override this
behavior by defining your copy constructor (see L<"Copy Constructor">).
X
It is expected that arguments to methods that are not explicitly supposed
to be changed are constant (but this is not enforced).
X
=head1 AUTHOR
X
Ilya Zakharevich <F<ilya@math.mps.ohio-state.edu>>.
X
=head1 DIAGNOSTICS
X
When Perl is run with the B<-Do> switch or its equivalent, overloading
induces diagnostic messages.
X
=head1 BUGS
X
Because it's used for overloading, the per-package associative array
%OVERLOAD now has a special meaning in Perl.
X
As shipped, %OVERLOAD is not inherited via the @ISA tree.
X
This document is confusing.
X
=cut
SHAR_EOF
$shar_touch -am 0315155195 'lib/Overload.pm' &&
chmod 0644 'lib/Overload.pm' ||
echo 'restore of lib/Overload.pm failed'
shar_count="`wc -c < 'lib/Overload.pm'`"
test 13762 -eq "$shar_count" ||
echo "lib/Overload.pm: original size 13762, current size $shar_count"
fi
# ============= pod/perlovl.pod ==============
if test ! -d 'pod'; then
echo 'x - creating directory pod'
mkdir 'pod'
fi
if test -f 'pod/perlovl.pod' && test X"$1" != X"-c"; then
echo 'x - skipping pod/perlovl.pod (file already exists)'
else
echo 'x - extracting pod/perlovl.pod (text)'
sed 's/^X//' << 'SHAR_EOF' > 'pod/perlovl.pod' &&
=head1 NAME
X
C<Overload.pm> - Package for overloading of perl operations
X
=head1 SYNOPSIS
X
X package SomeThing;
X
X use Overload
X '+' => \&myadd,
X '-' => \&mysub;
X # etc
X ...
X
X package main;
X $a = new SomeThing 57;
X $b=5+$a;
X ...
X if (Overload::Overloaded $b) {...}
X ...
X $strval = Overload::StrVal $b;
X
=head1 CAVEAT SCRIPTOR
X
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.
X
=head1 DESCRIPTION
X
=head2 Declaration of overloaded functions
X
The compilation directive
X
X package Number;
X use OVERLOAD
X "+" => \&add,
X "*=" => "muas";
X
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.
X
Arguments of this directive come in (key, value) pairs. Legal values
are values legal inside 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.
X
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 $a is
not an object from a package with defined mathemagic addition, but $b is a
reference to a C<Number>. It can be called also 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.)
X
=head2 Calling Conventions for Binary Operations
X
The functions specified in 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 be
always an object in the package, so in the situation of C<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:
X
=over 7
X
=item FALSE
X
the order of arguments is as in the current operation.
X
=item TRUE
X
the arguments are reversed.
X
=item C<undef>
X
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.
X
=back
X
=head2 Calling Conventions for Unary Operations
X
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.
X
=head2 Overloadable Operations
X
The following symbols can be specified in C<use Overload>:
X
=over 5
X
=item * I<Arithmetic operations>
X
X "+", "+=", "-", "-=", "*", "*=", "/", "/=", "%", "%=",
X "**", "**=", "<<", "<<=", ">>", ">>=", "x", "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 operations "C<->" can be used to
autogenerate missing methods for unary minus or C<abs>.
X
=item * I<Comparison operations>
X
X "<", "<=", ">", ">=", "==", "!=", "<=>",
X "lt", "le", "gt", "ge", "eq", "ne", "cmp",
X
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>.
X
=item * I<Bit operations>
X
X "&", "^", "|", "neg", "!", "~",
X
"C<neg>" stands for unary minus. If the method for C<neg> is not
specified, it can be autogenerated using on the method for subtraction.
X
=item * I<Increment and decrement>
X
X "++", "--",
X
If undefined, addition and subtraction methods can be
used instead. These operations are called both in prefix and
postfix form.
X
=item * I<Transcendental functions>
X
X "atan2", "cos", "sin", "exp", "abs", "log", "sqrt",
X
If C<abs> is unavailable, it can be autogenerated using methods
for "<" or "<=>" combined with either unary minus or subtraction.
X
=item * I<Boolean, string and numeric conversion>
X
X "bool", "\"\"", "0+",
X
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.
X
=item * I<Special>
X
X "nomethod", "fallback", "=",
X
see L<SPECIAL SYMBOLS FOR C<use Overload>>.
X
=back
X
See L<"Fallback"> for an explanation of when a missing method can be autogenerated.
X
=head1 SPECIAL SYMBOLS FOR C<use Overload>
X
Three keys are recognized by Perl that are not covered by the above
description.
X
=head2 Last Resort
X
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 arguments for the corresponding method if
it were found, the fourth argument is the symbol for C<use Overload>
corresponding to the missing method. If several methods are tried,
the last one is used. Say, C<1-$a> can be equivalent to
X
X &nomethodMethod($a,1,1,"-")
X
if the pair C<"nomethod" =E<gt> "nomethodMethod"> was specified in the
C<use Overload> directive.
X
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.
X
=head2 Fallback
X
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
value of C<"fallback">:
X
=over 16
X
=item * C<undef>
X
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.
X
=item * TRUE
X
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.
X
=item * defined, but FALSE
X
No autogeneration is tried. Perl tries to call
C<"nomethod"> value, and if this is missing, raises an exception.
X
=back
X
=head2 Copy Constructor
X
Value for C<"="> is a reference to a function with three arguments,
i.e., it looks like a usual value in C<use Overload>. 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
X
X $a=$b;
X $a++;
X
To make this change to $a and not to change $b, a freshly made copy of
C<$$a> is made, and $a is assigned a reference to this object. This
operation is executed during C<$a++>, (so before this C<$$a> coincides
with C<$$b>), and only if C<++> is expressed via method for C<'++'> or
C<'+='>. Note that if this operation is expressed via C<'+'>,
i.e., as
X
X $a=$b;
X $a=$a+1;
X
then C<$$a> and C<$$b> do not appear as lvalues.
X
If the copy constructor is required during execution of some mutator,
but method for C<'='> was not specified, it can be autogenerated as a
string copy if an object of the package is a plain scalar.
X
=head1 MAGIC AUTOGENERATION
X
If a method for an operation is not found, and value for C<"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:
X
=over 16
X
=item I<Assignment forms of arithmetic operations>
X
C<$a=+$b> can use the method for C<"+"> if method for C<"+=">
is not defined.
X
=item I<Conversion operations>
X
String, numeric, and boolean conversion are calculated in terms of one
another if not all of them are defined.
X
=item I<Increment and decrement>
X
The C<++$a> operation can be expressed in terms of C<$a+=1> or C<$a+1>,
and C<$a--> in terms of C<$a-=1> and C<$a-1>.
X
=item C<abs($a)>
X
can be expressed in terms of C<$aE<lt>0> and C<-$a> (or C<0-$a>).
X
=item I<Unary minus>
X
can be expressed in terms of subtraction.
X
=item I<Concatenation>
X
can be expressed in terms of string conversion.
X
=item I<Comparison operations>
X
can be expressed in terms of its "spaceship" counterpart: either
C<E<lt>=E<gt>> or C<cmp>:
X
X <, >, <=, >=, ==, != in terms of <=>
X lt, gt, le, ge, eq, ne in terms of cmp
X
=item I<Copy operator>
X
can be expressed in terms of assignment to the dereferenced value, if this
value is scalar but not a reference.
X
=back
X
=head1 WARNING
X
The restriction for the comparison operation is that even if, for example,
`C<cmp>' should return a blessed reference, the autogenerated `C<lt>'
function will produce only a standard logical value based on the
numerical value of the result of `C<cmp>'. In particular, a working
numeric conversion is needed in this case (possibly expressed in terms of
other conversions).
X
Similarly, C<.=> and C<x=> operators lose their mathemagical properties
if the string conversion substitution is applied.
X
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.
X
=head1 Run-time Overloading
X
Since any C<use> directive is executed at compile-time, the only way to change overloading during run-time is to
X
X eval 'use Overload "+" => \&addmethod';
X
You can use also
X
X eval 'no Overload "+", "--", "<="';
X
while the utility of this construction during compile-time is questionable.
X
=head1 Public functions
X
Package C<Overload.pm> provides the following public functions:
X
=over 5
X
=item Overload::StrVal(arg)
X
Gives string value of C<arg> as in absence of stringify overloading.
X
=item Overload::Overloaded(arg)
X
Returns true if C<arg> is subject to overloading of some operations.
X
=item Overload::Method(obj,op)
X
Returns C<undef> or reference to method that implements C<op>.
X
=back
X
=head1 IMPLEMENTATION
X
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 due to
C<use Overload>, C<no Overload>, and @ISA only during
C<bless>ing; so if it is changed dynamically, you'll need an
additional fake C<bless>ing to update the table.
X
(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.)
X
If an object belongs to a package using Overload, it carries a special
flag. Thus the only speed penalty during arithmetic operations without
overload is the check of this flag.
X
In fact, if C<use Overload> is not present, 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 used, the current operation is overloadable but
the arguments in question do not belong to packages using Overload. When
in doubt, test your speed with C<use Overload> and without it. So far there
have been no reports of substantial speed degradation if Perl is compiled
with optimization turned on.
X
There is no size penalty for data if Overload is not used.
X
The copying like C<$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 C<$b++>. You can override this
behavior by defining your copy constructor (see L<"Copy Constructor">).
X
It is expected that arguments to methods that are not explicitly supposed
to be changed are constant (but this is not enforced).
X
=head1 AUTHOR
X
Ilya Zakharevich <F<ilya@math.mps.ohio-state.edu>>.
X
=head1 DIAGNOSTICS
X
When Perl is run with the B<-Do> switch or its equivalent, overloading
induces diagnostic messages.
X
=head1 BUGS
X
Because it's used for overloading, the per-package associative array
%OVERLOAD now has a special meaning in Perl.
X
As shipped, %OVERLOAD is not inherited via the @ISA tree.
X
This document is confusing.
X
SHAR_EOF
$shar_touch -am 0315154795 'pod/perlovl.pod' &&
chmod 0644 'pod/perlovl.pod' ||
echo 'restore of pod/perlovl.pod failed'
shar_count="`wc -c < 'pod/perlovl.pod'`"
test 12646 -eq "$shar_count" ||
echo "pod/perlovl.pod: original size 12646, current size $shar_count"
fi
exit 0
[Acked]
************ History ************
bugs 950315 000000 Submitted to NL.perl by ilya@math.ohio-state.edu (Ilya Zakharevich)