NAME

MooseX::Collect - provides method modifier for collecting method calls from roles and superclasses

SYNOPSIS

package A;
use Moose::Role;
sub items () { qw/apple orange/ }

package B;
use Moose::Role;
with 'A';
sub items () { qw/watermelon/ }

package C;
use Moose::Role;
sub items () { qw/banana/ }


package Foo;
use Moose;
use MooseX::Collect;

# easy syntax
collect 'items';

# explicit collector subroutine (allows you to process results)
collect 'items' => {
    my $self = shift;
    return @_;
};

# explicit arguments for fine-grained configuration
collect 'itemz' => (
    provider     => 'items',
    from         => [qw(self superclasses roles)],
    method_order => 'standard',
    context      => 'list',
    collector    => sub {
        my $self = shift;
        return @_;
    },
    superclass_recurse => 1,
);

# 'with' statements must be called after any 'collect'
with qw(B C);


my @items = $Foo->items;  # watermelon, apple, orange, banana

ABSTRACT

MooseX::Collect exports a "collect" method modifier that allows you to collect/compose the results of a method call dispatched to superclasses and/or roles of a given class. Its interface is designed to be easy and similar to standard Moose method modifiers: nothing special is required in the inherited classes, you just need to call the "collect" modifier in your final class in order to set up a method that will call all methods with the provided name in the inherited classes and return you the results.

Any arguments passed to the newly created accessor will be passed to each method call.

EXPORTED FUNCTIONS

collect $method_name

collect $method_name => sub {}

collect $method_name => ()

This will install a method of a given $name into the current class. You can pass a hash of options to the function. Available options are listed below. As a shortcut, you can pass a coderef: it will be used as a collector option (see below).

provider => $provider_method_name

This option sets the name of the method that will be searched in the inherited classes. This is useful if you want to use a different name for the local accessor. By default, the providers method name is the same of the accessor name (i.e. the $method_name you passed to collect).

from => 'self' | 'superclass' | 'roles' | ARRAYREF

This options accepts a string containing one of the above values or an arrayref containing one or more of them. Use it to specify which classes you want MooseX::Collect to search for provider methods. The order is relevant. The value self enables searching of the method inside the current class too. The default value is self, superclass, roles.

method_order => 'standard' | 'reverse' =item method_order => 'top_down' | 'bottom_up'

This option lets you reverse the default method resolution order, which is standard (aliased as top_down): derived classes will be called first. If you set this to reverse or bottom_up, base classes will be called first.

superclass_recurse => BOOL

By setting this options to false, MooseX::Collect will not recurse into parent classes but will only call the uppermost method available (i.e. the one that overrides any other with the same name implemented by parent classes). This option, which is false by default (allowing full recursion), does not affect searching in roles because they have no hierarchy.

context => 'scalar' | 'list'>

This arguments lets you set the Perl context to use when calling the provider methods. By default it's value is list.

collector => CODEREF

If you want to customize or filter the collection results, you can provide a custom coderef. It will receive the results in @_ and it's expected to return a list.

SEE ALSO

Moose

Moose::Role

MooseX::ComposedBehavior

BUGS

Please report any bugs to bug-moosex-collect@rt.cpan.org, or through the web interface at https://rt.cpan.org/Public/Bug/Report.html?Queue=MooseX-Collect.

AUTHOR

Alessandro Ranellucci <aar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Alessandro Ranellucci.

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