X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/ca6102577e2112f9ab35a6504913f9234b4e8af7..b05fd80e8a75b8bba137db6cd6688f7aa8a0ec39:/lib/overload.pm diff --git a/lib/overload.pm b/lib/overload.pm index a2797e7..51801d6 100644 --- a/lib/overload.pm +++ b/lib/overload.pm @@ -1,6 +1,6 @@ package overload; -our $VERSION = '1.17'; +our $VERSION = '1.22'; %ops = ( with_assign => "+ - * / % ** << >> x .", @@ -31,17 +31,18 @@ sub OVERLOAD { $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; } @@ -49,7 +50,6 @@ sub OVERLOAD { *{$package . "::(" . $_} = \&{ $sub }; } } - ${$package . "::()"} = $fb; # Make it findable too (fallback only). } sub import { @@ -61,21 +61,19 @@ 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; - mycan ($package, '()'); + mycan ($package, '()') || mycan ($package, '(('); } sub ov_method { @@ -113,17 +111,8 @@ sub Method { } 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; @@ -272,7 +261,7 @@ The second argument is the other operand, or C in the 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 Cs: @@ -288,7 +277,7 @@ have not been specified in the C directive, according to the rules for L described later. For example, the C above declared no subroutine for any of the operators C<-->, C (the overload key for -unary minus), or C<-=>. Thus +unary minus), or C<-=>. Thus operation | generates a call to ============|====================== @@ -487,7 +476,7 @@ If the corresponding operation for this value is overloaded too, 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. @@ -507,9 +496,6 @@ If CE> is overloaded then the same implementation is used for both the I syntax C$varE> and I syntax C${var}E>. -B Even in list context, the iterator is currently called only -once and with scalar context. - =item * I The key C<'-X'> is used to specify a subroutine to handle all the @@ -521,7 +507,7 @@ second argument (that is, in the slot that for binary operators 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, C or unoverloaded filetest. This overload was introduced in Perl 5.12. @@ -678,7 +664,7 @@ 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. The minimal set is: +expects. The minimal set is: + - * / % ** << >> x <=> cmp @@ -778,7 +764,7 @@ Note: 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 above.) +here. (See L above.) =item * @@ -945,10 +931,10 @@ be called to implement operation C<+> for an object in package C. =back -Note that since the value of the C key is not a subroutine, -its inheritance is not governed by the above rules. In the current -implementation, the value of C 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 key +was not governed by the above rules. The value of C in the first +overloaded ancestor was used. This was fixed in 5.18 to follow the usual +rules of inheritance. =head2 Run-time Overloading @@ -971,7 +957,8 @@ Package C provides the following public functions: =item overload::StrVal(arg) -Gives string value of C as in absence of stringify overloading. If you +Gives the string value of C 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, which is faster. @@ -1042,12 +1029,12 @@ Note that it is probably meaningless to call the functions overload::constant() 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 @@ -1056,37 +1043,22 @@ What follows is subject to change RSN. 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, C, new function -definitions, and changes in @ISA. However, this invalidation remains -unprocessed until the next Cing into the package. Hence if you -want to change overloading structure dynamically, you'll need an -additional (fake) Cing 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 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 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 the -packages acquire a magic during the next Cing 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). @@ -1259,7 +1231,7 @@ Put this in F in your Perl library directory: This module is very unusual as overloaded modules go: it does not provide any usual overloaded operators, instead it provides an -implementation for L>. In this example the C +implementation for L>. In this example the C 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]]>. @@ -1579,8 +1551,8 @@ induces diagnostic messages. Using the C command of Perl debugger (see L) one can deduce which operations are overloaded (and which ancestor triggers -this overloading). Say, if C is overloaded, then the method C<(eq> -is shown by debugger. The method C<()> corresponds to the C +this overloading). Say, if C is overloaded, then the method C<(eq> +is shown by debugger. The method C<()> corresponds to the C key (in fact a presence of this method shows that this package has overloading enabled, and it is what is used by the C function of module C). @@ -1601,9 +1573,14 @@ The arguments should come in pairs. =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 was passed an argument it did not +recognize. Did you mistype an operator? + =back =head1 BUGS AND PITFALLS @@ -1612,16 +1589,6 @@ to a subroutine. =item * -No warning is issued for invalid C 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<|>: @@ -1678,21 +1645,22 @@ may be optimized to =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 is present (possibly undefined). This may create +C 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 class of the +Overloading was triggered or not based on the I class of the tie()d variable. This happened because the presence of overloading was checked @@ -1707,6 +1675,10 @@ coincides with the current one. Barewords are not covered by overloaded string constants. +=item * + +The range operator C<..> cannot be overloaded. + =back =cut