home *** CD-ROM | disk | FTP | other *** search
/ BURKS 2 / BURKS_AUG97.ISO / SLAKWARE / D12 / PERL1.TGZ / perl1.tar / usr / lib / perl5 / overload.pm < prev    next >
Text File  |  1996-06-28  |  14KB  |  490 lines
  1. package overload;
  2.  
  3. sub OVERLOAD {
  4.   $package = shift;
  5.   my %arg = @_;
  6.   my $hash = \%{$package . "::OVERLOAD"};
  7.   for (keys %arg) {
  8.     $hash->{$_} = $arg{$_};
  9.   }
  10. }
  11.  
  12. sub import {
  13.   $package = (caller())[0];
  14.   # *{$package . "::OVERLOAD"} = \&OVERLOAD;
  15.   shift;
  16.   $package->overload::OVERLOAD(@_);
  17. }
  18.  
  19. sub unimport {
  20.   $package = (caller())[0];
  21.   my $hash = \%{$package . "::OVERLOAD"};
  22.   shift;
  23.   for (@_) {
  24.     delete $hash->{$_};
  25.   }
  26. }
  27.  
  28. sub Overloaded {
  29.   defined ($package = ref $_[0]) and defined %{$package . "::OVERLOAD"};
  30. }
  31.  
  32. sub OverloadedStringify {
  33.   defined ($package = ref $_[0]) and 
  34.     defined %{$package . "::OVERLOAD"} and 
  35.       exists $ {$package . "::OVERLOAD"}{'""'} and
  36.     defined &{$ {$package . "::OVERLOAD"}{'""'}};
  37. }
  38.  
  39. sub Method {
  40.   defined ($package = ref $_[0]) and 
  41.     defined %{$package . "::OVERLOAD"} and 
  42.       $ {$package . "::OVERLOAD"}{$_[1]};
  43. }
  44.  
  45. sub AddrRef {
  46.   $package = ref $_[0];
  47.   bless $_[0], Overload::Fake;    # Non-overloaded package
  48.   my $str = "$_[0]";
  49.   bless $_[0], $package;    # Back
  50.   $str;
  51. }
  52.  
  53. sub StrVal {
  54.   (OverloadedStringify) ?
  55.     (AddrRef) :
  56.     "$_[0]";
  57. }
  58.  
  59. 1;
  60.  
  61. __END__
  62.  
  63. =head1 NAME 
  64.  
  65. overload - Package for overloading perl operations
  66.  
  67. =head1 SYNOPSIS
  68.  
  69.     package SomeThing;
  70.  
  71.     use overload 
  72.     '+' => \&myadd,
  73.     '-' => \&mysub;
  74.     # etc
  75.     ...
  76.  
  77.     package main;
  78.     $a = new SomeThing 57;
  79.     $b=5+$a;
  80.     ...
  81.     if (overload::Overloaded $b) {...}
  82.     ...
  83.     $strval = overload::StrVal $b;
  84.  
  85. =head1 CAVEAT SCRIPTOR
  86.  
  87. Overloading of operators is a subject not to be taken lightly.
  88. Neither its precise implementation, syntax, nor semantics are
  89. 100% endorsed by Larry Wall.  So any of these may be changed 
  90. at some point in the future.
  91.  
  92. =head1 DESCRIPTION
  93.  
  94. =head2 Declaration of overloaded functions
  95.  
  96. The compilation directive
  97.  
  98.     package Number;
  99.     use overload
  100.     "+" => \&add, 
  101.     "*=" => "muas";
  102.  
  103. declares function Number::add() for addition, and method muas() in
  104. the "class" C<Number> (or one of its base classes)
  105. for the assignment form C<*=> of multiplication.  
  106.  
  107. Arguments of this directive come in (key, value) pairs.  Legal values
  108. are values legal inside a C<&{ ... }> call, so the name of a subroutine,
  109. a reference to a subroutine, or an anonymous subroutine will all work.
  110. Legal keys are listed below.
  111.  
  112. The subroutine C<add> will be called to execute C<$a+$b> if $a
  113. is a reference to an object blessed into the package C<Number>, or if $a is
  114. not an object from a package with defined mathemagic addition, but $b is a
  115. reference to a C<Number>.  It can also be called in other situations, like
  116. C<$a+=7>, or C<$a++>.  See L<MAGIC AUTOGENERATION>.  (Mathemagical
  117. methods refer to methods triggered by an overloaded mathematical
  118. operator.)
  119.  
  120. =head2 Calling Conventions for Binary Operations
  121.  
  122. The functions specified in the C<use overload ...> directive are called
  123. with three (in one particular case with four, see L<Last Resort>)
  124. arguments.  If the corresponding operation is binary, then the first
  125. two arguments are the two arguments of the operation.  However, due to
  126. general object calling conventions, the first argument should always be
  127. an object in the package, so in the situation of C<7+$a>, the
  128. order of the arguments is interchanged.  It probably does not matter
  129. when implementing the addition method, but whether the arguments
  130. are reversed is vital to the subtraction method.  The method can
  131. query this information by examining the third argument, which can take
  132. three different values:
  133.  
  134. =over 7
  135.  
  136. =item FALSE
  137.  
  138. the order of arguments is as in the current operation.
  139.  
  140. =item TRUE
  141.  
  142. the arguments are reversed.
  143.  
  144. =item C<undef>
  145.  
  146. the current operation is an assignment variant (as in
  147. C<$a+=7>), but the usual function is called instead.  This additional
  148. information can be used to generate some optimizations.
  149.  
  150. =back
  151.  
  152. =head2 Calling Conventions for Unary Operations
  153.  
  154. Unary operation are considered binary operations with the second
  155. argument being C<undef>.  Thus the functions that overloads C<{"++"}>
  156. is called with arguments C<($a,undef,'')> when $a++ is executed.
  157.  
  158. =head2 Overloadable Operations
  159.  
  160. The following symbols can be specified in C<use overload>:
  161.  
  162. =over 5
  163.  
  164. =item * I<Arithmetic operations>
  165.  
  166.     "+", "+=", "-", "-=", "*", "*=", "/", "/=", "%", "%=",
  167.     "**", "**=", "<<", "<<=", ">>", ">>=", "x", "x=", ".", ".=",
  168.  
  169. For these operations a substituted non-assignment variant can be called if
  170. the assignment variant is not available.  Methods for operations "C<+>",
  171. "C<->", "C<+=>", and "C<-=>" can be called to automatically generate
  172. increment and decrement methods.  The operation "C<->" can be used to
  173. autogenerate missing methods for unary minus or C<abs>.
  174.  
  175. =item * I<Comparison operations>
  176.  
  177.     "<",  "<=", ">",  ">=", "==", "!=", "<=>",
  178.     "lt", "le", "gt", "ge", "eq", "ne", "cmp",
  179.  
  180. If the corresponding "spaceship" variant is available, it can be
  181. used to substitute for the missing operation.  During C<sort>ing
  182. arrays, C<cmp> is used to compare values subject to C<use overload>.
  183.  
  184. =item * I<Bit operations>
  185.  
  186.     "&", "^", "|", "neg", "!", "~",
  187.  
  188. "C<neg>" stands for unary minus.  If the method for C<neg> is not
  189. specified, it can be autogenerated using the method for subtraction.
  190.  
  191. =item * I<Increment and decrement>
  192.  
  193.     "++", "--",
  194.  
  195. If undefined, addition and subtraction methods can be
  196. used instead.  These operations are called both in prefix and
  197. postfix form.
  198.  
  199. =item * I<Transcendental functions>
  200.  
  201.     "atan2", "cos", "sin", "exp", "abs", "log", "sqrt",
  202.  
  203. If C<abs> is unavailable, it can be autogenerated using methods
  204. for "<" or "<=>" combined with either unary minus or subtraction.
  205.  
  206. =item * I<Boolean, string and numeric conversion>
  207.  
  208.     "bool", "\"\"", "0+",
  209.  
  210. If one or two of these operations are unavailable, the remaining ones can
  211. be used instead.  C<bool> is used in the flow control operators
  212. (like C<while>) and for the ternary "C<?:>" operation.  These functions can
  213. return any arbitrary Perl value.  If the corresponding operation for this value
  214. is overloaded too, that operation will be called again with this value.
  215.  
  216. =item * I<Special>
  217.  
  218.     "nomethod", "fallback", "=",
  219.  
  220. see L<SPECIAL SYMBOLS FOR C<use overload>>.
  221.  
  222. =back
  223.  
  224. See L<"Fallback"> for an explanation of when a missing method can be autogenerated.
  225.  
  226. =head1 SPECIAL SYMBOLS FOR C<use overload>
  227.  
  228. Three keys are recognized by Perl that are not covered by the above
  229. description.
  230.  
  231. =head2  Last Resort
  232.  
  233. C<"nomethod"> should be followed by a reference to a function of four
  234. parameters.  If defined, it is called when the overloading mechanism
  235. cannot find a method for some operation.  The first three arguments of
  236. this function coincide with the arguments for the corresponding method if
  237. it were found, the fourth argument is the symbol
  238. corresponding to the missing method.  If several methods are tried,
  239. the last one is used.  Say, C<1-$a> can be equivalent to
  240.  
  241.     &nomethodMethod($a,1,1,"-")
  242.  
  243. if the pair C<"nomethod" =E<gt> "nomethodMethod"> was specified in the
  244. C<use overload> directive.
  245.  
  246. If some operation cannot be resolved, and there is no function
  247. assigned to C<"nomethod">, then an exception will be raised via die()--
  248. unless C<"fallback"> was specified as a key in C<use overload> directive.
  249.  
  250. =head2 Fallback 
  251.  
  252. The key C<"fallback"> governs what to do if a method for a particular
  253. operation is not found.  Three different cases are possible depending on
  254. the value of C<"fallback">:
  255.  
  256. =over 16
  257.  
  258. =item * C<undef>
  259.  
  260. Perl tries to use a
  261. substituted method (see L<MAGIC AUTOGENERATION>).  If this fails, it
  262. then tries to calls C<"nomethod"> value; if missing, an exception
  263. will be raised.
  264.  
  265. =item * TRUE
  266.  
  267. The same as for the C<undef> value, but no exception is raised.  Instead,
  268. it silently reverts to what it would have done were there no C<use overload>
  269. present.
  270.  
  271. =item * defined, but FALSE
  272.  
  273. No autogeneration is tried.  Perl tries to call
  274. C<"nomethod"> value, and if this is missing, raises an exception. 
  275.  
  276. =back
  277.  
  278. =head2 Copy Constructor
  279.  
  280. The value for C<"="> is a reference to a function with three
  281. arguments, i.e., it looks like the other values in C<use
  282. overload>. However, it does not overload the Perl assignment
  283. operator. This would go against Camel hair.
  284.  
  285. This operation is called in the situations when a mutator is applied
  286. to a ref