package overload;
-our $VERSION = '1.14';
+our $VERSION = '1.22';
+
+%ops = (
+ 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 int",
+ conversion => 'bool "" 0+ qr',
+ iterators => '<>',
+ filetest => "-X",
+ dereferencing => '${} @{} %{} &{} *{}',
+ matching => '~~',
+ special => 'nomethod fallback =',
+);
+
+my %ops_seen;
+for $category (keys %ops) {
+ $ops_seen{$_}++ for (split /\s+/, $ops{$category});
+}
sub nil {}
$package = shift;
my %arg = @_;
my ($sub, $fb);
- $ {$package . "::OVERLOAD"}{dummy}++; # Register with magic by touching.
- $fb = ${$package . "::()"}; # preserve old fallback value RT#68196
- *{$package . "::()"} = \&nil; # Make it findable via fetchmethod.
+ *{$package . "::(("} = \&nil; # Make it findable via fetchmethod.
for (keys %arg) {
if ($_ eq 'fallback') {
- $fb = $arg{$_};
+ for my $sym (*{$package . "::()"}) {
+ *$sym = \&nil; # Make it findable via fetchmethod.
+ $$sym = $arg{$_};
+ }
} else {
+ warnings::warnif("overload arg '$_' is invalid")
+ unless $ops_seen{$_};
$sub = $arg{$_};
- if (not ref $sub and $sub !~ /::/) {
+ if (not ref $sub) {
$ {$package . "::(" . $_} = $sub;
$sub = \&nil;
}
- #print STDERR "Setting `$ {'package'}::\cO$_' to \\&`$sub'.\n";
+ #print STDERR "Setting '$ {'package'}::\cO$_' to \\&'$sub'.\n";
*{$package . "::(" . $_} = \&{ $sub };
}
}
- ${$package . "::()"} = $fb; # Make it findable too (fallback only).
}
sub import {
sub unimport {
$package = (caller())[0];
- ${$package . "::OVERLOAD"}{dummy}++; # Upgrade the table
shift;
+ *{$package . "::(("} = \&nil;
for (@_) {
- if ($_ eq 'fallback') {
- undef $ {$package . "::()"};
- } else {
- delete $ {$package . "::"}{"(" . $_};
- }
+ warnings::warnif("overload arg '$_' is invalid")
+ unless $ops_seen{$_};
+ delete $ {$package . "::"}{$_ eq 'fallback' ? '()' : "(" .$_};
}
}
sub Overloaded {
my $package = shift;
$package = ref $package if ref $package;
- $package->can('()');
+ mycan ($package, '()') || mycan ($package, '((');
}
sub ov_method {
my $globref = shift;
return undef unless $globref;
my $sub = \&{*$globref};
- require Scalar::Util;
- return $sub
- if Scalar::Util::refaddr($sub) != Scalar::Util::refaddr(\&nil);
+ no overloading;
+ return $sub if !ref $sub or $sub != \&nil;
return shift->can($ {*$globref});
}
}
sub AddrRef {
- my $package = ref $_[0];
- return "$_[0]" unless $package;
-
- local $@;
- local $!;
- require Scalar::Util;
- my $class = Scalar::Util::blessed($_[0]);
- my $class_prefix = defined($class) ? "$class=" : "";
- my $type = Scalar::Util::reftype($_[0]);
- my $addr = Scalar::Util::refaddr($_[0]);
- return sprintf("%s%s(0x%x)", $class_prefix, $type, $addr);
+ no overloading;
+ "$_[0]";
}
*StrVal = *AddrRef;
'qr' => 0x10000, # HINT_NEW_RE
);
-%ops = ( 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 int",
- conversion => 'bool "" 0+ qr',
- iterators => '<>',
- filetest => "-X",
- dereferencing => '${} @{} %{} &{} *{}',
- matching => '~~',
- special => 'nomethod fallback =');
-
use warnings::register;
sub constant {
# Arguments: what, sub
last;
}
elsif (!exists $constants {$_ [0]}) {
- warnings::warnif ("`$_[0]' is not an overloadable type");
+ warnings::warnif ("'$_[0]' is not an overloadable type");
}
elsif (!ref $_ [1] || "$_[1]" !~ /(^|=)CODE\(0x[0-9a-f]+\)$/) {
# Can't use C<ref $_[1] eq "CODE"> above as code references can be
# blessed, and C<ref> would return the package the ref is blessed into.
if (warnings::enabled) {
$_ [1] = "undef" unless defined $_ [1];
- warnings::warn ("`$_[1]' is not a code reference");
+ warnings::warn ("'$_[1]' is not a code reference");
}
}
else {
case of a unary operator.
The third argument is set to TRUE if (and only if) the two
-operands have been swapped. Perl may do this to ensure that the
+operands have been swapped. Perl may do this to ensure that the
first argument (C<$self>) is an object implementing the overloaded
operation, in line with general object calling conventions.
For example, if C<$x> and C<$y> are C<Number>s:
according to the rules for L<Magic Autogeneration> described later.
For example, the C<use overload> above declared no subroutine
for any of the operators C<-->, C<neg> (the overload key for
-unary minus), or C<-=>. Thus
+unary minus), or C<-=>. Thus
operation | generates a call to
============|======================
Exceptions, including additional overloadable operations not
apparent from this hash, are included in the notes which follow.
+A warning is issued if an attempt is made to register an operator not found
+above.
+
=over 5
=item * C<not>
the operation will be called again with this value.
As a special case if the overload returns the object itself then it will
-be used directly. An overloaded conversion returning the object is
+be used directly. An overloaded conversion returning the object is
probably a bug, because you're likely to get something that looks like
C<YourPackage=HASH(0x8172b34)>.
for both the I<read-filehandle> syntax C<E<lt>$varE<gt>> and
I<globbing> syntax C<E<lt>${var}E<gt>>.
-B<BUGS> Even in list context, the iterator is currently called only
-once and with scalar context.
-
=item * I<File tests>
The key C<'-X'> is used to specify a subroutine to handle all the
is used to pass the second operand).
Calling an overloaded filetest operator does not affect the stat value
-associated with the special filehandle C<_>. It still refers to the
+associated with the special filehandle C<_>. It still refers to the
result of the last C<stat>, C<lstat> or unoverloaded filetest.
This overload was introduced in Perl 5.12.
The key C<"~~"> allows you to override the smart matching logic used by
the C<~~> operator and the switch construct (C<given>/C<when>). See
-L<perlsyn/Switch statements> and L<feature>.
+L<perlsyn/Switch Statements> and L<feature>.
Unusually, the overloaded implementation of the smart match operator
does not get full control of the smart match behaviour.
$obj->match(2,0);
$obj->match(3,0);
-Consult the match table in L<perlsyn/"Smart matching in detail"> for
+Consult the match table in L<perlop/"Smartmatch Operator"> for
details of when overloading is invoked.
=item * I<Dereferencing>
a minimal set of operations that need to be overloaded in order to have
the complete set of overloaded operations at one's disposal.
Of course, the autogenerated operations may not do exactly what the user
-expects. The minimal set is:
+expects. The minimal set is:
+ - * / % ** << >> x
<=> cmp
The subroutine for C<'='> does not overload the Perl assignment
operator: it is used only to allow mutators to work as described
-here. (See L</Assignments> above.)
+here. (See L</Assignments> above.)
=item *
There are exceptions to the above rules for dereference operations
(which, if Step 1 fails, always fall back to the normal, built-in
implementations - see Dereferencing), and for C<~~> (which has its
-own set of rules - see L<Matching>).
+own set of rules - see C<Matching> under L</Overloadable Operations>
+above).
Note on Step 7: some operators have a different semantic depending
on the type of their operands.
=head2 Losing Overloading
The restriction for the comparison operation is that even if, for example,
-`C<cmp>' should return a blessed reference, the autogenerated `C<lt>'
+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
+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).
=back
-Note that since the value of the C<fallback> key is not a subroutine,
-its inheritance is not governed by the above rules. In the current
-implementation, the value of C<fallback> in the first overloaded
-ancestor is used, but this is accidental and subject to change.
+Note that in Perl version prior to 5.18 inheritance of the C<fallback> key
+was not governed by the above rules. The value of C<fallback> in the first
+overloaded ancestor was used. This was fixed in 5.18 to follow the usual
+rules of inheritance.
=head2 Run-time Overloading
=item overload::StrVal(arg)
-Gives string value of C<arg> as in absence of stringify overloading. If you
+Gives the string value of C<arg> as in the
+absence of stringify overloading. If you
are using this to get the address of a reference (useful for checking if two
references point to the same thing) then you may be better off using
C<Scalar::Util::refaddr()>, which is faster.
and overload::remove_constant() from anywhere but import() and unimport() methods.
From these methods they may be called as
- sub import {
- shift;
- return unless @_;
- die "unknown import: @_" unless @_ == 1 and $_[0] eq ':constant';
- overload::constant integer => sub {Math::BigInt->new(shift)};
- }
+ sub import {
+ shift;
+ return unless @_;
+ die "unknown import: @_" unless @_ == 1 and $_[0] eq ':constant';
+ overload::constant integer => sub {Math::BigInt->new(shift)};
+ }
=head1 IMPLEMENTATION
The table of methods for all operations is cached in magic for the
symbol table hash for the package. The cache is invalidated during
processing of C<use overload>, C<no overload>, new function
-definitions, and changes in @ISA. However, this invalidation remains
-unprocessed until the next C<bless>ing into the package. Hence if you
-want to change overloading structure dynamically, you'll need an
-additional (fake) C<bless>ing to update the table.
+definitions, and changes in @ISA.
(Every SVish thing has a magic queue, and 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. However, the magic which implements overloading is applied to
+magic. However, the magic which implements overloading is applied to
the stashes, which are rarely used directly, thus should not slow down
Perl.)
-If an object belongs to a package using overload, it carries a special
-flag. Thus the only speed penalty during arithmetic operations without
-overloading is the checking of this flag.
-
-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. A considerable effort was made to
-minimize the overhead when overload is used in some package, 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.
-
-There is no size penalty for data if overload is not used. The only
-size penalty if overload is used in some package is that I<all> the
-packages acquire a magic during the next C<bless>ing into the
-package. This magic is three-words-long for packages without
-overloading, and carries the cache table if the package is overloaded.
+If a package uses overload, it carries a special flag. This flag is also
+set when new function are defined or @ISA is modified. There will be a
+slight speed penalty on the very first operation thereafter that supports
+overloading, while the overload tables are updated. If there is no
+overloading present, the flag is turned off. Thus the only speed penalty
+thereafter is the checking of this flag.
It is expected that arguments to methods that are not explicitly supposed
to be changed are constant (but this is not enforced).
require two_face;
my $seven = two_face->new("vii", 7);
printf "seven=$seven, seven=%d, eight=%d\n", $seven, $seven+1;
- print "seven contains `i'\n" if $seven =~ /i/;
+ print "seven contains 'i'\n" if $seven =~ /i/;
(The second line creates a scalar which has both a string value, and a
numeric value.) This prints:
seven=vii, seven=7, eight=8
- seven contains `i'
+ seven contains 'i'
=head2 Two-face References
This module is very unusual as overloaded modules go: it does not
provide any usual overloaded operators, instead it provides an
-implementation for L<C<nomethod>>. In this example the C<nomethod>
+implementation for L</C<nomethod>>. In this example the C<nomethod>
subroutine returns an object which encapsulates operations done over
the objects: C<< symbolic->new(3) >> contains C<['n', 3]>, C<< 2 +
symbolic->new(3) >> contains C<['+', 2, ['n', 3]]>.
my $cnt = $iter;
while ($cnt) {
- $cnt = $cnt - 1; # Mutator `--' not implemented
+ $cnt = $cnt - 1; # Mutator '--' not implemented
$side = (sqrt(1 + $side**2) - 1)/$side;
}
printf "%s=%f\n", $side, $side;
$subr{$op} = eval "sub {shift() $op shift()}";
}
foreach my $op (split " ", "@overload::ops{qw(unary func)}") {
- print "defining `$op'\n";
+ print "defining '$op'\n";
$subr{$op} = eval "sub {$op shift()}";
}
Using the C<m> command of Perl debugger (see L<perldebug>) one can
deduce which operations are overloaded (and which ancestor triggers
-this overloading). Say, if C<eq> is overloaded, then the method C<(eq>
-is shown by debugger. The method C<()> corresponds to the C<fallback>
+this overloading). Say, if C<eq> is overloaded, then the method C<(eq>
+is shown by debugger. The method C<()> corresponds to the C<fallback>
key (in fact a presence of this method shows that this package has
overloading enabled, and it is what is used by the C<Overloaded>
function of module C<overload>).
(W) The call to overload::constant contained an odd number of arguments.
The arguments should come in pairs.
-=item `%s' is not an overloadable type
+=item '%s' is not an overloadable type
(W) You tried to overload a constant type the overload package is unaware of.
-=item `%s' is not a code reference
+=item '%s' is not a code reference
(W) The second (fourth, sixth, ...) argument of overload::constant needs
-to be a code reference. Either an anonymous subroutine, or a reference
+to be a code reference. Either an anonymous subroutine, or a reference
to a subroutine.
+=item overload arg '%s' is invalid
+
+(W) C<use overload> was passed an argument it did not
+recognize. Did you mistype an operator?
+
=back
=head1 BUGS AND PITFALLS
=item *
-No warning is issued for invalid C<use overload> keys.
-Such errors are not always obvious:
-
- use overload "+0" => sub { ...; }, # should be "0+"
- "not" => sub { ...; }; # should be "!"
-
-(Bug #74098)
-
-=item *
-
A pitfall when fallback is TRUE and Perl resorts to a built-in
implementation of an operator is that some operators have more
than one semantic, for example C<|>:
=item *
-Because it is used for overloading, the per-package hash
-C<%OVERLOAD> now has a special meaning in Perl.
The symbol table is filled with names looking like line-noise.
=item *
+This bug was fixed in Perl 5.18, but may still trip you up if you are using
+older versions:
+
For the purpose of inheritance every overloaded package behaves as if
-C<fallback> is present (possibly undefined). This may create
+C<fallback> is present (possibly undefined). This may create
interesting effects if some package is not overloaded, but inherits
from two overloaded packages.
=item *
Before Perl 5.14, the relation between overloading and tie()ing was broken.
-Overloading
is triggered or not basing on the I<previous> class of the
+Overloading
was triggered or not based on the I<previous> class of the
tie()d variable.
This happened because the presence of overloading was checked
Barewords are not covered by overloaded string constants.
+=item *
+
+The range operator C<..> cannot be overloaded.
+
=back
=cut
https://perl5.git.perl.org / perl5.git / blobdiff