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 | |
117 | "&", "^", "|", "neg", "!", "~", |
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, |
209 | i.e., it looks like a usual value of %OVERLOAD. What is special about |
210 | this subroutine is that it should not return a blessed reference into |
211 | a package (as most other methods are expected to), but rather a freshly made |
212 | copy of its dereferenced argument (see L<"BUGS">, though). This operation |
213 | is called in the situations when a mutator is applied to a reference |
214 | that shares its object with some other reference, such as |
215 | |
216 | $a=$b; |
217 | $a++; |
218 | |
219 | To make this change to $a and not to change $b, a freshly made copy of |
220 | C<$$a> is made, and $a is assigned a reference to this object. This |
221 | operation is executed during C<$a++>, (so before this C<$$a> coincides |
222 | with C<$$b>), and only if C<++> is expressed via C<$OPERATOR{'++'}> or |
223 | C<$OPERATOR{'+='}>. Note that if this operation is expressed via 'C<+>', |
224 | i.e., as |
225 | |
226 | $a=$b; |
227 | $a=$a+1; |
228 | |
229 | then C<$$a> and C<$$b> do not appear as lvalues. |
230 | |
231 | If the copy constructor is required during execution of some mutator, but |
232 | C<$OPERATOR{'='}> is missing, it can be autogenerated as a string |
233 | copy if an object of |
234 | the package is a plain scalar. |
235 | |
236 | =head1 MAGIC AUTOGENERATION |
237 | |
238 | If a method for an operation is not found, and C<$OVERLOAD{"fallback"}> is |
239 | TRUE or undefined, Perl tries to to autogenerate a substitute method for |
240 | the missing operation based on defined operations. Autogenerated method |
241 | substitutions are possible for the following operations: |
242 | |
243 | =over 16 |
244 | |
245 | =item I<Assignment forms of arithmetic operations> |
246 | |
247 | C<$a=+$b> can use the C<$OVERLOAD{"+"}> method if C<$OVERLOAD{"+="}> |
248 | is not defined. |
249 | |
250 | =item I<Conversion operations> |
251 | |
252 | String, numeric, and boolean conversion are calculated in terms of one |
253 | another if not all of them are defined. |
254 | |
255 | =item I<Increment and decrement> |
256 | |
257 | The C<++$a> operation can be expressed in terms of C<$a+=1> or C<$a+1>, |
258 | and C<$a--> in terms of C<$a-=1> and C<$a-1>. |
259 | |
260 | =item C<abs($a)> |
261 | |
262 | can be expressed in terms of C<$aE<lt>0> and C<-$a> (or C<0-$a>). |
263 | |
264 | =item I<Unary minus> |
265 | |
266 | can be expressed in terms of subtraction. |
267 | |
268 | =item I<Concatenation> |
269 | |
270 | can be expressed in terms of string conversion. |
271 | |
272 | =item I<Comparison operations> |
273 | |
274 | can be expressed in terms of its "spaceship" counterpart: either |
275 | C<E<lt>=E<gt>> or C<cmp>: |
276 | |
277 | <, >, <=, >=, ==, != in terms of <=> |
278 | lt, gt, le, ge, eq, ne in terms of cmp |
279 | |
280 | =item I<Copy operator> |
281 | |
282 | can be expressed in terms of assignment to the dereferenced value, if this |
283 | value is scalar but not a reference. |
284 | |
285 | =back |
286 | |
287 | =head1 WARNING |
288 | |
289 | The restriction for the comparison operation is that even if, for example, |
290 | `C<cmp>' should return a blessed reference, the autogenerated `C<lt>' |
291 | function will produce only a standard logical value based on the |
292 | numerical value of the result of `C<cmp>'. In particular, a working |
293 | numeric conversion is needed in this case (possibly expressed in terms of |
294 | other conversions). |
295 | |
296 | Similarly, C<.=> and C<x=> operators lose their mathemagical properties |
297 | if the string conversion substitution is applied. |
298 | |
299 | When you chop() a mathemagical object, it becomes promoted to a string |
300 | first, and its mathemagical qualities is lost. The same can happen with other |
301 | operations as well. |
302 | |
303 | =head1 IMPLEMENTATION |
304 | |
305 | The table of methods for all operations is cached as a magic for the |
306 | symbol table hash of the package. It is rechecked for changes of |
307 | %OVERLOAD and @ISA only during C<bless>ing; so if it is changed |
308 | dynamically, you'll need an additional fake C<bless>ing to update the |
309 | table. |
310 | |
311 | (Every SVish thing has a magic queue, and a magic is an entry in that queue. |
312 | This is how a single variable may participate in multiple forms of magic |
313 | simultaneously. For instance, environment variables regularly have two |
314 | forms at once: their %ENV magic and their taint magic.) |
315 | |
316 | If an object belongs to a package with %OVERLOAD, it carries a special |
317 | flag. Thus the only speed penalty during arithmetic operations without |
318 | overload is the check of this flag. |
319 | |
320 | In fact, if no %OVERLOAD is ever accessed, there is almost no overhead for |
321 | overloadable operations, so most programs should not suffer measurable |
322 | performance penalties. Considerable effort was made minimize overhead |
323 | when %OVERLOAD is accessed and the current operation is overloadable but |
324 | the arguments in question do not belong to packages with %OVERLOAD. When |
325 | in doubt, test your speed with %OVERLOAD and without it. So far there |
326 | have been no reports of substantial speed degradation if Perl is compiled |
327 | with optimization turned on. |
328 | |
329 | There is no size penalty for data if there is no %OVERLOAD. |
330 | |
331 | The copying like C<$a=$b> is shallow; however, a one-level-deep |
332 | copying is |
333 | carried out before any operation that can imply an assignment to the |
334 | object $b (or $a) refers to, like C<$b++>. You can override this |
335 | behavior by defining your copy constructor (see L<"Copy Constructor">). |
336 | |
337 | It is expected that arguments to methods that are not explicitly supposed |
338 | to be changed are constant (but this is not enforced). |
339 | |
340 | =head1 AUTHOR |
341 | |
342 | Ilya Zakharevich <F<ilya@math.mps.ohio-state.edu>>. |
343 | |
344 | =head1 DIAGNOSTICS |
345 | |
346 | When Perl is run with the B<-Do> switch or its equivalent, overloading |
347 | induces diagnostic messages. |
348 | |
349 | =head1 BUGS |
350 | |
351 | Because it's used for overloading, the per-package associative array |
352 | %OVERLOAD now has a special meaning in Perl. |
353 | |
354 | Although the copy constructor is specially designed to make overloading |
355 | operations with references to an array simpler, as it now works it's |
356 | useless for this because a subroutine cannot return an array in the same |
357 | way as it returns a scalar (from the point of view of Perl |
358 | internals). Expect a change of interface for the copy constructor. |
359 | |
360 | As shipped, %OVERLOAD is not inherited via the @ISA tree. A patch for |
361 | this is available from the author. |
362 | |
363 | This document is confusing. |