Name

       Class::Delegator - Simple and fast object-oriented delegation

Synopsis

         package Car;

         use Class::Delegator
             send => 'start',
               to => '{engine}',

             send => 'power',
               to => 'flywheel',
               as => 'brake',

             send => [qw(play pause rewind fast_forward shuffle)],
               to => 'ipod',

             send => [qw(accelerate decelerate)],
               to => 'brakes',
               as => [qw(start stop)],

             send => 'drive',
               to => [qw(right_rear_wheel left_rear_wheel)],
               as => [qw(rotate_clockwise rotate_anticlockwise)]
         ;

Description

       This module provides a subset of the functionality of Damian Conway's lovely
       Class::Delegation module. Why a subset? Well, I didn't need all of the fancy matching
       semantics, just string string specifications to map delegations. Furthermore, I wanted it
       to be fast (See Benchmarks). And finally, since Class::Delegation uses an "INIT" block to
       do its magic, it doesn't work in persistent environments that don't execute "INIT" blocks,
       such as in mod_perl.

       However the specification semantics of Class::Delegator differ slightly from those of
       Class::Delegation, so this module isn't a drop-in replacement for Class::Delegation. Read
       on for details.

   Specifying methods to be delegated
       The names of methods to be redispatched can be specified using the "send" parameter. This
       parameter may be specified as a single string or as an array of strings. A single string
       specifies a single method to be delegated, while an array reference is a list of methods
       to be delegated.

   Specifying attributes to be delegated to
       Use the "to" parameter to specify the attribute(s) or accessor method(s) to which the
       method(s) specified by the "send" parameter are to be delegated.  The semantics of the
       "to" parameter are a bit different from Class::Delegation. In order to ensure the fastest
       performance possible, this module simply installs methods into the calling class to handle
       the delegation. There is no use of $AUTOLOAD or other such trickery. But since the new
       methods are installed by "eval"ing a string, the "to" parameter for each delegation
       statement must be specified in the manner appropriate to accessing the underlying
       attribute. For example, to delegate a method call to an attribute stored in a hash key,
       simply wrap the key in braces:

         use Class::Delegator
             send => 'start',
               to => '{engine}',
         ;

       To delegate to a method, simply name the method:

         use Class::Delegator
             send => 'power',
               to => 'flywheel',
         ;

       If your objects are array-based, wrap the appropriate array index number in brackets:

         use Class::Delegator
             send => 'idle',
               to => '[3]',
         ;

       And so on.

   Specifying the name of a delegated method
       Sometimes it's necessary for the name of the method that's being delegated to be different
       from the name of the method to which you're delegating execution.  For example, your class
       might already have a method with the same name as the method to which you're delegating.
       The "as" parameter allows you translate the method name or names in a delegation
       statement. The value associated with an "as" parameter specifies the name of the method to
       be invoked, and may be a string or an array (with the number of elements in the array
       matching the number of elements in a corresponding "send" array).

       If the attribute is specified via a single string, that string is taken as the name of the
       attribute to which the associated method (or methods) should be delegated. For example, to
       delegate invocations of "$self->power(...)" to "$self->{flywheel}->brake(...)":

         use Class::Delegator
             send => 'power',
               to => '{flywheel}',
               as => 'brake',
         ;

       If both the "send" and the "as" parameters specify array references, each local method
       name and deleted method name form a pair, which is invoked. For example:

         use Class::Delegator
             send => [qw(accelerate decelerate)],
               to => 'brakes',
               as => [qw(start stop)],
         ;

       In this example, the "accelerate" method will be delegated to the "start" method of the
       "brakes" attribute and the "decelerate" method will be delegated to the "stop" method of
       the "brakes" attribute.

   Delegation to multiple attributes in parallel
       An array reference can be used as the value of the "to" parameter to specify the a list of
       attributes, all of which are delegated to--in the same order as they appear in the array.
       In this case, the "send" parameter must be a scalar value, not an array of methods to
       delegate.

       For example, to distribute invocations of "$self->drive(...)" to both
       "$self->{left_rear_wheel}->drive(...)" and "$self->{right_rear_wheel}->drive(...)":

         use Class::Delegator
             send => 'drive',
               to => ["{left_rear_wheel}", "{right_rear_wheel}"]
         ;

       Note that using an array to specify parallel delegation has an effect on the return value
       of the delegation method specified by the "send" parameter. In a scalar context, the
       original call returns a reference to an array containing the (scalar context) return
       values of each of the calls. In a list context, the original call returns a list of array
       references containing references to the individual (list context) return lists of the
       calls. So, for example, if the "cost" method of a class were delegated like so:

         use Class::Delegator
             send => 'cost',
               to => ['supplier', 'manufacturer', 'distributor']
         ;

       then the total cost could be calculated like this:

         use List::Util 'sum';
         my $total = sum @{$obj->cost()};

       If both the "to" key and the "as" parameters specify multiple values, then each attribute
       and method name form a pair, which is invoked. For example:

         use Class::Delegator
             send => 'escape',
               to => ['{flywheel}', '{smokescreen}'],
               as => ['engage',   'release'],
         ;

       would sequentially call, within the "escape()" delegation method:

         $self->{flywheel}->engage(...);
         $self->{smokescreen}->release(...);

Benchmarks

       I whipped up a quick script to compare the performance of Class::Delegator to
       Class::Delegation and a manually-installed delegation method (the control).  I'll let the
       numbers speak for themselves:

         Benchmark: timing 1000000 iterations of Class::Delegation, Class::Delegator, Manually...
         Class::Delegation: 106 wallclock secs (89.03 usr +  2.09 sys = 91.12 CPU) @ 10974.54/s  (n=1000000)
         Class::Delegator:    3 wallclock secs ( 3.44 usr +  0.02 sys =  3.46 CPU) @ 289017.34/s (n=1000000)
                  Control:    3 wallclock secs ( 3.01 usr +  0.02 sys =  3.03 CPU) @ 330033.00/s (n=1000000)

Bugs

       Please send bug reports to <bug-class-delegator@rt.cpan.org> or report them via the CPAN
       Request Tracker at <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Class-Delegator>.

Author

       David Wheeler <david@kineticode.com>

See Also

       Class::Delegation
           Damian Conway's brilliant module does ten times what this one does--and does it ten
           times slower.

       Class::Delegate
           Kurt Starsinic's module uses inheritance to manage delegation, and has a somewhat more
           complex interface.

       Class::HasA
           Simon Cozen's delegation module takes the same approach as this module, but provides
           no method for resolving method name clashes the way this module's "as" parameter does.

Copyright and License

       Copyright (c) 2005-2008 David Wheeler. Some Rights Reserved.

       This module is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.