diff options
Diffstat (limited to 'pod/perlovl.pod')
| -rw-r--r-- | pod/perlovl.pod | 363 |
1 files changed, 363 insertions, 0 deletions
diff --git a/pod/perlovl.pod b/pod/perlovl.pod new file mode 100644 index 0000000000..db00f4dbf1 --- /dev/null +++ b/pod/perlovl.pod @@ -0,0 +1,363 @@ +=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. + +=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 + +=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. + +This document is confusing. |