Commit | Line | Data |
a0d0e21e |
1 | =head1 NAME |
2 | |
3 | perlovl - perl overloading semantics |
4 | |
5 | =head1 SYNOPSIS |
6 | |
7 | package SomeThing; |
8 | |
9 | %OVERLOAD = ( |
10 | '+' => \&myadd, |
11 | '-' => \&mysub, |
12 | # etc |
13 | ); |
14 | ... |
15 | |
16 | package main; |
17 | $a = new SomeThing 57; |
18 | $b=5+$a; |
19 | |
20 | =head1 CAVEAT SCRIPTOR |
21 | |
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. |
26 | |
27 | =head1 DESCRIPTION |
28 | |
29 | =head2 Declaration of overloaded functions |
30 | |
31 | package Number; |
32 | %OVERLOAD = ( |
33 | "+" => \&add, |
34 | "*=" => "muas" |
35 | ); |
36 | |
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 |
42 | will all work. |
43 | |
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 |
50 | operator.) |
51 | |
52 | =head2 Calling Conventions for Binary Operations |
53 | |
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: |
64 | |
65 | =over 7 |
66 | |
67 | =item FALSE |
68 | |
69 | the order of arguments is as in the current operation. |
70 | |
71 | =item TRUE |
72 | |
73 | the arguments are reversed. |
74 | |
75 | =item C<undef> |
76 | |
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. |
80 | |
81 | =back |
82 | |
83 | =head2 Calling Conventions for Unary Operations |
84 | |
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. |
88 | |
89 | =head2 Overloadable Operations |
90 | |
91 | The following keys of %OVERLOAD are recognized: |
92 | |
93 | =over 5 |
94 | |
95 | =item * I<Arithmetic operations> |
96 | |
97 | "+", "+=", "-", "-=", "*", "*=", "/", "/=", "%", "%=", |
98 | "**", "**=", "<<", "<<=", ">>", ">>=", "x", "x=", ".", ".=", |
99 | |
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>. |
105 | |
106 | =item * I<Comparison operations> |
107 | |
108 | "<", "<=", ">", ">=", "==", "!=", "<=>", |
109 | "lt", "le", "gt", "ge", "eq", "ne", "cmp", |
110 | |
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. |
114 | |
115 | =item * I<Bit operations> |
116 | |
748a9306 |
117 | "&", "^", "|", "&=", "^=", "|=", "neg", "!", "~", |
a0d0e21e |
118 | |
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. |
121 | |
122 | =item * I<Increment and decrement> |
123 | |
124 | "++", "--", |
125 | |
126 | If undefined, addition and subtraction methods can be |
127 | used instead. These operations are called both in prefix and |
128 | postfix form. |
129 | |
130 | =item * I<Transcendental functions> |
131 | |
132 | "atan2", "cos", "sin", "exp", "abs", "log", "sqrt", |
133 | |
134 | If C<abs> is unavailable, it can be autogenerated using methods |
135 | for "<" or "<=>" combined with either unary minus or subtraction. |
136 | |
137 | =item * I<Boolean, string and numeric conversion> |
138 | |
139 | "bool", "\"\"", "0+", |
140 | |
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. |
146 | |
147 | =item * I<Special> |
148 | |
149 | "nomethod", "fallback", "=", |
150 | |
151 | see L<SPECIAL KEYS OF %OVERLOAD>. |
152 | |
153 | =back |
154 | |
155 | See L<"Fallback"> for an explanation of when a missing method can be autogenerated. |
156 | |
157 | =head1 SPECIAL KEYS OF %OVERLOAD |
158 | |
159 | Three keys are recognized by Perl that are not covered by the above |
160 | description. |
161 | |
162 | =head2 Last Resort |
163 | |
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> |
170 | can be equivalent to |
171 | |
172 | &{ $Pack::OVERLOAD{"nomethod"} }($a,1,1,"-"). |
173 | |
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. |
177 | |
178 | =head2 Fallback |
179 | |
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"}>: |
183 | |
184 | =over 16 |
185 | |
186 | =item * C<undef> |
187 | |
188 | Perl tries to use a |
189 | substituted method (see L<MAGIC AUTOGENERATION>). If this fails, it |
190 | then tries to calls C<$OVERLOAD{"nomethod"}>; if missing, an exception |
191 | will be raised. |
192 | |
193 | =item * TRUE |
194 | |
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 |
197 | present. |
198 | |
199 | =item * defined, but FALSE |
200 | |
201 | No autogeneration is tried. Perl tries to call |
202 | C<$OVERLOAD{"nomethod"}>, and if this is missing, raises an exception. |
203 | |
204 | =back |
205 | |
206 | =head2 Copy Constructor |
207 | |
208 | C<$OVERLOAD{"="}> is a reference to a function with three arguments, |
748a9306 |
209 | i.e., it looks like a usual value of %OVERLOAD. This operation |
a0d0e21e |
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 |
212 | |
213 | $a=$b; |
214 | $a++; |
215 | |
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<+>', |
221 | i.e., as |
222 | |
223 | $a=$b; |
224 | $a=$a+1; |
225 | |
226 | then C<$$a> and C<$$b> do not appear as lvalues. |
227 | |
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 |
230 | copy if an object of |
231 | the package is a plain scalar. |
232 | |
233 | =head1 MAGIC AUTOGENERATION |
234 | |
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: |
239 | |
240 | =over 16 |
241 | |
242 | =item I<Assignment forms of arithmetic operations> |
243 | |
244 | C<$a=+$b> can use the C<$OVERLOAD{"+"}> method if C<$OVERLOAD{"+="}> |
245 | is not defined. |
246 | |
247 | =item I<Conversion operations> |
248 | |
249 | String, numeric, and boolean conversion are calculated in terms of one |
250 | another if not all of them are defined. |
251 | |
252 | =item I<Increment and decrement> |
253 | |
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>. |
256 | |
257 | =item C<abs($a)> |
258 | |
259 | can be expressed in terms of C<$aE<lt>0> and C<-$a> (or C<0-$a>). |
260 | |
261 | =item I<Unary minus> |
262 | |
263 | can be expressed in terms of subtraction. |
264 | |
265 | =item I<Concatenation> |
266 | |
267 | can be expressed in terms of string conversion. |
268 | |
269 | =item I<Comparison operations> |
270 | |
271 | can be expressed in terms of its "spaceship" counterpart: either |
272 | C<E<lt>=E<gt>> or C<cmp>: |
273 | |
274 | <, >, <=, >=, ==, != in terms of <=> |
275 | lt, gt, le, ge, eq, ne in terms of cmp |
276 | |
277 | =item I<Copy operator> |
278 | |
279 | can be expressed in terms of assignment to the dereferenced value, if this |
280 | value is scalar but not a reference. |
281 | |
282 | =back |
283 | |
284 | =head1 WARNING |
285 | |
286 | The restriction for the comparison operation is that even if, for example, |
748a9306 |
287 | `C<cmp>' should return a reference to a blessed object, the |
288 | autogenerated `C<lt>' |
a0d0e21e |
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 |
292 | other conversions). |
293 | |
294 | Similarly, C<.=> and C<x=> operators lose their mathemagical properties |
295 | if the string conversion substitution is applied. |
296 | |
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 |
299 | operations as well. |
300 | |
301 | =head1 IMPLEMENTATION |
302 | |
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 |
307 | table. |
308 | |
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.) |
313 | |
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. |
317 | |
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. |
326 | |
327 | There is no size penalty for data if there is no %OVERLOAD. |
328 | |
329 | The copying like C<$a=$b> is shallow; however, a one-level-deep |
330 | copying is |
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">). |
334 | |
335 | It is expected that arguments to methods that are not explicitly supposed |
336 | to be changed are constant (but this is not enforced). |
337 | |
338 | =head1 AUTHOR |
339 | |
340 | Ilya Zakharevich <F<ilya@math.mps.ohio-state.edu>>. |
341 | |
342 | =head1 DIAGNOSTICS |
343 | |
344 | When Perl is run with the B<-Do> switch or its equivalent, overloading |
345 | induces diagnostic messages. |
346 | |
347 | =head1 BUGS |
348 | |
349 | Because it's used for overloading, the per-package associative array |
350 | %OVERLOAD now has a special meaning in Perl. |
351 | |
a0d0e21e |
352 | As shipped, %OVERLOAD is not inherited via the @ISA tree. A patch for |
353 | this is available from the author. |
354 | |
355 | This document is confusing. |