lib/overload.pm

   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 C<overload.pm> - 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 reference that shares its object with some other reference, such
 287 as
 288
 289         $a=$b;
 290         $a++;
 291
 292 To make this change $a and not change $b, a copy of C<$$a> is made,
 293 and $a is assigned a reference to this new object.  This operation is
 294 done during execution of the C<$a++>, and not during the assignment,
 295 (so before the increment C<$$a> coincides with C<$$b>).  This is only
 296 done if C<++> is expressed via a method for C<'++'> or C<'+='>.  Note
 297 that if this operation is expressed via C<'+'> a nonmutator, i.e., as
 298 in
 299
 300         $a=$b;
 301         $a=$a+1;
 302
 303 then C<$a> does not reference a new copy of C<$$a>, since $$a does not
 304 appear as lvalue when the above code is executed.
 305
 306 If the copy constructor is required during the execution of some mutator,
 307 but a method for C<'='> was not specified, it can be autogenerated as a
 308 string copy if the object is a plain scalar.
 309
 310 =over 5
 311
 312 =item B<Example>
 313
 314 The actually executed code for
 315
 316         $a=$b;
 317         Something else which does not modify $a or $b....
 318         ++$a;
 319
 320 may be
 321
 322         $a=$b;
 323         Something else which does not modify $a or $b....
 324         $a = $a->clone(undef,"");
 325         $a->incr(undef,"");
 326
 327 if $b was mathemagical, and C<'++'> was overloaded with C<\&incr>,
 328 C<'='> was overloaded with C<\&clone>.
 329
 330 =back
 331
 332 =head1 MAGIC AUTOGENERATION
 333
 334 If a method for an operation is not found, and the value for  C<"fallback"> is
 335 TRUE or undefined, Perl tries to autogenerate a substitute method for
 336 the missing operation based on the defined operations.  Autogenerated method
 337 substitutions are possible for the following operations:
 338
 339 =over 16
 340
 341 =item I<Assignment forms of arithmetic operations>
 342
 343 C<$a+=$b> can use the method for C<"+"> if the method for C<"+=">
 344 is not defined.
 345
 346 =item I<Conversion operations>
 347
 348 String, numeric, and boolean conversion are calculated in terms of one
 349 another if not all of them are defined.
 350
 351 =item I<Increment and decrement>
 352
 353 The C<++$a> operation can be expressed in terms of C<$a+=1> or C<$a+1>,
 354 and C<$a--> in terms of C<$a-=1> and C<$a-1>.
 355
 356 =item C<abs($a)>
 357
 358 can be expressed in terms of C<$aE<lt>0> and C<-$a> (or C<0-$a>).
 359
 360 =item I<Unary minus>
 361
 362 can be expressed in terms of subtraction.
 363
 364 =item I<Concatenation>
 365
 366 can be expressed in terms of string conversion.
 367
 368 =item I<Comparison operations>
 369
 370 can be expressed in terms of its "spaceship" counterpart: either
 371 C<E<lt>=E<gt>> or C<cmp>:
 372
 373     <, >, <=, >=, ==, !=        in terms of <=>
 374     lt, gt, le, ge, eq, ne      in terms of cmp
 375
 376 =item I<Copy operator>
 377
 378 can be expressed in terms of an assignment to the dereferenced value, if this
 379 value is a scalar and not a reference.
 380
 381 =back
 382
 383 =head1 WARNING
 384
 385 The restriction for the comparison operation is that even if, for example,
 386 `C<cmp>' should return a blessed reference, the autogenerated `C<lt>'
 387 function will produce only a standard logical value based on the
 388 numerical value of the result of `C<cmp>'.  In particular, a working
 389 numeric conversion is needed in this case (possibly expressed in terms of
 390 other conversions).
 391
 392 Similarly, C<.=>  and C<x=> operators lose their mathemagical properties
 393 if the string conversion substitution is applied.
 394
 395 When you chop() a mathemagical object it is promoted to a string and its
 396 mathemagical properties are lost.  The same can happen with other
 397 operations as well.
 398
 399 =head1 Run-time Overloading
 400
 401 Since all C<use> directives are executed at compile-time, the only way to
 402 change overloading during run-time is to
 403
 404     eval 'use overload "+" => \&addmethod';
 405
 406 You can also use
 407
 408     eval 'no overload "+", "--", "<="';
 409
 410 though the use of these constructs during run-time is questionable.
 411
 412 =head1 Public functions
 413
 414 Package C<overload.pm> provides the following public functions:
 415
 416 =over 5
 417
 418 =item overload::StrVal(arg)
 419
 420 Gives string value of C<arg> as in absence of stringify overloading.
 421
 422 =item overload::Overloaded(arg)
 423
 424 Returns true if C<arg> is subject to overloading of some operations.
 425
 426 =item overload::Method(obj,op)
 427
 428 Returns C<undef> or a reference to the method that implements C<op>.
 429
 430 =back
 431
 432 =head1 IMPLEMENTATION
 433
 434 What follows is subject to change RSN.
 435
 436 The table of methods for all operations is cached as magic in the
 437 symbol table hash for the package.  The table is rechecked for changes due to
 438 C<use overload>, C<no overload>, and @ISA only during
 439 C<bless>ing; so if they are changed dynamically, you'll need an
 440 additional fake C<bless>ing to update the table.
 441
 442 (Every SVish thing has a magic queue, and magic is an entry in that queue.
 443 This is how a single variable may participate in multiple forms of magic
 444 simultaneously.  For instance, environment variables regularly have two
 445 forms at once: their %ENV magic and their taint magic.)
 446
 447 If an object belongs to a package using overload, it carries a special
 448 flag.  Thus the only speed penalty during arithmetic operations without
 449 overloading is the checking of this flag.
 450
 451 In fact, if C<use overload> is not present, there is almost no overhead for
 452 overloadable operations, so most programs should not suffer measurable
 453 performance penalties.  A considerable effort was made to minimize the overhead
 454 when overload is used and the current operation is overloadable but
 455 the arguments in question do not belong to packages using overload.  When
 456 in doubt, test your speed with C<use overload> and without it.  So far there
 457 have been no reports of substantial speed degradation if Perl is compiled
 458 with optimization turned on.
 459
 460 There is no size penalty for data if overload is not used.
 461
 462 Copying (C<$a=$b>) is shallow; however, a one-level-deep copying is
 463 carried out before any operation that can imply an assignment to the
 464 object $a (or $b) refers to, like C<$a++>.  You can override this
 465 behavior by defining your own copy constructor (see L<"Copy Constructor">).
 466
 467 It is expected that arguments to methods that are not explicitly supposed
 468 to be changed are constant (but this is not enforced).
 469
 470 =head1 AUTHOR
 471
 472 Ilya Zakharevich <F<ilya@math.mps.ohio-state.edu>>.
 473
 474 =head1 DIAGNOSTICS
 475
 476 When Perl is run with the B<-Do> switch or its equivalent, overloading
 477 induces diagnostic messages.
 478
 479 =head1 BUGS
 480
 481 Because it is used for overloading, the per-package associative array
 482 %OVERLOAD now has a special meaning in Perl.
 483
 484 As shipped, mathemagical properties are not inherited via the @ISA tree.
 485
 486 This document is confusing.
 487
 488 =cut
 489