package overload;
-our $VERSION = '1.03';
-
-$overload::hint_bits = 0x20000; # HINT_LOCALIZE_HH
+our $VERSION = '1.11';
sub nil {}
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.
for (keys %arg) {
if ($_ eq 'fallback') {
my $globref = shift;
return undef unless $globref;
my $sub = \&{*$globref};
- return $sub if $sub ne \&nil;
+ require Scalar::Util;
+ return $sub
+ if Scalar::Util::refaddr($sub) != Scalar::Util::refaddr(\&nil);
return shift->can($ {*$globref});
}
sub Method {
my $package = shift;
- $package = ref $package if ref $package;
+ if(ref $package) {
+ local $@;
+ local $!;
+ require Scalar::Util;
+ $package = Scalar::Util::blessed($package);
+ return undef if !defined $package;
+ }
#my $meth = $package->can('(' . shift);
ov_method mycan($package, '(' . shift), $package;
#return $meth if $meth ne \&nil;
my $package = ref $_[0];
return "$_[0]" unless $package;
- 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("$class_prefix$type(0x%x)", $addr);
+ 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);
}
*StrVal = *AddrRef;
sub mycan { # Real can would leave stubs.
my ($package, $meth) = @_;
- return \*{$package . "::$meth"} if defined &{$package . "::$meth"};
- my $p;
- foreach $p (@{$package . "::ISA"}) {
- my $out = mycan($p, $meth);
- return $out if $out;
+
+ local $@;
+ local $!;
+ require mro;
+
+ my $mro = mro::get_linear_isa($package);
+ foreach my $p (@$mro) {
+ my $fqmeth = $p . q{::} . $meth;
+ return \*{$fqmeth} if defined &{$fqmeth};
}
+
return undef;
}
num_comparison => "< <= > >= == !=",
'3way_comparison'=> "<=> cmp",
str_comparison => "lt le gt ge eq ne",
- binary => "& | ^",
+ binary => '& &= | |= ^ ^=',
unary => "neg ! ~",
mutators => '++ --',
func => "atan2 cos sin exp abs log sqrt int",
- conversion => 'bool "" 0+',
+ conversion => 'bool "" 0+ qr',
iterators => '<>',
+ filetest => "-X",
dereferencing => '${} @{} %{} &{} *{}',
+ matching => '~~',
special => 'nomethod fallback =');
use warnings::register;
elsif (!exists $constants {$_ [0]}) {
warnings::warnif ("`$_[0]' is not an overloadable type");
}
- elsif (!ref $_ [1] || "$_[1]" !~ /CODE\(0x[\da-f]+\)$/) {
+ 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) {
}
else {
$^H{$_[0]} = $_[1];
- $^H |= $constants{$_[0]} | $overload::hint_bits;
+ $^H |= $constants{$_[0]};
}
shift, shift;
}
...
package main;
- $a = new SomeThing 57;
+ $a = SomeThing->new( 57 );
$b=5+$a;
...
if (overload::Overloaded $b) {...}
=head1 DESCRIPTION
+This pragma allows overloading of Perl's operators for a class.
+To overload built-in functions, see L<perlsub/Overriding Built-in Functions> instead.
+
=head2 Declaration of overloaded functions
The compilation directive
=item * I<Bit operations>
- "&", "^", "|", "neg", "!", "~",
+ "&", "&=", "^", "^=", "|", "|=", "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. If the method for C<!> is not specified, it can be
autogenerated using the methods for C<bool>, or C<"">, or C<0+>.
+The same remarks in L<"Arithmetic operations"> about
+assignment-variants and autogeneration apply for
+bit operations C<"&">, C<"^">, and C<"|"> as well.
+
=item * I<Increment and decrement>
"++", "--",
C<int> is unavailable, it can be autogenerated using the overloading of
C<0+>.
-=item * I<Boolean, string and numeric conversion>
+=item * I<Boolean, string, numeric and regexp conversions>
- 'bool', '""', '0+',
+ 'bool', '""', '0+', 'qr'
-If one or two of these operations are not overloaded, 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.
+If one or two of these operations are not overloaded, 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; C<qr> is used for
+the RHS of C<=~> and when an object is interpolated into a regexp.
+
+C<bool>, C<"">, and C<0+> 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. C<qr> must return a compiled
+regexp, or a ref to a compiled regexp (such as C<qr//> returns), and any
+further overloading on the return value will be ignored.
As a special case if the overload returns the object itself then it will
be used directly. An overloaded conversion returning the object is
B<BUGS> Even in list context, the iterator is currently called only
once and with scalar context.
+=item * I<File tests>
+
+ "-X"
+
+This overload is used for all the filetest operators (C<-f>, C<-x> and
+so on: see L<perlfunc/-X> for the full list). Even though these are
+unary operators, the method will be called with a second argument which
+is a single letter indicating which test was performed. Note that the
+overload key is the literal string C<"-X">: you can't provide separate
+overloads for the different tests.
+
+Calling an overloaded filetest operator does not affect the stat value
+associated with the special filehandle C<_>. It still refers to the
+result of the last C<stat>, C<lstat> or unoverloaded filetest.
+
+If not overloaded, these operators will fall back to the default
+behaviour even without C<< fallback => 1 >>. This means that if the
+object is a blessed glob or blessed IO ref it will be treated as a
+filehandle, otherwise string overloading will be invoked and the result
+treated as a filename.
+
+This overload was introduced in perl 5.12.
+
+=item * I<Matching>
+
+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> and L<feature>.
+
+Unusually, overloading of the smart match operator does not automatically
+take precedence over normal smart match behaviour. In particular, in the
+following code:
+
+ package Foo;
+ use overload '~~' => 'match';
+
+ my $obj = Foo->new();
+ $obj ~~ [ 1,2,3 ];
+
+the smart match does I<not> invoke the method call like this:
+
+ $obj->match([1,2,3],0);
+
+rather, the smart match distributive rule takes precedence, so $obj is
+smart matched against each array element in turn until a match is found,
+so you may see between one and three of these calls instead:
+
+ $obj->match(1,0);
+ $obj->match(2,0);
+ $obj->match(3,0);
+
+Consult the match table in L<perlsyn/"Smart matching in detail"> for
+details of when overloading is invoked.
+
=item * I<Dereferencing>
'${}', '@{}', '%{}', '&{}', '*{}'.
=item * I<Special>
- "nomethod", "fallback", "=",
+ "nomethod", "fallback", "=".
see L<SPECIAL SYMBOLS FOR C<use overload>>.
num_comparison => '< <= > >= == !=',
'3way_comparison'=> '<=> cmp',
str_comparison => 'lt le gt ge eq ne',
- binary => '& | ^',
+ binary => '& &= | |= ^ ^=',
unary => 'neg ! ~',
mutators => '++ --',
func => 'atan2 cos sin exp abs log sqrt',
- conversion => 'bool "" 0+',
+ conversion => 'bool "" 0+ qr',
iterators => '<>',
+ filetest => '-X',
dereferencing => '${} @{} %{} &{} *{}',
+ matching => '~~',
special => 'nomethod fallback ='
=head2 Inheritance and overloading
If the copy constructor is required during the execution of some mutator,
but a method for C<'='> was not specified, it can be autogenerated as a
-string copy if the object is a plain scalar.
+string copy if the object is a plain scalar or a simple assignment if it
+is not.
=over 5
=item I<Conversion operations>
-String, numeric, and boolean conversion are calculated in terms of one
-another if not all of them are defined.
+String, numeric, boolean and regexp conversions are calculated in terms
+of one another if not all of them are defined.
=item I<Increment and decrement>
=item I<Copy operator>
can be expressed in terms of an assignment to the dereferenced value, if this
-value is a scalar and not a reference.
+value is a scalar and not a reference, or simply a reference assignment
+otherwise.
=back
+=head1 Minimal set of overloaded operations
+
+Since some operations can be automatically generated from others, there is
+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. See L<MAGIC AUTOGENERATION> above. The minimal set is:
+
+ + - * / % ** << >> x
+ <=> cmp
+ & | ^ ~
+ atan2 cos sin exp log sqrt int
+
+Additionally, you need to define at least one of string, boolean or
+numeric conversions because any one can be used to emulate the others.
+The string conversion can also be used to emulate concatenation.
+
=head1 Losing overloading
The restriction for the comparison operation is that even if, for example,
=head1 Overloading constants
For some applications, the Perl parser mangles constants too much.
-It is possible to hook into this process via the C<overload::constant()>
+It is possible to hook into this process via C<overload::constant()>
and C<overload::remove_constant()> functions.
These functions take a hash as an argument. The recognized keys of this hash
overload::constant integer => sub {Math::BigInt->new(shift)};
}
-B<BUGS> Currently overloaded-ness of constants does not propagate
-into C<eval '...'>.
-
=head1 IMPLEMENTATION
What follows is subject to change RSN.
one may need to I<explicitly unlink> other values which references the
same value:
- $a = new Data 23;
+ $a = Data->new(23);
...
$b = $a; # $b is "linked" to $a
...
Note that overloaded access makes this transparent:
- $a = new Data 23;
+ $a = Data->new(23);
$b = $a; # $b is "linked" to $a
$a += 4; # would unlink $b automagically
However, it would not make
- $a = new Data 23;
+ $a = Data->new(23);
$a = 4; # Now $a is a plain 4, not 'Data'
preserve "objectness" of $a. But Perl I<has> a way to make assignments
Use it as follows:
require two_face;
- my $seven = new two_face ("vii", 7);
+ 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/;
Now one can access an object using both the array and hash syntax:
- my $bar = new two_refs 3,4,5,6;
+ my $bar = two_refs->new(3,4,5,6);
$bar->[2] = 11;
$bar->{two} == 11 or die 'bad hash fetch';
provide any usual overloaded operators, instead it provides the L<Last
Resort> operator C<nomethod>. In this example the corresponding
subroutine returns an object which encapsulates operations done over
-the objects: C<new symbolic 3> contains C<['n', 3]>, C<2 + new
-symbolic 3> contains C<['+', 2, ['n', 3]]>.
+the objects: C<< symbolic->new(3) >> contains C<['n', 3]>, C<< 2 +
+symbolic->new(3) >> contains C<['+', 2, ['n', 3]]>.
Here is an example of the script which "calculates" the side of
circumscribed octagon using the above package:
require symbolic;
my $iter = 1; # 2**($iter+2) = 8
- my $side = new symbolic 1;
+ my $side = symbolic->new(1);
my $cnt = $iter;
while ($cnt--) {
Note that while we obtained this value using a nice little script,
there is no simple way to I<use> this value. In fact this value may
-be inspected in debugger (see L<perldebug>), but ony if
+be inspected in debugger (see L<perldebug>), but only if
C<bareStringify> B<O>ption is set, and not via C<p> command.
If one attempts to print this value, then the overloaded operator
Use this module like this:
require symbolic;
- my $iter = new symbolic 2; # 16-gon
- my $side = new symbolic 1;
+ my $iter = symbolic->new(2); # 16-gon
+ my $side = symbolic->new(1);
my $cnt = $iter;
while ($cnt) {
to the package C<symbolic>. After this change one can do
- my $a = new symbolic 3;
- my $b = new symbolic 4;
+ my $a = symbolic->new(3);
+ my $b = symbolic->new(4);
my $c = sqrt($a**2 + $b**2);
and the numeric value of $c becomes 5. However, after calling
Ilya Zakharevich E<lt>F<ilya@math.mps.ohio-state.edu>E<gt>.
+=head1 SEE ALSO
+
+The L<overloading> pragma can be used to enable or disable overloaded
+operations within a lexical scope.
+
=head1 DIAGNOSTICS
When Perl is run with the B<-Do> switch or its equivalent, overloading
https://perl5.git.perl.org / perl5.git / blobdiff