"Fossies" - the Fresh Open Source Software Archive

Member "install-tl-20200916/tlpkg/tlperl/lib/overload.pm" (10 Mar 2019, 53288 Bytes) of package /windows/misc/install-tl.zip:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) Perl source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file.

    1 package overload;
    2 
    3 our $VERSION = '1.30';
    4 
    5 %ops = (
    6     with_assign         => "+ - * / % ** << >> x .",
    7     assign              => "+= -= *= /= %= **= <<= >>= x= .=",
    8     num_comparison      => "< <= >  >= == !=",
    9     '3way_comparison'   => "<=> cmp",
   10     str_comparison      => "lt le gt ge eq ne",
   11     binary              => '& &= | |= ^ ^= &. &.= |. |.= ^. ^.=',
   12     unary               => "neg ! ~ ~.",
   13     mutators            => '++ --',
   14     func                => "atan2 cos sin exp abs log sqrt int",
   15     conversion          => 'bool "" 0+ qr',
   16     iterators           => '<>',
   17     filetest            => "-X",
   18     dereferencing       => '${} @{} %{} &{} *{}',
   19     matching            => '~~',
   20     special             => 'nomethod fallback =',
   21 );
   22 
   23 my %ops_seen;
   24 @ops_seen{ map split(/ /), values %ops } = ();
   25 
   26 sub nil {}
   27 
   28 sub OVERLOAD {
   29   $package = shift;
   30   my %arg = @_;
   31   my $sub;
   32   *{$package . "::(("} = \&nil; # Make it findable via fetchmethod.
   33   for (keys %arg) {
   34     if ($_ eq 'fallback') {
   35       for my $sym (*{$package . "::()"}) {
   36     *$sym = \&nil; # Make it findable via fetchmethod.
   37     $$sym = $arg{$_};
   38       }
   39     } else {
   40       warnings::warnif("overload arg '$_' is invalid")
   41         unless exists $ops_seen{$_};
   42       $sub = $arg{$_};
   43       if (not ref $sub) {
   44     $ {$package . "::(" . $_} = $sub;
   45     $sub = \&nil;
   46       }
   47       #print STDERR "Setting '$ {'package'}::\cO$_' to \\&'$sub'.\n";
   48       *{$package . "::(" . $_} = \&{ $sub };
   49     }
   50   }
   51 }
   52 
   53 sub import {
   54   $package = (caller())[0];
   55   # *{$package . "::OVERLOAD"} = \&OVERLOAD;
   56   shift;
   57   $package->overload::OVERLOAD(@_);
   58 }
   59 
   60 sub unimport {
   61   $package = (caller())[0];
   62   shift;
   63   *{$package . "::(("} = \&nil;
   64   for (@_) {
   65       warnings::warnif("overload arg '$_' is invalid")
   66         unless exists $ops_seen{$_};
   67       delete $ {$package . "::"}{$_ eq 'fallback' ? '()' : "(" .$_};
   68   }
   69 }
   70 
   71 sub Overloaded {
   72   my $package = shift;
   73   $package = ref $package if ref $package;
   74   mycan ($package, '()') || mycan ($package, '((');
   75 }
   76 
   77 sub ov_method {
   78   my $globref = shift;
   79   return undef unless $globref;
   80   my $sub = \&{*$globref};
   81   no overloading;
   82   return $sub if $sub != \&nil;
   83   return shift->can($ {*$globref});
   84 }
   85 
   86 sub OverloadedStringify {
   87   my $package = shift;
   88   $package = ref $package if ref $package;
   89   #$package->can('(""')
   90   ov_method mycan($package, '(""'), $package
   91     or ov_method mycan($package, '(0+'), $package
   92     or ov_method mycan($package, '(bool'), $package
   93     or ov_method mycan($package, '(nomethod'), $package;
   94 }
   95 
   96 sub Method {
   97   my $package = shift;
   98   if(ref $package) {
   99     local $@;
  100     local $!;
  101     require Scalar::Util;
  102     $package = Scalar::Util::blessed($package);
  103     return undef if !defined $package;
  104   }
  105   #my $meth = $package->can('(' . shift);
  106   ov_method mycan($package, '(' . shift), $package;
  107   #return $meth if $meth ne \&nil;
  108   #return $ {*{$meth}};
  109 }
  110 
  111 sub AddrRef {
  112   no overloading;
  113   "$_[0]";
  114 }
  115 
  116 *StrVal = *AddrRef;
  117 
  118 sub mycan {             # Real can would leave stubs.
  119   my ($package, $meth) = @_;
  120 
  121   local $@;
  122   local $!;
  123   require mro;
  124 
  125   my $mro = mro::get_linear_isa($package);
  126   foreach my $p (@$mro) {
  127     my $fqmeth = $p . q{::} . $meth;
  128     return \*{$fqmeth} if defined &{$fqmeth};
  129   }
  130 
  131   return undef;
  132 }
  133 
  134 %constants = (
  135           'integer'   =>  0x1000, # HINT_NEW_INTEGER
  136           'float'     =>  0x2000, # HINT_NEW_FLOAT
  137           'binary'    =>  0x4000, # HINT_NEW_BINARY
  138           'q'     =>  0x8000, # HINT_NEW_STRING
  139           'qr'    => 0x10000, # HINT_NEW_RE
  140          );
  141 
  142 use warnings::register;
  143 sub constant {
  144   # Arguments: what, sub
  145   while (@_) {
  146     if (@_ == 1) {
  147         warnings::warnif ("Odd number of arguments for overload::constant");
  148         last;
  149     }
  150     elsif (!exists $constants {$_ [0]}) {
  151         warnings::warnif ("'$_[0]' is not an overloadable type");
  152     }
  153     elsif (!ref $_ [1] || "$_[1]" !~ /(^|=)CODE\(0x[0-9a-f]+\)$/) {
  154         # Can't use C<ref $_[1] eq "CODE"> above as code references can be
  155         # blessed, and C<ref> would return the package the ref is blessed into.
  156         if (warnings::enabled) {
  157             $_ [1] = "undef" unless defined $_ [1];
  158             warnings::warn ("'$_[1]' is not a code reference");
  159         }
  160     }
  161     else {
  162         $^H{$_[0]} = $_[1];
  163         $^H |= $constants{$_[0]};
  164     }
  165     shift, shift;
  166   }
  167 }
  168 
  169 sub remove_constant {
  170   # Arguments: what, sub
  171   while (@_) {
  172     delete $^H{$_[0]};
  173     $^H &= ~ $constants{$_[0]};
  174     shift, shift;
  175   }
  176 }
  177 
  178 1;
  179 
  180 __END__
  181 
  182 =head1 NAME
  183 
  184 overload - Package for overloading Perl operations
  185 
  186 =head1 SYNOPSIS
  187 
  188     package SomeThing;
  189 
  190     use overload
  191     '+' => \&myadd,
  192     '-' => \&mysub;
  193     # etc
  194     ...
  195 
  196     package main;
  197     $a = SomeThing->new( 57 );
  198     $b = 5 + $a;
  199     ...
  200     if (overload::Overloaded $b) {...}
  201     ...
  202     $strval = overload::StrVal $b;
  203 
  204 =head1 DESCRIPTION
  205 
  206 This pragma allows overloading of Perl's operators for a class.
  207 To overload built-in functions, see L<perlsub/Overriding Built-in Functions> instead.
  208 
  209 =head2 Fundamentals
  210 
  211 =head3 Declaration
  212 
  213 Arguments of the C<use overload> directive are (key, value) pairs.
  214 For the full set of legal keys, see L<Overloadable Operations> below.
  215 
  216 Operator implementations (the values) can be subroutines,
  217 references to subroutines, or anonymous subroutines
  218 - in other words, anything legal inside a C<&{ ... }> call.
  219 Values specified as strings are interpreted as method names.
  220 Thus
  221 
  222     package Number;
  223     use overload
  224         "-" => "minus",
  225         "*=" => \&muas,
  226         '""' => sub { ...; };
  227 
  228 declares that subtraction is to be implemented by method C<minus()>
  229 in the class C<Number> (or one of its base classes),
  230 and that the function C<Number::muas()> is to be used for the
  231 assignment form of multiplication, C<*=>.
  232 It also defines an anonymous subroutine to implement stringification:
  233 this is called whenever an object blessed into the package C<Number>
  234 is used in a string context (this subroutine might, for example,
  235 return the number as a Roman numeral).
  236 
  237 =head3 Calling Conventions and Magic Autogeneration
  238 
  239 The following sample implementation of C<minus()> (which assumes
  240 that C<Number> objects are simply blessed references to scalars)
  241 illustrates the calling conventions:
  242 
  243     package Number;
  244     sub minus {
  245         my ($self, $other, $swap) = @_;
  246         my $result = $$self - $other;         # *
  247         $result = -$result if $swap;
  248         ref $result ? $result : bless \$result;
  249     }
  250     # * may recurse once - see table below
  251 
  252 Three arguments are passed to all subroutines specified in the
  253 C<use overload> directive (with exceptions - see below, particularly
  254 L</nomethod>).
  255 
  256 The first of these is the operand providing the overloaded
  257 operator implementation -
  258 in this case, the object whose C<minus()> method is being called.
  259 
  260 The second argument is the other operand, or C<undef> in the
  261 case of a unary operator.
  262 
  263 The third argument is set to TRUE if (and only if) the two
  264 operands have been swapped.  Perl may do this to ensure that the
  265 first argument (C<$self>) is an object implementing the overloaded
  266 operation, in line with general object calling conventions.
  267 For example, if C<$x> and C<$y> are C<Number>s:
  268 
  269     operation   |   generates a call to
  270     ============|======================
  271     $x - $y     |   minus($x, $y, '')
  272     $x - 7      |   minus($x, 7, '')
  273     7 - $x      |   minus($x, 7, 1)
  274 
  275 Perl may also use C<minus()> to implement other operators which
  276 have not been specified in the C<use overload> directive,
  277 according to the rules for L<Magic Autogeneration> described later.
  278 For example, the C<use overload> above declared no subroutine
  279 for any of the operators C<-->, C<neg> (the overload key for
  280 unary minus), or C<-=>.  Thus
  281 
  282     operation   |   generates a call to
  283     ============|======================
  284     -$x         |   minus($x, 0, 1)
  285     $x--        |   minus($x, 1, undef)
  286     $x -= 3     |   minus($x, 3, undef)
  287 
  288 Note the C<undef>s:
  289 where autogeneration results in the method for a standard
  290 operator which does not change either of its operands, such
  291 as C<->, being used to implement an operator which changes
  292 the operand ("mutators": here, C<--> and C<-=>),
  293 Perl passes undef as the third argument.
  294 This still evaluates as FALSE, consistent with the fact that
  295 the operands have not been swapped, but gives the subroutine
  296 a chance to alter its behaviour in these cases.
  297 
  298 In all the above examples, C<minus()> is required
  299 only to return the result of the subtraction:
  300 Perl takes care of the assignment to $x.
  301 In fact, such methods should I<not> modify their operands,
  302 even if C<undef> is passed as the third argument
  303 (see L<Overloadable Operations>).
  304 
  305 The same is not true of implementations of C<++> and C<-->:
  306 these are expected to modify their operand.
  307 An appropriate implementation of C<--> might look like
  308 
  309     use overload '--' => "decr",
  310         # ...
  311     sub decr { --${$_[0]}; }
  312 
  313 If the "bitwise" feature is enabled (see L<feature>), a fifth
  314 TRUE argument is passed to subroutines handling C<&>, C<|>, C<^> and C<~>.
  315 This indicates that the caller is expecting numeric behaviour.  The fourth
  316 argument will be C<undef>, as that position (C<$_[3]>) is reserved for use
  317 by L</nomethod>.
  318 
  319 =head3 Mathemagic, Mutators, and Copy Constructors
  320 
  321 The term 'mathemagic' describes the overloaded implementation
  322 of mathematical operators.
  323 Mathemagical operations raise an issue.
  324 Consider the code:
  325 
  326     $a = $b;
  327     --$a;
  328 
  329 If C<$a> and C<$b> are scalars then after these statements
  330 
  331     $a == $b - 1
  332 
  333 An object, however, is a reference to blessed data, so if
  334 C<$a> and C<$b> are objects then the assignment C<$a = $b>
  335 copies only the reference, leaving C<$a> and C<$b> referring
  336 to the same object data.
  337 One might therefore expect the operation C<--$a> to decrement
  338 C<$b> as well as C<$a>.
  339 However, this would not be consistent with how we expect the
  340 mathematical operators to work.
  341 
  342 Perl resolves this dilemma by transparently calling a copy
  343 constructor before calling a method defined to implement
  344 a mutator (C<-->, C<+=>, and so on.).
  345 In the above example, when Perl reaches the decrement
  346 statement, it makes a copy of the object data in C<$a> and
  347 assigns to C<$a> a reference to the copied data.
  348 Only then does it call C<decr()>, which alters the copied
  349 data, leaving C<$b> unchanged.
  350 Thus the object metaphor is preserved as far as possible,
  351 while mathemagical operations still work according to the
  352 arithmetic metaphor.
  353 
  354 Note: the preceding paragraph describes what happens when
  355 Perl autogenerates the copy constructor for an object based
  356 on a scalar.
  357 For other cases, see L<Copy Constructor>.
  358 
  359 =head2 Overloadable Operations
  360 
  361 The complete list of keys that can be specified in the C<use overload>
  362 directive are given, separated by spaces, in the values of the
  363 hash C<%overload::ops>:
  364 
  365  with_assign      => '+ - * / % ** << >> x .',
  366  assign       => '+= -= *= /= %= **= <<= >>= x= .=',
  367  num_comparison   => '< <= > >= == !=',
  368  '3way_comparison'=> '<=> cmp',
  369  str_comparison   => 'lt le gt ge eq ne',
  370  binary       => '& &= | |= ^ ^= &. &.= |. |.= ^. ^.=',
  371  unary        => 'neg ! ~ ~.',
  372  mutators     => '++ --',
  373  func         => 'atan2 cos sin exp abs log sqrt int',
  374  conversion   => 'bool "" 0+ qr',
  375  iterators    => '<>',
  376  filetest         => '-X',
  377  dereferencing    => '${} @{} %{} &{} *{}',
  378  matching     => '~~',
  379  special      => 'nomethod fallback ='
  380 
  381 Most of the overloadable operators map one-to-one to these keys.
  382 Exceptions, including additional overloadable operations not
  383 apparent from this hash, are included in the notes which follow.
  384 This list is subject to growth over time.
  385 
  386 A warning is issued if an attempt is made to register an operator not found
  387 above.
  388 
  389 =over 5
  390 
  391 =item * C<not>
  392 
  393 The operator C<not> is not a valid key for C<use overload>.
  394 However, if the operator C<!> is overloaded then the same
  395 implementation will be used for C<not>
  396 (since the two operators differ only in precedence).
  397 
  398 =item * C<neg>
  399 
  400 The key C<neg> is used for unary minus to disambiguate it from
  401 binary C<->.
  402 
  403 =item * C<++>, C<-->
  404 
  405 Assuming they are to behave analogously to Perl's C<++> and C<-->,
  406 overloaded implementations of these operators are required to
  407 mutate their operands.
  408 
  409 No distinction is made between prefix and postfix forms of the
  410 increment and decrement operators: these differ only in the
  411 point at which Perl calls the associated subroutine when
  412 evaluating an expression.
  413 
  414 =item * I<Assignments>
  415 
  416     +=  -=  *=  /=  %=  **=  <<=  >>=  x=  .=
  417     &=  |=  ^=  &.=  |.=  ^.=
  418 
  419 Simple assignment is not overloadable (the C<'='> key is used
  420 for the L<Copy Constructor>).
  421 Perl does have a way to make assignments to an object do whatever
  422 you want, but this involves using tie(), not overload -
  423 see L<perlfunc/tie> and the L</COOKBOOK> examples below.
  424 
  425 The subroutine for the assignment variant of an operator is
  426 required only to return the result of the operation.
  427 It is permitted to change the value of its operand
  428 (this is safe because Perl calls the copy constructor first),
  429 but this is optional since Perl assigns the returned value to
  430 the left-hand operand anyway.
  431 
  432 An object that overloads an assignment operator does so only in
  433 respect of assignments to that object.
  434 In other words, Perl never calls the corresponding methods with
  435 the third argument (the "swap" argument) set to TRUE.
  436 For example, the operation
  437 
  438     $a *= $b
  439 
  440 cannot lead to C<$b>'s implementation of C<*=> being called,
  441 even if C<$a> is a scalar.
  442 (It can, however, generate a call to C<$b>'s method for C<*>).
  443 
  444 =item * I<Non-mutators with a mutator variant>
  445 
  446      +  -  *  /  %  **  <<  >>  x  .
  447      &  |  ^  &.  |.  ^.
  448 
  449 As described L<above|"Calling Conventions and Magic Autogeneration">,
  450 Perl may call methods for operators like C<+> and C<&> in the course
  451 of implementing missing operations like C<++>, C<+=>, and C<&=>.
  452 While these methods may detect this usage by testing the definedness
  453 of the third argument, they should in all cases avoid changing their
  454 operands.
  455 This is because Perl does not call the copy constructor before
  456 invoking these methods.
  457 
  458 =item * C<int>
  459 
  460 Traditionally, the Perl function C<int> rounds to 0
  461 (see L<perlfunc/int>), and so for floating-point-like types one
  462 should follow the same semantic.
  463 
  464 =item * I<String, numeric, boolean, and regexp conversions>
  465 
  466     ""  0+  bool
  467 
  468 These conversions are invoked according to context as necessary.
  469 For example, the subroutine for C<'""'> (stringify) may be used
  470 where the overloaded object is passed as an argument to C<print>,
  471 and that for C<'bool'> where it is tested in the condition of a flow
  472 control statement (like C<while>) or the ternary C<?:> operation.
  473 
  474 Of course, in contexts like, for example, C<$obj + 1>, Perl will
  475 invoke C<$obj>'s implementation of C<+> rather than (in this
  476 example) converting C<$obj> to a number using the numify method
  477 C<'0+'> (an exception to this is when no method has been provided
  478 for C<'+'> and L</fallback> is set to TRUE).
  479 
  480 The subroutines for C<'""'>, C<'0+'>, and C<'bool'> can return
  481 any arbitrary Perl value.
  482 If the corresponding operation for this value is overloaded too,
  483 the operation will be called again with this value.
  484 
  485 As a special case if the overload returns the object itself then it will
  486 be used directly.  An overloaded conversion returning the object is
  487 probably a bug, because you're likely to get something that looks like
  488 C<YourPackage=HASH(0x8172b34)>.
  489 
  490     qr
  491 
  492 The subroutine for C<'qr'> is used wherever the object is
  493 interpolated into or used as a regexp, including when it
  494 appears on the RHS of a C<=~> or C<!~> operator.
  495 
  496 C<qr> must return a compiled regexp, or a ref to a compiled regexp
  497 (such as C<qr//> returns), and any further overloading on the return
  498 value will be ignored.
  499 
  500 =item * I<Iteration>
  501 
  502 If C<E<lt>E<gt>> is overloaded then the same implementation is used
  503 for both the I<read-filehandle> syntax C<E<lt>$varE<gt>> and
  504 I<globbing> syntax C<E<lt>${var}E<gt>>.
  505 
  506 =item * I<File tests>
  507 
  508 The key C<'-X'> is used to specify a subroutine to handle all the
  509 filetest operators (C<-f>, C<-x>, and so on: see L<perlfunc/-X> for
  510 the full list);
  511 it is not possible to overload any filetest operator individually.
  512 To distinguish them, the letter following the '-' is passed as the
  513 second argument (that is, in the slot that for binary operators
  514 is used to pass the second operand).
  515 
  516 Calling an overloaded filetest operator does not affect the stat value
  517 associated with the special filehandle C<_>.  It still refers to the
  518 result of the last C<stat>, C<lstat> or unoverloaded filetest.
  519 
  520 This overload was introduced in Perl 5.12.
  521 
  522 =item * I<Matching>
  523 
  524 The key C<"~~"> allows you to override the smart matching logic used by
  525 the C<~~> operator and the switch construct (C<given>/C<when>).  See
  526 L<perlsyn/Switch Statements> and L<feature>.
  527 
  528 Unusually, the overloaded implementation of the smart match operator
  529 does not get full control of the smart match behaviour.
  530 In particular, in the following code:
  531 
  532     package Foo;
  533     use overload '~~' => 'match';
  534 
  535     my $obj =  Foo->new();
  536     $obj ~~ [ 1,2,3 ];
  537 
  538 the smart match does I<not> invoke the method call like this:
  539 
  540     $obj->match([1,2,3],0);
  541 
  542 rather, the smart match distributive rule takes precedence, so $obj is
  543 smart matched against each array element in turn until a match is found,
  544 so you may see between one and three of these calls instead:
  545 
  546     $obj->match(1,0);
  547     $obj->match(2,0);
  548     $obj->match(3,0);
  549 
  550 Consult the match table in  L<perlop/"Smartmatch Operator"> for
  551 details of when overloading is invoked.
  552 
  553 =item * I<Dereferencing>
  554 
  555     ${}  @{}  %{}  &{}  *{}
  556 
  557 If these operators are not explicitly overloaded then they
  558 work in the normal way, yielding the underlying scalar,
  559 array, or whatever stores the object data (or the appropriate
  560 error message if the dereference operator doesn't match it).
  561 Defining a catch-all C<'nomethod'> (see L<below|/nomethod>)
  562 makes no difference to this as the catch-all function will
  563 not be called to implement a missing dereference operator.
  564 
  565 If a dereference operator is overloaded then it must return a
  566 I<reference> of the appropriate type (for example, the
  567 subroutine for key C<'${}'> should return a reference to a
  568 scalar, not a scalar), or another object which overloads the
  569 operator: that is, the subroutine only determines what is
  570 dereferenced and the actual dereferencing is left to Perl.
  571 As a special case, if the subroutine returns the object itself
  572 then it will not be called again - avoiding infinite recursion.
  573 
  574 =item * I<Special>
  575 
  576     nomethod  fallback  =
  577 
  578 See L<Special Keys for C<use overload>>.
  579 
  580 =back
  581 
  582 =head2 Magic Autogeneration
  583 
  584 If a method for an operation is not found then Perl tries to
  585 autogenerate a substitute implementation from the operations
  586 that have been defined.
  587 
  588 Note: the behaviour described in this section can be disabled
  589 by setting C<fallback> to FALSE (see L</fallback>).
  590 
  591 In the following tables, numbers indicate priority.
  592 For example, the table below states that,
  593 if no implementation for C<'!'> has been defined then Perl will
  594 implement it using C<'bool'> (that is, by inverting the value
  595 returned by the method for C<'bool'>);
  596 if boolean conversion is also unimplemented then Perl will
  597 use C<'0+'> or, failing that, C<'""'>.
  598 
  599     operator | can be autogenerated from
  600              |
  601              | 0+   ""   bool   .   x
  602     =========|==========================
  603        0+    |       1     2
  604        ""    |  1          2
  605        bool  |  1    2
  606        int   |  1    2     3
  607        !     |  2    3     1
  608        qr    |  2    1     3
  609        .     |  2    1     3
  610        x     |  2    1     3
  611        .=    |  3    2     4    1
  612        x=    |  3    2     4        1
  613        <>    |  2    1     3
  614        -X    |  2    1     3
  615 
  616 Note: The iterator (C<'E<lt>E<gt>'>) and file test (C<'-X'>)
  617 operators work as normal: if the operand is not a blessed glob or
  618 IO reference then it is converted to a string (using the method
  619 for C<'""'>, C<'0+'>, or C<'bool'>) to be interpreted as a glob
  620 or filename.
  621 
  622     operator | can be autogenerated from
  623              |
  624              |  <   <=>   neg   -=    -
  625     =========|==========================
  626        neg   |                        1
  627        -=    |                        1
  628        --    |                   1    2
  629        abs   | a1    a2    b1        b2    [*]
  630        <     |        1
  631        <=    |        1
  632        >     |        1
  633        >=    |        1
  634        ==    |        1
  635        !=    |        1
  636 
  637     * one from [a1, a2] and one from [b1, b2]
  638 
  639 Just as numeric comparisons can be autogenerated from the method
  640 for C<< '<=>' >>, string comparisons can be autogenerated from
  641 that for C<'cmp'>:
  642 
  643      operators          |  can be autogenerated from
  644     ====================|===========================
  645      lt gt le ge eq ne  |  cmp
  646 
  647 Similarly, autogeneration for keys C<'+='> and C<'++'> is analogous
  648 to C<'-='> and C<'--'> above:
  649 
  650     operator | can be autogenerated from
  651              |
  652              |  +=    +
  653     =========|==========================
  654         +=   |        1
  655         ++   |   1    2
  656 
  657 And other assignment variations are analogous to
  658 C<'+='> and C<'-='> (and similar to C<'.='> and C<'x='> above):
  659 
  660               operator ||  *= /= %= **= <<= >>= &= ^= |= &.= ^.= |.=
  661     -------------------||-------------------------------------------
  662     autogenerated from ||  *  /  %  **  <<  >>  &  ^  |  &.  ^.  |.
  663 
  664 Note also that the copy constructor (key C<'='>) may be
  665 autogenerated, but only for objects based on scalars.
  666 See L<Copy Constructor>.
  667 
  668 =head3 Minimal Set of Overloaded Operations
  669 
  670 Since some operations can be automatically generated from others, there is
  671 a minimal set of operations that need to be overloaded in order to have
  672 the complete set of overloaded operations at one's disposal.
  673 Of course, the autogenerated operations may not do exactly what the user
  674 expects.  The minimal set is:
  675 
  676     + - * / % ** << >> x
  677     <=> cmp
  678     & | ^ ~ &. |. ^. ~.
  679     atan2 cos sin exp log sqrt int
  680     "" 0+ bool
  681     ~~
  682 
  683 Of the conversions, only one of string, boolean or numeric is
  684 needed because each can be generated from either of the other two.
  685 
  686 =head2 Special Keys for C<use overload>
  687 
  688 =head3 C<nomethod>
  689 
  690 The C<'nomethod'> key is used to specify a catch-all function to
  691 be called for any operator that is not individually overloaded.
  692 The specified function will be passed four parameters.
  693 The first three arguments coincide with those that would have been
  694 passed to the corresponding method if it had been defined.
  695 The fourth argument is the C<use overload> key for that missing
  696 method.  If the "bitwise" feature is enabled (see L<feature>),
  697 a fifth TRUE argument is passed to subroutines handling C<&>, C<|>, C<^> and C<~> to indicate that the caller is expecting numeric behaviour.
  698 
  699 For example, if C<$a> is an object blessed into a package declaring
  700 
  701     use overload 'nomethod' => 'catch_all', # ...
  702 
  703 then the operation
  704 
  705     3 + $a
  706 
  707 could (unless a method is specifically declared for the key
  708 C<'+'>) result in a call
  709 
  710     catch_all($a, 3, 1, '+')
  711 
  712 See L<How Perl Chooses an Operator Implementation>.
  713 
  714 =head3 C<fallback>
  715 
  716 The value assigned to the key C<'fallback'> tells Perl how hard
  717 it should try to find an alternative way to implement a missing
  718 operator.
  719 
  720 =over
  721 
  722 =item * defined, but FALSE
  723 
  724     use overload "fallback" => 0, # ... ;
  725 
  726 This disables L<Magic Autogeneration>.
  727 
  728 =item * C<undef>
  729 
  730 In the default case where no value is explicitly assigned to
  731 C<fallback>, magic autogeneration is enabled.
  732 
  733 =item * TRUE
  734 
  735 The same as for C<undef>, but if a missing operator cannot be
  736 autogenerated then, instead of issuing an error message, Perl
  737 is allowed to revert to what it would have done for that
  738 operator if there had been no C<use overload> directive.
  739 
  740 Note: in most cases, particularly the L<Copy Constructor>,
  741 this is unlikely to be appropriate behaviour.
  742 
  743 =back
  744 
  745 See L<How Perl Chooses an Operator Implementation>.
  746 
  747 =head3 Copy Constructor
  748 
  749 As mentioned L<above|"Mathemagic, Mutators, and Copy Constructors">,
  750 this operation is called when a mutator is applied to a reference
  751 that shares its object with some other reference.
  752 For example, if C<$b> is mathemagical, and C<'++'> is overloaded
  753 with C<'incr'>, and C<'='> is overloaded with C<'clone'>, then the
  754 code
  755 
  756     $a = $b;
  757     # ... (other code which does not modify $a or $b) ...
  758     ++$b;
  759 
  760 would be executed in a manner equivalent to
  761 
  762     $a = $b;
  763     # ...
  764     $b = $b->clone(undef, "");
  765     $b->incr(undef, "");
  766 
  767 Note:
  768 
  769 =over
  770 
  771 =item *
  772 
  773 The subroutine for C<'='> does not overload the Perl assignment
  774 operator: it is used only to allow mutators to work as described
  775 here.  (See L</Assignments> above.)
  776 
  777 =item *
  778 
  779 As for other operations, the subroutine implementing '=' is passed
  780 three arguments, though the last two are always C<undef> and C<''>.
  781 
  782 =item *
  783 
  784 The copy constructor is called only before a call to a function
  785 declared to implement a mutator, for example, if C<++$b;> in the
  786 code above is effected via a method declared for key C<'++'>
  787 (or 'nomethod', passed C<'++'> as the fourth argument) or, by
  788 autogeneration, C<'+='>.
  789 It is not called if the increment operation is effected by a call
  790 to the method for C<'+'> since, in the equivalent code,
  791 
  792     $a = $b;
  793     $b = $b + 1;
  794 
  795 the data referred to by C<$a> is unchanged by the assignment to
  796 C<$b> of a reference to new object data.
  797 
  798 =item *
  799 
  800 The copy constructor is not called if Perl determines that it is
  801 unnecessary because there is no other reference to the data being
  802 modified.
  803 
  804 =item *
  805 
  806 If C<'fallback'> is undefined or TRUE then a copy constructor
  807 can be autogenerated, but only for objects based on scalars.
  808 In other cases it needs to be defined explicitly.
  809 Where an object's data is stored as, for example, an array of
  810 scalars, the following might be appropriate:
  811 
  812     use overload '=' => sub { bless [ @{$_[0]} ] },  # ...
  813 
  814 =item *
  815 
  816 If C<'fallback'> is TRUE and no copy constructor is defined then,
  817 for objects not based on scalars, Perl may silently fall back on
  818 simple assignment - that is, assignment of the object reference.
  819 In effect, this disables the copy constructor mechanism since
  820 no new copy of the object data is created.
  821 This is almost certainly not what you want.
  822 (It is, however, consistent: for example, Perl's fallback for the
  823 C<++> operator is to increment the reference itself.)
  824 
  825 =back
  826 
  827 =head2 How Perl Chooses an Operator Implementation
  828 
  829 Which is checked first, C<nomethod> or C<fallback>?
  830 If the two operands of an operator are of different types and
  831 both overload the operator, which implementation is used?
  832 The following are the precedence rules:
  833 
  834 =over
  835 
  836 =item 1.
  837 
  838 If the first operand has declared a subroutine to overload the
  839 operator then use that implementation.
  840 
  841 =item 2.
  842 
  843 Otherwise, if fallback is TRUE or undefined for the
  844 first operand then see if the
  845 L<rules for autogeneration|"Magic Autogeneration">
  846 allows another of its operators to be used instead.
  847 
  848 =item 3.
  849 
  850 Unless the operator is an assignment (C<+=>, C<-=>, etc.),
  851 repeat step (1) in respect of the second operand.
  852 
  853 =item 4.
  854 
  855 Repeat Step (2) in respect of the second operand.
  856 
  857 =item 5.
  858 
  859 If the first operand has a "nomethod" method then use that.
  860 
  861 =item 6.
  862 
  863 If the second operand has a "nomethod" method then use that.
  864 
  865 =item 7.
  866 
  867 If C<fallback> is TRUE for both operands
  868 then perform the usual operation for the operator,
  869 treating the operands as numbers, strings, or booleans
  870 as appropriate for the operator (see note).
  871 
  872 =item 8.
  873 
  874 Nothing worked - die.
  875 
  876 =back
  877 
  878 Where there is only one operand (or only one operand with
  879 overloading) the checks in respect of the other operand above are
  880 skipped.
  881 
  882 There are exceptions to the above rules for dereference operations
  883 (which, if Step 1 fails, always fall back to the normal, built-in
  884 implementations - see Dereferencing), and for C<~~> (which has its
  885 own set of rules - see C<Matching> under L</Overloadable Operations>
  886 above).
  887 
  888 Note on Step 7: some operators have a different semantic depending
  889 on the type of their operands.
  890 As there is no way to instruct Perl to treat the operands as, e.g.,
  891 numbers instead of strings, the result here may not be what you
  892 expect.
  893 See L<BUGS AND PITFALLS>.
  894 
  895 =head2 Losing Overloading
  896 
  897 The restriction for the comparison operation is that even if, for example,
  898 C<cmp> should return a blessed reference, the autogenerated C<lt>
  899 function will produce only a standard logical value based on the
  900 numerical value of the result of C<cmp>.  In particular, a working
  901 numeric conversion is needed in this case (possibly expressed in terms of
  902 other conversions).
  903 
  904 Similarly, C<.=>  and C<x=> operators lose their mathemagical properties
  905 if the string conversion substitution is applied.
  906 
  907 When you chop() a mathemagical object it is promoted to a string and its
  908 mathemagical properties are lost.  The same can happen with other
  909 operations as well.
  910 
  911 =head2 Inheritance and Overloading
  912 
  913 Overloading respects inheritance via the @ISA hierarchy.
  914 Inheritance interacts with overloading in two ways.
  915 
  916 =over
  917 
  918 =item Method names in the C<use overload> directive
  919 
  920 If C<value> in
  921 
  922   use overload key => value;
  923 
  924 is a string, it is interpreted as a method name - which may
  925 (in the usual way) be inherited from another class.
  926 
  927 =item Overloading of an operation is inherited by derived classes
  928 
  929 Any class derived from an overloaded class is also overloaded
  930 and inherits its operator implementations.
  931 If the same operator is overloaded in more than one ancestor
  932 then the implementation is determined by the usual inheritance
  933 rules.
  934 
  935 For example, if C<A> inherits from C<B> and C<C> (in that order),
  936 C<B> overloads C<+> with C<\&D::plus_sub>, and C<C> overloads
  937 C<+> by C<"plus_meth">, then the subroutine C<D::plus_sub> will
  938 be called to implement operation C<+> for an object in package C<A>.
  939 
  940 =back
  941 
  942 Note that in Perl version prior to 5.18 inheritance of the C<fallback> key
  943 was not governed by the above rules.  The value of C<fallback> in the first 
  944 overloaded ancestor was used.  This was fixed in 5.18 to follow the usual
  945 rules of inheritance.
  946 
  947 =head2 Run-time Overloading
  948 
  949 Since all C<use> directives are executed at compile-time, the only way to
  950 change overloading during run-time is to
  951 
  952     eval 'use overload "+" => \&addmethod';
  953 
  954 You can also use
  955 
  956     eval 'no overload "+", "--", "<="';
  957 
  958 though the use of these constructs during run-time is questionable.
  959 
  960 =head2 Public Functions
  961 
  962 Package C<overload.pm> provides the following public functions:
  963 
  964 =over 5
  965 
  966 =item overload::StrVal(arg)
  967 
  968 Gives the string value of C<arg> as in the
  969 absence of stringify overloading.  If you
  970 are using this to get the address of a reference (useful for checking if two
  971 references point to the same thing) then you may be better off using
  972 C<Scalar::Util::refaddr()>, which is faster.
  973 
  974 =item overload::Overloaded(arg)
  975 
  976 Returns true if C<arg> is subject to overloading of some operations.
  977 
  978 =item overload::Method(obj,op)
  979 
  980 Returns C<undef> or a reference to the method that implements C<op>.
  981 
  982 =back
  983 
  984 =head2 Overloading Constants
  985 
  986 For some applications, the Perl parser mangles constants too much.
  987 It is possible to hook into this process via C<overload::constant()>
  988 and C<overload::remove_constant()> functions.
  989 
  990 These functions take a hash as an argument.  The recognized keys of this hash
  991 are:
  992 
  993 =over 8
  994 
  995 =item integer
  996 
  997 to overload integer constants,
  998 
  999 =item float
 1000 
 1001 to overload floating point constants,
 1002 
 1003 =item binary
 1004 
 1005 to overload octal and hexadecimal constants,
 1006 
 1007 =item q
 1008 
 1009 to overload C<q>-quoted strings, constant pieces of C<qq>- and C<qx>-quoted
 1010 strings and here-documents,
 1011 
 1012 =item qr
 1013 
 1014 to overload constant pieces of regular expressions.
 1015 
 1016 =back
 1017 
 1018 The corresponding values are references to functions which take three arguments:
 1019 the first one is the I<initial> string form of the constant, the second one
 1020 is how Perl interprets this constant, the third one is how the constant is used.
 1021 Note that the initial string form does not
 1022 contain string delimiters, and has backslashes in backslash-delimiter
 1023 combinations stripped (thus the value of delimiter is not relevant for
 1024 processing of this string).  The return value of this function is how this
 1025 constant is going to be interpreted by Perl.  The third argument is undefined
 1026 unless for overloaded C<q>- and C<qr>- constants, it is C<q> in single-quote
 1027 context (comes from strings, regular expressions, and single-quote HERE
 1028 documents), it is C<tr> for arguments of C<tr>/C<y> operators,
 1029 it is C<s> for right-hand side of C<s>-operator, and it is C<qq> otherwise.
 1030 
 1031 Since an expression C<"ab$cd,,"> is just a shortcut for C<'ab' . $cd . ',,'>,
 1032 it is expected that overloaded constant strings are equipped with reasonable
 1033 overloaded catenation operator, otherwise absurd results will result.
 1034 Similarly, negative numbers are considered as negations of positive constants.
 1035 
 1036 Note that it is probably meaningless to call the functions overload::constant()
 1037 and overload::remove_constant() from anywhere but import() and unimport() methods.
 1038 From these methods they may be called as
 1039 
 1040     sub import {
 1041        shift;
 1042        return unless @_;
 1043        die "unknown import: @_" unless @_ == 1 and $_[0] eq ':constant';
 1044        overload::constant integer => sub {Math::BigInt->new(shift)};
 1045     }
 1046 
 1047 =head1 IMPLEMENTATION
 1048 
 1049 What follows is subject to change RSN.
 1050 
 1051 The table of methods for all operations is cached in magic for the
 1052 symbol table hash for the package.  The cache is invalidated during
 1053 processing of C<use overload>, C<no overload>, new function
 1054 definitions, and changes in @ISA.
 1055 
 1056 (Every SVish thing has a magic queue, and magic is an entry in that
 1057 queue.  This is how a single variable may participate in multiple
 1058 forms of magic simultaneously.  For instance, environment variables
 1059 regularly have two forms at once: their %ENV magic and their taint
 1060 magic.  However, the magic which implements overloading is applied to
 1061 the stashes, which are rarely used directly, thus should not slow down
 1062 Perl.)
 1063 
 1064 If a package uses overload, it carries a special flag.  This flag is also
 1065 set when new functions are defined or @ISA is modified.  There will be a
 1066 slight speed penalty on the very first operation thereafter that supports
 1067 overloading, while the overload tables are updated.  If there is no
 1068 overloading present, the flag is turned off.  Thus the only speed penalty
 1069 thereafter is the checking of this flag.
 1070 
 1071 It is expected that arguments to methods that are not explicitly supposed
 1072 to be changed are constant (but this is not enforced).
 1073 
 1074 =head1 COOKBOOK
 1075 
 1076 Please add examples to what follows!
 1077 
 1078 =head2 Two-face Scalars
 1079 
 1080 Put this in F<two_face.pm> in your Perl library directory:
 1081 
 1082   package two_face;     # Scalars with separate string and
 1083                                 # numeric values.
 1084   sub new { my $p = shift; bless [@_], $p }
 1085   use overload '""' => \&str, '0+' => \&num, fallback => 1;
 1086   sub num {shift->[1]}
 1087   sub str {shift->[0]}
 1088 
 1089 Use it as follows:
 1090 
 1091   require two_face;
 1092   my $seven = two_face->new("vii", 7);
 1093   printf "seven=$seven, seven=%d, eight=%d\n", $seven, $seven+1;
 1094   print "seven contains 'i'\n" if $seven =~ /i/;
 1095 
 1096 (The second line creates a scalar which has both a string value, and a
 1097 numeric value.)  This prints:
 1098 
 1099   seven=vii, seven=7, eight=8
 1100   seven contains 'i'
 1101 
 1102 =head2 Two-face References
 1103 
 1104 Suppose you want to create an object which is accessible as both an
 1105 array reference and a hash reference.
 1106 
 1107   package two_refs;
 1108   use overload '%{}' => \&gethash, '@{}' => sub { $ {shift()} };
 1109   sub new {
 1110     my $p = shift;
 1111     bless \ [@_], $p;
 1112   }
 1113   sub gethash {
 1114     my %h;
 1115     my $self = shift;
 1116     tie %h, ref $self, $self;
 1117     \%h;
 1118   }
 1119 
 1120   sub TIEHASH { my $p = shift; bless \ shift, $p }
 1121   my %fields;
 1122   my $i = 0;
 1123   $fields{$_} = $i++ foreach qw{zero one two three};
 1124   sub STORE {
 1125     my $self = ${shift()};
 1126     my $key = $fields{shift()};
 1127     defined $key or die "Out of band access";
 1128     $$self->[$key] = shift;
 1129   }
 1130   sub FETCH {
 1131     my $self = ${shift()};
 1132     my $key = $fields{shift()};
 1133     defined $key or die "Out of band access";
 1134     $$self->[$key];
 1135   }
 1136 
 1137 Now one can access an object using both the array and hash syntax:
 1138 
 1139   my $bar = two_refs->new(3,4,5,6);
 1140   $bar->[2] = 11;
 1141   $bar->{two} == 11 or die 'bad hash fetch';
 1142 
 1143 Note several important features of this example.  First of all, the
 1144 I<actual> type of $bar is a scalar reference, and we do not overload
 1145 the scalar dereference.  Thus we can get the I<actual> non-overloaded
 1146 contents of $bar by just using C<$$bar> (what we do in functions which
 1147 overload dereference).  Similarly, the object returned by the
 1148 TIEHASH() method is a scalar reference.
 1149 
 1150 Second, we create a new tied hash each time the hash syntax is used.
 1151 This allows us not to worry about a possibility of a reference loop,
 1152 which would lead to a memory leak.
 1153 
 1154 Both these problems can be cured.  Say, if we want to overload hash
 1155 dereference on a reference to an object which is I<implemented> as a
 1156 hash itself, the only problem one has to circumvent is how to access
 1157 this I<actual> hash (as opposed to the I<virtual> hash exhibited by the
 1158 overloaded dereference operator).  Here is one possible fetching routine:
 1159 
 1160   sub access_hash {
 1161     my ($self, $key) = (shift, shift);
 1162     my $class = ref $self;
 1163     bless $self, 'overload::dummy'; # Disable overloading of %{}
 1164     my $out = $self->{$key};
 1165     bless $self, $class;    # Restore overloading
 1166     $out;
 1167   }
 1168 
 1169 To remove creation of the tied hash on each access, one may an extra
 1170 level of indirection which allows a non-circular structure of references:
 1171 
 1172   package two_refs1;
 1173   use overload '%{}' => sub { ${shift()}->[1] },
 1174                '@{}' => sub { ${shift()}->[0] };
 1175   sub new {
 1176     my $p = shift;
 1177     my $a = [@_];
 1178     my %h;
 1179     tie %h, $p, $a;
 1180     bless \ [$a, \%h], $p;
 1181   }
 1182   sub gethash {
 1183     my %h;
 1184     my $self = shift;
 1185     tie %h, ref $self, $self;
 1186     \%h;
 1187   }
 1188 
 1189   sub TIEHASH { my $p = shift; bless \ shift, $p }
 1190   my %fields;
 1191   my $i = 0;
 1192   $fields{$_} = $i++ foreach qw{zero one two three};
 1193   sub STORE {
 1194     my $a = ${shift()};
 1195     my $key = $fields{shift()};
 1196     defined $key or die "Out of band access";
 1197     $a->[$key] = shift;
 1198   }
 1199   sub FETCH {
 1200     my $a = ${shift()};
 1201     my $key = $fields{shift()};
 1202     defined $key or die "Out of band access";
 1203     $a->[$key];
 1204   }
 1205 
 1206 Now if $baz is overloaded like this, then C<$baz> is a reference to a
 1207 reference to the intermediate array, which keeps a reference to an
 1208 actual array, and the access hash.  The tie()ing object for the access
 1209 hash is a reference to a reference to the actual array, so
 1210 
 1211 =over
 1212 
 1213 =item *
 1214 
 1215 There are no loops of references.
 1216 
 1217 =item *
 1218 
 1219 Both "objects" which are blessed into the class C<two_refs1> are
 1220 references to a reference to an array, thus references to a I<scalar>.
 1221 Thus the accessor expression C<$$foo-E<gt>[$ind]> involves no
 1222 overloaded operations.
 1223 
 1224 =back
 1225 
 1226 =head2 Symbolic Calculator
 1227 
 1228 Put this in F<symbolic.pm> in your Perl library directory:
 1229 
 1230   package symbolic;     # Primitive symbolic calculator
 1231   use overload nomethod => \&wrap;
 1232 
 1233   sub new { shift; bless ['n', @_] }
 1234   sub wrap {
 1235     my ($obj, $other, $inv, $meth) = @_;
 1236     ($obj, $other) = ($other, $obj) if $inv;
 1237     bless [$meth, $obj, $other];
 1238   }
 1239 
 1240 This module is very unusual as overloaded modules go: it does not
 1241 provide any usual overloaded operators, instead it provides an
 1242 implementation for L</C<nomethod>>.  In this example the C<nomethod>
 1243 subroutine returns an object which encapsulates operations done over
 1244 the objects: C<< symbolic->new(3) >> contains C<['n', 3]>, C<< 2 +
 1245 symbolic->new(3) >> contains C<['+', 2, ['n', 3]]>.
 1246 
 1247 Here is an example of the script which "calculates" the side of
 1248 circumscribed octagon using the above package:
 1249 
 1250   require symbolic;
 1251   my $iter = 1;         # 2**($iter+2) = 8
 1252   my $side = symbolic->new(1);
 1253   my $cnt = $iter;
 1254 
 1255   while ($cnt--) {
 1256     $side = (sqrt(1 + $side**2) - 1)/$side;
 1257   }
 1258   print "OK\n";
 1259 
 1260 The value of $side is
 1261 
 1262   ['/', ['-', ['sqrt', ['+', 1, ['**', ['n', 1], 2]],
 1263                    undef], 1], ['n', 1]]
 1264 
 1265 Note that while we obtained this value using a nice little script,
 1266 there is no simple way to I<use> this value.  In fact this value may
 1267 be inspected in debugger (see L<perldebug>), but only if
 1268 C<bareStringify> B<O>ption is set, and not via C<p> command.
 1269 
 1270 If one attempts to print this value, then the overloaded operator
 1271 C<""> will be called, which will call C<nomethod> operator.  The
 1272 result of this operator will be stringified again, but this result is
 1273 again of type C<symbolic>, which will lead to an infinite loop.
 1274 
 1275 Add a pretty-printer method to the module F<symbolic.pm>:
 1276 
 1277   sub pretty {
 1278     my ($meth, $a, $b) = @{+shift};
 1279     $a = 'u' unless defined $a;
 1280     $b = 'u' unless defined $b;
 1281     $a = $a->pretty if ref $a;
 1282     $b = $b->pretty if ref $b;
 1283     "[$meth $a $b]";
 1284   }
 1285 
 1286 Now one can finish the script by
 1287 
 1288   print "side = ", $side->pretty, "\n";
 1289 
 1290 The method C<pretty> is doing object-to-string conversion, so it
 1291 is natural to overload the operator C<""> using this method.  However,
 1292 inside such a method it is not necessary to pretty-print the
 1293 I<components> $a and $b of an object.  In the above subroutine
 1294 C<"[$meth $a $b]"> is a catenation of some strings and components $a
 1295 and $b.  If these components use overloading, the catenation operator
 1296 will look for an overloaded operator C<.>; if not present, it will
 1297 look for an overloaded operator C<"">.  Thus it is enough to use
 1298 
 1299   use overload nomethod => \&wrap, '""' => \&str;
 1300   sub str {
 1301     my ($meth, $a, $b) = @{+shift};
 1302     $a = 'u' unless defined $a;
 1303     $b = 'u' unless defined $b;
 1304     "[$meth $a $b]";
 1305   }
 1306 
 1307 Now one can change the last line of the script to
 1308 
 1309   print "side = $side\n";
 1310 
 1311 which outputs
 1312 
 1313   side = [/ [- [sqrt [+ 1 [** [n 1 u] 2]] u] 1] [n 1 u]]
 1314 
 1315 and one can inspect the value in debugger using all the possible
 1316 methods.
 1317 
 1318 Something is still amiss: consider the loop variable $cnt of the
 1319 script.  It was a number, not an object.  We cannot make this value of
 1320 type C<symbolic>, since then the loop will not terminate.
 1321 
 1322 Indeed, to terminate the cycle, the $cnt should become false.
 1323 However, the operator C<bool> for checking falsity is overloaded (this
 1324 time via overloaded C<"">), and returns a long string, thus any object
 1325 of type C<symbolic> is true.  To overcome this, we need a way to
 1326 compare an object to 0.  In fact, it is easier to write a numeric
 1327 conversion routine.
 1328 
 1329 Here is the text of F<symbolic.pm> with such a routine added (and
 1330 slightly modified str()):
 1331 
 1332   package symbolic;     # Primitive symbolic calculator
 1333   use overload
 1334     nomethod => \&wrap, '""' => \&str, '0+' => \&num;
 1335 
 1336   sub new { shift; bless ['n', @_] }
 1337   sub wrap {
 1338     my ($obj, $other, $inv, $meth) = @_;
 1339     ($obj, $other) = ($other, $obj) if $inv;
 1340     bless [$meth, $obj, $other];
 1341   }
 1342   sub str {
 1343     my ($meth, $a, $b) = @{+shift};
 1344     $a = 'u' unless defined $a;
 1345     if (defined $b) {
 1346       "[$meth $a $b]";
 1347     } else {
 1348       "[$meth $a]";
 1349     }
 1350   }
 1351   my %subr = ( n => sub {$_[0]},
 1352            sqrt => sub {sqrt $_[0]},
 1353            '-' => sub {shift() - shift()},
 1354            '+' => sub {shift() + shift()},
 1355            '/' => sub {shift() / shift()},
 1356            '*' => sub {shift() * shift()},
 1357            '**' => sub {shift() ** shift()},
 1358          );
 1359   sub num {
 1360     my ($meth, $a, $b) = @{+shift};
 1361     my $subr = $subr{$meth}
 1362       or die "Do not know how to ($meth) in symbolic";
 1363     $a = $a->num if ref $a eq __PACKAGE__;
 1364     $b = $b->num if ref $b eq __PACKAGE__;
 1365     $subr->($a,$b);
 1366   }
 1367 
 1368 All the work of numeric conversion is done in %subr and num().  Of
 1369 course, %subr is not complete, it contains only operators used in the
 1370 example below.  Here is the extra-credit question: why do we need an
 1371 explicit recursion in num()?  (Answer is at the end of this section.)
 1372 
 1373 Use this module like this:
 1374 
 1375   require symbolic;
 1376   my $iter = symbolic->new(2);  # 16-gon
 1377   my $side = symbolic->new(1);
 1378   my $cnt = $iter;
 1379 
 1380   while ($cnt) {
 1381     $cnt = $cnt - 1;        # Mutator '--' not implemented
 1382     $side = (sqrt(1 + $side**2) - 1)/$side;
 1383   }
 1384   printf "%s=%f\n", $side, $side;
 1385   printf "pi=%f\n", $side*(2**($iter+2));
 1386 
 1387 It prints (without so many line breaks)
 1388 
 1389   [/ [- [sqrt [+ 1 [** [/ [- [sqrt [+ 1 [** [n 1] 2]]] 1]
 1390               [n 1]] 2]]] 1]
 1391      [/ [- [sqrt [+ 1 [** [n 1] 2]]] 1] [n 1]]]=0.198912
 1392   pi=3.182598
 1393 
 1394 The above module is very primitive.  It does not implement
 1395 mutator methods (C<++>, C<-=> and so on), does not do deep copying
 1396 (not required without mutators!), and implements only those arithmetic
 1397 operations which are used in the example.
 1398 
 1399 To implement most arithmetic operations is easy; one should just use
 1400 the tables of operations, and change the code which fills %subr to
 1401 
 1402   my %subr = ( 'n' => sub {$_[0]} );
 1403   foreach my $op (split " ", $overload::ops{with_assign}) {
 1404     $subr{$op} = $subr{"$op="} = eval "sub {shift() $op shift()}";
 1405   }
 1406   my @bins = qw(binary 3way_comparison num_comparison str_comparison);
 1407   foreach my $op (split " ", "@overload::ops{ @bins }") {
 1408     $subr{$op} = eval "sub {shift() $op shift()}";
 1409   }
 1410   foreach my $op (split " ", "@overload::ops{qw(unary func)}") {
 1411     print "defining '$op'\n";
 1412     $subr{$op} = eval "sub {$op shift()}";
 1413   }
 1414 
 1415 Since subroutines implementing assignment operators are not required
 1416 to modify their operands (see L<Overloadable Operations> above),
 1417 we do not need anything special to make C<+=> and friends work,
 1418 besides adding these operators to %subr and defining a copy
 1419 constructor (needed since Perl has no way to know that the
 1420 implementation of C<'+='> does not mutate the argument -
 1421 see L<Copy Constructor>).
 1422 
 1423 To implement a copy constructor, add C<< '=' => \&cpy >> to C<use overload>
 1424 line, and code (this code assumes that mutators change things one level
 1425 deep only, so recursive copying is not needed):
 1426 
 1427   sub cpy {
 1428     my $self = shift;
 1429     bless [@$self], ref $self;
 1430   }
 1431 
 1432 To make C<++> and C<--> work, we need to implement actual mutators,
 1433 either directly, or in C<nomethod>.  We continue to do things inside
 1434 C<nomethod>, thus add
 1435 
 1436     if ($meth eq '++' or $meth eq '--') {
 1437       @$obj = ($meth, (bless [@$obj]), 1); # Avoid circular reference
 1438       return $obj;
 1439     }
 1440 
 1441 after the first line of wrap().  This is not a most effective
 1442 implementation, one may consider
 1443 
 1444   sub inc { $_[0] = bless ['++', shift, 1]; }
 1445 
 1446 instead.
 1447 
 1448 As a final remark, note that one can fill %subr by
 1449 
 1450   my %subr = ( 'n' => sub {$_[0]} );
 1451   foreach my $op (split " ", $overload::ops{with_assign}) {
 1452     $subr{$op} = $subr{"$op="} = eval "sub {shift() $op shift()}";
 1453   }
 1454   my @bins = qw(binary 3way_comparison num_comparison str_comparison);
 1455   foreach my $op (split " ", "@overload::ops{ @bins }") {
 1456     $subr{$op} = eval "sub {shift() $op shift()}";
 1457   }
 1458   foreach my $op (split " ", "@overload::ops{qw(unary func)}") {
 1459     $subr{$op} = eval "sub {$op shift()}";
 1460   }
 1461   $subr{'++'} = $subr{'+'};
 1462   $subr{'--'} = $subr{'-'};
 1463 
 1464 This finishes implementation of a primitive symbolic calculator in
 1465 50 lines of Perl code.  Since the numeric values of subexpressions
 1466 are not cached, the calculator is very slow.
 1467 
 1468 Here is the answer for the exercise: In the case of str(), we need no
 1469 explicit recursion since the overloaded C<.>-operator will fall back
 1470 to an existing overloaded operator C<"">.  Overloaded arithmetic
 1471 operators I<do not> fall back to numeric conversion if C<fallback> is
 1472 not explicitly requested.  Thus without an explicit recursion num()
 1473 would convert C<['+', $a, $b]> to C<$a + $b>, which would just rebuild
 1474 the argument of num().
 1475 
 1476 If you wonder why defaults for conversion are different for str() and
 1477 num(), note how easy it was to write the symbolic calculator.  This
 1478 simplicity is due to an appropriate choice of defaults.  One extra
 1479 note: due to the explicit recursion num() is more fragile than sym():
 1480 we need to explicitly check for the type of $a and $b.  If components
 1481 $a and $b happen to be of some related type, this may lead to problems.
 1482 
 1483 =head2 I<Really> Symbolic Calculator
 1484 
 1485 One may wonder why we call the above calculator symbolic.  The reason
 1486 is that the actual calculation of the value of expression is postponed
 1487 until the value is I<used>.
 1488 
 1489 To see it in action, add a method
 1490 
 1491   sub STORE {
 1492     my $obj = shift;
 1493     $#$obj = 1;
 1494     @$obj->[0,1] = ('=', shift);
 1495   }
 1496 
 1497 to the package C<symbolic>.  After this change one can do
 1498 
 1499   my $a = symbolic->new(3);
 1500   my $b = symbolic->new(4);
 1501   my $c = sqrt($a**2 + $b**2);
 1502 
 1503 and the numeric value of $c becomes 5.  However, after calling
 1504 
 1505   $a->STORE(12);  $b->STORE(5);
 1506 
 1507 the numeric value of $c becomes 13.  There is no doubt now that the module
 1508 symbolic provides a I<symbolic> calculator indeed.
 1509 
 1510 To hide the rough edges under the hood, provide a tie()d interface to the
 1511 package C<symbolic>.  Add methods
 1512 
 1513   sub TIESCALAR { my $pack = shift; $pack->new(@_) }
 1514   sub FETCH { shift }
 1515   sub nop {  }      # Around a bug
 1516 
 1517 (the bug, fixed in Perl 5.14, is described in L<"BUGS">).  One can use this
 1518 new interface as
 1519 
 1520   tie $a, 'symbolic', 3;
 1521   tie $b, 'symbolic', 4;
 1522   $a->nop;  $b->nop;    # Around a bug
 1523 
 1524   my $c = sqrt($a**2 + $b**2);
 1525 
 1526 Now numeric value of $c is 5.  After C<$a = 12; $b = 5> the numeric value
 1527 of $c becomes 13.  To insulate the user of the module add a method
 1528 
 1529   sub vars { my $p = shift; tie($_, $p), $_->nop foreach @_; }
 1530 
 1531 Now
 1532 
 1533   my ($a, $b);
 1534   symbolic->vars($a, $b);
 1535   my $c = sqrt($a**2 + $b**2);
 1536 
 1537   $a = 3; $b = 4;
 1538   printf "c5  %s=%f\n", $c, $c;
 1539 
 1540   $a = 12; $b = 5;
 1541   printf "c13  %s=%f\n", $c, $c;
 1542 
 1543 shows that the numeric value of $c follows changes to the values of $a
 1544 and $b.
 1545 
 1546 =head1 AUTHOR
 1547 
 1548 Ilya Zakharevich E<lt>F<ilya@math.mps.ohio-state.edu>E<gt>.
 1549 
 1550 =head1 SEE ALSO
 1551 
 1552 The C<overloading> pragma can be used to enable or disable overloaded
 1553 operations within a lexical scope - see L<overloading>.
 1554 
 1555 =head1 DIAGNOSTICS
 1556 
 1557 When Perl is run with the B<-Do> switch or its equivalent, overloading
 1558 induces diagnostic messages.
 1559 
 1560 Using the C<m> command of Perl debugger (see L<perldebug>) one can
 1561 deduce which operations are overloaded (and which ancestor triggers
 1562 this overloading).  Say, if C<eq> is overloaded, then the method C<(eq>
 1563 is shown by debugger.  The method C<()> corresponds to the C<fallback>
 1564 key (in fact a presence of this method shows that this package has
 1565 overloading enabled, and it is what is used by the C<Overloaded>
 1566 function of module C<overload>).
 1567 
 1568 The module might issue the following warnings:
 1569 
 1570 =over 4
 1571 
 1572 =item Odd number of arguments for overload::constant
 1573 
 1574 (W) The call to overload::constant contained an odd number of arguments.
 1575 The arguments should come in pairs.
 1576 
 1577 =item '%s' is not an overloadable type
 1578 
 1579 (W) You tried to overload a constant type the overload package is unaware of.
 1580 
 1581 =item '%s' is not a code reference
 1582 
 1583 (W) The second (fourth, sixth, ...) argument of overload::constant needs
 1584 to be a code reference.  Either an anonymous subroutine, or a reference
 1585 to a subroutine.
 1586 
 1587 =item overload arg '%s' is invalid
 1588 
 1589 (W) C<use overload> was passed an argument it did not
 1590 recognize.  Did you mistype an operator?
 1591 
 1592 =back
 1593 
 1594 =head1 BUGS AND PITFALLS
 1595 
 1596 =over
 1597 
 1598 =item *
 1599 
 1600 A pitfall when fallback is TRUE and Perl resorts to a built-in
 1601 implementation of an operator is that some operators have more
 1602 than one semantic, for example C<|>:
 1603 
 1604         use overload '0+' => sub { $_[0]->{n}; },
 1605             fallback => 1;
 1606         my $x = bless { n => 4 }, "main";
 1607         my $y = bless { n => 8 }, "main";
 1608         print $x | $y, "\n";
 1609 
 1610 You might expect this to output "12".
 1611 In fact, it prints "<": the ASCII result of treating "|"
 1612 as a bitwise string operator - that is, the result of treating
 1613 the operands as the strings "4" and "8" rather than numbers.
 1614 The fact that numify (C<0+>) is implemented but stringify
 1615 (C<"">) isn't makes no difference since the latter is simply
 1616 autogenerated from the former.
 1617 
 1618 The only way to change this is to provide your own subroutine
 1619 for C<'|'>.
 1620 
 1621 =item *
 1622 
 1623 Magic autogeneration increases the potential for inadvertently
 1624 creating self-referential structures.
 1625 Currently Perl will not free self-referential
 1626 structures until cycles are explicitly broken.
 1627 For example,
 1628 
 1629     use overload '+' => 'add';
 1630     sub add { bless [ \$_[0], \$_[1] ] };
 1631 
 1632 is asking for trouble, since
 1633 
 1634     $obj += $y;
 1635 
 1636 will effectively become
 1637 
 1638     $obj = add($obj, $y, undef);
 1639 
 1640 with the same result as
 1641 
 1642     $obj = [\$obj, \$foo];
 1643 
 1644 Even if no I<explicit> assignment-variants of operators are present in
 1645 the script, they may be generated by the optimizer.
 1646 For example,
 1647 
 1648     "obj = $obj\n"
 1649 
 1650 may be optimized to
 1651 
 1652     my $tmp = 'obj = ' . $obj;  $tmp .= "\n";
 1653 
 1654 =item *
 1655 
 1656 The symbol table is filled with names looking like line-noise.
 1657 
 1658 =item *
 1659 
 1660 This bug was fixed in Perl 5.18, but may still trip you up if you are using
 1661 older versions:
 1662 
 1663 For the purpose of inheritance every overloaded package behaves as if
 1664 C<fallback> is present (possibly undefined).  This may create
 1665 interesting effects if some package is not overloaded, but inherits
 1666 from two overloaded packages.
 1667 
 1668 =item *
 1669 
 1670 Before Perl 5.14, the relation between overloading and tie()ing was broken.
 1671 Overloading was triggered or not based on the I<previous> class of the
 1672 tie()d variable.
 1673 
 1674 This happened because the presence of overloading was checked
 1675 too early, before any tie()d access was attempted.  If the
 1676 class of the value FETCH()ed from the tied variable does not
 1677 change, a simple workaround for code that is to run on older Perl
 1678 versions is to access the value (via C<() = $foo> or some such)
 1679 immediately after tie()ing, so that after this call the I<previous> class
 1680 coincides with the current one.
 1681 
 1682 =item *
 1683 
 1684 Barewords are not covered by overloaded string constants.
 1685 
 1686 =item *
 1687 
 1688 The range operator C<..> cannot be overloaded.
 1689 
 1690 =back
 1691 
 1692 =cut
 1693