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