X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlovl.pod;h=208456d239e27a473e7631cec0248c0144608d4f;hb=a2eb900354d7492c5b0c2f521e88387de8974900;hp=db00f4dbf14823db9912cacf1a35cfcdd0162c81;hpb=a0d0e21ea6ea90a22318550944fe6cb09ae10cda;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlovl.pod b/pod/perlovl.pod index db00f4d..208456d 100644 --- a/pod/perlovl.pod +++ b/pod/perlovl.pod @@ -1,363 +1,15 @@ -=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 (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, or $a is -not an object from a package with defined mathemagic addition, but $b is a -reference to a C. It can be called also in other situations, like -C<$a+=7>, or C<$a++>. See L. (Mathemagical -methods refer to methods triggered by an overloaded mathematical -operator.) - -=head2 Calling Conventions for Binary Operations - -The functions in C are called with three (in one -particular case with four, see L) 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 - -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. 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 - - "+", "+=", "-", "-=", "*", "*=", "/", "/=", "%", "%=", - "**", "**=", "<<", "<<=", ">>", ">>=", "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. - -=item * I - - "<", "<=", ">", ">=", "==", "!=", "<=>", - "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 Cing -arrays, C is used to compare values subject to %OVERLOAD. - -=item * I - - "&", "^", "|", "neg", "!", "~", - -"C" stands for unary minus. If the method for C is not -specified, it can be autogenerated using on the method for subtraction. - -=item * I - - "++", "--", - -If undefined, addition and subtraction methods can be -used instead. These operations are called both in prefix and -postfix form. - -=item * I - - "atan2", "cos", "sin", "exp", "abs", "log", "sqrt", - -If C is unavailable, it can be autogenerated using methods -for "<" or "<=>" combined with either unary minus or subtraction. - -=item * I - - "bool", "\"\"", "0+", - -If one or two of these operations are unavailable, the remaining ones can -be used instead. C is used in the flow control operators -(like C) 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 - - "nomethod", "fallback", "=", - -see L. - -=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 - -Perl tries to use a -substituted method (see L). 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 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 - -C<$a=+$b> can use the C<$OVERLOAD{"+"}> method if C<$OVERLOAD{"+="}> -is not defined. - -=item I - -String, numeric, and boolean conversion are calculated in terms of one -another if not all of them are defined. - -=item I - -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 - -can be expressed in terms of C<$aE0> and C<-$a> (or C<0-$a>). - -=item I - -can be expressed in terms of subtraction. - -=item I - -can be expressed in terms of string conversion. - -=item I - -can be expressed in terms of its "spaceship" counterpart: either -C=E> or C: - - <, >, <=, >=, ==, != in terms of <=> - lt, gt, le, ge, eq, ne in terms of cmp - -=item I - -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. =head1 WARNING -The restriction for the comparison operation is that even if, for example, -`C' should return a blessed reference, the autogenerated `C' -function will produce only a standard logical value based on the -numerical value of the result of `C'. In particular, a working -numeric conversion is needed in this case (possibly expressed in terms of -other conversions). - -Similarly, C<.=> and C 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 Cing; so if it is changed -dynamically, you'll need an additional fake Cing 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 >. - -=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.