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