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