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