3 perlovl - perl overloading semantics
17 $a = new SomeThing 57;
20 =head1 CAVEAT SCRIPTOR
22 Overloading of operators is a subject not to be taken lightly.
23 Neither its precise implementation, syntax, nor semantics are
24 100% endorsed by Larry Wall. So any of these may be changed
25 at some point in the future.
29 =head2 Declaration of overloaded functions
37 declares function Number::add() for addition, and method muas() in
38 the "class" C<Number> (or one of its base classes)
39 for the assignment form C<*=> of multiplication. Legal values of this
40 hash array are values legal inside C<&{ ... }> call, so the name of a
41 subroutine, a reference to a subroutine, or an anonymous subroutine
44 The subroutine C<$OVERLOAD{"+"}> will be called to execute C<$a+$b> if $a
45 is a reference to an object blessed into the package C<Number>, or $a is
46 not an object from a package with defined mathemagic addition, but $b is a
47 reference to a C<Number>. It can be called also in other situations, like
48 C<$a+=7>, or C<$a++>. See L<MAGIC AUTOGENERATION>. (Mathemagical
49 methods refer to methods triggered by an overloaded mathematical
52 =head2 Calling Conventions for Binary Operations
54 The functions in C<values %OVERLOAD> are called with three (in one
55 particular case with four, see L<Last Resort>) arguments. If the
56 corresponding operation is binary, then the first two arguments are the
57 two arguments of the operation. However, due to general object calling
58 conventions, the first argument should be always an object in the package,
59 so in the situation of C<7+$a>, the order of arguments is interchanged.
60 Most probably it does not matter for implementation of the addition
61 method, but whether the arguments are reversed is vital for the
62 subtraction method. The subroutine can query this information by
63 examining the third argument, which can take three different values:
69 the order of arguments is as in the current operation.
73 the arguments are reversed.
77 the current operation is an assignment variant (as in
78 C<$a+=7>), but the usual function is called instead. This additional
79 information can be used to generate some optimizations.
83 =head2 Calling Conventions for Unary Operations
85 Unary operation are considered binary operations with the second
86 argument being C<undef>. Thus C<$OVERLOAD{"++"}> is called with
87 arguments C<($a,undef,'')> when $a++ is executed.
89 =head2 Overloadable Operations
91 The following keys of %OVERLOAD are recognized:
95 =item * I<Arithmetic operations>
97 "+", "+=", "-", "-=", "*", "*=", "/", "/=", "%", "%=",
98 "**", "**=", "<<", "<<=", ">>", ">>=", "x", "x=", ".", ".=",
100 For these operations a substituted non-assignment variant can be called if
101 the assignment variant is not available. Methods for operations "C<+>",
102 "C<->", "C<+=>", and "C<-=>" can be called to automatically generate
103 increment and decrement methods. The operations "C<->" can be used to
104 autogenerate missing methods for unary minus or C<abs>.
106 =item * I<Comparison operations>
108 "<", "<=", ">", ">=", "==", "!=", "<=>",
109 "lt", "le", "gt", "ge", "eq", "ne", "cmp",
111 If the corresponding "spaceship" variant is available, it can be
112 used to substitute for the missing operation. During C<sort>ing
113 arrays, C<cmp> is used to compare values subject to %OVERLOAD.
115 =item * I<Bit operations>
117 "&", "^", "|", "&=", "^=", "|=", "neg", "!", "~",
119 "C<neg>" stands for unary minus. If the method for C<neg> is not
120 specified, it can be autogenerated using on the method for subtraction.
122 =item * I<Increment and decrement>
126 If undefined, addition and subtraction methods can be
127 used instead. These operations are called both in prefix and
130 =item * I<Transcendental functions>
132 "atan2", "cos", "sin", "exp", "abs", "log", "sqrt",
134 If C<abs> is unavailable, it can be autogenerated using methods
135 for "<" or "<=>" combined with either unary minus or subtraction.
137 =item * I<Boolean, string and numeric conversion>
139 "bool", "\"\"", "0+",
141 If one or two of these operations are unavailable, the remaining ones can
142 be used instead. C<bool> is used in the flow control operators
143 (like C<while>) and for the ternary "C<?:>" operation. These functions can
144 return any arbitrary Perl value. If the corresponding operation for this value
145 is overloaded too, that operation will be called again with this value.
149 "nomethod", "fallback", "=",
151 see L<SPECIAL KEYS OF %OVERLOAD>.
155 See L<"Fallback"> for an explanation of when a missing method can be autogenerated.
157 =head1 SPECIAL KEYS OF %OVERLOAD
159 Three keys are recognized by Perl that are not covered by the above
164 C<$OVERLOAD{"nomethod"}> is a reference to a function of four parameters.
165 If defined, it is called when the overloading mechanism cannot find a
166 method for some operation. The first three arguments of this function
167 coincide with arguments for the corresponding method if it were found, the
168 fourth argument is the key of %OVERLOAD corresponding to the missing
169 method. If several methods are tried, the last one is used. Say, C<1-$a>
172 &{ $Pack::OVERLOAD{"nomethod"} }($a,1,1,"-").
174 If some operation cannot be resolved, and there is no
175 C<$OVERLOAD{"nomethod"}>, then an exception will be raised
176 via die() -- unless C<$OVERLOAD{"fallback"}> is true.
180 C<$OVERLOAD{"fallback"}> governs what to do if a method for a particular
181 operation is not found. Three different cases are possible depending on
182 value of C<$OVERLOAD{"fallback"}>:
189 substituted method (see L<MAGIC AUTOGENERATION>). If this fails, it
190 then tries to calls C<$OVERLOAD{"nomethod"}>; if missing, an exception
195 The same as for the C<undef> value, but no exception is raised. Instead,
196 it silently reverts to what it would have done were there no %OVERLOAD is
199 =item * defined, but FALSE
201 No autogeneration is tried. Perl tries to call
202 C<$OVERLOAD{"nomethod"}>, and if this is missing, raises an exception.
206 =head2 Copy Constructor
208 C<$OVERLOAD{"="}> is a reference to a function with three arguments,
209 i.e., it looks like a usual value of %OVERLOAD. This operation
210 is called in the situations when a mutator is applied to a reference
211 that shares its object with some other reference, such as
216 To make this change to $a and not to change $b, a freshly made copy of
217 C<$$a> is made, and $a is assigned a reference to this object. This
218 operation is executed during C<$a++>, (so before this C<$$a> coincides
219 with C<$$b>), and only if C<++> is expressed via C<$OPERATOR{'++'}> or
220 C<$OPERATOR{'+='}>. Note that if this operation is expressed via 'C<+>',
226 then C<$$a> and C<$$b> do not appear as lvalues.
228 If the copy constructor is required during execution of some mutator, but
229 C<$OPERATOR{'='}> is missing, it can be autogenerated as a string
231 the package is a plain scalar.
233 =head1 MAGIC AUTOGENERATION
235 If a method for an operation is not found, and C<$OVERLOAD{"fallback"}> is
236 TRUE or undefined, Perl tries to to autogenerate a substitute method for
237 the missing operation based on defined operations. Autogenerated method
238 substitutions are possible for the following operations:
242 =item I<Assignment forms of arithmetic operations>
244 C<$a=+$b> can use the C<$OVERLOAD{"+"}> method if C<$OVERLOAD{"+="}>
247 =item I<Conversion operations>
249 String, numeric, and boolean conversion are calculated in terms of one
250 another if not all of them are defined.
252 =item I<Increment and decrement>
254 The C<++$a> operation can be expressed in terms of C<$a+=1> or C<$a+1>,
255 and C<$a--> in terms of C<$a-=1> and C<$a-1>.
259 can be expressed in terms of C<$aE<lt>0> and C<-$a> (or C<0-$a>).
263 can be expressed in terms of subtraction.
265 =item I<Concatenation>
267 can be expressed in terms of string conversion.
269 =item I<Comparison operations>
271 can be expressed in terms of its "spaceship" counterpart: either
272 C<E<lt>=E<gt>> or C<cmp>:
274 <, >, <=, >=, ==, != in terms of <=>
275 lt, gt, le, ge, eq, ne in terms of cmp
277 =item I<Copy operator>
279 can be expressed in terms of assignment to the dereferenced value, if this
280 value is scalar but not a reference.
286 The restriction for the comparison operation is that even if, for example,
287 `C<cmp>' should return a reference to a blessed object, the
288 autogenerated `C<lt>'
289 function will produce only a standard logical value based on the
290 numerical value of the result of `C<cmp>'. In particular, a working
291 numeric conversion is needed in this case (possibly expressed in terms of
294 Similarly, C<.=> and C<x=> operators lose their mathemagical properties
295 if the string conversion substitution is applied.
297 When you chop() a mathemagical object, it becomes promoted to a string
298 first, and its mathemagical qualities is lost. The same can happen with other
301 =head1 IMPLEMENTATION
303 The table of methods for all operations is cached as a magic for the
304 symbol table hash of the package. It is rechecked for changes of
305 %OVERLOAD and @ISA only during C<bless>ing; so if it is changed
306 dynamically, you'll need an additional fake C<bless>ing to update the
309 (Every SVish thing has a magic queue, and a magic is an entry in that queue.
310 This is how a single variable may participate in multiple forms of magic
311 simultaneously. For instance, environment variables regularly have two
312 forms at once: their %ENV magic and their taint magic.)
314 If an object belongs to a package with %OVERLOAD, it carries a special
315 flag. Thus the only speed penalty during arithmetic operations without
316 overload is the check of this flag.
318 In fact, if no %OVERLOAD is ever accessed, there is almost no overhead for
319 overloadable operations, so most programs should not suffer measurable
320 performance penalties. Considerable effort was made minimize overhead
321 when %OVERLOAD is accessed and the current operation is overloadable but
322 the arguments in question do not belong to packages with %OVERLOAD. When
323 in doubt, test your speed with %OVERLOAD and without it. So far there
324 have been no reports of substantial speed degradation if Perl is compiled
325 with optimization turned on.
327 There is no size penalty for data if there is no %OVERLOAD.
329 The copying like C<$a=$b> is shallow; however, a one-level-deep
331 carried out before any operation that can imply an assignment to the
332 object $b (or $a) refers to, like C<$b++>. You can override this
333 behavior by defining your copy constructor (see L<"Copy Constructor">).
335 It is expected that arguments to methods that are not explicitly supposed
336 to be changed are constant (but this is not enforced).
340 Ilya Zakharevich <F<ilya@math.mps.ohio-state.edu>>.
344 When Perl is run with the B<-Do> switch or its equivalent, overloading
345 induces diagnostic messages.
349 Because it's used for overloading, the per-package associative array
350 %OVERLOAD now has a special meaning in Perl.
352 As shipped, %OVERLOAD is not inherited via the @ISA tree. A patch for
353 this is available from the author.
355 This document is confusing.