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