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