This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update perlhist.
[perl5.git] / lib / overload.pm
CommitLineData
4633a7c4
LW
1package overload;
2
d5448623
GS
3$overload::hint_bits = 0x20000;
4
a6006777
PP
5sub nil {}
6
4633a7c4
LW
7sub OVERLOAD {
8 $package = shift;
9 my %arg = @_;
a6006777
PP
10 my ($sub, $fb);
11 $ {$package . "::OVERLOAD"}{dummy}++; # Register with magic by touching.
12 *{$package . "::()"} = \&nil; # Make it findable via fetchmethod.
4633a7c4 13 for (keys %arg) {
a6006777
PP
14 if ($_ eq 'fallback') {
15 $fb = $arg{$_};
16 } else {
17 $sub = $arg{$_};
18 if (not ref $sub and $sub !~ /::/) {
44a8e56a
PP
19 $ {$package . "::(" . $_} = $sub;
20 $sub = \&nil;
a6006777
PP
21 }
22 #print STDERR "Setting `$ {'package'}::\cO$_' to \\&`$sub'.\n";
23 *{$package . "::(" . $_} = \&{ $sub };
24 }
4633a7c4 25 }
a6006777 26 ${$package . "::()"} = $fb; # Make it findable too (fallback only).
4633a7c4
LW
27}
28
29sub import {
30 $package = (caller())[0];
31 # *{$package . "::OVERLOAD"} = \&OVERLOAD;
32 shift;
33 $package->overload::OVERLOAD(@_);
34}
35
36sub unimport {
37 $package = (caller())[0];
a6006777 38 ${$package . "::OVERLOAD"}{dummy}++; # Upgrade the table
4633a7c4
LW
39 shift;
40 for (@_) {
a6006777
PP
41 if ($_ eq 'fallback') {
42 undef $ {$package . "::()"};
43 } else {
44 delete $ {$package . "::"}{"(" . $_};
45 }
4633a7c4
LW
46 }
47}
48
49sub Overloaded {
a6006777
PP
50 my $package = shift;
51 $package = ref $package if ref $package;
52 $package->can('()');
4633a7c4
LW
53}
54
44a8e56a
PP
55sub ov_method {
56 my $globref = shift;
57 return undef unless $globref;
58 my $sub = \&{*$globref};
59 return $sub if $sub ne \&nil;
60 return shift->can($ {*$globref});
61}
62
4633a7c4 63sub OverloadedStringify {
a6006777
PP
64 my $package = shift;
65 $package = ref $package if ref $package;
44a8e56a 66 #$package->can('(""')
ee239bfe
IZ
67 ov_method mycan($package, '(""'), $package
68 or ov_method mycan($package, '(0+'), $package
69 or ov_method mycan($package, '(bool'), $package
70 or ov_method mycan($package, '(nomethod'), $package;
4633a7c4
LW
71}
72
73sub Method {
a6006777
PP
74 my $package = shift;
75 $package = ref $package if ref $package;
44a8e56a
PP
76 #my $meth = $package->can('(' . shift);
77 ov_method mycan($package, '(' . shift), $package;
78 #return $meth if $meth ne \&nil;
79 #return $ {*{$meth}};
4633a7c4
LW
80}
81
82sub AddrRef {
a6006777
PP
83 my $package = ref $_[0];
84 return "$_[0]" unless $package;
85 bless $_[0], overload::Fake; # Non-overloaded package
4633a7c4
LW
86 my $str = "$_[0]";
87 bless $_[0], $package; # Back
a6006777 88 $package . substr $str, index $str, '=';
4633a7c4
LW
89}
90
91sub StrVal {
f6b3007c 92 (OverloadedStringify($_[0]) or ref($_[0]) eq 'Regexp') ?
a6006777 93 (AddrRef(shift)) :
4633a7c4
LW
94 "$_[0]";
95}
96
44a8e56a
PP
97sub mycan { # Real can would leave stubs.
98 my ($package, $meth) = @_;
99 return \*{$package . "::$meth"} if defined &{$package . "::$meth"};
100 my $p;
101 foreach $p (@{$package . "::ISA"}) {
102 my $out = mycan($p, $meth);
103 return $out if $out;
104 }
105 return undef;
106}
107
b3ac6de7
IZ
108%constants = (
109 'integer' => 0x1000,
110 'float' => 0x2000,
111 'binary' => 0x4000,
112 'q' => 0x8000,
113 'qr' => 0x10000,
114 );
115
ee239bfe
IZ
116%ops = ( with_assign => "+ - * / % ** << >> x .",
117 assign => "+= -= *= /= %= **= <<= >>= x= .=",
2877bd81 118 num_comparison => "< <= > >= == !=",
ee239bfe 119 '3way_comparison'=> "<=> cmp",
2877bd81 120 str_comparison => "lt le gt ge eq ne",
ee239bfe
IZ
121 binary => "& | ^",
122 unary => "neg ! ~",
123 mutators => '++ --',
124 func => "atan2 cos sin exp abs log sqrt",
125 conversion => 'bool "" 0+',
f5284f61
IZ
126 iterators => '<>',
127 dereferencing => '${} @{} %{} &{} *{}',
ee239bfe
IZ
128 special => 'nomethod fallback =');
129
6b82e2f5 130use warnings::register;
b3ac6de7
IZ
131sub constant {
132 # Arguments: what, sub
133 while (@_) {
6b82e2f5 134 if (@_ == 1) {
4498a751 135 warnings::warnif ("Odd number of arguments for overload::constant");
6b82e2f5
A
136 last;
137 }
138 elsif (!exists $constants {$_ [0]}) {
4498a751 139 warnings::warnif ("`$_[0]' is not an overloadable type");
6b82e2f5
A
140 }
141 elsif (!ref $_ [1] || "$_[1]" !~ /CODE\(0x[\da-f]+\)$/) {
142 # Can't use C<ref $_[1] eq "CODE"> above as code references can be
143 # blessed, and C<ref> would return the package the ref is blessed into.
144 if (warnings::enabled) {
6b82e2f5 145 $_ [1] = "undef" unless defined $_ [1];
4498a751 146 warnings::warn ("`$_[1]' is not a code reference");
6b82e2f5
A
147 }
148 }
149 else {
150 $^H{$_[0]} = $_[1];
151 $^H |= $constants{$_[0]} | $overload::hint_bits;
152 }
b3ac6de7
IZ
153 shift, shift;
154 }
155}
156
157sub remove_constant {
158 # Arguments: what, sub
159 while (@_) {
160 delete $^H{$_[0]};
161 $^H &= ~ $constants{$_[0]};
162 shift, shift;
163 }
164}
165
4633a7c4
LW
1661;
167
168__END__
169
170=head1 NAME
171
cb1a09d0 172overload - Package for overloading perl operations
4633a7c4
LW
173
174=head1 SYNOPSIS
175
176 package SomeThing;
177
178 use overload
179 '+' => \&myadd,
180 '-' => \&mysub;
181 # etc
182 ...
183
184 package main;
185 $a = new SomeThing 57;
186 $b=5+$a;
187 ...
188 if (overload::Overloaded $b) {...}
189 ...
190 $strval = overload::StrVal $b;
191
4633a7c4
LW
192=head1 DESCRIPTION
193
194=head2 Declaration of overloaded functions
195
196The compilation directive
197
198 package Number;
199 use overload
200 "+" => \&add,
201 "*=" => "muas";
202
203declares function Number::add() for addition, and method muas() in
204the "class" C<Number> (or one of its base classes)
205for the assignment form C<*=> of multiplication.
206
207Arguments of this directive come in (key, value) pairs. Legal values
e7ea3e70
IZ
208are values legal inside a C<&{ ... }> call, so the name of a
209subroutine, a reference to a subroutine, or an anonymous subroutine
210will all work. Note that values specified as strings are
211interpreted as methods, not subroutines. Legal keys are listed below.
4633a7c4
LW
212
213The subroutine C<add> will be called to execute C<$a+$b> if $a
214is a reference to an object blessed into the package C<Number>, or if $a is
215not an object from a package with defined mathemagic addition, but $b is a
216reference to a C<Number>. It can also be called in other situations, like
217C<$a+=7>, or C<$a++>. See L<MAGIC AUTOGENERATION>. (Mathemagical
218methods refer to methods triggered by an overloaded mathematical
219operator.)
220
774d564b
PP
221Since overloading respects inheritance via the @ISA hierarchy, the
222above declaration would also trigger overloading of C<+> and C<*=> in
223all the packages which inherit from C<Number>.
e7ea3e70 224
4633a7c4
LW
225=head2 Calling Conventions for Binary Operations
226
227The functions specified in the C<use overload ...> directive are called
228with three (in one particular case with four, see L<Last Resort>)
229arguments. If the corresponding operation is binary, then the first
230two arguments are the two arguments of the operation. However, due to
231general object calling conventions, the first argument should always be
232an object in the package, so in the situation of C<7+$a>, the
233order of the arguments is interchanged. It probably does not matter
234when implementing the addition method, but whether the arguments
235are reversed is vital to the subtraction method. The method can
236query this information by examining the third argument, which can take
237three different values:
238
239=over 7
240
241=item FALSE
242
243the order of arguments is as in the current operation.
244
245=item TRUE
246
247the arguments are reversed.
248
249=item C<undef>
250
251the current operation is an assignment variant (as in
252C<$a+=7>), but the usual function is called instead. This additional
ee239bfe
IZ
253information can be used to generate some optimizations. Compare
254L<Calling Conventions for Mutators>.
4633a7c4
LW
255
256=back
257
258=head2 Calling Conventions for Unary Operations
259
260Unary operation are considered binary operations with the second
261argument being C<undef>. Thus the functions that overloads C<{"++"}>
262is called with arguments C<($a,undef,'')> when $a++ is executed.
263
ee239bfe
IZ
264=head2 Calling Conventions for Mutators
265
266Two types of mutators have different calling conventions:
267
268=over
269
270=item C<++> and C<-->
271
272The routines which implement these operators are expected to actually
273I<mutate> their arguments. So, assuming that $obj is a reference to a
274number,
275
276 sub incr { my $n = $ {$_[0]}; ++$n; $_[0] = bless \$n}
277
278is an appropriate implementation of overloaded C<++>. Note that
279
280 sub incr { ++$ {$_[0]} ; shift }
281
282is OK if used with preincrement and with postincrement. (In the case
283of postincrement a copying will be performed, see L<Copy Constructor>.)
284
285=item C<x=> and other assignment versions
286
287There is nothing special about these methods. They may change the
288value of their arguments, and may leave it as is. The result is going
289to be assigned to the value in the left-hand-side if different from
290this value.
291
f610777f 292This allows for the same method to be used as overloaded C<+=> and
ee239bfe
IZ
293C<+>. Note that this is I<allowed>, but not recommended, since by the
294semantic of L<"Fallback"> Perl will call the method for C<+> anyway,
295if C<+=> is not overloaded.
296
297=back
298
299B<Warning.> Due to the presense of assignment versions of operations,
300routines which may be called in assignment context may create
f610777f 301self-referential structures. Currently Perl will not free self-referential
ee239bfe
IZ
302structures until cycles are C<explicitly> broken. You may get problems
303when traversing your structures too.
304
305Say,
306
307 use overload '+' => sub { bless [ \$_[0], \$_[1] ] };
308
309is asking for trouble, since for code C<$obj += $foo> the subroutine
310is called as C<$obj = add($obj, $foo, undef)>, or C<$obj = [\$obj,
311\$foo]>. If using such a subroutine is an important optimization, one
312can overload C<+=> explicitly by a non-"optimized" version, or switch
313to non-optimized version if C<not defined $_[2]> (see
314L<Calling Conventions for Binary Operations>).
315
316Even if no I<explicit> assignment-variants of operators are present in
317the script, they may be generated by the optimizer. Say, C<",$obj,"> or
318C<',' . $obj . ','> may be both optimized to
319
320 my $tmp = ',' . $obj; $tmp .= ',';
321
4633a7c4
LW
322=head2 Overloadable Operations
323
ee239bfe 324The following symbols can be specified in C<use overload> directive:
4633a7c4
LW
325
326=over 5
327
328=item * I<Arithmetic operations>
329
330 "+", "+=", "-", "-=", "*", "*=", "/", "/=", "%", "%=",
331 "**", "**=", "<<", "<<=", ">>", ">>=", "x", "x=", ".", ".=",
332
333For these operations a substituted non-assignment variant can be called if
334the assignment variant is not available. Methods for operations "C<+>",
335"C<->", "C<+=>", and "C<-=>" can be called to automatically generate
336increment and decrement methods. The operation "C<->" can be used to
337autogenerate missing methods for unary minus or C<abs>.
338
ee239bfe
IZ
339See L<"MAGIC AUTOGENERATION">, L<"Calling Conventions for Mutators"> and
340L<"Calling Conventions for Binary Operations">) for details of these
341substitutions.
342
4633a7c4
LW
343=item * I<Comparison operations>
344
345 "<", "<=", ">", ">=", "==", "!=", "<=>",
346 "lt", "le", "gt", "ge", "eq", "ne", "cmp",
347
348If the corresponding "spaceship" variant is available, it can be
349used to substitute for the missing operation. During C<sort>ing
350arrays, C<cmp> is used to compare values subject to C<use overload>.
351
352=item * I<Bit operations>
353
354 "&", "^", "|", "neg", "!", "~",
355
356"C<neg>" stands for unary minus. If the method for C<neg> is not
3bc6ec80
PP
357specified, it can be autogenerated using the method for
358subtraction. If the method for "C<!>" is not specified, it can be
359autogenerated using the methods for "C<bool>", or "C<\"\">", or "C<0+>".
4633a7c4
LW
360
361=item * I<Increment and decrement>
362
363 "++", "--",
364
365If undefined, addition and subtraction methods can be
366used instead. These operations are called both in prefix and
367postfix form.
368
369=item * I<Transcendental functions>
370
371 "atan2", "cos", "sin", "exp", "abs", "log", "sqrt",
372
373If C<abs> is unavailable, it can be autogenerated using methods
1fef88e7 374for "E<lt>" or "E<lt>=E<gt>" combined with either unary minus or subtraction.
4633a7c4
LW
375
376=item * I<Boolean, string and numeric conversion>
377
378 "bool", "\"\"", "0+",
379
f5284f61 380If one or two of these operations are not overloaded, the remaining ones can
4633a7c4
LW
381be used instead. C<bool> is used in the flow control operators
382(like C<while>) and for the ternary "C<?:>" operation. These functions can
383return any arbitrary Perl value. If the corresponding operation for this value
384is overloaded too, that operation will be called again with this value.
385
f5284f61
IZ
386=item * I<Iteration>
387
388 "<>"
389
390If not overloaded, the argument will be converted to a filehandle or
391glob (which may require a stringification). The same overloading
392happens both for the I<read-filehandle> syntax C<E<lt>$varE<gt>> and
393I<globbing> syntax C<E<lt>${var}E<gt>>.
394
395=item * I<Dereferencing>
396
397 '${}', '@{}', '%{}', '&{}', '*{}'.
398
399If not overloaded, the argument will be dereferenced I<as is>, thus
400should be of correct type. These functions should return a reference
401of correct type, or another object with overloaded dereferencing.
402
4633a7c4
LW
403=item * I<Special>
404
405 "nomethod", "fallback", "=",
406
407see L<SPECIAL SYMBOLS FOR C<use overload>>.
408
409=back
410
ee239bfe
IZ
411See L<"Fallback"> for an explanation of when a missing method can be
412autogenerated.
413
414A computer-readable form of the above table is available in the hash
415%overload::ops, with values being space-separated lists of names:
416
417 with_assign => '+ - * / % ** << >> x .',
418 assign => '+= -= *= /= %= **= <<= >>= x= .=',
2877bd81 419 num_comparison => '< <= > >= == !=',
ee239bfe 420 '3way_comparison'=> '<=> cmp',
2877bd81 421 str_comparison => 'lt le gt ge eq ne',
ee239bfe
IZ
422 binary => '& | ^',
423 unary => 'neg ! ~',
424 mutators => '++ --',
425 func => 'atan2 cos sin exp abs log sqrt',
426 conversion => 'bool "" 0+',
f5284f61
IZ
427 iterators => '<>',
428 dereferencing => '${} @{} %{} &{} *{}',
ee239bfe 429 special => 'nomethod fallback ='
4633a7c4 430
e7ea3e70
IZ
431=head2 Inheritance and overloading
432
774d564b 433Inheritance interacts with overloading in two ways.
e7ea3e70
IZ
434
435=over
436
437=item Strings as values of C<use overload> directive
438
774d564b 439If C<value> in
e7ea3e70
IZ
440
441 use overload key => value;
442
774d564b 443is a string, it is interpreted as a method name.
e7ea3e70
IZ
444
445=item Overloading of an operation is inherited by derived classes
446
774d564b
PP
447Any class derived from an overloaded class is also overloaded. The
448set of overloaded methods is the union of overloaded methods of all
449the ancestors. If some method is overloaded in several ancestor, then
e7ea3e70 450which description will be used is decided by the usual inheritance
774d564b 451rules:
e7ea3e70 452
774d564b
PP
453If C<A> inherits from C<B> and C<C> (in this order), C<B> overloads
454C<+> with C<\&D::plus_sub>, and C<C> overloads C<+> by C<"plus_meth">,
455then the subroutine C<D::plus_sub> will be called to implement
456operation C<+> for an object in package C<A>.
e7ea3e70
IZ
457
458=back
459
774d564b
PP
460Note that since the value of the C<fallback> key is not a subroutine,
461its inheritance is not governed by the above rules. In the current
462implementation, the value of C<fallback> in the first overloaded
463ancestor is used, but this is accidental and subject to change.
e7ea3e70 464
4633a7c4
LW
465=head1 SPECIAL SYMBOLS FOR C<use overload>
466
467Three keys are recognized by Perl that are not covered by the above
468description.
469
774d564b 470=head2 Last Resort
4633a7c4
LW
471
472C<"nomethod"> should be followed by a reference to a function of four
473parameters. If defined, it is called when the overloading mechanism
474cannot find a method for some operation. The first three arguments of
475this function coincide with the arguments for the corresponding method if
476it were found, the fourth argument is the symbol
477corresponding to the missing method. If several methods are tried,
478the last one is used. Say, C<1-$a> can be equivalent to
479
480 &nomethodMethod($a,1,1,"-")
481
482if the pair C<"nomethod" =E<gt> "nomethodMethod"> was specified in the
483C<use overload> directive.
484
485If some operation cannot be resolved, and there is no function
486assigned to C<"nomethod">, then an exception will be raised via die()--
487unless C<"fallback"> was specified as a key in C<use overload> directive.
488
489=head2 Fallback
490
491The key C<"fallback"> governs what to do if a method for a particular
492operation is not found. Three different cases are possible depending on
493the value of C<"fallback">:
494
495=over 16
496
497=item * C<undef>
498
499Perl tries to use a
500substituted method (see L<MAGIC AUTOGENERATION>). If this fails, it
501then tries to calls C<"nomethod"> value; if missing, an exception
502will be raised.
503
504=item * TRUE
505
506The same as for the C<undef> value, but no exception is raised. Instead,
507it silently reverts to what it would have done were there no C<use overload>
508present.
509
510=item * defined, but FALSE
511
512No autogeneration is tried. Perl tries to call
513C<"nomethod"> value, and if this is missing, raises an exception.
514
515=back
516
e7ea3e70
IZ
517B<Note.> C<"fallback"> inheritance via @ISA is not carved in stone
518yet, see L<"Inheritance and overloading">.
519
4633a7c4
LW
520=head2 Copy Constructor
521
522The value for C<"="> is a reference to a function with three
523arguments, i.e., it looks like the other values in C<use
524overload>. However, it does not overload the Perl assignment
525operator. This would go against Camel hair.
526
527This operation is called in the situations when a mutator is applied
528to a reference that shares its object with some other reference, such
529as
530
531 $a=$b;
ee239bfe 532 ++$a;
4633a7c4
LW
533
534To make this change $a and not change $b, a copy of C<$$a> is made,
535and $a is assigned a reference to this new object. This operation is
ee239bfe 536done during execution of the C<++$a>, and not during the assignment,
4633a7c4 537(so before the increment C<$$a> coincides with C<$$b>). This is only
ee239bfe
IZ
538done if C<++> is expressed via a method for C<'++'> or C<'+='> (or
539C<nomethod>). Note that if this operation is expressed via C<'+'>
540a nonmutator, i.e., as in
4633a7c4
LW
541
542 $a=$b;
543 $a=$a+1;
544
545then C<$a> does not reference a new copy of C<$$a>, since $$a does not
546appear as lvalue when the above code is executed.
547
548If the copy constructor is required during the execution of some mutator,
549but a method for C<'='> was not specified, it can be autogenerated as a
550string copy if the object is a plain scalar.
551
552=over 5
553
554=item B<Example>
555
556The actually executed code for
557
558 $a=$b;
559 Something else which does not modify $a or $b....
560 ++$a;
561
562may be
563
564 $a=$b;
565 Something else which does not modify $a or $b....
566 $a = $a->clone(undef,"");
567 $a->incr(undef,"");
568
569if $b was mathemagical, and C<'++'> was overloaded with C<\&incr>,
570C<'='> was overloaded with C<\&clone>.
571
572=back
573
f610777f 574Same behaviour is triggered by C<$b = $a++>, which is consider a synonym for
ee239bfe
IZ
575C<$b = $a; ++$a>.
576
4633a7c4
LW
577=head1 MAGIC AUTOGENERATION
578
579If a method for an operation is not found, and the value for C<"fallback"> is
580TRUE or undefined, Perl tries to autogenerate a substitute method for
581the missing operation based on the defined operations. Autogenerated method
582substitutions are possible for the following operations:
583
584=over 16
585
586=item I<Assignment forms of arithmetic operations>
587
588C<$a+=$b> can use the method for C<"+"> if the method for C<"+=">
589is not defined.
590
591=item I<Conversion operations>
592
593String, numeric, and boolean conversion are calculated in terms of one
594another if not all of them are defined.
595
596=item I<Increment and decrement>
597
598The C<++$a> operation can be expressed in terms of C<$a+=1> or C<$a+1>,
599and C<$a--> in terms of C<$a-=1> and C<$a-1>.
600
601=item C<abs($a)>
602
603can be expressed in terms of C<$aE<lt>0> and C<-$a> (or C<0-$a>).
604
605=item I<Unary minus>
606
607can be expressed in terms of subtraction.
608
3bc6ec80
PP
609=item I<Negation>
610
611C<!> and C<not> can be expressed in terms of boolean conversion, or
612string or numerical conversion.
613
4633a7c4
LW
614=item I<Concatenation>
615
616can be expressed in terms of string conversion.
617
618=item I<Comparison operations>
619
620can be expressed in terms of its "spaceship" counterpart: either
621C<E<lt>=E<gt>> or C<cmp>:
1fef88e7 622
4633a7c4
LW
623 <, >, <=, >=, ==, != in terms of <=>
624 lt, gt, le, ge, eq, ne in terms of cmp
625
f5284f61
IZ
626=item I<Iterator>
627
628 <> in terms of builtin operations
629
630=item I<Dereferencing>
631
632 ${} @{} %{} &{} *{} in terms of builtin operations
633
4633a7c4
LW
634=item I<Copy operator>
635
636can be expressed in terms of an assignment to the dereferenced value, if this
637value is a scalar and not a reference.
638
639=back
640
ee239bfe 641=head1 Losing overloading
4633a7c4
LW
642
643The restriction for the comparison operation is that even if, for example,
644`C<cmp>' should return a blessed reference, the autogenerated `C<lt>'
645function will produce only a standard logical value based on the
646numerical value of the result of `C<cmp>'. In particular, a working
647numeric conversion is needed in this case (possibly expressed in terms of
648other conversions).
649
650Similarly, C<.=> and C<x=> operators lose their mathemagical properties
651if the string conversion substitution is applied.
652
653When you chop() a mathemagical object it is promoted to a string and its
654mathemagical properties are lost. The same can happen with other
655operations as well.
656
657=head1 Run-time Overloading
658
659Since all C<use> directives are executed at compile-time, the only way to
660change overloading during run-time is to
661
662 eval 'use overload "+" => \&addmethod';
663
664You can also use
665
666 eval 'no overload "+", "--", "<="';
667
668though the use of these constructs during run-time is questionable.
669
670=head1 Public functions
671
672Package C<overload.pm> provides the following public functions:
673
674=over 5
675
676=item overload::StrVal(arg)
677
678Gives string value of C<arg> as in absence of stringify overloading.
679
680=item overload::Overloaded(arg)
681
682Returns true if C<arg> is subject to overloading of some operations.
683
684=item overload::Method(obj,op)
685
686Returns C<undef> or a reference to the method that implements C<op>.
687
688=back
689
b3ac6de7
IZ
690=head1 Overloading constants
691
692For some application Perl parser mangles constants too much. It is possible
693to hook into this process via overload::constant() and overload::remove_constant()
694functions.
695
696These functions take a hash as an argument. The recognized keys of this hash
697are
698
699=over 8
700
701=item integer
702
703to overload integer constants,
704
705=item float
706
707to overload floating point constants,
708
709=item binary
710
711to overload octal and hexadecimal constants,
712
713=item q
714
715to overload C<q>-quoted strings, constant pieces of C<qq>- and C<qx>-quoted
716strings and here-documents,
717
718=item qr
719
720to overload constant pieces of regular expressions.
721
722=back
723
724The corresponding values are references to functions which take three arguments:
725the first one is the I<initial> string form of the constant, the second one
726is how Perl interprets this constant, the third one is how the constant is used.
727Note that the initial string form does not
728contain string delimiters, and has backslashes in backslash-delimiter
729combinations stripped (thus the value of delimiter is not relevant for
730processing of this string). The return value of this function is how this
731constant is going to be interpreted by Perl. The third argument is undefined
732unless for overloaded C<q>- and C<qr>- constants, it is C<q> in single-quote
733context (comes from strings, regular expressions, and single-quote HERE
734documents), it is C<tr> for arguments of C<tr>/C<y> operators,
735it is C<s> for right-hand side of C<s>-operator, and it is C<qq> otherwise.
736
737Since an expression C<"ab$cd,,"> is just a shortcut for C<'ab' . $cd . ',,'>,
738it is expected that overloaded constant strings are equipped with reasonable
739overloaded catenation operator, otherwise absurd results will result.
740Similarly, negative numbers are considered as negations of positive constants.
741
742Note that it is probably meaningless to call the functions overload::constant()
743and overload::remove_constant() from anywhere but import() and unimport() methods.
744From these methods they may be called as
745
746 sub import {
747 shift;
748 return unless @_;
749 die "unknown import: @_" unless @_ == 1 and $_[0] eq ':constant';
750 overload::constant integer => sub {Math::BigInt->new(shift)};
751 }
752
753B<BUGS> Currently overloaded-ness of constants does not propagate
754into C<eval '...'>.
755
4633a7c4
LW
756=head1 IMPLEMENTATION
757
758What follows is subject to change RSN.
759
e7ea3e70
IZ
760The table of methods for all operations is cached in magic for the
761symbol table hash for the package. The cache is invalidated during
762processing of C<use overload>, C<no overload>, new function
763definitions, and changes in @ISA. However, this invalidation remains
764unprocessed until the next C<bless>ing into the package. Hence if you
765want to change overloading structure dynamically, you'll need an
766additional (fake) C<bless>ing to update the table.
767
768(Every SVish thing has a magic queue, and magic is an entry in that
769queue. This is how a single variable may participate in multiple
770forms of magic simultaneously. For instance, environment variables
771regularly have two forms at once: their %ENV magic and their taint
772magic. However, the magic which implements overloading is applied to
773the stashes, which are rarely used directly, thus should not slow down
774Perl.)
4633a7c4
LW
775
776If an object belongs to a package using overload, it carries a special
777flag. Thus the only speed penalty during arithmetic operations without
778overloading is the checking of this flag.
779
774d564b
PP
780In fact, if C<use overload> is not present, there is almost no overhead
781for overloadable operations, so most programs should not suffer
782measurable performance penalties. A considerable effort was made to
783minimize the overhead when overload is used in some package, but the
784arguments in question do not belong to packages using overload. When
785in doubt, test your speed with C<use overload> and without it. So far
786there have been no reports of substantial speed degradation if Perl is
787compiled with optimization turned on.
4633a7c4 788
e7ea3e70
IZ
789There is no size penalty for data if overload is not used. The only
790size penalty if overload is used in some package is that I<all> the
791packages acquire a magic during the next C<bless>ing into the
792package. This magic is three-words-long for packages without
f610777f 793overloading, and carries the cache table if the package is overloaded.
4633a7c4
LW
794
795Copying (C<$a=$b>) is shallow; however, a one-level-deep copying is
796carried out before any operation that can imply an assignment to the
797object $a (or $b) refers to, like C<$a++>. You can override this
798behavior by defining your own copy constructor (see L<"Copy Constructor">).
799
800It is expected that arguments to methods that are not explicitly supposed
801to be changed are constant (but this is not enforced).
802
ee239bfe
IZ
803=head1 Metaphor clash
804
f610777f
A
805One may wonder why the semantic of overloaded C<=> is so counter intuitive.
806If it I<looks> counter intuitive to you, you are subject to a metaphor
ee239bfe
IZ
807clash.
808
809Here is a Perl object metaphor:
810
811I< object is a reference to blessed data>
812
813and an arithmetic metaphor:
814
815I< object is a thing by itself>.
816
817The I<main> problem of overloading C<=> is the fact that these metaphors
818imply different actions on the assignment C<$a = $b> if $a and $b are
819objects. Perl-think implies that $a becomes a reference to whatever
820$b was referencing. Arithmetic-think implies that the value of "object"
821$a is changed to become the value of the object $b, preserving the fact
822that $a and $b are separate entities.
823
824The difference is not relevant in the absence of mutators. After
825a Perl-way assignment an operation which mutates the data referenced by $a
826would change the data referenced by $b too. Effectively, after
827C<$a = $b> values of $a and $b become I<indistinguishable>.
828
829On the other hand, anyone who has used algebraic notation knows the
830expressive power of the arithmetic metaphor. Overloading works hard
831to enable this metaphor while preserving the Perlian way as far as
832possible. Since it is not not possible to freely mix two contradicting
833metaphors, overloading allows the arithmetic way to write things I<as
834far as all the mutators are called via overloaded access only>. The
835way it is done is described in L<Copy Constructor>.
836
837If some mutator methods are directly applied to the overloaded values,
838one may need to I<explicitly unlink> other values which references the
839same value:
840
841 $a = new Data 23;
842 ...
843 $b = $a; # $b is "linked" to $a
844 ...
845 $a = $a->clone; # Unlink $b from $a
846 $a->increment_by(4);
847
848Note that overloaded access makes this transparent:
849
850 $a = new Data 23;
851 $b = $a; # $b is "linked" to $a
852 $a += 4; # would unlink $b automagically
853
854However, it would not make
855
856 $a = new Data 23;
857 $a = 4; # Now $a is a plain 4, not 'Data'
858
859preserve "objectness" of $a. But Perl I<has> a way to make assignments
860to an object do whatever you want. It is just not the overload, but
861tie()ing interface (see L<perlfunc/tie>). Adding a FETCH() method
862which returns the object itself, and STORE() method which changes the
863value of the object, one can reproduce the arithmetic metaphor in its
864completeness, at least for variables which were tie()d from the start.
865
866(Note that a workaround for a bug may be needed, see L<"BUGS">.)
867
868=head1 Cookbook
869
870Please add examples to what follows!
871
872=head2 Two-face scalars
873
874Put this in F<two_face.pm> in your Perl library directory:
875
876 package two_face; # Scalars with separate string and
877 # numeric values.
878 sub new { my $p = shift; bless [@_], $p }
879 use overload '""' => \&str, '0+' => \&num, fallback => 1;
880 sub num {shift->[1]}
881 sub str {shift->[0]}
882
883Use it as follows:
884
885 require two_face;
886 my $seven = new two_face ("vii", 7);
887 printf "seven=$seven, seven=%d, eight=%d\n", $seven, $seven+1;
888 print "seven contains `i'\n" if $seven =~ /i/;
889
890(The second line creates a scalar which has both a string value, and a
891numeric value.) This prints:
892
893 seven=vii, seven=7, eight=8
894 seven contains `i'
895
f5284f61
IZ
896=head2 Two-face references
897
898Suppose you want to create an object which is accessible as both an
8db13b63
DC
899array reference and a hash reference, similar to the
900L<pseudo-hash|perlref/"Pseudo-hashes: Using an array as a hash">
901builtin Perl type. Let's make it better than a pseudo-hash by
902allowing index 0 to be treated as a normal element.
f5284f61
IZ
903
904 package two_refs;
905 use overload '%{}' => \&gethash, '@{}' => sub { $ {shift()} };
906 sub new {
907 my $p = shift;
908 bless \ [@_], $p;
909 }
910 sub gethash {
911 my %h;
912 my $self = shift;
913 tie %h, ref $self, $self;
914 \%h;
915 }
916
917 sub TIEHASH { my $p = shift; bless \ shift, $p }
918 my %fields;
919 my $i = 0;
920 $fields{$_} = $i++ foreach qw{zero one two three};
921 sub STORE {
922 my $self = ${shift()};
923 my $key = $fields{shift()};
924 defined $key or die "Out of band access";
925 $$self->[$key] = shift;
926 }
927 sub FETCH {
928 my $self = ${shift()};
929 my $key = $fields{shift()};
930 defined $key or die "Out of band access";
931 $$self->[$key];
932 }
933
934Now one can access an object using both the array and hash syntax:
935
936 my $bar = new two_refs 3,4,5,6;
937 $bar->[2] = 11;
938 $bar->{two} == 11 or die 'bad hash fetch';
939
940Note several important features of this example. First of all, the
941I<actual> type of $bar is a scalar reference, and we do not overload
942the scalar dereference. Thus we can get the I<actual> non-overloaded
943contents of $bar by just using C<$$bar> (what we do in functions which
944overload dereference). Similarly, the object returned by the
945TIEHASH() method is a scalar reference.
946
947Second, we create a new tied hash each time the hash syntax is used.
948This allows us not to worry about a possibility of a reference loop,
949would would lead to a memory leak.
950
951Both these problems can be cured. Say, if we want to overload hash
952dereference on a reference to an object which is I<implemented> as a
953hash itself, the only problem one has to circumvent is how to access
954this I<actual> hash (as opposed to the I<virtual> exhibited by
955overloaded dereference operator). Here is one possible fetching routine:
956
957 sub access_hash {
958 my ($self, $key) = (shift, shift);
959 my $class = ref $self;
960 bless $self, 'overload::dummy'; # Disable overloading of %{}
961 my $out = $self->{$key};
962 bless $self, $class; # Restore overloading
963 $out;
964 }
965
966To move creation of the tied hash on each access, one may an extra
967level of indirection which allows a non-circular structure of references:
968
969 package two_refs1;
970 use overload '%{}' => sub { ${shift()}->[1] },
971 '@{}' => sub { ${shift()}->[0] };
972 sub new {
973 my $p = shift;
974 my $a = [@_];
975 my %h;
976 tie %h, $p, $a;
977 bless \ [$a, \%h], $p;
978 }
979 sub gethash {
980 my %h;
981 my $self = shift;
982 tie %h, ref $self, $self;
983 \%h;
984 }
985
986 sub TIEHASH { my $p = shift; bless \ shift, $p }
987 my %fields;
988 my $i = 0;
989 $fields{$_} = $i++ foreach qw{zero one two three};
990 sub STORE {
991 my $a = ${shift()};
992 my $key = $fields{shift()};
993 defined $key or die "Out of band access";
994 $a->[$key] = shift;
995 }
996 sub FETCH {
997 my $a = ${shift()};
998 my $key = $fields{shift()};
999 defined $key or die "Out of band access";
1000 $a->[$key];
1001 }
1002
1003Now if $baz is overloaded like this, then C<$bar> is a reference to a
1004reference to the intermediate array, which keeps a reference to an
1005actual array, and the access hash. The tie()ing object for the access
1006hash is also a reference to a reference to the actual array, so
1007
1008=over
1009
1010=item *
1011
1012There are no loops of references.
1013
1014=item *
1015
1016Both "objects" which are blessed into the class C<two_refs1> are
1017references to a reference to an array, thus references to a I<scalar>.
1018Thus the accessor expression C<$$foo-E<gt>[$ind]> involves no
1019overloaded operations.
1020
1021=back
1022
ee239bfe
IZ
1023=head2 Symbolic calculator
1024
1025Put this in F<symbolic.pm> in your Perl library directory:
1026
1027 package symbolic; # Primitive symbolic calculator
1028 use overload nomethod => \&wrap;
1029
1030 sub new { shift; bless ['n', @_] }
1031 sub wrap {
1032 my ($obj, $other, $inv, $meth) = @_;
1033 ($obj, $other) = ($other, $obj) if $inv;
1034 bless [$meth, $obj, $other];
1035 }
1036
1037This module is very unusual as overloaded modules go: it does not
1038provide any usual overloaded operators, instead it provides the L<Last
1039Resort> operator C<nomethod>. In this example the corresponding
f610777f 1040subroutine returns an object which encapsulates operations done over
ee239bfe
IZ
1041the objects: C<new symbolic 3> contains C<['n', 3]>, C<2 + new
1042symbolic 3> contains C<['+', 2, ['n', 3]]>.
1043
1044Here is an example of the script which "calculates" the side of
1045circumscribed octagon using the above package:
1046
1047 require symbolic;
1048 my $iter = 1; # 2**($iter+2) = 8
1049 my $side = new symbolic 1;
1050 my $cnt = $iter;
3cb6de81 1051
ee239bfe
IZ
1052 while ($cnt--) {
1053 $side = (sqrt(1 + $side**2) - 1)/$side;
1054 }
1055 print "OK\n";
1056
1057The value of $side is
1058
1059 ['/', ['-', ['sqrt', ['+', 1, ['**', ['n', 1], 2]],
1060 undef], 1], ['n', 1]]
1061
1062Note that while we obtained this value using a nice little script,
1063there is no simple way to I<use> this value. In fact this value may
1064be inspected in debugger (see L<perldebug>), but ony if
1065C<bareStringify> B<O>ption is set, and not via C<p> command.
1066
1067If one attempts to print this value, then the overloaded operator
1068C<""> will be called, which will call C<nomethod> operator. The
1069result of this operator will be stringified again, but this result is
1070again of type C<symbolic>, which will lead to an infinite loop.
1071
1072Add a pretty-printer method to the module F<symbolic.pm>:
1073
1074 sub pretty {
1075 my ($meth, $a, $b) = @{+shift};
1076 $a = 'u' unless defined $a;
1077 $b = 'u' unless defined $b;
1078 $a = $a->pretty if ref $a;
1079 $b = $b->pretty if ref $b;
1080 "[$meth $a $b]";
1081 }
1082
1083Now one can finish the script by
1084
1085 print "side = ", $side->pretty, "\n";
1086
1087The method C<pretty> is doing object-to-string conversion, so it
1088is natural to overload the operator C<""> using this method. However,
1089inside such a method it is not necessary to pretty-print the
1090I<components> $a and $b of an object. In the above subroutine
1091C<"[$meth $a $b]"> is a catenation of some strings and components $a
1092and $b. If these components use overloading, the catenation operator
1093will look for an overloaded operator C<.>, if not present, it will
1094look for an overloaded operator C<"">. Thus it is enough to use
1095
1096 use overload nomethod => \&wrap, '""' => \&str;
1097 sub str {
1098 my ($meth, $a, $b) = @{+shift};
1099 $a = 'u' unless defined $a;
1100 $b = 'u' unless defined $b;
1101 "[$meth $a $b]";
1102 }
1103
1104Now one can change the last line of the script to
1105
1106 print "side = $side\n";
1107
1108which outputs
1109
1110 side = [/ [- [sqrt [+ 1 [** [n 1 u] 2]] u] 1] [n 1 u]]
1111
1112and one can inspect the value in debugger using all the possible
1113methods.
1114
1115Something is is still amiss: consider the loop variable $cnt of the
1116script. It was a number, not an object. We cannot make this value of
1117type C<symbolic>, since then the loop will not terminate.
1118
1119Indeed, to terminate the cycle, the $cnt should become false.
1120However, the operator C<bool> for checking falsity is overloaded (this
1121time via overloaded C<"">), and returns a long string, thus any object
1122of type C<symbolic> is true. To overcome this, we need a way to
1123compare an object to 0. In fact, it is easier to write a numeric
1124conversion routine.
1125
1126Here is the text of F<symbolic.pm> with such a routine added (and
f610777f 1127slightly modified str()):
ee239bfe
IZ
1128
1129 package symbolic; # Primitive symbolic calculator
1130 use overload
1131 nomethod => \&wrap, '""' => \&str, '0+' => \&num;
1132
1133 sub new { shift; bless ['n', @_] }
1134 sub wrap {
1135 my ($obj, $other, $inv, $meth) = @_;
1136 ($obj, $other) = ($other, $obj) if $inv;
1137 bless [$meth, $obj, $other];
1138 }
1139 sub str {
1140 my ($meth, $a, $b) = @{+shift};
1141 $a = 'u' unless defined $a;
1142 if (defined $b) {
1143 "[$meth $a $b]";
1144 } else {
1145 "[$meth $a]";
1146 }
1147 }
1148 my %subr = ( n => sub {$_[0]},
1149 sqrt => sub {sqrt $_[0]},
1150 '-' => sub {shift() - shift()},
1151 '+' => sub {shift() + shift()},
1152 '/' => sub {shift() / shift()},
1153 '*' => sub {shift() * shift()},
1154 '**' => sub {shift() ** shift()},
1155 );
1156 sub num {
1157 my ($meth, $a, $b) = @{+shift};
1158 my $subr = $subr{$meth}
1159 or die "Do not know how to ($meth) in symbolic";
1160 $a = $a->num if ref $a eq __PACKAGE__;
1161 $b = $b->num if ref $b eq __PACKAGE__;
1162 $subr->($a,$b);
1163 }
1164
1165All the work of numeric conversion is done in %subr and num(). Of
f610777f 1166course, %subr is not complete, it contains only operators used in the
ee239bfe
IZ
1167example below. Here is the extra-credit question: why do we need an
1168explicit recursion in num()? (Answer is at the end of this section.)
1169
1170Use this module like this:
1171
1172 require symbolic;
1173 my $iter = new symbolic 2; # 16-gon
1174 my $side = new symbolic 1;
1175 my $cnt = $iter;
3cb6de81 1176
ee239bfe
IZ
1177 while ($cnt) {
1178 $cnt = $cnt - 1; # Mutator `--' not implemented
1179 $side = (sqrt(1 + $side**2) - 1)/$side;
1180 }
1181 printf "%s=%f\n", $side, $side;
1182 printf "pi=%f\n", $side*(2**($iter+2));
1183
1184It prints (without so many line breaks)
1185
1186 [/ [- [sqrt [+ 1 [** [/ [- [sqrt [+ 1 [** [n 1] 2]]] 1]
1187 [n 1]] 2]]] 1]
1188 [/ [- [sqrt [+ 1 [** [n 1] 2]]] 1] [n 1]]]=0.198912
1189 pi=3.182598
1190
1191The above module is very primitive. It does not implement
1192mutator methods (C<++>, C<-=> and so on), does not do deep copying
1193(not required without mutators!), and implements only those arithmetic
1194operations which are used in the example.
1195
f610777f 1196To implement most arithmetic operations is easy, one should just use
ee239bfe
IZ
1197the tables of operations, and change the code which fills %subr to
1198
1199 my %subr = ( 'n' => sub {$_[0]} );
1200 foreach my $op (split " ", $overload::ops{with_assign}) {
1201 $subr{$op} = $subr{"$op="} = eval "sub {shift() $op shift()}";
1202 }
1203 my @bins = qw(binary 3way_comparison num_comparison str_comparison);
1204 foreach my $op (split " ", "@overload::ops{ @bins }") {
1205 $subr{$op} = eval "sub {shift() $op shift()}";
1206 }
1207 foreach my $op (split " ", "@overload::ops{qw(unary func)}") {
1208 print "defining `$op'\n";
1209 $subr{$op} = eval "sub {$op shift()}";
1210 }
1211
1212Due to L<Calling Conventions for Mutators>, we do not need anything
1213special to make C<+=> and friends work, except filling C<+=> entry of
1214%subr, and defining a copy constructor (needed since Perl has no
1215way to know that the implementation of C<'+='> does not mutate
1216the argument, compare L<Copy Constructor>).
1217
1218To implement a copy constructor, add C<'=' => \&cpy> to C<use overload>
1219line, and code (this code assumes that mutators change things one level
1220deep only, so recursive copying is not needed):
1221
1222 sub cpy {
1223 my $self = shift;
1224 bless [@$self], ref $self;
1225 }
1226
1227To make C<++> and C<--> work, we need to implement actual mutators,
1228either directly, or in C<nomethod>. We continue to do things inside
1229C<nomethod>, thus add
1230
1231 if ($meth eq '++' or $meth eq '--') {
1232 @$obj = ($meth, (bless [@$obj]), 1); # Avoid circular reference
1233 return $obj;
1234 }
1235
1236after the first line of wrap(). This is not a most effective
1237implementation, one may consider
1238
1239 sub inc { $_[0] = bless ['++', shift, 1]; }
1240
1241instead.
1242
1243As a final remark, note that one can fill %subr by
1244
1245 my %subr = ( 'n' => sub {$_[0]} );
1246 foreach my $op (split " ", $overload::ops{with_assign}) {
1247 $subr{$op} = $subr{"$op="} = eval "sub {shift() $op shift()}";
1248 }
1249 my @bins = qw(binary 3way_comparison num_comparison str_comparison);
1250 foreach my $op (split " ", "@overload::ops{ @bins }") {
1251 $subr{$op} = eval "sub {shift() $op shift()}";
1252 }
1253 foreach my $op (split " ", "@overload::ops{qw(unary func)}") {
1254 $subr{$op} = eval "sub {$op shift()}";
1255 }
1256 $subr{'++'} = $subr{'+'};
1257 $subr{'--'} = $subr{'-'};
1258
1259This finishes implementation of a primitive symbolic calculator in
126050 lines of Perl code. Since the numeric values of subexpressions
1261are not cached, the calculator is very slow.
1262
1263Here is the answer for the exercise: In the case of str(), we need no
1264explicit recursion since the overloaded C<.>-operator will fall back
1265to an existing overloaded operator C<"">. Overloaded arithmetic
1266operators I<do not> fall back to numeric conversion if C<fallback> is
1267not explicitly requested. Thus without an explicit recursion num()
1268would convert C<['+', $a, $b]> to C<$a + $b>, which would just rebuild
1269the argument of num().
1270
1271If you wonder why defaults for conversion are different for str() and
1272num(), note how easy it was to write the symbolic calculator. This
1273simplicity is due to an appropriate choice of defaults. One extra
f610777f
A
1274note: due to the explicit recursion num() is more fragile than sym():
1275we need to explicitly check for the type of $a and $b. If components
ee239bfe
IZ
1276$a and $b happen to be of some related type, this may lead to problems.
1277
1278=head2 I<Really> symbolic calculator
1279
1280One may wonder why we call the above calculator symbolic. The reason
1281is that the actual calculation of the value of expression is postponed
1282until the value is I<used>.
1283
1284To see it in action, add a method
1285
1286 sub STORE {
1287 my $obj = shift;
1288 $#$obj = 1;
1289 @$obj->[0,1] = ('=', shift);
1290 }
1291
1292to the package C<symbolic>. After this change one can do
1293
1294 my $a = new symbolic 3;
1295 my $b = new symbolic 4;
1296 my $c = sqrt($a**2 + $b**2);
1297
1298and the numeric value of $c becomes 5. However, after calling
1299
1300 $a->STORE(12); $b->STORE(5);
1301
1302the numeric value of $c becomes 13. There is no doubt now that the module
1303symbolic provides a I<symbolic> calculator indeed.
1304
1305To hide the rough edges under the hood, provide a tie()d interface to the
1306package C<symbolic> (compare with L<Metaphor clash>). Add methods
1307
1308 sub TIESCALAR { my $pack = shift; $pack->new(@_) }
1309 sub FETCH { shift }
1310 sub nop { } # Around a bug
1311
1312(the bug is described in L<"BUGS">). One can use this new interface as
1313
1314 tie $a, 'symbolic', 3;
1315 tie $b, 'symbolic', 4;
1316 $a->nop; $b->nop; # Around a bug
1317
1318 my $c = sqrt($a**2 + $b**2);
1319
1320Now numeric value of $c is 5. After C<$a = 12; $b = 5> the numeric value
1321of $c becomes 13. To insulate the user of the module add a method
1322
1323 sub vars { my $p = shift; tie($_, $p), $_->nop foreach @_; }
1324
1325Now
1326
1327 my ($a, $b);
1328 symbolic->vars($a, $b);
1329 my $c = sqrt($a**2 + $b**2);
1330
1331 $a = 3; $b = 4;
1332 printf "c5 %s=%f\n", $c, $c;
1333
1334 $a = 12; $b = 5;
1335 printf "c13 %s=%f\n", $c, $c;
1336
1337shows that the numeric value of $c follows changes to the values of $a
1338and $b.
1339
4633a7c4
LW
1340=head1 AUTHOR
1341
1fef88e7 1342Ilya Zakharevich E<lt>F<ilya@math.mps.ohio-state.edu>E<gt>.
4633a7c4
LW
1343
1344=head1 DIAGNOSTICS
1345
1346When Perl is run with the B<-Do> switch or its equivalent, overloading
1347induces diagnostic messages.
1348
e7ea3e70
IZ
1349Using the C<m> command of Perl debugger (see L<perldebug>) one can
1350deduce which operations are overloaded (and which ancestor triggers
1351this overloading). Say, if C<eq> is overloaded, then the method C<(eq>
1352is shown by debugger. The method C<()> corresponds to the C<fallback>
1353key (in fact a presence of this method shows that this package has
1354overloading enabled, and it is what is used by the C<Overloaded>
ee239bfe 1355function of module C<overload>).
e7ea3e70 1356
6ad11d81 1357The module might issue the following warnings:
6b82e2f5
A
1358
1359=over 4
1360
1361=item Odd number of arguments for overload::constant
1362
1363(W) The call to overload::constant contained an odd number of arguments.
1364The arguments should come in pairs.
1365
1366=item `%s' is not an overloadable type
1367
1368(W) You tried to overload a constant type the overload package is unaware of.
1369
1370=item `%s' is not a code reference
1371
1372(W) The second (fourth, sixth, ...) argument of overload::constant needs
1373to be a code reference. Either an anonymous subroutine, or a reference
1374to a subroutine.
1375
1376=back
1377
4633a7c4
LW
1378=head1 BUGS
1379
aa689395
PP
1380Because it is used for overloading, the per-package hash %OVERLOAD now
1381has a special meaning in Perl. The symbol table is filled with names
1382looking like line-noise.
4633a7c4 1383
a6006777
PP
1384For the purpose of inheritance every overloaded package behaves as if
1385C<fallback> is present (possibly undefined). This may create
1386interesting effects if some package is not overloaded, but inherits
1387from two overloaded packages.
4633a7c4 1388
ee239bfe
IZ
1389Relation between overloading and tie()ing is broken. Overloading is
1390triggered or not basing on the I<previous> class of tie()d value.
1391
1392This happens because the presence of overloading is checked too early,
1393before any tie()d access is attempted. If the FETCH()ed class of the
1394tie()d value does not change, a simple workaround is to access the value
1395immediately after tie()ing, so that after this call the I<previous> class
1396coincides with the current one.
1397
1398B<Needed:> a way to fix this without a speed penalty.
1399
b3ac6de7
IZ
1400Barewords are not covered by overloaded string constants.
1401
ee239bfe
IZ
1402This document is confusing. There are grammos and misleading language
1403used in places. It would seem a total rewrite is needed.
4633a7c4
LW
1404
1405=cut
1406