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