pod/perlovl.pod

   1 =head1 NAME
   2
   3 perlovl - perl overloading semantics
   4
   5 =head1 SYNOPSIS
   6
   7     package SomeThing;
   8
   9     %OVERLOAD = (
  10         '+' => \&myadd,
  11         '-' => \&mysub,
  12         # etc
  13     );
  14     ...
  15
  16     package main;
  17     $a = new SomeThing 57;
  18     $b=5+$a;
  19
  20 =head1 CAVEAT SCRIPTOR
  21
  22 Overloading of operators is a subject not to be taken lightly.
  23 Neither its precise implementation, syntax, nor semantics are
  24 100% endorsed by Larry Wall.  So any of these may be changed
  25 at some point in the future.
  26
  27 =head1 DESCRIPTION
  28
  29 =head2 Declaration of overloaded functions
  30
  31     package Number;
  32     %OVERLOAD = (
  33         "+" => \&add,
  34         "*=" => "muas"
  35     );
  36
  37 declares function Number::add() for addition, and method muas() in
  38 the "class" C<Number> (or one of its base classes)
  39 for the assignment form C<*=> of multiplication.  Legal values of this
  40 hash array are values legal inside C<&{ ... }> call, so the name of a
  41 subroutine, a reference to a subroutine, or an anonymous subroutine
  42 will all work.
  43
  44 The subroutine C<$OVERLOAD{"+"}> will be called to execute C<$a+$b> if $a
  45 is a reference to an object blessed into the package C<Number>, or $a is
  46 not an object from a package with defined mathemagic addition, but $b is a
  47 reference to a C<Number>.  It can be called also in other situations, like
  48 C<$a+=7>, or C<$a++>.  See L<MAGIC AUTOGENERATION>.  (Mathemagical
  49 methods refer to methods triggered by an overloaded mathematical
  50 operator.)
  51
  52 =head2 Calling Conventions for Binary Operations
  53
  54 The functions in C<values %OVERLOAD> are called with three (in one
  55 particular case with four, see L<Last Resort>) arguments.  If the
  56 corresponding operation is binary, then the first two arguments are the
  57 two arguments of the operation.  However, due to general object calling
  58 conventions, the first argument should be always an object in the package,
  59 so in the situation of C<7+$a>, the order of arguments is interchanged.
  60 Most probably it does not matter for implementation of the addition
  61 method, but whether the arguments are reversed is vital for the
  62 subtraction method.  The subroutine can query this information by
  63 examining the third argument, which can take three different values:
  64
  65 =over 7
  66
  67 =item FALSE
  68
  69 the order of arguments is as in the current operation.
  70
  71 =item TRUE
  72
  73 the arguments are reversed.
  74
  75 =item C<undef>
  76
  77 the current operation is an assignment variant (as in
  78 C<$a+=7>), but the usual function is called instead.  This additional
  79 information can be used to generate some optimizations.
  80
  81 =back
  82
  83 =head2 Calling Conventions for Unary Operations
  84
  85 Unary operation are considered binary operations with the second
  86 argument being C<undef>.  Thus C<$OVERLOAD{"++"}> is called with
  87 arguments C<($a,undef,'')> when $a++ is executed.
  88
  89 =head2 Overloadable Operations
  90
  91 The following keys of %OVERLOAD are recognized:
  92
  93 =over 5
  94
  95 =item * I<Arithmetic operations>
  96
  97     "+", "+=", "-", "-=", "*", "*=", "/", "/=", "%", "%=",
  98     "**", "**=", "<<", "<<=", ">>", ">>=", "x", "x=", ".", ".=",
  99
 100 For these operations a substituted non-assignment variant can be called if
 101 the assignment variant is not available.  Methods for operations "C<+>",
 102 "C<->", "C<+=>", and "C<-=>" can be called to automatically generate
 103 increment and decrement methods.  The operations "C<->" can be used to
 104 autogenerate missing methods for unary minus or C<abs>.
 105
 106 =item * I<Comparison operations>
 107
 108     "<",  "<=", ">",  ">=", "==", "!=", "<=>",
 109     "lt", "le", "gt", "ge", "eq", "ne", "cmp",
 110
 111 If the corresponding "spaceship" variant is available, it can be
 112 used to substitute for the missing operation.  During C<sort>ing
 113 arrays, C<cmp> is used to compare values subject to %OVERLOAD.
 114
 115 =item * I<Bit operations>
 116
 117     "&", "^", "|", "neg", "!", "~",
 118
 119 "C<neg>" stands for unary minus.  If the method for C<neg> is not
 120 specified, it can be autogenerated using on the method for subtraction.
 121
 122 =item * I<Increment and decrement>
 123
 124     "++", "--",
 125
 126 If undefined, addition and subtraction methods can be
 127 used instead.  These operations are called both in prefix and
 128 postfix form.
 129
 130 =item * I<Transcendental functions>
 131
 132     "atan2", "cos", "sin", "exp", "abs", "log", "sqrt",
 133
 134 If C<abs> is unavailable, it can be autogenerated using methods
 135 for "<" or "<=>" combined with either unary minus or subtraction.
 136
 137 =item * I<Boolean, string and numeric conversion>
 138
 139     "bool", "\"\"", "0+",
 140
 141 If one or two of these operations are unavailable, the remaining ones can
 142 be used instead.  C<bool> is used in the flow control operators
 143 (like C<while>) and for the ternary "C<?:>" operation.  These functions can
 144 return any arbitrary Perl value.  If the corresponding operation for this value
 145 is overloaded too, that operation will be called again with this value.
 146
 147 =item * I<Special>
 148
 149     "nomethod", "fallback", "=",
 150
 151 see L<SPECIAL KEYS OF %OVERLOAD>.
 152
 153 =back
 154
 155 See L<"Fallback"> for an explanation of when a missing method can be autogenerated.
 156
 157 =head1 SPECIAL KEYS OF %OVERLOAD
 158
 159 Three keys are recognized by Perl that are not covered by the above
 160 description.
 161
 162 =head2  Last Resort
 163
 164 C<$OVERLOAD{"nomethod"}> is a reference to a function of four parameters.
 165 If defined, it is called when the overloading mechanism cannot find a
 166 method for some operation.  The first three arguments of this function
 167 coincide with arguments for the corresponding method if it were found, the
 168 fourth argument is the key of %OVERLOAD corresponding to the missing
 169 method.  If several methods are tried, the last one is used.  Say, C<1-$a>
 170 can be equivalent to
 171
 172         &{ $Pack::OVERLOAD{"nomethod"} }($a,1,1,"-").
 173
 174 If some operation cannot be resolved, and there is no
 175 C<$OVERLOAD{"nomethod"}>, then an exception will be raised
 176 via die() -- unless C<$OVERLOAD{"fallback"}> is true.
 177
 178 =head2 Fallback
 179
 180 C<$OVERLOAD{"fallback"}> governs what to do if a method for a particular
 181 operation is not found.  Three different cases are possible depending on
 182 value of C<$OVERLOAD{"fallback"}>:
 183
 184 =over 16
 185
 186 =item * C<undef>
 187
 188 Perl tries to use a
 189 substituted method (see L<MAGIC AUTOGENERATION>).  If this fails, it
 190 then tries to calls C<$OVERLOAD{"nomethod"}>; if missing, an exception
 191 will be raised.
 192
 193 =item * TRUE
 194
 195 The same as for the C<undef> value, but no exception is raised.  Instead,
 196 it silently reverts to what it would have done were there no %OVERLOAD is
 197 present.
 198
 199 =item * defined, but FALSE
 200
 201 No autogeneration is tried.  Perl tries to call
 202 C<$OVERLOAD{"nomethod"}>, and if this is missing, raises an exception.
 203
 204 =back
 205
 206 =head2 Copy Constructor
 207
 208 C<$OVERLOAD{"="}> is a reference to a function with three arguments,
 209 i.e., it looks like a usual value of %OVERLOAD.  What is special about
 210 this subroutine is that it should not return a blessed reference into
 211 a package (as most other methods are expected to), but rather a freshly made
 212 copy of its dereferenced argument (see L<"BUGS">, though).  This operation
 213 is called in the situations when a mutator is applied to a reference
 214 that shares its object with some other reference, such as
 215
 216         $a=$b;
 217         $a++;
 218
 219 To make this change to $a and not to change $b, a freshly made copy of
 220 C<$$a> is made, and $a is assigned a reference to this object.  This
 221 operation is executed during C<$a++>, (so before this C<$$a> coincides
 222 with C<$$b>), and only if C<++> is expressed via  C<$OPERATOR{'++'}> or
 223 C<$OPERATOR{'+='}>.  Note that if this operation is expressed via 'C<+>',
 224 i.e., as
 225
 226         $a=$b;
 227         $a=$a+1;
 228
 229 then C<$$a> and C<$$b> do not appear as lvalues.
 230
 231 If the copy constructor is required during execution of some mutator, but
 232 C<$OPERATOR{'='}> is missing, it can be autogenerated as a string
 233 copy if an object of
 234 the package is a plain scalar.
 235
 236 =head1 MAGIC AUTOGENERATION
 237
 238 If a method for an operation is not found, and C<$OVERLOAD{"fallback"}> is
 239 TRUE or undefined, Perl tries to to autogenerate a substitute method for
 240 the missing operation based on defined operations.  Autogenerated method
 241 substitutions are possible for the following operations:
 242
 243 =over 16
 244
 245 =item I<Assignment forms of arithmetic operations>
 246
 247 C<$a=+$b> can use the C<$OVERLOAD{"+"}> method if C<$OVERLOAD{"+="}>
 248 is not defined.
 249
 250 =item I<Conversion operations>
 251
 252 String, numeric, and boolean conversion are calculated in terms of one
 253 another if not all of them are defined.
 254
 255 =item I<Increment and decrement>
 256
 257 The C<++$a> operation can be expressed in terms of C<$a+=1> or C<$a+1>,
 258 and C<$a--> in terms of C<$a-=1> and C<$a-1>.
 259
 260 =item C<abs($a)>
 261
 262 can be expressed in terms of C<$aE<lt>0> and C<-$a> (or C<0-$a>).
 263
 264 =item I<Unary minus>
 265
 266 can be expressed in terms of subtraction.
 267
 268 =item I<Concatenation>
 269
 270 can be expressed in terms of string conversion.
 271
 272 =item I<Comparison operations>
 273
 274 can be expressed in terms of its "spaceship" counterpart: either
 275 C<E<lt>=E<gt>> or C<cmp>:
 276
 277     <, >, <=, >=, ==, !=        in terms of <=>
 278     lt, gt, le, ge, eq, ne      in terms of cmp
 279
 280 =item I<Copy operator>
 281
 282 can be expressed in terms of assignment to the dereferenced value, if this
 283 value is scalar but not a reference.
 284
 285 =back
 286
 287 =head1 WARNING
 288
 289 The restriction for the comparison operation is that even if, for example,
 290 `C<cmp>' should return a blessed reference, the autogenerated `C<lt>'
 291 function will produce only a standard logical value based on the
 292 numerical value of the result of `C<cmp>'.  In particular, a working
 293 numeric conversion is needed in this case (possibly expressed in terms of
 294 other conversions).
 295
 296 Similarly, C<.=>  and C<x=> operators lose their mathemagical properties
 297 if the string conversion substitution is applied.
 298
 299 When you chop() a mathemagical object, it becomes promoted to a string
 300 first, and its mathemagical qualities is lost.  The same can happen with other
 301 operations as well.
 302
 303 =head1 IMPLEMENTATION
 304
 305 The table of methods for all operations is cached as a magic for the
 306 symbol table hash of the package.  It is rechecked for changes of
 307 %OVERLOAD and @ISA only during C<bless>ing; so if it is changed
 308 dynamically, you'll need an additional fake C<bless>ing to update the
 309 table.
 310
 311 (Every SVish thing has a magic queue, and a magic is an entry in that queue.
 312 This is how a single variable may participate in multiple forms of magic
 313 simultaneously.  For instance, environment variables regularly have two
 314 forms at once: their %ENV magic and their taint magic.)
 315
 316 If an object belongs to a package with %OVERLOAD, it carries a special
 317 flag.  Thus the only speed penalty during arithmetic operations without
 318 overload is the check of this flag.
 319
 320 In fact, if no %OVERLOAD is ever accessed, there is almost no overhead for
 321 overloadable operations, so most programs should not suffer measurable
 322 performance penalties.  Considerable effort was made minimize overhead
 323 when %OVERLOAD is accessed and the current operation is overloadable but
 324 the arguments in question do not belong to packages with %OVERLOAD.  When
 325 in doubt, test your speed with %OVERLOAD and without it.  So far there
 326 have been no reports of substantial speed degradation if Perl is compiled
 327 with optimization turned on.
 328
 329 There is no size penalty for data if there is no %OVERLOAD.
 330
 331 The copying like C<$a=$b> is shallow; however, a one-level-deep
 332 copying is
 333 carried out before any operation that can imply an assignment to the
 334 object $b (or $a) refers to, like C<$b++>.  You can override this
 335 behavior by defining your copy constructor (see L<"Copy Constructor">).
 336
 337 It is expected that arguments to methods that are not explicitly supposed
 338 to be changed are constant (but this is not enforced).
 339
 340 =head1 AUTHOR
 341
 342 Ilya Zakharevich <F<ilya@math.mps.ohio-state.edu>>.
 343
 344 =head1 DIAGNOSTICS
 345
 346 When Perl is run with the B<-Do> switch or its equivalent, overloading
 347 induces diagnostic messages.
 348
 349 =head1 BUGS
 350
 351 Because it's used for overloading, the per-package associative array
 352 %OVERLOAD now has a special meaning in Perl.
 353
 354 Although the copy constructor is specially designed to make overloading
 355 operations with references to an array simpler, as it now works it's
 356 useless for this because a subroutine cannot return an array in the same
 357 way as it returns a scalar (from the point of view of Perl
 358 internals).  Expect a change of interface for the copy constructor.
 359
 360 As shipped, %OVERLOAD is not inherited via the @ISA tree.  A patch for
 361 this is available from the author.
 362
 363 This document is confusing.