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