package overload;
-our $VERSION = '1.07';
+our $VERSION = '1.31';
+
+%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;
+@ops_seen{ map split(/ /), values %ops } = ();
sub nil {}
sub OVERLOAD {
$package = shift;
my %arg = @_;
- my ($sub, $fb);
- $ {$package . "::OVERLOAD"}{dummy}++; # Register with magic by touching.
- *{$package . "::()"} = \&nil; # Make it findable via fetchmethod.
+ my $sub;
+ *{$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 exists $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 exists $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};
- return $sub if $sub ne \&nil;
+ no overloading;
+ return $sub if $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("$class_prefix$type(0x%x)", $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+',
- iterators => '<>',
- dereferencing => '${} @{} %{} &{} *{}',
- 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[\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) {
$_ [1] = "undef" unless defined $_ [1];
- warnings::warn ("`$_[1]' is not a code reference");
+ warnings::warn ("'$_[1]' is not a code reference");
}
}
else {
...
package main;
- $a = new SomeThing 57;
- $b=5+$a;
+ $a = SomeThing->new( 57 );
+ $b = 5 + $a;
...
if (overload::Overloaded $b) {...}
...
=head1 DESCRIPTION
-=head2 Declaration of overloaded functions
-
-The compilation directive
-
- package Number;
- use overload
- "+" => \&add,
- "*=" => "muas";
+This pragma allows overloading of Perl's operators for a class.
+To overload built-in functions, see L<perlsub/Overriding Built-in Functions> instead.
-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.
+=head2 Fundamentals
-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. Note that values specified as strings are
-interpreted as methods, not subroutines. Legal keys are listed below.
+=head3 Declaration
-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.)
+Arguments of the C<use overload> directive are (key, value) pairs.
+For the full set of legal keys, see L</Overloadable Operations> below.
-Since overloading respects inheritance via the @ISA hierarchy, the
-above declaration would also trigger overloading of C<+> and C<*=> in
-all the packages which inherit from C<Number>.
+Operator implementations (the values) can be subroutines,
+references to subroutines, or anonymous subroutines
+- in other words, anything legal inside a C<&{ ... }> call.
+Values specified as strings are interpreted as method names.
+Thus
-=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
+ package Number;
+ use overload
+ "-" => "minus",
+ "*=" => \&muas,
+ '""' => sub { ...; };
-the arguments are reversed.
+declares that subtraction is to be implemented by method C<minus()>
+in the class C<Number> (or one of its base classes),
+and that the function C<Number::muas()> is to be used for the
+assignment form of multiplication, C<*=>.
+It also defines an anonymous subroutine to implement stringification:
+this is called whenever an object blessed into the package C<Number>
+is used in a string context (this subroutine might, for example,
+return the number as a Roman numeral).
-=item C<undef>
+=head3 Calling Conventions and Magic Autogeneration
-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. Compare
-L<Calling Conventions for Mutators>.
+The following sample implementation of C<minus()> (which assumes
+that C<Number> objects are simply blessed references to scalars)
+illustrates the calling conventions:
-=back
+ package Number;
+ sub minus {
+ my ($self, $other, $swap) = @_;
+ my $result = $$self - $other; # *
+ $result = -$result if $swap;
+ ref $result ? $result : bless \$result;
+ }
+ # * may recurse once - see table below
+
+Three arguments are passed to all subroutines specified in the
+C<use overload> directive (with exceptions - see below, particularly
+L</nomethod>).
+
+The first of these is the operand providing the overloaded
+operator implementation -
+in this case, the object whose C<minus()> method is being called.
+
+The second argument is the other operand, or C<undef> 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
+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:
+
+ operation | generates a call to
+ ============|======================
+ $x - $y | minus($x, $y, '')
+ $x - 7 | minus($x, 7, '')
+ 7 - $x | minus($x, 7, 1)
+
+Perl may also use C<minus()> to implement other operators which
+have not been specified in the C<use overload> directive,
+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
+
+ operation | generates a call to
+ ============|======================
+ -$x | minus($x, 0, 1)
+ $x-- | minus($x, 1, undef)
+ $x -= 3 | minus($x, 3, undef)
+
+Note the C<undef>s:
+where autogeneration results in the method for a standard
+operator which does not change either of its operands, such
+as C<->, being used to implement an operator which changes
+the operand ("mutators": here, C<--> and C<-=>),
+Perl passes undef as the third argument.
+This still evaluates as FALSE, consistent with the fact that
+the operands have not been swapped, but gives the subroutine
+a chance to alter its behaviour in these cases.
+
+In all the above examples, C<minus()> is required
+only to return the result of the subtraction:
+Perl takes care of the assignment to $x.
+In fact, such methods should I<not> modify their operands,
+even if C<undef> is passed as the third argument
+(see L</Overloadable Operations>).
+
+The same is not true of implementations of C<++> and C<-->:
+these are expected to modify their operand.
+An appropriate implementation of C<--> might look like
+
+ use overload '--' => "decr",
+ # ...
+ sub decr { --${$_[0]}; }
+
+If the "bitwise" feature is enabled (see L<feature>), a fifth
+TRUE argument is passed to subroutines handling C<&>, C<|>, C<^> and C<~>.
+This indicates that the caller is expecting numeric behaviour. The fourth
+argument will be C<undef>, as that position (C<$_[3]>) is reserved for use
+by L</nomethod>.
+
+=head3 Mathemagic, Mutators, and Copy Constructors
+
+The term 'mathemagic' describes the overloaded implementation
+of mathematical operators.
+Mathemagical operations raise an issue.
+Consider the code:
+
+ $a = $b;
+ --$a;
+
+If C<$a> and C<$b> are scalars then after these statements
+
+ $a == $b - 1
+
+An object, however, is a reference to blessed data, so if
+C<$a> and C<$b> are objects then the assignment C<$a = $b>
+copies only the reference, leaving C<$a> and C<$b> referring
+to the same object data.
+One might therefore expect the operation C<--$a> to decrement
+C<$b> as well as C<$a>.
+However, this would not be consistent with how we expect the
+mathematical operators to work.
+
+Perl resolves this dilemma by transparently calling a copy
+constructor before calling a method defined to implement
+a mutator (C<-->, C<+=>, and so on.).
+In the above example, when Perl reaches the decrement
+statement, it makes a copy of the object data in C<$a> and
+assigns to C<$a> a reference to the copied data.
+Only then does it call C<decr()>, which alters the copied
+data, leaving C<$b> unchanged.
+Thus the object metaphor is preserved as far as possible,
+while mathemagical operations still work according to the
+arithmetic metaphor.
+
+Note: the preceding paragraph describes what happens when
+Perl autogenerates the copy constructor for an object based
+on a scalar.
+For other cases, see L</Copy Constructor>.
-=head2 Calling Conventions for Unary Operations
+=head2 Overloadable 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.
+The complete list of keys that can be specified in the C<use overload>
+directive are given, separated by spaces, in the values of the
+hash C<%overload::ops>:
-=head2 Calling Conventions for Mutators
+ 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 ='
-Two types of mutators have different calling conventions:
+Most of the overloadable operators map one-to-one to these keys.
+Exceptions, including additional overloadable operations not
+apparent from this hash, are included in the notes which follow.
+This list is subject to growth over time.
-=over
+A warning is issued if an attempt is made to register an operator not found
+above.
-=item C<++> and C<-->
+=over 5
-The routines which implement these operators are expected to actually
-I<mutate> their arguments. So, assuming that $obj is a reference to a
-number,
+=item * C<not>
- sub incr { my $n = $ {$_[0]}; ++$n; $_[0] = bless \$n}
+The operator C<not> is not a valid key for C<use overload>.
+However, if the operator C<!> is overloaded then the same
+implementation will be used for C<not>
+(since the two operators differ only in precedence).
-is an appropriate implementation of overloaded C<++>. Note that
+=item * C<neg>
- sub incr { ++$ {$_[0]} ; shift }
+The key C<neg> is used for unary minus to disambiguate it from
+binary C<->.
-is OK if used with preincrement and with postincrement. (In the case
-of postincrement a copying will be performed, see L<Copy Constructor>.)
+=item * C<++>, C<-->
-=item C<x=> and other assignment versions
+Assuming they are to behave analogously to Perl's C<++> and C<-->,
+overloaded implementations of these operators are required to
+mutate their operands.
-There is nothing special about these methods. They may change the
-value of their arguments, and may leave it as is. The result is going
-to be assigned to the value in the left-hand-side if different from
-this value.
+No distinction is made between prefix and postfix forms of the
+increment and decrement operators: these differ only in the
+point at which Perl calls the associated subroutine when
+evaluating an expression.
-This allows for the same method to be used as overloaded C<+=> and
-C<+>. Note that this is I<allowed>, but not recommended, since by the
-semantic of L<"Fallback"> Perl will call the method for C<+> anyway,
-if C<+=> is not overloaded.
+=item * I<Assignments>
-=back
+ += -= *= /= %= **= <<= >>= x= .=
+ &= |= ^= &.= |.= ^.=
-B<Warning.> Due to the presence of assignment versions of operations,
-routines which may be called in assignment context may create
-self-referential structures. Currently Perl will not free self-referential
-structures until cycles are C<explicitly> broken. You may get problems
-when traversing your structures too.
+Simple assignment is not overloadable (the C<'='> key is used
+for the L</Copy Constructor>).
+Perl does have a way to make assignments to an object do whatever
+you want, but this involves using tie(), not overload -
+see L<perlfunc/tie> and the L</COOKBOOK> examples below.
-Say,
+The subroutine for the assignment variant of an operator is
+required only to return the result of the operation.
+It is permitted to change the value of its operand
+(this is safe because Perl calls the copy constructor first),
+but this is optional since Perl assigns the returned value to
+the left-hand operand anyway.
- use overload '+' => sub { bless [ \$_[0], \$_[1] ] };
+An object that overloads an assignment operator does so only in
+respect of assignments to that object.
+In other words, Perl never calls the corresponding methods with
+the third argument (the "swap" argument) set to TRUE.
+For example, the operation
-is asking for trouble, since for code C<$obj += $foo> the subroutine
-is called as C<$obj = add($obj, $foo, undef)>, or C<$obj = [\$obj,
-\$foo]>. If using such a subroutine is an important optimization, one
-can overload C<+=> explicitly by a non-"optimized" version, or switch
-to non-optimized version if C<not defined $_[2]> (see
-L<Calling Conventions for Binary Operations>).
+ $a *= $b
-Even if no I<explicit> assignment-variants of operators are present in
-the script, they may be generated by the optimizer. Say, C<",$obj,"> or
-C<',' . $obj . ','> may be both optimized to
+cannot lead to C<$b>'s implementation of C<*=> being called,
+even if C<$a> is a scalar.
+(It can, however, generate a call to C<$b>'s method for C<*>).
- my $tmp = ',' . $obj; $tmp .= ',';
+=item * I<Non-mutators with a mutator variant>
-=head2 Overloadable Operations
+ + - * / % ** << >> x .
+ & | ^ &. |. ^.
-The following symbols can be specified in C<use overload> directive:
+As described L<above|"Calling Conventions and Magic Autogeneration">,
+Perl may call methods for operators like C<+> and C<&> in the course
+of implementing missing operations like C<++>, C<+=>, and C<&=>.
+While these methods may detect this usage by testing the definedness
+of the third argument, they should in all cases avoid changing their
+operands.
+This is because Perl does not call the copy constructor before
+invoking these methods.
-=over 5
+=item * C<int>
-=item * I<Arithmetic operations>
+Traditionally, the Perl function C<int> rounds to 0
+(see L<perlfunc/int>), and so for floating-point-like types one
+should follow the same semantic.
- "+", "+=", "-", "-=", "*", "*=", "/", "/=", "%", "%=",
- "**", "**=", "<<", "<<=", ">>", ">>=", "x", "x=", ".", ".=",
+=item * I<String, numeric, boolean, and regexp conversions>
-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>.
+ "" 0+ bool
-See L<"MAGIC AUTOGENERATION">, L<"Calling Conventions for Mutators"> and
-L<"Calling Conventions for Binary Operations">) for details of these
-substitutions.
+These conversions are invoked according to context as necessary.
+For example, the subroutine for C<'""'> (stringify) may be used
+where the overloaded object is passed as an argument to C<print>,
+and that for C<'bool'> where it is tested in the condition of a flow
+control statement (like C<while>) or the ternary C<?:> operation.
-=item * I<Comparison operations>
+Of course, in contexts like, for example, C<$obj + 1>, Perl will
+invoke C<$obj>'s implementation of C<+> rather than (in this
+example) converting C<$obj> to a number using the numify method
+C<'0+'> (an exception to this is when no method has been provided
+for C<'+'> and L</fallback> is set to TRUE).
- "<", "<=", ">", ">=", "==", "!=", "<=>",
- "lt", "le", "gt", "ge", "eq", "ne", "cmp",
+The subroutines for C<'""'>, C<'0+'>, and C<'bool'> can return
+any arbitrary Perl value.
+If the corresponding operation for this value is overloaded too,
+the operation will be called again with this value.
-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>.
+As a special case if the overload returns the object itself then it will
+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)>.
-=item * I<Bit operations>
+ qr
- "&", "&=", "^", "^=", "|", "|=", "neg", "!", "~",
+The subroutine for C<'qr'> is used wherever the object is
+interpolated into or used as a regexp, including when it
+appears on the RHS of a C<=~> or C<!~> operator.
-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+>.
+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.
-The same remarks in L<"Arithmetic operations"> about
-assignment-variants and autogeneration apply for
-bit operations C<"&">, C<"^">, and C<"|"> as well.
+=item * I<Iteration>
-=item * I<Increment and decrement>
+If C<E<lt>E<gt>> is overloaded then the same implementation is used
+for both the I<read-filehandle> syntax C<E<lt>$varE<gt>> and
+I<globbing> syntax C<E<lt>${var}E<gt>>.
- "++", "--",
+=item * I<File tests>
-If undefined, addition and subtraction methods can be
-used instead. These operations are called both in prefix and
-postfix form.
+The key C<'-X'> is used to specify a subroutine to handle all the
+filetest operators (C<-f>, C<-x>, and so on: see L<perlfunc/-X> for
+the full list);
+it is not possible to overload any filetest operator individually.
+To distinguish them, the letter following the '-' is passed as the
+second argument (that is, in the slot that for binary operators
+is used to pass the second operand).
-=item * I<Transcendental functions>
+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.
- "atan2", "cos", "sin", "exp", "abs", "log", "sqrt", "int"
+This overload was introduced in Perl 5.12.
-If C<abs> is unavailable, it can be autogenerated using methods
-for "E<lt>" or "E<lt>=E<gt>" combined with either unary minus or subtraction.
+=item * I<Matching>
-Note that traditionally the Perl function L<int> rounds to 0, thus for
-floating-point-like types one should follow the same semantic. If
-C<int> is unavailable, it can be autogenerated using the overloading of
-C<0+>.
+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>.
-=item * I<Boolean, string and numeric conversion>
+Unusually, the overloaded implementation of the smart match operator
+does not get full control of the smart match behaviour.
+In particular, in the following code:
- 'bool', '""', '0+',
+ package Foo;
+ use overload '~~' => 'match';
-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.
+ my $obj = Foo->new();
+ $obj ~~ [ 1,2,3 ];
-As a special case if the overload returns the object itself then it will
-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)>.
+the smart match does I<not> invoke the method call like this:
-=item * I<Iteration>
+ $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:
-If not overloaded, the argument will be converted to a filehandle or
-glob (which may require a stringification). The same overloading
-happens both for the I<read-filehandle> syntax C<E<lt>$varE<gt>> and
-I<globbing> syntax C<E<lt>${var}E<gt>>.
+ $obj->match(1,0);
+ $obj->match(2,0);
+ $obj->match(3,0);
-B<BUGS> Even in list context, the iterator is currently called only
-once and with scalar context.
+Consult the match table in L<perlop/"Smartmatch Operator"> for
+details of when overloading is invoked.
=item * I<Dereferencing>
- '${}', '@{}', '%{}', '&{}', '*{}'.
-
-If not overloaded, the argument will be dereferenced I<as is>, thus
-should be of correct type. These functions should return a reference
-of correct type, or another object with overloaded dereferencing.
-
-As a special case if the overload returns the object itself then it
-will be used directly (provided it is the correct type).
-
-The dereference operators must be specified explicitly they will not be passed to
-"nomethod".
+ ${} @{} %{} &{} *{}
+
+If these operators are not explicitly overloaded then they
+work in the normal way, yielding the underlying scalar,
+array, or whatever stores the object data (or the appropriate
+error message if the dereference operator doesn't match it).
+Defining a catch-all C<'nomethod'> (see L<below|/nomethod>)
+makes no difference to this as the catch-all function will
+not be called to implement a missing dereference operator.
+
+If a dereference operator is overloaded then it must return a
+I<reference> of the appropriate type (for example, the
+subroutine for key C<'${}'> should return a reference to a
+scalar, not a scalar), or another object which overloads the
+operator: that is, the subroutine only determines what is
+dereferenced and the actual dereferencing is left to Perl.
+As a special case, if the subroutine returns the object itself
+then it will not be called again - avoiding infinite recursion.
=item * I<Special>
- "nomethod", "fallback", "=", "~~",
+ nomethod fallback =
-see L<SPECIAL SYMBOLS FOR C<use overload>>.
+See L</Special Keys for C<use overload>>.
=back
-See L<"Fallback"> for an explanation of when a missing method can be
-autogenerated.
-
-A computer-readable form of the above table is available in the hash
-%overload::ops, with values being space-separated lists of names:
-
- 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',
- conversion => 'bool "" 0+',
- iterators => '<>',
- dereferencing => '${} @{} %{} &{} *{}',
- special => 'nomethod fallback ='
-
-=head2 Inheritance and overloading
-
-Inheritance interacts with overloading in two ways.
-
-=over
-
-=item Strings as values of C<use overload> directive
-
-If C<value> in
-
- use overload key => value;
+=head2 Magic Autogeneration
+
+If a method for an operation is not found then Perl tries to
+autogenerate a substitute implementation from the operations
+that have been defined.
+
+Note: the behaviour described in this section can be disabled
+by setting C<fallback> to FALSE (see L</fallback>).
+
+In the following tables, numbers indicate priority.
+For example, the table below states that,
+if no implementation for C<'!'> has been defined then Perl will
+implement it using C<'bool'> (that is, by inverting the value
+returned by the method for C<'bool'>);
+if boolean conversion is also unimplemented then Perl will
+use C<'0+'> or, failing that, C<'""'>.
+
+ operator | can be autogenerated from
+ |
+ | 0+ "" bool . x
+ =========|==========================
+ 0+ | 1 2
+ "" | 1 2
+ bool | 1 2
+ int | 1 2 3
+ ! | 2 3 1
+ qr | 2 1 3
+ . | 2 1 3
+ x | 2 1 3
+ .= | 3 2 4 1
+ x= | 3 2 4 1
+ <> | 2 1 3
+ -X | 2 1 3
+
+Note: The iterator (C<'E<lt>E<gt>'>) and file test (C<'-X'>)
+operators work as normal: if the operand is not a blessed glob or
+IO reference then it is converted to a string (using the method
+for C<'""'>, C<'0+'>, or C<'bool'>) to be interpreted as a glob
+or filename.
+
+ operator | can be autogenerated from
+ |
+ | < <=> neg -= -
+ =========|==========================
+ neg | 1
+ -= | 1
+ -- | 1 2
+ abs | a1 a2 b1 b2 [*]
+ < | 1
+ <= | 1
+ > | 1
+ >= | 1
+ == | 1
+ != | 1
+
+ * one from [a1, a2] and one from [b1, b2]
+
+Just as numeric comparisons can be autogenerated from the method
+for C<< '<=>' >>, string comparisons can be autogenerated from
+that for C<'cmp'>:
+
+ operators | can be autogenerated from
+ ====================|===========================
+ lt gt le ge eq ne | cmp
+
+Similarly, autogeneration for keys C<'+='> and C<'++'> is analogous
+to C<'-='> and C<'--'> above:
+
+ operator | can be autogenerated from
+ |
+ | += +
+ =========|==========================
+ += | 1
+ ++ | 1 2
+
+And other assignment variations are analogous to
+C<'+='> and C<'-='> (and similar to C<'.='> and C<'x='> above):
+
+ operator || *= /= %= **= <<= >>= &= ^= |= &.= ^.= |.=
+ -------------------||-------------------------------------------
+ autogenerated from || * / % ** << >> & ^ | &. ^. |.
+
+Note also that the copy constructor (key C<'='>) may be
+autogenerated, but only for objects based on scalars.
+See L</Copy Constructor>.
+
+=head3 Minimal Set of Overloaded Operations
-is a string, it is interpreted as a method name.
+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:
-=item Overloading of an operation is inherited by derived classes
+ + - * / % ** << >> x
+ <=> cmp
+ & | ^ ~ &. |. ^. ~.
+ atan2 cos sin exp log sqrt int
+ "" 0+ bool
+ ~~
-Any class derived from an overloaded class is also overloaded. The
-set of overloaded methods is the union of overloaded methods of all
-the ancestors. If some method is overloaded in several ancestor, then
-which description will be used is decided by the usual inheritance
-rules:
+Of the conversions, only one of string, boolean or numeric is
+needed because each can be generated from either of the other two.
-If C<A> inherits from C<B> and C<C> (in this order), C<B> overloads
-C<+> with C<\&D::plus_sub>, and C<C> overloads C<+> by C<"plus_meth">,
-then the subroutine C<D::plus_sub> will be called to implement
-operation C<+> for an object in package C<A>.
+=head2 Special Keys for C<use overload>
-=back
+=head3 C<nomethod>
-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.
+The C<'nomethod'> key is used to specify a catch-all function to
+be called for any operator that is not individually overloaded.
+The specified function will be passed four parameters.
+The first three arguments coincide with those that would have been
+passed to the corresponding method if it had been defined.
+The fourth argument is the C<use overload> key for that missing
+method. If the "bitwise" feature is enabled (see L<feature>),
+a fifth TRUE argument is passed to subroutines handling C<&>, C<|>, C<^> and C<~> to indicate that the caller is expecting numeric behaviour.
-=head1 SPECIAL SYMBOLS FOR C<use overload>
+For example, if C<$a> is an object blessed into a package declaring
-Three keys are recognized by Perl that are not covered by the above
-description.
+ use overload 'nomethod' => 'catch_all', # ...
-=head2 Last Resort
+then the operation
-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
+ 3 + $a
- &nomethodMethod($a,1,1,"-")
+could (unless a method is specifically declared for the key
+C<'+'>) result in a call
-if the pair C<"nomethod" =E<gt> "nomethodMethod"> was specified in the
-C<use overload> directive.
+ catch_all($a, 3, 1, '+')
-The C<"nomethod"> mechanism is I<not> used for the dereference operators
-( ${} @{} %{} &{} *{} ).
+See L</How Perl Chooses an Operator Implementation>.
+=head3 C<fallback>
-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.
+The value assigned to the key C<'fallback'> tells Perl how hard
+it should try to find an alternative way to implement a missing
+operator.
+=over
-=head2 Fallback
+=item * defined, but FALSE
-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">:
+ use overload "fallback" => 0, # ... ;
-=over 16
+This disables L</Magic Autogeneration>.
=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.
+In the default case where no value is explicitly assigned to
+C<fallback>, magic autogeneration is enabled.
=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
+The same as for C<undef>, but if a missing operator cannot be
+autogenerated then, instead of issuing an error message, Perl
+is allowed to revert to what it would have done for that
+operator if there had been no C<use overload> directive.
-No autogeneration is tried. Perl tries to call
-C<"nomethod"> value, and if this is missing, raises an exception.
+Note: in most cases, particularly the L</Copy Constructor>,
+this is unlikely to be appropriate behaviour.
=back
-B<Note.> C<"fallback"> inheritance via @ISA is not carved in stone
-yet, see L<"Inheritance and overloading">.
-
-=head2 Smart Match
-
-The key C<"~~"> allows you to override the smart matching used by
-the switch construct. See L<feature>.
+See L</How Perl Chooses an Operator Implementation>.
-=head2 Copy Constructor
+=head3 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.
+As mentioned L<above|"Mathemagic, Mutators, and Copy Constructors">,
+this operation is called when a mutator is applied to a reference
+that shares its object with some other reference.
+For example, if C<$b> is mathemagical, and C<'++'> is overloaded
+with C<'incr'>, and C<'='> is overloaded with C<'clone'>, then the
+code
-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
+ $a = $b;
+ # ... (other code which does not modify $a or $b) ...
+ ++$b;
- $a=$b;
- ++$a;
+would be executed in a manner equivalent to
-To make this change $a and not change $b, a copy of C<$$a> is made,
-and $a is assigned a reference to this new object. This operation is
-done during execution of the C<++$a>, and not during the assignment,
-(so before the increment C<$$a> coincides with C<$$b>). This is only
-done if C<++> is expressed via a method for C<'++'> or C<'+='> (or
-C<nomethod>). Note that if this operation is expressed via C<'+'>
-a nonmutator, i.e., as in
+ $a = $b;
+ # ...
+ $b = $b->clone(undef, "");
+ $b->incr(undef, "");
- $a=$b;
- $a=$a+1;
+Note:
-then C<$a> does not reference a new copy of C<$$a>, since $$a does not
-appear as lvalue when the above code is executed.
-
-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 or a simple assignment if it
-is not.
+=over
-=over 5
+=item *
-=item B<Example>
+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.)
-The actually executed code for
+=item *
- $a=$b;
- Something else which does not modify $a or $b....
- ++$a;
+As for other operations, the subroutine implementing '=' is passed
+three arguments, though the last two are always C<undef> and C<''>.
-may be
+=item *
- $a=$b;
- Something else which does not modify $a or $b....
- $a = $a->clone(undef,"");
- $a->incr(undef,"");
+The copy constructor is called only before a call to a function
+declared to implement a mutator, for example, if C<++$b;> in the
+code above is effected via a method declared for key C<'++'>
+(or 'nomethod', passed C<'++'> as the fourth argument) or, by
+autogeneration, C<'+='>.
+It is not called if the increment operation is effected by a call
+to the method for C<'+'> since, in the equivalent code,
-if $b was mathemagical, and C<'++'> was overloaded with C<\&incr>,
-C<'='> was overloaded with C<\&clone>.
+ $a = $b;
+ $b = $b + 1;
-=back
+the data referred to by C<$a> is unchanged by the assignment to
+C<$b> of a reference to new object data.
-Same behaviour is triggered by C<$b = $a++>, which is consider a synonym for
-C<$b = $a; ++$a>.
+=item *
-=head1 MAGIC AUTOGENERATION
+The copy constructor is not called if Perl determines that it is
+unnecessary because there is no other reference to the data being
+modified.
-If a method for an operation is not found, and the value for C<"fallback"> is
-TRUE or undefined, Perl tries to autogenerate a substitute method for
-the missing operation based on the defined operations. Autogenerated method
-substitutions are possible for the following operations:
+=item *
-=over 16
+If C<'fallback'> is undefined or TRUE then a copy constructor
+can be autogenerated, but only for objects based on scalars.
+In other cases it needs to be defined explicitly.
+Where an object's data is stored as, for example, an array of
+scalars, the following might be appropriate:
-=item I<Assignment forms of arithmetic operations>
+ use overload '=' => sub { bless [ @{$_[0]} ] }, # ...
-C<$a+=$b> can use the method for C<"+"> if the method for C<"+=">
-is not defined.
+=item *
-=item I<Conversion operations>
+If C<'fallback'> is TRUE and no copy constructor is defined then,
+for objects not based on scalars, Perl may silently fall back on
+simple assignment - that is, assignment of the object reference.
+In effect, this disables the copy constructor mechanism since
+no new copy of the object data is created.
+This is almost certainly not what you want.
+(It is, however, consistent: for example, Perl's fallback for the
+C<++> operator is to increment the reference itself.)
-String, numeric, and boolean conversion are calculated in terms of one
-another if not all of them are defined.
+=back
-=item I<Increment and decrement>
+=head2 How Perl Chooses an Operator Implementation
-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>.
+Which is checked first, C<nomethod> or C<fallback>?
+If the two operands of an operator are of different types and
+both overload the operator, which implementation is used?
+The following are the precedence rules:
-=item C<abs($a)>
+=over
-can be expressed in terms of C<$aE<lt>0> and C<-$a> (or C<0-$a>).
+=item 1.
-=item I<Unary minus>
+If the first operand has declared a subroutine to overload the
+operator then use that implementation.
-can be expressed in terms of subtraction.
+=item 2.
-=item I<Negation>
+Otherwise, if fallback is TRUE or undefined for the
+first operand then see if the
+L<rules for autogeneration|"Magic Autogeneration">
+allows another of its operators to be used instead.
-C<!> and C<not> can be expressed in terms of boolean conversion, or
-string or numerical conversion.
+=item 3.
-=item I<Concatenation>
+Unless the operator is an assignment (C<+=>, C<-=>, etc.),
+repeat step (1) in respect of the second operand.
-can be expressed in terms of string conversion.
+=item 4.
-=item I<Comparison operations>
+Repeat Step (2) in respect of the second operand.
-can be expressed in terms of its "spaceship" counterpart: either
-C<E<lt>=E<gt>> or C<cmp>:
+=item 5.
- <, >, <=, >=, ==, != in terms of <=>
- lt, gt, le, ge, eq, ne in terms of cmp
+If the first operand has a "nomethod" method then use that.
-=item I<Iterator>
+=item 6.
- <> in terms of builtin operations
+If the second operand has a "nomethod" method then use that.
-=item I<Dereferencing>
+=item 7.
- ${} @{} %{} &{} *{} in terms of builtin operations
+If C<fallback> is TRUE for both operands
+then perform the usual operation for the operator,
+treating the operands as numbers, strings, or booleans
+as appropriate for the operator (see note).
-=item I<Copy operator>
+=item 8.
-can be expressed in terms of an assignment to the dereferenced value, if this
-value is a scalar and not a reference, or simply a reference assignment
-otherwise.
+Nothing worked - die.
=back
-=head1 Minimal set of overloaded operations
+Where there is only one operand (or only one operand with
+overloading) the checks in respect of the other operand above are
+skipped.
-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:
+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 C<Matching> under L</Overloadable Operations>
+above).
- + - * / % ** << >> 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.
+Note on Step 7: some operators have a different semantic depending
+on the type of their operands.
+As there is no way to instruct Perl to treat the operands as, e.g.,
+numbers instead of strings, the result here may not be what you
+expect.
+See L</BUGS AND PITFALLS>.
-=head1 Losing overloading
+=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).
mathemagical properties are lost. The same can happen with other
operations as well.
-=head1 Run-time Overloading
+=head2 Inheritance and Overloading
+
+Overloading respects inheritance via the @ISA hierarchy.
+Inheritance interacts with overloading in two ways.
+
+=over
+
+=item Method names in the C<use overload> directive
+
+If C<value> in
+
+ use overload key => value;
+
+is a string, it is interpreted as a method name - which may
+(in the usual way) be inherited from another class.
+
+=item Overloading of an operation is inherited by derived classes
+
+Any class derived from an overloaded class is also overloaded
+and inherits its operator implementations.
+If the same operator is overloaded in more than one ancestor
+then the implementation is determined by the usual inheritance
+rules.
+
+For example, if C<A> inherits from C<B> and C<C> (in that order),
+C<B> overloads C<+> with C<\&D::plus_sub>, and C<C> overloads
+C<+> by C<"plus_meth">, then the subroutine C<D::plus_sub> will
+be called to implement operation C<+> for an object in package C<A>.
+
+=back
+
+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
Since all C<use> directives are executed at compile-time, the only way to
change overloading during run-time is to
though the use of these constructs during run-time is questionable.
-=head1 Public functions
+=head2 Public Functions
Package C<overload.pm> provides the following public functions:
=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.
=back
-=head1 Overloading constants
+=head2 Overloading Constants
For some applications, the Perl parser mangles constants too much.
It is possible to hook into this process via C<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
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.
-
-Copying (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 $a (or $b) refers to, like C<$a++>. You can override this
-behavior by defining your own copy constructor (see L<"Copy Constructor">).
+If a package uses overload, it carries a special flag. This flag is also
+set when new functions 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).
-=head1 Metaphor clash
-
-One may wonder why the semantic of overloaded C<=> is so counter intuitive.
-If it I<looks> counter intuitive to you, you are subject to a metaphor
-clash.
-
-Here is a Perl object metaphor:
-
-I< object is a reference to blessed data>
-
-and an arithmetic metaphor:
-
-I< object is a thing by itself>.
-
-The I<main> problem of overloading C<=> is the fact that these metaphors
-imply different actions on the assignment C<$a = $b> if $a and $b are
-objects. Perl-think implies that $a becomes a reference to whatever
-$b was referencing. Arithmetic-think implies that the value of "object"
-$a is changed to become the value of the object $b, preserving the fact
-that $a and $b are separate entities.
-
-The difference is not relevant in the absence of mutators. After
-a Perl-way assignment an operation which mutates the data referenced by $a
-would change the data referenced by $b too. Effectively, after
-C<$a = $b> values of $a and $b become I<indistinguishable>.
-
-On the other hand, anyone who has used algebraic notation knows the
-expressive power of the arithmetic metaphor. Overloading works hard
-to enable this metaphor while preserving the Perlian way as far as
-possible. Since it is not possible to freely mix two contradicting
-metaphors, overloading allows the arithmetic way to write things I<as
-far as all the mutators are called via overloaded access only>. The
-way it is done is described in L<Copy Constructor>.
-
-If some mutator methods are directly applied to the overloaded values,
-one may need to I<explicitly unlink> other values which references the
-same value:
-
- $a = new Data 23;
- ...
- $b = $a; # $b is "linked" to $a
- ...
- $a = $a->clone; # Unlink $b from $a
- $a->increment_by(4);
-
-Note that overloaded access makes this transparent:
-
- $a = new Data 23;
- $b = $a; # $b is "linked" to $a
- $a += 4; # would unlink $b automagically
-
-However, it would not make
-
- $a = new Data 23;
- $a = 4; # Now $a is a plain 4, not 'Data'
-
-preserve "objectness" of $a. But Perl I<has> a way to make assignments
-to an object do whatever you want. It is just not the overload, but
-tie()ing interface (see L<perlfunc/tie>). Adding a FETCH() method
-which returns the object itself, and STORE() method which changes the
-value of the object, one can reproduce the arithmetic metaphor in its
-completeness, at least for variables which were tie()d from the start.
-
-(Note that a workaround for a bug may be needed, see L<"BUGS">.)
-
-=head1 Cookbook
+=head1 COOKBOOK
Please add examples to what follows!
-=head2 Two-face scalars
+=head2 Two-face Scalars
Put this in F<two_face.pm> in your Perl library directory:
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/;
+ 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
+=head2 Two-face References
Suppose you want to create an object which is accessible as both an
array reference and a hash reference.
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';
=back
-=head2 Symbolic calculator
+=head2 Symbolic Calculator
Put this in F<symbolic.pm> 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 the L<Last
-Resort> operator C<nomethod>. In this example the corresponding
+provide any usual overloaded operators, instead it provides an
+implementation for L</C<nomethod>>. In this example the C<nomethod>
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--) {
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) {
- $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()}";
}
-Due to L<Calling Conventions for Mutators>, we do not need anything
-special to make C<+=> and friends work, except filling C<+=> entry of
-%subr, and defining a copy constructor (needed since Perl has no
-way to know that the implementation of C<'+='> does not mutate
-the argument, compare L<Copy Constructor>).
+Since subroutines implementing assignment operators are not required
+to modify their operands (see L</Overloadable Operations> above),
+we do not need anything special to make C<+=> and friends work,
+besides adding these operators to %subr and defining a copy
+constructor (needed since Perl has no way to know that the
+implementation of C<'+='> does not mutate the argument -
+see L</Copy Constructor>).
To implement a copy constructor, add C<< '=' => \&cpy >> to C<use overload>
line, and code (this code assumes that mutators change things one level
we need to explicitly check for the type of $a and $b. If components
$a and $b happen to be of some related type, this may lead to problems.
-=head2 I<Really> symbolic calculator
+=head2 I<Really> Symbolic Calculator
One may wonder why we call the above calculator symbolic. The reason
is that the actual calculation of the value of expression is postponed
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
symbolic provides a I<symbolic> calculator indeed.
To hide the rough edges under the hood, provide a tie()d interface to the
-package C<symbolic> (compare with L<Metaphor clash>). Add methods
+package C<symbolic>. Add methods
sub TIESCALAR { my $pack = shift; $pack->new(@_) }
sub FETCH { shift }
sub nop { } # Around a bug
-(the bug is described in L<"BUGS">). One can use this new interface as
+(the bug, fixed in Perl 5.14, is described in L<"BUGS">). One can use this
+new interface as
tie $a, 'symbolic', 3;
tie $b, 'symbolic', 4;
Ilya Zakharevich E<lt>F<ilya@math.mps.ohio-state.edu>E<gt>.
+=head1 SEE ALSO
+
+The C<overloading> pragma can be used to enable or disable overloaded
+operations within a lexical scope - see L<overloading>.
+
=head1 DIAGNOSTICS
When Perl is run with the B<-Do> switch or its equivalent, overloading
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
+=head1 BUGS AND PITFALLS
+
+=over
+
+=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<|>:
+
+ use overload '0+' => sub { $_[0]->{n}; },
+ fallback => 1;
+ my $x = bless { n => 4 }, "main";
+ my $y = bless { n => 8 }, "main";
+ print $x | $y, "\n";
+
+You might expect this to output "12".
+In fact, it prints "<": the ASCII result of treating "|"
+as a bitwise string operator - that is, the result of treating
+the operands as the strings "4" and "8" rather than numbers.
+The fact that numify (C<0+>) is implemented but stringify
+(C<"">) isn't makes no difference since the latter is simply
+autogenerated from the former.
+
+The only way to change this is to provide your own subroutine
+for C<'|'>.
+
+=item *
+
+Magic autogeneration increases the potential for inadvertently
+creating self-referential structures.
+Currently Perl will not free self-referential
+structures until cycles are explicitly broken.
+For example,
+
+ use overload '+' => 'add';
+ sub add { bless [ \$_[0], \$_[1] ] };
-Because it is used for overloading, the per-package hash %OVERLOAD now
-has a special meaning in Perl. The symbol table is filled with names
-looking like line-noise.
+is asking for trouble, since
+
+ $obj += $y;
+
+will effectively become
+
+ $obj = add($obj, $y, undef);
+
+with the same result as
+
+ $obj = [\$obj, \$foo];
+
+Even if no I<explicit> assignment-variants of operators are present in
+the script, they may be generated by the optimizer.
+For example,
+
+ "obj = $obj\n"
+
+may be optimized to
+
+ my $tmp = 'obj = ' . $obj; $tmp .= "\n";
+
+=item *
+
+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.
-Relation between overloading and tie()ing is broken. Overloading is
-triggered or not basing on the I<previous> class of tie()d value.
+=item *
+
+Before Perl 5.14, the relation between overloading and tie()ing was broken.
+Overloading was triggered or not based on the I<previous> class of the
+tie()d variable.
-This happens because the presence of overloading is checked too early,
-before any tie()d access is attempted. If the FETCH()ed class of the
-tie()d value does not change, a simple workaround is to access the value
+This happened because the presence of overloading was checked
+too early, before any tie()d access was attempted. If the
+class of the value FETCH()ed from the tied variable does not
+change, a simple workaround for code that is to run on older Perl
+versions is to access the value (via C<() = $foo> or some such)
immediately after tie()ing, so that after this call the I<previous> class
coincides with the current one.
-B<Needed:> a way to fix this without a speed penalty.
+=item *
Barewords are not covered by overloaded string constants.
-This document is confusing. There are grammos and misleading language
-used in places. It would seem a total rewrite is needed.
+=item *
+
+The range operator C<..> cannot be overloaded.
+
+=back
=cut
https://perl5.git.perl.org / perl5.git / blobdiff