This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
dfcdb02b1e658130bbdbc9ff15541edae2aaa9ed
[perl5.git] / lib / overload.pm
1 package overload;
2
3 sub nil {}
4
5 sub OVERLOAD {
6   $package = shift;
7   my %arg = @_;
8   my ($sub, $fb);
9   $ {$package . "::OVERLOAD"}{dummy}++; # Register with magic by touching.
10   *{$package . "::()"} = \&nil; # Make it findable via fetchmethod.
11   for (keys %arg) {
12     if ($_ eq 'fallback') {
13       $fb = $arg{$_};
14     } else {
15       $sub = $arg{$_};
16       if (not ref $sub and $sub !~ /::/) {
17         $ {$package . "::(" . $_} = $sub;
18         $sub = \&nil;
19       }
20       #print STDERR "Setting `$ {'package'}::\cO$_' to \\&`$sub'.\n";
21       *{$package . "::(" . $_} = \&{ $sub };
22     }
23   }
24   ${$package . "::()"} = $fb; # Make it findable too (fallback only).
25 }
26
27 sub import {
28   $package = (caller())[0];
29   # *{$package . "::OVERLOAD"} = \&OVERLOAD;
30   shift;
31   $package->overload::OVERLOAD(@_);
32 }
33
34 sub unimport {
35   $package = (caller())[0];
36   ${$package . "::OVERLOAD"}{dummy}++; # Upgrade the table
37   shift;
38   for (@_) {
39     if ($_ eq 'fallback') {
40       undef $ {$package . "::()"};
41     } else {
42       delete $ {$package . "::"}{"(" . $_};
43     }
44   }
45 }
46
47 sub Overloaded {
48   my $package = shift;
49   $package = ref $package if ref $package;
50   $package->can('()');
51 }
52
53 sub ov_method {
54   my $globref = shift;
55   return undef unless $globref;
56   my $sub = \&{*$globref};
57   return $sub if $sub ne \&nil;
58   return shift->can($ {*$globref});
59 }
60
61 sub OverloadedStringify {
62   my $package = shift;
63   $package = ref $package if ref $package;
64   #$package->can('(""')
65   ov_method mycan($package, '(""'), $package;
66 }
67
68 sub Method {
69   my $package = shift;
70   $package = ref $package if ref $package;
71   #my $meth = $package->can('(' . shift);
72   ov_method mycan($package, '(' . shift), $package;
73   #return $meth if $meth ne \&nil;
74   #return $ {*{$meth}};
75 }
76
77 sub AddrRef {
78   my $package = ref $_[0];
79   return "$_[0]" unless $package;
80   bless $_[0], overload::Fake;  # Non-overloaded package
81   my $str = "$_[0]";
82   bless $_[0], $package;        # Back
83   $package . substr $str, index $str, '=';
84 }
85
86 sub StrVal {
87   (OverloadedStringify($_[0])) ?
88     (AddrRef(shift)) :
89     "$_[0]";
90 }
91
92 sub mycan {                             # Real can would leave stubs.
93   my ($package, $meth) = @_;
94   return \*{$package . "::$meth"} if defined &{$package . "::$meth"};
95   my $p;
96   foreach $p (@{$package . "::ISA"}) {
97     my $out = mycan($p, $meth);
98     return $out if $out;
99   }
100   return undef;
101 }
102
103 %constants = (
104               'integer'   =>  0x1000, 
105               'float'     =>  0x2000,
106               'binary'    =>  0x4000,
107               'q'         =>  0x8000,
108               'qr'        => 0x10000,
109              );
110
111 sub constant {
112   # Arguments: what, sub
113   while (@_) {
114     $^H{$_[0]} = $_[1];
115     $^H |= $constants{$_[0]} | 0x20000;
116     shift, shift;
117   }
118 }
119
120 sub remove_constant {
121   # Arguments: what, sub
122   while (@_) {
123     delete $^H{$_[0]};
124     $^H &= ~ $constants{$_[0]};
125     shift, shift;
126   }
127 }
128
129 1;
130
131 __END__
132
133 =head1 NAME 
134
135 overload - Package for overloading perl operations
136
137 =head1 SYNOPSIS
138
139     package SomeThing;
140
141     use overload 
142         '+' => \&myadd,
143         '-' => \&mysub;
144         # etc
145     ...
146
147     package main;
148     $a = new SomeThing 57;
149     $b=5+$a;
150     ...
151     if (overload::Overloaded $b) {...}
152     ...
153     $strval = overload::StrVal $b;
154
155 =head1 CAVEAT SCRIPTOR
156
157 Overloading of operators is a subject not to be taken lightly.
158 Neither its precise implementation, syntax, nor semantics are
159 100% endorsed by Larry Wall.  So any of these may be changed 
160 at some point in the future.
161
162 =head1 DESCRIPTION
163
164 =head2 Declaration of overloaded functions
165
166 The compilation directive
167
168     package Number;
169     use overload
170         "+" => \&add, 
171         "*=" => "muas";
172
173 declares function Number::add() for addition, and method muas() in
174 the "class" C<Number> (or one of its base classes)
175 for the assignment form C<*=> of multiplication.  
176
177 Arguments of this directive come in (key, value) pairs.  Legal values
178 are values legal inside a C<&{ ... }> call, so the name of a
179 subroutine, a reference to a subroutine, or an anonymous subroutine
180 will all work.  Note that values specified as strings are
181 interpreted as methods, not subroutines.  Legal keys are listed below.
182
183 The subroutine C<add> will be called to execute C<$a+$b> if $a
184 is a reference to an object blessed into the package C<Number>, or if $a is
185 not an object from a package with defined mathemagic addition, but $b is a
186 reference to a C<Number>.  It can also be called in other situations, like
187 C<$a+=7>, or C<$a++>.  See L<MAGIC AUTOGENERATION>.  (Mathemagical
188 methods refer to methods triggered by an overloaded mathematical
189 operator.)
190
191 Since overloading respects inheritance via the @ISA hierarchy, the
192 above declaration would also trigger overloading of C<+> and C<*=> in
193 all the packages which inherit from C<Number>.
194
195 =head2 Calling Conventions for Binary Operations
196
197 The functions specified in the C<use overload ...> directive are called
198 with three (in one particular case with four, see L<Last Resort>)
199 arguments.  If the corresponding operation is binary, then the first
200 two arguments are the two arguments of the operation.  However, due to
201 general object calling conventions, the first argument should always be
202 an object in the package, so in the situation of C<7+$a>, the
203 order of the arguments is interchanged.  It probably does not matter
204 when implementing the addition method, but whether the arguments
205 are reversed is vital to the subtraction method.  The method can
206 query this information by examining the third argument, which can take
207 three different values:
208
209 =over 7
210
211 =item FALSE
212
213 the order of arguments is as in the current operation.
214
215 =item TRUE
216
217 the arguments are reversed.
218
219 =item C<undef>
220
221 the current operation is an assignment variant (as in
222 C<$a+=7>), but the usual function is called instead.  This additional
223 information can be used to generate some optimizations.
224
225 =back
226
227 =head2 Calling Conventions for Unary Operations
228
229 Unary operation are considered binary operations with the second
230 argument being C<undef>.  Thus the functions that overloads C<{"++"}>
231 is called with arguments C<($a,undef,'')> when $a++ is executed.
232
233 =head2 Overloadable Operations
234
235 The following symbols can be specified in C<use overload>:
236
237 =over 5
238
239 =item * I<Arithmetic operations>
240
241     "+", "+=", "-", "-=", "*", "*=", "/", "/=", "%", "%=",
242     "**", "**=", "<<", "<<=", ">>", ">>=", "x", "x=", ".", ".=",
243
244 For these operations a substituted non-assignment variant can be called if
245 the assignment variant is not available.  Methods for operations "C<+>",
246 "C<->", "C<+=>", and "C<-=>" can be called to automatically generate
247 increment and decrement methods.  The operation "C<->" can be used to
248 autogenerate missing methods for unary minus or C<abs>.
249
250 =item * I<Comparison operations>
251
252     "<",  "<=", ">",  ">=", "==", "!=", "<=>",
253     "lt", "le", "gt", "ge", "eq", "ne", "cmp",
254
255 If the corresponding "spaceship" variant is available, it can be
256 used to substitute for the missing operation.  During C<sort>ing
257 arrays, C<cmp> is used to compare values subject to C<use overload>.
258
259 =item * I<Bit operations>
260
261     "&", "^", "|", "neg", "!", "~",
262
263 "C<neg>" stands for unary minus.  If the method for C<neg> is not
264 specified, it can be autogenerated using the method for
265 subtraction. If the method for "C<!>" is not specified, it can be
266 autogenerated using the methods for "C<bool>", or "C<\"\">", or "C<0+>".
267
268 =item * I<Increment and decrement>
269
270     "++", "--",
271
272 If undefined, addition and subtraction methods can be
273 used instead.  These operations are called both in prefix and
274 postfix form.
275
276 =item * I<Transcendental functions>
277
278     "atan2", "cos", "sin", "exp", "abs", "log", "sqrt",
279
280 If C<abs> is unavailable, it can be autogenerated using methods
281 for "E<lt>" or "E<lt>=E<gt>" combined with either unary minus or subtraction.
282
283 =item * I<Boolean, string and numeric conversion>
284
285     "bool", "\"\"", "0+",
286
287 If one or two of these operations are unavailable, the remaining ones can
288 be used instead.  C<bool> is used in the flow control operators
289 (like C<while>) and for the ternary "C<?:>" operation.  These functions can
290 return any arbitrary Perl value.  If the corresponding operation for this value
291 is overloaded too, that operation will be called again with this value.
292
293 =item * I<Special>
294
295     "nomethod", "fallback", "=",
296
297 see L<SPECIAL SYMBOLS FOR C<use overload>>.
298
299 =back
300
301 See L<"Fallback"> for an explanation of when a missing method can be autogenerated.
302
303 =head2 Inheritance and overloading
304
305 Inheritance interacts with overloading in two ways.
306
307 =over
308
309 =item Strings as values of C<use overload> directive
310
311 If C<value> in
312
313   use overload key => value;
314
315 is a string, it is interpreted as a method name.
316
317 =item Overloading of an operation is inherited by derived classes
318
319 Any class derived from an overloaded class is also overloaded.  The
320 set of overloaded methods is the union of overloaded methods of all
321 the ancestors. If some method is overloaded in several ancestor, then
322 which description will be used is decided by the usual inheritance
323 rules:
324
325 If C<A> inherits from C<B> and C<C> (in this order), C<B> overloads
326 C<+> with C<\&D::plus_sub>, and C<C> overloads C<+> by C<"plus_meth">,
327 then the subroutine C<D::plus_sub> will be called to implement
328 operation C<+> for an object in package C<A>.
329
330 =back
331
332 Note that since the value of the C<fallback> key is not a subroutine,
333 its inheritance is not governed by the above rules.  In the current
334 implementation, the value of C<fallback> in the first overloaded
335 ancestor is used, but this is accidental and subject to change.
336
337 =head1 SPECIAL SYMBOLS FOR C<use overload>
338
339 Three keys are recognized by Perl that are not covered by the above
340 description.
341
342 =head2 Last Resort
343
344 C<"nomethod"> should be followed by a reference to a function of four
345 parameters.  If defined, it is called when the overloading mechanism
346 cannot find a method for some operation.  The first three arguments of
347 this function coincide with the arguments for the corresponding method if
348 it were found, the fourth argument is the symbol
349 corresponding to the missing method.  If several methods are tried,
350 the last one is used.  Say, C<1-$a> can be equivalent to
351
352         &nomethodMethod($a,1,1,"-")
353
354 if the pair C<"nomethod" =E<gt> "nomethodMethod"> was specified in the
355 C<use overload> directive.
356
357 If some operation cannot be resolved, and there is no function
358 assigned to C<"nomethod">, then an exception will be raised via die()--
359 unless C<"fallback"> was specified as a key in C<use overload> directive.
360
361 =head2 Fallback 
362
363 The key C<"fallback"> governs what to do if a method for a particular
364 operation is not found.  Three different cases are possible depending on
365 the value of C<"fallback">:
366
367 =over 16
368
369 =item * C<undef>
370
371 Perl tries to use a
372 substituted method (see L<MAGIC AUTOGENERATION>).  If this fails, it
373 then tries to calls C<"nomethod"> value; if missing, an exception
374 will be raised.
375
376 =item * TRUE
377
378 The same as for the C<undef> value, but no exception is raised.  Instead,
379 it silently reverts to what it would have done were there no C<use overload>
380 present.
381
382 =item * defined, but FALSE
383
384 No autogeneration is tried.  Perl tries to call
385 C<"nomethod"> value, and if this is missing, raises an exception. 
386
387 =back
388
389 B<Note.> C<"fallback"> inheritance via @ISA is not carved in stone
390 yet, see L<"Inheritance and overloading">.
391
392 =head2 Copy Constructor
393
394 The value for C<"="> is a reference to a function with three
395 arguments, i.e., it looks like the other values in C<use
396 overload>. However, it does not overload the Perl assignment
397 operator. This would go against Camel hair.
398
399 This operation is called in the situations when a mutator is applied
400 to a reference that shares its object with some other reference, such
401 as
402
403         $a=$b; 
404         $a++;
405
406 To make this change $a and not change $b, a copy of C<$$a> is made,
407 and $a is assigned a reference to this new object.  This operation is
408 done during execution of the C<$a++>, and not during the assignment,
409 (so before the increment C<$$a> coincides with C<$$b>).  This is only
410 done if C<++> is expressed via a method for C<'++'> or C<'+='>.  Note
411 that if this operation is expressed via C<'+'> a nonmutator, i.e., as
412 in
413
414         $a=$b; 
415         $a=$a+1;
416
417 then C<$a> does not reference a new copy of C<$$a>, since $$a does not
418 appear as lvalue when the above code is executed.
419
420 If the copy constructor is required during the execution of some mutator,
421 but a method for C<'='> was not specified, it can be autogenerated as a
422 string copy if the object is a plain scalar.
423
424 =over 5
425
426 =item B<Example>
427
428 The actually executed code for 
429
430         $a=$b; 
431         Something else which does not modify $a or $b....
432         ++$a;
433
434 may be
435
436         $a=$b; 
437         Something else which does not modify $a or $b....
438         $a = $a->clone(undef,"");
439         $a->incr(undef,"");
440
441 if $b was mathemagical, and C<'++'> was overloaded with C<\&incr>,
442 C<'='> was overloaded with C<\&clone>.
443
444 =back
445
446 =head1 MAGIC AUTOGENERATION
447
448 If a method for an operation is not found, and the value for  C<"fallback"> is
449 TRUE or undefined, Perl tries to autogenerate a substitute method for
450 the missing operation based on the defined operations.  Autogenerated method
451 substitutions are possible for the following operations:
452
453 =over 16
454
455 =item I<Assignment forms of arithmetic operations>
456
457 C<$a+=$b> can use the method for C<"+"> if the method for C<"+=">
458 is not defined.
459
460 =item I<Conversion operations> 
461
462 String, numeric, and boolean conversion are calculated in terms of one
463 another if not all of them are defined.
464
465 =item I<Increment and decrement>
466
467 The C<++$a> operation can be expressed in terms of C<$a+=1> or C<$a+1>,
468 and C<$a--> in terms of C<$a-=1> and C<$a-1>.
469
470 =item C<abs($a)>
471
472 can be expressed in terms of C<$aE<lt>0> and C<-$a> (or C<0-$a>).
473
474 =item I<Unary minus>
475
476 can be expressed in terms of subtraction.
477
478 =item I<Negation>
479
480 C<!> and C<not> can be expressed in terms of boolean conversion, or
481 string or numerical conversion.
482
483 =item I<Concatenation>
484
485 can be expressed in terms of string conversion.
486
487 =item I<Comparison operations> 
488
489 can be expressed in terms of its "spaceship" counterpart: either
490 C<E<lt>=E<gt>> or C<cmp>:
491
492     <, >, <=, >=, ==, !=        in terms of <=>
493     lt, gt, le, ge, eq, ne      in terms of cmp
494
495 =item I<Copy operator>
496
497 can be expressed in terms of an assignment to the dereferenced value, if this
498 value is a scalar and not a reference.
499
500 =back
501
502 =head1 WARNING
503
504 The restriction for the comparison operation is that even if, for example,
505 `C<cmp>' should return a blessed reference, the autogenerated `C<lt>'
506 function will produce only a standard logical value based on the
507 numerical value of the result of `C<cmp>'.  In particular, a working
508 numeric conversion is needed in this case (possibly expressed in terms of
509 other conversions).
510
511 Similarly, C<.=>  and C<x=> operators lose their mathemagical properties
512 if the string conversion substitution is applied.
513
514 When you chop() a mathemagical object it is promoted to a string and its
515 mathemagical properties are lost.  The same can happen with other
516 operations as well.
517
518 =head1 Run-time Overloading
519
520 Since all C<use> directives are executed at compile-time, the only way to
521 change overloading during run-time is to
522
523     eval 'use overload "+" => \&addmethod';
524
525 You can also use
526
527     eval 'no overload "+", "--", "<="';
528
529 though the use of these constructs during run-time is questionable.
530
531 =head1 Public functions
532
533 Package C<overload.pm> provides the following public functions:
534
535 =over 5
536
537 =item overload::StrVal(arg)
538
539 Gives string value of C<arg> as in absence of stringify overloading.
540
541 =item overload::Overloaded(arg)
542
543 Returns true if C<arg> is subject to overloading of some operations.
544
545 =item overload::Method(obj,op)
546
547 Returns C<undef> or a reference to the method that implements C<op>.
548
549 =back
550
551 =head1 Overloading constants
552
553 For some application Perl parser mangles constants too much.  It is possible
554 to hook into this process via overload::constant() and overload::remove_constant()
555 functions.
556
557 These functions take a hash as an argument.  The recognized keys of this hash
558 are
559
560 =over 8
561
562 =item integer
563
564 to overload integer constants,
565
566 =item float
567
568 to overload floating point constants,
569
570 =item binary
571
572 to overload octal and hexadecimal constants,
573
574 =item q
575
576 to overload C<q>-quoted strings, constant pieces of C<qq>- and C<qx>-quoted
577 strings and here-documents,
578
579 =item qr
580
581 to overload constant pieces of regular expressions.
582
583 =back
584
585 The corresponding values are references to functions which take three arguments:
586 the first one is the I<initial> string form of the constant, the second one
587 is how Perl interprets this constant, the third one is how the constant is used.  
588 Note that the initial string form does not
589 contain string delimiters, and has backslashes in backslash-delimiter 
590 combinations stripped (thus the value of delimiter is not relevant for
591 processing of this string).  The return value of this function is how this 
592 constant is going to be interpreted by Perl.  The third argument is undefined
593 unless for overloaded C<q>- and C<qr>- constants, it is C<q> in single-quote
594 context (comes from strings, regular expressions, and single-quote HERE
595 documents), it is C<tr> for arguments of C<tr>/C<y> operators, 
596 it is C<s> for right-hand side of C<s>-operator, and it is C<qq> otherwise.
597
598 Since an expression C<"ab$cd,,"> is just a shortcut for C<'ab' . $cd . ',,'>,
599 it is expected that overloaded constant strings are equipped with reasonable
600 overloaded catenation operator, otherwise absurd results will result.  
601 Similarly, negative numbers are considered as negations of positive constants.
602
603 Note that it is probably meaningless to call the functions overload::constant()
604 and overload::remove_constant() from anywhere but import() and unimport() methods.
605 From these methods they may be called as
606
607         sub import {
608           shift;
609           return unless @_;
610           die "unknown import: @_" unless @_ == 1 and $_[0] eq ':constant';
611           overload::constant integer => sub {Math::BigInt->new(shift)};
612         }
613
614 B<BUGS> Currently overloaded-ness of constants does not propagate 
615 into C<eval '...'>.
616
617 =head1 IMPLEMENTATION
618
619 What follows is subject to change RSN.
620
621 The table of methods for all operations is cached in magic for the
622 symbol table hash for the package.  The cache is invalidated during
623 processing of C<use overload>, C<no overload>, new function
624 definitions, and changes in @ISA. However, this invalidation remains
625 unprocessed until the next C<bless>ing into the package. Hence if you
626 want to change overloading structure dynamically, you'll need an
627 additional (fake) C<bless>ing to update the table.
628
629 (Every SVish thing has a magic queue, and magic is an entry in that
630 queue.  This is how a single variable may participate in multiple
631 forms of magic simultaneously.  For instance, environment variables
632 regularly have two forms at once: their %ENV magic and their taint
633 magic. However, the magic which implements overloading is applied to
634 the stashes, which are rarely used directly, thus should not slow down
635 Perl.)
636
637 If an object belongs to a package using overload, it carries a special
638 flag.  Thus the only speed penalty during arithmetic operations without
639 overloading is the checking of this flag.
640
641 In fact, if C<use overload> is not present, there is almost no overhead
642 for overloadable operations, so most programs should not suffer
643 measurable performance penalties.  A considerable effort was made to
644 minimize the overhead when overload is used in some package, but the
645 arguments in question do not belong to packages using overload.  When
646 in doubt, test your speed with C<use overload> and without it.  So far
647 there have been no reports of substantial speed degradation if Perl is
648 compiled with optimization turned on.
649
650 There is no size penalty for data if overload is not used. The only
651 size penalty if overload is used in some package is that I<all> the
652 packages acquire a magic during the next C<bless>ing into the
653 package. This magic is three-words-long for packages without
654 overloading, and carries the cache tabel if the package is overloaded.
655
656 Copying (C<$a=$b>) is shallow; however, a one-level-deep copying is 
657 carried out before any operation that can imply an assignment to the
658 object $a (or $b) refers to, like C<$a++>.  You can override this
659 behavior by defining your own copy constructor (see L<"Copy Constructor">).
660
661 It is expected that arguments to methods that are not explicitly supposed
662 to be changed are constant (but this is not enforced).
663
664 =head1 AUTHOR
665
666 Ilya Zakharevich E<lt>F<ilya@math.mps.ohio-state.edu>E<gt>.
667
668 =head1 DIAGNOSTICS
669
670 When Perl is run with the B<-Do> switch or its equivalent, overloading
671 induces diagnostic messages.
672
673 Using the C<m> command of Perl debugger (see L<perldebug>) one can
674 deduce which operations are overloaded (and which ancestor triggers
675 this overloading). Say, if C<eq> is overloaded, then the method C<(eq>
676 is shown by debugger. The method C<()> corresponds to the C<fallback>
677 key (in fact a presence of this method shows that this package has
678 overloading enabled, and it is what is used by the C<Overloaded>
679 function).
680
681 =head1 BUGS
682
683 Because it is used for overloading, the per-package hash %OVERLOAD now
684 has a special meaning in Perl. The symbol table is filled with names
685 looking like line-noise.
686
687 For the purpose of inheritance every overloaded package behaves as if
688 C<fallback> is present (possibly undefined). This may create
689 interesting effects if some package is not overloaded, but inherits
690 from two overloaded packages.
691
692 Barewords are not covered by overloaded string constants.
693
694 This document is confusing.
695
696 =cut
697