The problem(s) with attribute-based hierarchies

        sub steer {
                my $self = shift;
                return ( $self->{left_front_wheel}->steer(@_),
                         $self->{right_front_wheel}->steer(@_), );
        }

        sub drive {
                my $self = shift;
                return ( $self->{left_rear_wheel}->drive(@_),
                         $self->{right_rear_wheel}->drive(@_),  );
        }

        sub brake {
                my $self = shift;
                return ( $self->{left_front_wheel}->brake(@_),
                         $self->{left_rear_wheel}->brake(@_),
                         $self->{right_front_wheel}->brake(@_),
                         $self->{right_rear_wheel}->brake(@_),  );
        }

"AUTOLOAD" methods can help in this regard, but usually at the cost of readability and maintainability:

        sub AUTOLOAD {
                my $self = shift;
                $AUTOLOAD =~ s/.*:://;
                my @results;
                return map { $self->{$_}->$AUTOLOAD(@_) },
                        grep { $self->{$_}->can($AUTOLOAD) },
                         keys %$self;
        }

Often, the simple auto-delegation mechanism shown above cannot be used at all, and the various cases must be hand-coded into the "AUTOLOAD" or into separate named methods (as shown earlier).

For example, an electric car might also have a flywheel and an MP3 player:

        sub new {
                bless { left_front_wheel  => Wheel->new('steer', 'brake'),
                        left_rear_wheel   => Wheel->new('drive', 'brake'),
                        right_front_wheel => Wheel->new('steer', 'brake'),
                        right_rear_wheel  => Wheel->new('drive', 'brake'),
                        flywheel          => Flywheel->new(),
                        mp3               => MP3::Player->new(),
                      }, $_[0];
        }

The Flywheel class would probably have its own "brake" method (to harvest motive energy from the flywheel) and MP3::Player might have its own "drive" method (to switch between storage devices).

An "AUTOLOAD" redispatch such as that shown above would then fail very badly. Whilst it would prove merely annoying to have one's music skip tracks ("$self->{mp3}->drive(+10)") every time one accelerated ("$self->{right_rear_wheel}->drive(+10)"), it might be disastrous to attempt to suck energy out of the flywheel ("$self->{flywheel}->brake()") whilst the brakes are trying to feed it back in ("$self->{right_rear_wheel}->brake()").

Class-action lawyers love this kind of programming.

The syntax and semantics of delegation

        package Car;
        
        use Class::Delegation
                send => 'steer',
                  to => ["left_front_wheel", "right_front_wheel"],
                
                send => 'drive',
                  to => ["right_rear_wheel", "left_rear_wheel"],
                  as => ["rotate_clockwise", "rotate_anticlockwise"]
                  
                send => 'power',
                  to => 'flywheel',
                  as => 'brake',
                
                send => 'brake',
                  to => qr/.*_wheel$/,
                  
                send => qr/^MP_(.+)/,
                  to => 'mp3',
                  as => sub { $1 },
                  
                send => -OTHER,
                  to => 'mp3',
                  
                send => 'debug',
                  to => -ALL,
                  as => 'dump',
                  
                send => -ALL,
                  to => 'logger',
                ;

Specifying methods to be delegated

• explicitly, by an array (the set consists of those method calls whose names appear in the array),
• implicitly, by a regex (the set consists of those method calls whose names match the pattern),
• procedurally, by a subroutine (the set consists of any method calls for which the subroutine returns a true value, when passed the method invocant, the method name, and the arguments with which the method was invoked),
• generically, by "-ALL" (the set consists of every method call -- excluding calls to "DESTROY" -- that is not handled by an explicit method of the class),
• exclusively, by "-OTHER" (the set consists of every method call -- excluding calls to "DESTROY" -- that is not successfully delegated by any earlier mapping in the "use Class::Delegation" list).

The exclusion of calls to "DESTROY" in the last two cases ensures that automatically invoked destructor calls are not erroneously delegated. "DESTROY" calls can be delegated through any of the other specification mechanisms.

Specifying attributes to be delegated to

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}->power(...)":

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

If the attribute is specified via a single string that starts with ""-"..."> then that string is taken as specifying the name of a method of the current object. That method is called and is expected to return an object. The original method that was being delegated is then delegated to that object. For example, to delegate invocations of "$self->power(...)" to "$self->flywheel()->power(...)":

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

Since this syntax is a little obscure (and not a little ugly), the same effect can also be obtained like so:

        use Class::Delegation
            send => 'power',
              to => -SELF->flywheel;

An array reference can be used in the attribute position to specify the a list of attributes, all of which are delegated to -- in sequence they appear in the list. Note that each element of the array is processed recursively, so it may contain any of the other attribute specifiers described in this section (or, indeed, a nested array of attribute specifiers)

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

        use Class::Delegation
            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 original method. 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 a class's "cost" method were delegated like so:

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

then the total cost could be calculated like this:

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

Specifying the attribute as a regular expression causes the associated method to be delegated to any attribute whose name matches the pattern. Attributes are tested for such a match -- and delegated to -- in the internal order of their hash (i.e. in the sequence returned by "keys"). For example, to redispatch "brake" calls to every attribute whose name ends in "_wheel":

        send => 'brake',
          to => qr/.*_wheel$/,

If a subroutine reference is used as the 'to' attribute specifier, it is passed the invocant, the name of the method, and the argument list. It is expected to return either a value specifying the correct attribute name (or names). As with an array, the value returned may be any valid attribute specifier (including another subroutine reference) and is iteratively processed to determine the correct target(s) for delegation.

A subroutine may also return a reference to an object, in which case the subroutine is delegated to that object (rather than to an attribute of the current object). This can be useful when the actual delegation target is more complex than just a direct attribute. For example:

        send => 'start',
          to => sub { $_[0]{ignition}{security}[$_[0]->next_key] },

If the "-ALL" flag is used as the name of the attribute, the method is delegated to all attributes of the object (in their "keys" order). For example, to forward debugging requests to every attribute in turn:

        send => 'debug',
          to => -ALL,

Specifying the name of a delegated method

If a string is provided, it is used as the new name of the delegated method. For example, to cause calls to "$self->power(...)" to be delegated to "$self->{flywheel}->brake(...)":

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

If an array is given, it specifies a list of delegated method names. If the 'to' key specifies a single attribute, each method in the list is invoked on that one attribute. For example:

        send => 'boost',
          to => 'flywheel',
          as => ['override', 'engage', 'discharge'],

would sequentially call:

        $self->{flywheel}->override(...);
        $self->{flywheel}->engage(...);
        $self->{flywheel}->discharge(...);

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

        send => 'escape',
          to => ['flywheel', 'smokescreen'],
          as => ['engage',   'release'],

would sequentially call:

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

If a subroutine reference is used as the 'as' specifier, it is passed the invocant, the name of the method, and the argument list, and is expected to return a string that will be used as the method name. For example, to strip method calls of a "driver_..." prefix and delegate them to the 'driver' attribute:

        send => sub { substr($_[1],0,7) eq "driver_" },
          to => 'driver', 
          as => sub { substr($_[1],7) }

or:

        send => qr/driver_(.*)/,
          to => 'driver', 
          as => sub { $1 }

Delegation to self

       send => 'overdrive',
         to => -SELF,
         as => 'boost',

Note that this only works if the object does not already have an "overdrive" method.

As with other delegations, a single call can be redelegated-to-self as multiple calls. For example:

       send => 'emergency',
         to => -SELF,
         as => ['overdrive', 'launch_rockets'],

Handling failure to delegate

Simulating single inheritance

Moreover, in many cases, it is not possible to tell -- without a detailed inspection of a base class's implementation -- whether such a class can easily be inherited. This inability to reliably treat classes as encapsulated and implementation-independent components seriously undermines the usability of object-oriented Perl.

But since inheritance in Perl merely specifies where a class is to look next if a suitable method is not found in its own package [3], it is often possible to replace derivation with aggregation and use a delegated attribute instead.

For example, it is possible to simulate the inheritance of the class Base via a delegated attribute:

        package Derived;
        use Class::Delegation send => -ALL, to => 'base';
        
        sub new {
                my ($class, $new_attr1, $new_attr2, @base_args) = @_;
                bless { attr1 => $new_attr1,
                        attr2 => $new_attr2,
                        base  => Base->new(@base_args),
                      }, $class;
        }

Now any method that is not present in Derived is delegated to the Base object referred to by the "base" attribute, just as it would have been if Derived actually inherited from Base.

This technique works in situations where the functionality of the Base methods is non-polymorphic with respect to their invocant. That is, if an inherited method in class Base were to interrogate the class of the object on which it was called, it would find a Derived object. But a delegated method in class Base will find a Base object. This is not the usual behaviour in OO Perl, but is correct and appropriate under the earlier assumption that Base has not been designed to be inherited from -- and must therefore always expect a Base class object as its invocant.

Replacing method dispatch semantics

For example, if various base classes in a class hierarchy provide a "dump_info" method for debugging purposes, then a derived class than multiply inherits from two or more of those classes will only dispatch calls to "dump_info" to the left-most ancestor's method. This is unlikely to be the desired behaviour.

Using delegation it is possible to cause calls to "dump_info" to invoke the corresponding methods of all the base classes, whilst all other method calls are dispatched left-most and depth-first, as normal:

        package Derived;
        use Class::Delegation
                send => 'dump_info',
                  to => -ALL,
                  
                send => -OTHER,
                  to => 'base1',
        
                send => -OTHER,
                  to => 'base2',
                ;
        
        sub new {
                my ($class, %named_args) = @_;
                bless { base1 => Base1->new(%named_args),
                        base2 => Base2->new(%named_args),
                      }, $class;
        }

Note that the semantics of "send => -OTHER" ensure that only one of the two base classes is delegated a method. If "base1" is able to handle a particular method delegation, then it will have been dispatched when the "-OTHER" governing "base2" is reached, so the second "-OTHER" will ignore it.

Simulating multiple inheritance of pseudohashs

Delegation provides a convenient way to provide the effects of pseudohash multiple inheritance, without the attendant problems. For example:

        package Derived;
        use Class::Delegation
                send => -ALL,
                  to => 'pseudobase1',
        
                send => -OTHER,
                  to => 'pseudobase2',
                ;
        
        sub new {
                my ($class, %named_args) = @_;
                bless { pseudobase1 => Pseudo::Base1->new(%named_args),
                        pseudobase2 => Pseudo::Base2->new(%named_args),
                      }, $class;
        }

As in the previous example, only one of the two base classes is delegated a method. The "-ALL" associated with "pseudobase1" attempts to delegate every method to that attribute, then the "-OTHER" associated with "pseudobase2" catches any methods that cannot be handled by "pseudobase1".

Adapting legacy code

        class DogTag;
        
        sub get_name   { return $_[0]->{name} }
        sub set_name   { $_[0]->{name} = $_[1] }

        sub get_rank   { return $_[0]->{rank} }
        sub set_rank   { $_[0]->{rank} = $_[1] }

        sub get_serial { return $_[0]->{serial} }
        sub set_serial { $_[0]->{serial} = $_[1] }
        
        # etc.

could be trivially adapted to provide combined get/set accessors like so:

        class DogTag::SingleAccess;
        
        use Class::Delegation
                send => -ALL
                  to => 'dogtag',
                  as => sub {
                             my ($invocant, $method, @args) = @_;
                             return @args ? "set_$method" : "get_$method"
                         },
                ;
                
        sub new { bless { dogtag => DogTag->new(@_[1..$#_) }, $_[0] }

Here, the 'as' subroutine determines whether an "new value" argument was passed to the original method, delegating to the "set_..." method if so, and to the "get_..." method otherwise.

Multiplexing a facade

        package Bilateral;
        
        %Bilateral = ( left  => 'Levorotatory',
                       right => 'Dextrorotatory',
                     );
                     
        use Class::Delegation
                send => qr/(left|right)_(.*)/,
                  to => sub { $1 },
                  as => sub { $2 },
                ;
        
        sub AUTOLOAD  { 
                carp "$AUTOLOAD does not begin with 'left_...' or 'right_...'"
        },

The Bilateral class now forwards all class method calls that are prefixed with "left_..." to the Laevorotatory class, and all those prefixed with "right_..." to the Dextrorotatory class. Any calls that cannot be dispatched are caught and ignored (with a warning) by the "AUTOLOAD".

The mechanism by which the class method dispatch is achieved is perhaps a little obscure. Consider the invocation of a class method:

        Bilateral->left_rotate(45);

Here, the invocant is the string "Bilateral", rather than a blessed object. Thus, when Class::Delegation forwards the call to:

        $self->{$1}->$2(45);

the effect is the same as calling:

        "Bilateral"->{left}->rotate(45);

This invokes a little-known feature of the "->" operator [4]. If a hash access is performed on a string, that string is taken as a symbolic reference to a package hash variable in the current package. Thus the above call is internally translated to:

        ${"Bilateral"}{left}->rotate(45);

which is equivalent to the class method call:

        Levorotatory->rotate(45);