-=head1 NAME
+=head1 NAME
-perlovl - perl overloading semantics
-
-=head1 SYNOPSIS
-
- package SomeThing;
-
- %OVERLOAD = (
- '+' => \&myadd,
- '-' => \&mysub,
- # etc
- );
- ...
-
- package main;
- $a = new SomeThing 57;
- $b=5+$a;
-
-=head1 CAVEAT SCRIPTOR
-
-Overloading of operators is a subject not to be taken lightly.
-Neither its precise implementation, syntax, nor semantics are
-100% endorsed by Larry Wall. So any of these may be changed
-at some point in the future.
+perlovl - overload perl mathematical functions [superseded]
=head1 DESCRIPTION
-=head2 Declaration of overloaded functions
-
- package Number;
- %OVERLOAD = (
- "+" => \&add,
- "*=" => "muas"
- );
-
-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. Legal values of this
-hash array are values legal inside C<&{ ... }> call, so the name of a
-subroutine, a reference to a subroutine, or an anonymous subroutine
-will all work.
-
-The subroutine C<$OVERLOAD{"+"}> will be called to execute C<$a+$b> if $a
-is a reference to an object blessed into the package C<Number>, or $a is
-not an object from a package with defined mathemagic addition, but $b is a
-reference to a C<Number>. It can be called also in other situations, like
-C<$a+=7>, or C<$a++>. See L<MAGIC AUTOGENERATION>. (Mathemagical
-methods refer to methods triggered by an overloaded mathematical
-operator.)
-
-=head2 Calling Conventions for Binary Operations
-
-The functions in C<values %OVERLOAD> are called with three (in one
-particular case with four, see L<Last Resort>) arguments. If the
-corresponding operation is binary, then the first two arguments are the
-two arguments of the operation. However, due to general object calling
-conventions, the first argument should be always an object in the package,
-so in the situation of C<7+$a>, the order of arguments is interchanged.
-Most probably it does not matter for implementation of the addition
-method, but whether the arguments are reversed is vital for the
-subtraction method. The subroutine can query this information by
-examining the third argument, which can take three different values:
-
-=over 7
-
-=item FALSE
-
-the order of arguments is as in the current operation.
-
-=item TRUE
-
-the arguments are reversed.
-
-=item C<undef>
-
-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.
-
-=back
-
-=head2 Calling Conventions for Unary Operations
-
-Unary operation are considered binary operations with the second
-argument being C<undef>. Thus C<$OVERLOAD{"++"}> is called with
-arguments C<($a,undef,'')> when $a++ is executed.
-
-=head2 Overloadable Operations
-
-The following keys of %OVERLOAD are recognized:
-
-=over 5
-
-=item * I<Arithmetic operations>
-
- "+", "+=", "-", "-=", "*", "*=", "/", "/=", "%", "%=",
- "**", "**=", "<<", "<<=", ">>", ">>=", "x", "x=", ".", ".=",
-
-For these operations a substituted non-assignment variant can be called if
-the assignment variant is not available. Methods for operations "C<+>",
-"C<->", "C<+=>", and "C<-=>" can be called to automatically generate
-increment and decrement methods. The operations "C<->" can be used to
-autogenerate missing methods for unary minus or C<abs>.
-
-=item * I<Comparison operations>
-
- "<", "<=", ">", ">=", "==", "!=", "<=>",
- "lt", "le", "gt", "ge", "eq", "ne", "cmp",
-
-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 %OVERLOAD.
-
-=item * I<Bit operations>
-
- "&", "^", "|", "neg", "!", "~",
-
-"C<neg>" stands for unary minus. If the method for C<neg> is not
-specified, it can be autogenerated using on the method for subtraction.
-
-=item * I<Increment and decrement>
-
- "++", "--",
-
-If undefined, addition and subtraction methods can be
-used instead. These operations are called both in prefix and
-postfix form.
-
-=item * I<Transcendental functions>
-
- "atan2", "cos", "sin", "exp", "abs", "log", "sqrt",
-
-If C<abs> is unavailable, it can be autogenerated using methods
-for "<" or "<=>" combined with either unary minus or subtraction.
-
-=item * I<Boolean, string and numeric conversion>
-
- "bool", "\"\"", "0+",
-
-If one or two of these operations are unavailable, the remaining ones can
-be used instead. C<bool> is used in the flow control operators
-(like C<while>) and for the ternary "C<?:>" operation. These functions can
-return any arbitrary Perl value. If the corresponding operation for this value
-is overloaded too, that operation will be called again with this value.
-
-=item * I<Special>
-
- "nomethod", "fallback", "=",
-
-see L<SPECIAL KEYS OF %OVERLOAD>.
-
-=back
-
-See L<"Fallback"> for an explanation of when a missing method can be autogenerated.
-
-=head1 SPECIAL KEYS OF %OVERLOAD
-
-Three keys are recognized by Perl that are not covered by the above
-description.
-
-=head2 Last Resort
-
-C<$OVERLOAD{"nomethod"}> is a reference to a function of four parameters.
-If defined, it is called when the overloading mechanism cannot find a
-method for some operation. The first three arguments of this function
-coincide with arguments for the corresponding method if it were found, the
-fourth argument is the key of %OVERLOAD corresponding to the missing
-method. If several methods are tried, the last one is used. Say, C<1-$a>
-can be equivalent to
-
- &{ $Pack::OVERLOAD{"nomethod"} }($a,1,1,"-").
-
-If some operation cannot be resolved, and there is no
-C<$OVERLOAD{"nomethod"}>, then an exception will be raised
-via die() -- unless C<$OVERLOAD{"fallback"}> is true.
-
-=head2 Fallback
-
-C<$OVERLOAD{"fallback"}> governs what to do if a method for a particular
-operation is not found. Three different cases are possible depending on
-value of C<$OVERLOAD{"fallback"}>:
-
-=over 16
-
-=item * C<undef>
-
-Perl tries to use a
-substituted method (see L<MAGIC AUTOGENERATION>). If this fails, it
-then tries to calls C<$OVERLOAD{"nomethod"}>; if missing, an exception
-will be raised.
-
-=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 %OVERLOAD is
-present.
-
-=item * defined, but FALSE
-
-No autogeneration is tried. Perl tries to call
-C<$OVERLOAD{"nomethod"}>, and if this is missing, raises an exception.
-
-=back
-
-=head2 Copy Constructor
-
-C<$OVERLOAD{"="}> is a reference to a function with three arguments,
-i.e., it looks like a usual value of %OVERLOAD. What is special about
-this subroutine is that it should not return a blessed reference into
-a package (as most other methods are expected to), but rather a freshly made
-copy of its dereferenced argument (see L<"BUGS">, though). 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;
- $a++;
-
-To make this change to $a and not to change $b, a freshly made copy of
-C<$$a> is made, and $a is assigned a reference to this object. This
-operation is executed during C<$a++>, (so before this C<$$a> coincides
-with C<$$b>), and only if C<++> is expressed via C<$OPERATOR{'++'}> or
-C<$OPERATOR{'+='}>. Note that if this operation is expressed via 'C<+>',
-i.e., as
-
- $a=$b;
- $a=$a+1;
-
-then C<$$a> and C<$$b> do not appear as lvalues.
-
-If the copy constructor is required during execution of some mutator, but
-C<$OPERATOR{'='}> is missing, it can be autogenerated as a string
-copy if an object of
-the package is a plain scalar.
-
-=head1 MAGIC AUTOGENERATION
-
-If a method for an operation is not found, and C<$OVERLOAD{"fallback"}> is
-TRUE or undefined, Perl tries to to autogenerate a substitute method for
-the missing operation based on defined operations. Autogenerated method
-substitutions are possible for the following operations:
-
-=over 16
-
-=item I<Assignment forms of arithmetic operations>
-
-C<$a=+$b> can use the C<$OVERLOAD{"+"}> method if C<$OVERLOAD{"+="}>
-is not defined.
-
-=item I<Conversion operations>
-
-String, numeric, and boolean conversion are calculated in terms of one
-another if not all of them are defined.
-
-=item I<Increment and decrement>
-
-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>.
-
-=item C<abs($a)>
-
-can be expressed in terms of C<$aE<lt>0> and C<-$a> (or C<0-$a>).
-
-=item I<Unary minus>
-
-can be expressed in terms of subtraction.
-
-=item I<Concatenation>
-
-can be expressed in terms of string conversion.
-
-=item I<Comparison operations>
-
-can be expressed in terms of its "spaceship" counterpart: either
-C<E<lt>=E<gt>> or C<cmp>:
-
- <, >, <=, >=, ==, != in terms of <=>
- lt, gt, le, ge, eq, ne in terms of cmp
-
-=item I<Copy operator>
-
-can be expressed in terms of assignment to the dereferenced value, if this
-value is scalar but not a reference.
-
-=back
+This man page has been superseded by L<overload>.
=head1 WARNING
-The restriction for the comparison operation is that even if, for example,
-`C<cmp>' should return a blessed reference, the autogenerated `C<lt>'
-function will produce only a standard logical value based on the
-numerical value of the result of `C<cmp>'. In particular, a working
-numeric conversion is needed in this case (possibly expressed in terms of
-other conversions).
-
-Similarly, C<.=> and C<x=> operators lose their mathemagical properties
-if the string conversion substitution is applied.
-
-When you chop() a mathemagical object, it becomes promoted to a string
-first, and its mathemagical qualities is lost. The same can happen with other
-operations as well.
-
-=head1 IMPLEMENTATION
-
-The table of methods for all operations is cached as a magic for the
-symbol table hash of the package. It is rechecked for changes of
-%OVERLOAD and @ISA only during C<bless>ing; so if it is changed
-dynamically, you'll need an additional fake C<bless>ing to update the
-table.
-
-(Every SVish thing has a magic queue, and a magic is an entry in that queue.
-This is how a single variable may participate in multiple forms of magic
-simultaneously. For instance, environment variables regularly have two
-forms at once: their %ENV magic and their taint magic.)
-
-If an object belongs to a package with %OVERLOAD, it carries a special
-flag. Thus the only speed penalty during arithmetic operations without
-overload is the check of this flag.
-
-In fact, if no %OVERLOAD is ever accessed, there is almost no overhead for
-overloadable operations, so most programs should not suffer measurable
-performance penalties. Considerable effort was made minimize overhead
-when %OVERLOAD is accessed and the current operation is overloadable but
-the arguments in question do not belong to packages with %OVERLOAD. When
-in doubt, test your speed with %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 there is no %OVERLOAD.
-
-The copying like C<$a=$b> is shallow; however, a one-level-deep
-copying is
-carried out before any operation that can imply an assignment to the
-object $b (or $a) refers to, like C<$b++>. You can override this
-behavior by defining your copy constructor (see L<"Copy Constructor">).
-
-It is expected that arguments to methods that are not explicitly supposed
-to be changed are constant (but this is not enforced).
-
-=head1 AUTHOR
-
-Ilya Zakharevich <F<ilya@math.mps.ohio-state.edu>>.
-
-=head1 DIAGNOSTICS
-
-When Perl is run with the B<-Do> switch or its equivalent, overloading
-induces diagnostic messages.
-
-=head1 BUGS
-
-Because it's used for overloading, the per-package associative array
-%OVERLOAD now has a special meaning in Perl.
-
-Although the copy constructor is specially designed to make overloading
-operations with references to an array simpler, as it now works it's
-useless for this because a subroutine cannot return an array in the same
-way as it returns a scalar (from the point of view of Perl
-internals). Expect a change of interface for the copy constructor.
-
-As shipped, %OVERLOAD is not inherited via the @ISA tree. A patch for
-this is available from the author.
+The old interface involving %OVERLOAD is deprecated and will go away
+RSN. Convert your scripts to
+use overload ...;
+style.
-This document is confusing.
projects / p5sagit/p5-mst-13.2.git / blobdiff