Thomas Klausner > Class-DispatchToAll-0.11 > Class::DispatchToAll

Download:
Class-DispatchToAll-0.11.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.11   Source  

NAME ^

Class::DispatchToAll - Dispatch a method call to all inherited methods

SYNOPSIS ^

  package My::Class;
  our @ISA=qw(SomeClass SomeOtherClass More::Classes);
  use Class::DispatchToAll qw(dispatch_to_all);

  my $self=bless {},My::Class  # not a proper constructor, I know..

  # this calls 'some_method' in all Classes My::Class inherits from
  # and all classes those classes inherit from, and all ... you get
  # the point.
  $self->dispatch_to_all('some_method');

  # saves all return values from all calls in an array
  my @returns=$self->dispatch_to_all('some_method');

DESCRIPTION ^

See the Docs of Damian Conways Module Class::Delegation for a good introduction about Dispatching vs. Inheritance.

Class::DispatchToAll enables you to call all instantances of a method in your inheritance tree (or labyrinth..).

The standard Perl behaviour is to call only the lefternmost instance it can fing doing a depth first traversial.

Imagine the following class structure:

              C
             /
   A    B  C::C
    \  / \ /
   A::A   D
       \ /
     My::Class

Perl will try to find a method in this mess in this order:

 My::Class -> A::A  ->  A  ->  B  ->  D  -> B  -> C::C -> C

(Note that it will look twice in B because B is a parent of both A::A and D))

As soon as Perl finds the method somewhere, it will short-circuit out of it's search and invoke the method.

And that is exactly the behaviour Class::DispatchToAll changes.

If you use dispatch_to_all (provided by Class::DispatchToAll) to call your method, Perl will look in all of the aforementioned packages and run all the methods it can find. It will even collect all the return values and return them to you as an array, if you want it too.

dispatch_to_all

Call it either as a function:

  dispatch_to_all($self,
                  $method_to_call,
                  \%attribs,
                  @params_passed_to_method);

or as a method

  $self->dispatch_to_all($method_to_call,
                         \%attribs,
                         @params_passed_to_method);

If you didn't set no_collect, dispatch_to_all will return an array or ARRAYREF (depending on what you were calling for, so watch your context) where each element is the return value of a method. (NOTA BENE: If one method returns more than one value, this might lead to some confusion.. See TODO).

Currently, the first called method (i.e. the one Perl would originally call) will be the first value of this array, followed by all other values. If a method doesn't exist in any class, no value will be returned (maybe undef would be better, don't know now..).

What you do with this values and how to decide which one to use (if you only need one) is up to you.

One thing I do (and the reason for writing this module) is to condensate different config values to one, e.g.:

  A::config="test";
  A::A::config="test2";
  My::Class::config="test3";

  # assuming a method get_config not implemented in this example
  print join(",",@{$self->dispatch_to_all('get_config')});
  # prints: test3,test2,test

Or this, merging a hash:

  A::hash={foo=>'foo'};
  C::hash={bar=>'bar'};
  A::A::hash={foo=>'FOO'};
  My::Class::hash={even=>'more'};

  # assuming a method get_hash not implemented in this example
  my @v=$self->dispatch_to_all('get_hash');
  my %hash=();
  foreach (reverse @v) {
      %hash=(%hash,%$_);
  }

  # %hash now looks like: { foo=>'FOO', # from A::A, overriding A
  # bar=>'bar', # from C even=>'more', # from My::Class }

Please note the reverse. This enables the overriding of values "further away" from the calling class by values that are "nearer"

See the test script for more examples.

TODO ^

INSTALLATION

To install this module type the following:

    perl Build.PL
    ./Build
    ./Build test
    sudo ./Build install

BUGS ^

Please report any bugs or feature requests to bug-class-dispatchtoall@rt.cpan.org, or through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SEE ALSO ^

Class::Delegation, NEXT

This thread on perlmonks: http://www.perlmonks.org/index.pl?node_id=180852

AUTHOR ^

Thomas Klausner, domm@cpan.org, http://domm.plix.at

COPYRIGHT ^

Class::DispatchToAll is Copyright (c) 2002,2006 Thomas Klausner. All rights reserved.

You may use and distribute this module according to the same terms that Perl is distributed under

syntax highlighting: