Commit | Line | Data |
4633a7c4 |
1 | package overload; |
2 | |
3 | sub OVERLOAD { |
4 | $package = shift; |
5 | my %arg = @_; |
6 | my $hash = \%{$package . "::OVERLOAD"}; |
7 | for (keys %arg) { |
8 | $hash->{$_} = $arg{$_}; |
9 | } |
10 | } |
11 | |
12 | sub import { |
13 | $package = (caller())[0]; |
14 | # *{$package . "::OVERLOAD"} = \&OVERLOAD; |
15 | shift; |
16 | $package->overload::OVERLOAD(@_); |
17 | } |
18 | |
19 | sub unimport { |
20 | $package = (caller())[0]; |
21 | my $hash = \%{$package . "::OVERLOAD"}; |
22 | shift; |
23 | for (@_) { |
24 | delete $hash->{$_}; |
25 | } |
26 | } |
27 | |
28 | sub Overloaded { |
29 | defined ($package = ref $_[0]) and defined %{$package . "::OVERLOAD"}; |
30 | } |
31 | |
32 | sub OverloadedStringify { |
33 | defined ($package = ref $_[0]) and |
34 | defined %{$package . "::OVERLOAD"} and |
35 | exists $ {$package . "::OVERLOAD"}{'""'} and |
36 | defined &{$ {$package . "::OVERLOAD"}{'""'}}; |
37 | } |
38 | |
39 | sub Method { |
40 | defined ($package = ref $_[0]) and |
41 | defined %{$package . "::OVERLOAD"} and |
42 | $ {$package . "::OVERLOAD"}{$_[1]}; |
43 | } |
44 | |
45 | sub AddrRef { |
46 | $package = ref $_[0]; |
47 | bless $_[0], Overload::Fake; # Non-overloaded package |
48 | my $str = "$_[0]"; |
49 | bless $_[0], $package; # Back |
50 | $str; |
51 | } |
52 | |
53 | sub StrVal { |
54 | (OverloadedStringify) ? |
55 | (AddrRef) : |
56 | "$_[0]"; |
57 | } |
58 | |
59 | 1; |
60 | |
61 | __END__ |
62 | |
63 | =head1 NAME |
64 | |
cb1a09d0 |
65 | overload - Package for overloading perl operations |
4633a7c4 |
66 | |
67 | =head1 SYNOPSIS |
68 | |
69 | package SomeThing; |
70 | |
71 | use overload |
72 | '+' => \&myadd, |
73 | '-' => \&mysub; |
74 | # etc |
75 | ... |
76 | |
77 | package main; |
78 | $a = new SomeThing 57; |
79 | $b=5+$a; |
80 | ... |
81 | if (overload::Overloaded $b) {...} |
82 | ... |
83 | $strval = overload::StrVal $b; |
84 | |
85 | =head1 CAVEAT SCRIPTOR |
86 | |
87 | Overloading of operators is a subject not to be taken lightly. |
88 | Neither its precise implementation, syntax, nor semantics are |
89 | 100% endorsed by Larry Wall. So any of these may be changed |
90 | at some point in the future. |
91 | |
92 | =head1 DESCRIPTION |
93 | |
94 | =head2 Declaration of overloaded functions |
95 | |
96 | The compilation directive |
97 | |
98 | package Number; |
99 | use overload |
100 | "+" => \&add, |
101 | "*=" => "muas"; |
102 | |
103 | declares function Number::add() for addition, and method muas() in |
104 | the "class" C<Number> (or one of its base classes) |
105 | for the assignment form C<*=> of multiplication. |
106 | |
107 | Arguments of this directive come in (key, value) pairs. Legal values |
108 | are values legal inside a C<&{ ... }> call, so the name of a subroutine, |
109 | a reference to a subroutine, or an anonymous subroutine will all work. |
110 | Legal keys are listed below. |
111 | |
112 | The subroutine C<add> will be called to execute C<$a+$b> if $a |
113 | is a reference to an object blessed into the package C<Number>, or if $a is |
114 | not an object from a package with defined mathemagic addition, but $b is a |
115 | reference to a C<Number>. It can also be called in other situations, like |
116 | C<$a+=7>, or C<$a++>. See L<MAGIC AUTOGENERATION>. (Mathemagical |
117 | methods refer to methods triggered by an overloaded mathematical |
118 | operator.) |
119 | |
120 | =head2 Calling Conventions for Binary Operations |
121 | |
122 | The functions specified in the C<use overload ...> directive are called |
123 | with three (in one particular case with four, see L<Last Resort>) |
124 | arguments. If the corresponding operation is binary, then the first |
125 | two arguments are the two arguments of the operation. However, due to |
126 | general object calling conventions, the first argument should always be |
127 | an object in the package, so in the situation of C<7+$a>, the |
128 | order of the arguments is interchanged. It probably does not matter |
129 | when implementing the addition method, but whether the arguments |
130 | are reversed is vital to the subtraction method. The method can |
131 | query this information by examining the third argument, which can take |
132 | three different values: |
133 | |
134 | =over 7 |
135 | |
136 | =item FALSE |
137 | |
138 | the order of arguments is as in the current operation. |
139 | |
140 | =item TRUE |
141 | |
142 | the arguments are reversed. |
143 | |
144 | =item C<undef> |
145 | |
146 | the current operation is an assignment variant (as in |
147 | C<$a+=7>), but the usual function is called instead. This additional |
148 | information can be used to generate some optimizations. |
149 | |
150 | =back |
151 | |
152 | =head2 Calling Conventions for Unary Operations |
153 | |
154 | Unary operation are considered binary operations with the second |
155 | argument being C<undef>. Thus the functions that overloads C<{"++"}> |
156 | is called with arguments C<($a,undef,'')> when $a++ is executed. |
157 | |
158 | =head2 Overloadable Operations |
159 | |
160 | The following symbols can be specified in C<use overload>: |
161 | |
162 | =over 5 |
163 | |
164 | =item * I<Arithmetic operations> |
165 | |
166 | "+", "+=", "-", "-=", "*", "*=", "/", "/=", "%", "%=", |
167 | "**", "**=", "<<", "<<=", ">>", ">>=", "x", "x=", ".", ".=", |
168 | |
169 | For these operations a substituted non-assignment variant can be called if |
170 | the assignment variant is not available. Methods for operations "C<+>", |
171 | "C<->", "C<+=>", and "C<-=>" can be called to automatically generate |
172 | increment and decrement methods. The operation "C<->" can be used to |
173 | autogenerate missing methods for unary minus or C<abs>. |
174 | |
175 | =item * I<Comparison operations> |
176 | |
177 | "<", "<=", ">", ">=", "==", "!=", "<=>", |
178 | "lt", "le", "gt", "ge", "eq", "ne", "cmp", |
179 | |
180 | If the corresponding "spaceship" variant is available, it can be |
181 | used to substitute for the missing operation. During C<sort>ing |
182 | arrays, C<cmp> is used to compare values subject to C<use overload>. |
183 | |
184 | =item * I<Bit operations> |
185 | |
186 | "&", "^", "|", "neg", "!", "~", |
187 | |
188 | "C<neg>" stands for unary minus. If the method for C<neg> is not |
189 | specified, it can be autogenerated using the method for subtraction. |
190 | |
191 | =item * I<Increment and decrement> |
192 | |
193 | "++", "--", |
194 | |
195 | If undefined, addition and subtraction methods can be |
196 | used instead. These operations are called both in prefix and |
197 | postfix form. |
198 | |
199 | =item * I<Transcendental functions> |
200 | |
201 | "atan2", "cos", "sin", "exp", "abs", "log", "sqrt", |
202 | |
203 | If C<abs> is unavailable, it can be autogenerated using methods |
204 | for "<" or "<=>" combined with either unary minus or subtraction. |
205 | |
206 | =item * I<Boolean, string and numeric conversion> |
207 | |
208 | "bool", "\"\"", "0+", |
209 | |
210 | If one or two of these operations are unavailable, the remaining ones can |
211 | be used instead. C<bool> is used in the flow control operators |
212 | (like C<while>) and for the ternary "C<?:>" operation. These functions can |
213 | return any arbitrary Perl value. If the corresponding operation for this value |
214 | is overloaded too, that operation will be called again with this value. |
215 | |
216 | =item * I<Special> |
217 | |
218 | "nomethod", "fallback", "=", |
219 | |
220 | see L<SPECIAL SYMBOLS FOR C<use overload>>. |
221 | |
222 | =back |
223 | |
224 | See L<"Fallback"> for an explanation of when a missing method can be autogenerated. |
225 | |
226 | =head1 SPECIAL SYMBOLS FOR C<use overload> |
227 | |
228 | Three keys are recognized by Perl that are not covered by the above |
229 | description. |
230 | |
231 | =head2 Last Resort |
232 | |
233 | C<"nomethod"> should be followed by a reference to a function of four |
234 | parameters. If defined, it is called when the overloading mechanism |
235 | cannot find a method for some operation. The first three arguments of |
236 | this function coincide with the arguments for the corresponding method if |
237 | it were found, the fourth argument is the symbol |
238 | corresponding to the missing method. If several methods are tried, |
239 | the last one is used. Say, C<1-$a> can be equivalent to |
240 | |
241 | &nomethodMethod($a,1,1,"-") |
242 | |
243 | if the pair C<"nomethod" =E<gt> "nomethodMethod"> was specified in the |
244 | C<use overload> directive. |
245 | |
246 | If some operation cannot be resolved, and there is no function |
247 | assigned to C<"nomethod">, then an exception will be raised via die()-- |
248 | unless C<"fallback"> was specified as a key in C<use overload> directive. |
249 | |
250 | =head2 Fallback |
251 | |
252 | The key C<"fallback"> governs what to do if a method for a particular |
253 | operation is not found. Three different cases are possible depending on |
254 | the value of C<"fallback">: |
255 | |
256 | =over 16 |
257 | |
258 | =item * C<undef> |
259 | |
260 | Perl tries to use a |
261 | substituted method (see L<MAGIC AUTOGENERATION>). If this fails, it |
262 | then tries to calls C<"nomethod"> value; if missing, an exception |
263 | will be raised. |
264 | |
265 | =item * TRUE |
266 | |
267 | The same as for the C<undef> value, but no exception is raised. Instead, |
268 | it silently reverts to what it would have done were there no C<use overload> |
269 | present. |
270 | |
271 | =item * defined, but FALSE |
272 | |
273 | No autogeneration is tried. Perl tries to call |
274 | C<"nomethod"> value, and if this is missing, raises an exception. |
275 | |
276 | =back |
277 | |
278 | =head2 Copy Constructor |
279 | |
280 | The value for C<"="> is a reference to a function with three |
281 | arguments, i.e., it looks like the other values in C<use |
282 | overload>. However, it does not overload the Perl assignment |
283 | operator. This would go against Camel hair. |
284 | |
285 | This operation is called in the situations when a mutator is applied |
286 | to a reference that shares its object with some other reference, such |
287 | as |
288 | |
289 | $a=$b; |
290 | $a++; |
291 | |
292 | To make this change $a and not change $b, a copy of C<$$a> is made, |
293 | and $a is assigned a reference to this new object. This operation is |
294 | done during execution of the C<$a++>, and not during the assignment, |
295 | (so before the increment C<$$a> coincides with C<$$b>). This is only |
296 | done if C<++> is expressed via a method for C<'++'> or C<'+='>. Note |
297 | that if this operation is expressed via C<'+'> a nonmutator, i.e., as |
298 | in |
299 | |
300 | $a=$b; |
301 | $a=$a+1; |
302 | |
303 | then C<$a> does not reference a new copy of C<$$a>, since $$a does not |
304 | appear as lvalue when the above code is executed. |
305 | |
306 | If the copy constructor is required during the execution of some mutator, |
307 | but a method for C<'='> was not specified, it can be autogenerated as a |
308 | string copy if the object is a plain scalar. |
309 | |
310 | =over 5 |
311 | |
312 | =item B<Example> |
313 | |
314 | The actually executed code for |
315 | |
316 | $a=$b; |
317 | Something else which does not modify $a or $b.... |
318 | ++$a; |
319 | |
320 | may be |
321 | |
322 | $a=$b; |
323 | Something else which does not modify $a or $b.... |
324 | $a = $a->clone(undef,""); |
325 | $a->incr(undef,""); |
326 | |
327 | if $b was mathemagical, and C<'++'> was overloaded with C<\&incr>, |
328 | C<'='> was overloaded with C<\&clone>. |
329 | |
330 | =back |
331 | |
332 | =head1 MAGIC AUTOGENERATION |
333 | |
334 | If a method for an operation is not found, and the value for C<"fallback"> is |
335 | TRUE or undefined, Perl tries to autogenerate a substitute method for |
336 | the missing operation based on the defined operations. Autogenerated method |
337 | substitutions are possible for the following operations: |
338 | |
339 | =over 16 |
340 | |
341 | =item I<Assignment forms of arithmetic operations> |
342 | |
343 | C<$a+=$b> can use the method for C<"+"> if the method for C<"+="> |
344 | is not defined. |
345 | |
346 | =item I<Conversion operations> |
347 | |
348 | String, numeric, and boolean conversion are calculated in terms of one |
349 | another if not all of them are defined. |
350 | |
351 | =item I<Increment and decrement> |
352 | |
353 | The C<++$a> operation can be expressed in terms of C<$a+=1> or C<$a+1>, |
354 | and C<$a--> in terms of C<$a-=1> and C<$a-1>. |
355 | |
356 | =item C<abs($a)> |
357 | |
358 | can be expressed in terms of C<$aE<lt>0> and C<-$a> (or C<0-$a>). |
359 | |
360 | =item I<Unary minus> |
361 | |
362 | can be expressed in terms of subtraction. |
363 | |
364 | =item I<Concatenation> |
365 | |
366 | can be expressed in terms of string conversion. |
367 | |
368 | =item I<Comparison operations> |
369 | |
370 | can be expressed in terms of its "spaceship" counterpart: either |
371 | C<E<lt>=E<gt>> or C<cmp>: |
372 | |
373 | <, >, <=, >=, ==, != in terms of <=> |
374 | lt, gt, le, ge, eq, ne in terms of cmp |
375 | |
376 | =item I<Copy operator> |
377 | |
378 | can be expressed in terms of an assignment to the dereferenced value, if this |
379 | value is a scalar and not a reference. |
380 | |
381 | =back |
382 | |
383 | =head1 WARNING |
384 | |
385 | The restriction for the comparison operation is that even if, for example, |
386 | `C<cmp>' should return a blessed reference, the autogenerated `C<lt>' |
387 | function will produce only a standard logical value based on the |
388 | numerical value of the result of `C<cmp>'. In particular, a working |
389 | numeric conversion is needed in this case (possibly expressed in terms of |
390 | other conversions). |
391 | |
392 | Similarly, C<.=> and C<x=> operators lose their mathemagical properties |
393 | if the string conversion substitution is applied. |
394 | |
395 | When you chop() a mathemagical object it is promoted to a string and its |
396 | mathemagical properties are lost. The same can happen with other |
397 | operations as well. |
398 | |
399 | =head1 Run-time Overloading |
400 | |
401 | Since all C<use> directives are executed at compile-time, the only way to |
402 | change overloading during run-time is to |
403 | |
404 | eval 'use overload "+" => \&addmethod'; |
405 | |
406 | You can also use |
407 | |
408 | eval 'no overload "+", "--", "<="'; |
409 | |
410 | though the use of these constructs during run-time is questionable. |
411 | |
412 | =head1 Public functions |
413 | |
414 | Package C<overload.pm> provides the following public functions: |
415 | |
416 | =over 5 |
417 | |
418 | =item overload::StrVal(arg) |
419 | |
420 | Gives string value of C<arg> as in absence of stringify overloading. |
421 | |
422 | =item overload::Overloaded(arg) |
423 | |
424 | Returns true if C<arg> is subject to overloading of some operations. |
425 | |
426 | =item overload::Method(obj,op) |
427 | |
428 | Returns C<undef> or a reference to the method that implements C<op>. |
429 | |
430 | =back |
431 | |
432 | =head1 IMPLEMENTATION |
433 | |
434 | What follows is subject to change RSN. |
435 | |
436 | The table of methods for all operations is cached as magic in the |
437 | symbol table hash for the package. The table is rechecked for changes due to |
438 | C<use overload>, C<no overload>, and @ISA only during |
439 | C<bless>ing; so if they are changed dynamically, you'll need an |
440 | additional fake C<bless>ing to update the table. |
441 | |
442 | (Every SVish thing has a magic queue, and magic is an entry in that queue. |
443 | This is how a single variable may participate in multiple forms of magic |
444 | simultaneously. For instance, environment variables regularly have two |
445 | forms at once: their %ENV magic and their taint magic.) |
446 | |
447 | If an object belongs to a package using overload, it carries a special |
448 | flag. Thus the only speed penalty during arithmetic operations without |
449 | overloading is the checking of this flag. |
450 | |
451 | In fact, if C<use overload> is not present, there is almost no overhead for |
452 | overloadable operations, so most programs should not suffer measurable |
453 | performance penalties. A considerable effort was made to minimize the overhead |
454 | when overload is used and the current operation is overloadable but |
455 | the arguments in question do not belong to packages using overload. When |
456 | in doubt, test your speed with C<use overload> and without it. So far there |
457 | have been no reports of substantial speed degradation if Perl is compiled |
458 | with optimization turned on. |
459 | |
460 | There is no size penalty for data if overload is not used. |
461 | |
462 | Copying (C<$a=$b>) is shallow; however, a one-level-deep copying is |
463 | carried out before any operation that can imply an assignment to the |
464 | object $a (or $b) refers to, like C<$a++>. You can override this |
465 | behavior by defining your own copy constructor (see L<"Copy Constructor">). |
466 | |
467 | It is expected that arguments to methods that are not explicitly supposed |
468 | to be changed are constant (but this is not enforced). |
469 | |
470 | =head1 AUTHOR |
471 | |
472 | Ilya Zakharevich <F<ilya@math.mps.ohio-state.edu>>. |
473 | |
474 | =head1 DIAGNOSTICS |
475 | |
476 | When Perl is run with the B<-Do> switch or its equivalent, overloading |
477 | induces diagnostic messages. |
478 | |
479 | =head1 BUGS |
480 | |
481 | Because it is used for overloading, the per-package associative array |
482 | %OVERLOAD now has a special meaning in Perl. |
483 | |
484 | As shipped, mathemagical properties are not inherited via the @ISA tree. |
485 | |
486 | This document is confusing. |
487 | |
488 | =cut |
489 | |