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.  This operation
 210 is called in the situations when a mutator is applied to a reference
 211 that shares its object with some other reference, such as
 212
 213         $a=$b;
 214         $a++;
 215
 216 To make this change to $a and not to change $b, a freshly made copy of
 217 C<$$a> is made, and $a is assigned a reference to this object.  This
 218 operation is executed during C<$a++>, (so before this C<$$a> coincides
 219 with C<$$b>), and only if C<++> is expressed via  C<$OPERATOR{'++'}> or
 220 C<$OPERATOR{'+='}>.  Note that if this operation is expressed via 'C<+>',
 221 i.e., as
 222
 223         $a=$b;
 224         $a=$a+1;
 225
 226 then C<$$a> and C<$$b> do not appear as lvalues.
 227
 228 If the copy constructor is required during execution of some mutator, but
 229 C<$OPERATOR{'='}> is missing, it can be autogenerated as a string
 230 copy if an object of
 231 the package is a plain scalar.
 232
 233 =head1 MAGIC AUTOGENERATION
 234
 235 If a method for an operation is not found, and C<$OVERLOAD{"fallback"}> is
 236 TRUE or undefined, Perl tries to to autogenerate a substitute method for
 237 the missing operation based on defined operations.  Autogenerated method
 238 substitutions are possible for the following operations:
 239
 240 =over 16
 241
 242 =item I<Assignment forms of arithmetic operations>
 243
 244 C<$a=+$b> can use the C<$OVERLOAD{"+"}> method if C<$OVERLOAD{"+="}>
 245 is not defined.
 246
 247 =item I<Conversion operations>
 248
 249 String, numeric, and boolean conversion are calculated in terms of one
 250 another if not all of them are defined.
 251
 252 =item I<Increment and decrement>
 253
 254 The C<++$a> operation can be expressed in terms of C<$a+=1> or C<$a+1>,
 255 and C<$a--> in terms of C<$a-=1> and C<$a-1>.
 256
 257 =item C<abs($a)>
 258
 259 can be expressed in terms of C<$aE<lt>0> and C<-$a> (or C<0-$a>).
 260
 261 =item I<Unary minus>
 262
 263 can be expressed in terms of subtraction.
 264
 265 =item I<Concatenation>
 266
 267 can be expressed in terms of string conversion.
 268
 269 =item I<Comparison operations>
 270
 271 can be expressed in terms of its "spaceship" counterpart: either
 272 C<E<lt>=E<gt>> or C<cmp>:
 273
 274     <, >, <=, >=, ==, !=        in terms of <=>
 275     lt, gt, le, ge, eq, ne      in terms of cmp
 276
 277 =item I<Copy operator>
 278
 279 can be expressed in terms of assignment to the dereferenced value, if this
 280 value is scalar but not a reference.
 281
 282 =back
 283
 284 =head1 WARNING
 285
 286 The restriction for the comparison operation is that even if, for example,
 287 `C<cmp>' should return a reference to a blessed object, the
 288 autogenerated `C<lt>'
 289 function will produce only a standard logical value based on the
 290 numerical value of the result of `C<cmp>'.  In particular, a working
 291 numeric conversion is needed in this case (possibly expressed in terms of
 292 other conversions).
 293
 294 Similarly, C<.=>  and C<x=> operators lose their mathemagical properties
 295 if the string conversion substitution is applied.
 296
 297 When you chop() a mathemagical object, it becomes promoted to a string
 298 first, and its mathemagical qualities is lost.  The same can happen with other
 299 operations as well.
 300
 301 =head1 IMPLEMENTATION
 302
 303 The table of methods for all operations is cached as a magic for the
 304 symbol table hash of the package.  It is rechecked for changes of
 305 %OVERLOAD and @ISA only during C<bless>ing; so if it is changed
 306 dynamically, you'll need an additional fake C<bless>ing to update the
 307 table.
 308
 309 (Every SVish thing has a magic queue, and a magic is an entry in that queue.
 310 This is how a single variable may participate in multiple forms of magic
 311 simultaneously.  For instance, environment variables regularly have two
 312 forms at once: their %ENV magic and their taint magic.)
 313
 314 If an object belongs to a package with %OVERLOAD, it carries a special
 315 flag.  Thus the only speed penalty during arithmetic operations without
 316 overload is the check of this flag.
 317
 318 In fact, if no %OVERLOAD is ever accessed, there is almost no overhead for
 319 overloadable operations, so most programs should not suffer measurable
 320 performance penalties.  Considerable effort was made minimize overhead
 321 when %OVERLOAD is accessed and the current operation is overloadable but
 322 the arguments in question do not belong to packages with %OVERLOAD.  When
 323 in doubt, test your speed with %OVERLOAD and without it.  So far there
 324 have been no reports of substantial speed degradation if Perl is compiled
 325 with optimization turned on.
 326
 327 There is no size penalty for data if there is no %OVERLOAD.
 328
 329 The copying like C<$a=$b> is shallow; however, a one-level-deep
 330 copying is
 331 carried out before any operation that can imply an assignment to the
 332 object $b (or $a) refers to, like C<$b++>.  You can override this
 333 behavior by defining your copy constructor (see L<"Copy Constructor">).
 334
 335 It is expected that arguments to methods that are not explicitly supposed
 336 to be changed are constant (but this is not enforced).
 337
 338 =head1 AUTHOR
 339
 340 Ilya Zakharevich <F<ilya@math.mps.ohio-state.edu>>.
 341
 342 =head1 DIAGNOSTICS
 343
 344 When Perl is run with the B<-Do> switch or its equivalent, overloading
 345 induces diagnostic messages.
 346
 347 =head1 BUGS
 348
 349 Because it's used for overloading, the per-package associative array
 350 %OVERLOAD now has a special meaning in Perl.
 351
 352 As shipped, %OVERLOAD is not inherited via the @ISA tree.  A patch for
 353 this is available from the author.
 354
 355 This document is confusing.