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