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