NAME

Data::ResultSet - Container for aggregating and examining multiple results

SYNOPSIS

    # Subclass the module
    package MyApp::ResultSet;
    use base qw( Data::ResultSet );

    # Generate methods to wrap 'is_success' and 'is_error'
    __PACKAGE__->make_wrappers( qw( is_success is_error ) );

    # And elsewhere...
    package MyApp;
    use MyApp::ResultSet;
    sub something
    {
        # Create a resultset object
        my $result = MyApp::ResultSet->new();

        foreach my $thing ( @_ ) {
                # Add results of calling do_something() to the result
                # set
                $result->add(
                         $thing->do_something();
                );
        }

        # Return the results
        return $result;
    }

    # And, check your results
    my $r = something( @some_data );

    if( $r->all_success ) {
        # Only true if each result's ->is_success method returns true
        print "happiness and puppies!\n";
    } elsif ( $r->all_error ) {
        # Only true if each result's ->is_error method returns true
        die 'Oh noes! Everything errored out!';
    } else {
        foreach my $failed ( $r->list_not_success() ) {
                # Do something with each failed result
        }
    }

DESCRIPTION

Data::ResultSet is a container object for aggregating and examining multiple results. It allows multiple result objects matching the same method signature to be returned as a single object that can then be queried for success or failure in a number of ways.

This is accomplished by generating wrappers to methods in the underlying list of result objects. For example, if you have a result object that has an is_ok() method, you can create a Data::ResultSet subclass to handle it with:

    package MyApp::ResultSet;
    use base qw( Data::ResultSet );
    __PACKAGE__->make_wrappers( 'is_ok' );
    1;

This will generate all_ok, has_ok, get_ok, and get_not_ok methods in MyApp::ResultSet that use the is_ok accessor on your result object.

CLASS METHODS

new ( )

Creates a new Data::ResultSet object. Generally you will want to do this on a subclass, not on Data::ResultSet.

make_wrappers ( @method_names )

Generates all wrapper methods ( all_, has_, get_, get_not ) for the provided method names. The resulting wrapper will consist of the provided name and the appropriate prefix, with the exception that provided names beginning with is_ will have the is_ stripped first.

The wrappers can be generated individually using other methods (see below).

make_wrappers_for_all ( @method_names )

Generates the all_ wrapper method for each provided name.

make_wrappers_for_has

Generates the has_ wrapper method for each provided name.

make_wrappers_for_get

Generates the get_ wrapper method for each provided name.

make_wrappers_for_get_not

Generates the get_not_ wrapper method for each provided name.

INSTANCE METHODS

add ( $object )

Adds an object to the result set. Returns $self.

count ( )

Returns number of objects in the set.

contents ( )

Returns contents of set.

clear ( )

Clears contents of set. Returns true.

all_METHOD ( )

Generated method that returns true if the METHOD called on every object within the set returns true.

has_METHOD ( )

Generated method that returns true if one object within the set returns true for METHOD.

get_METHOD ( )

Generated method that returns all objects for which METHOD returns true.

get_not_METHOD ( )

Generated method that returns all objects for which METHOD returns false.

INCOMPATIBILITIES

There are no known incompatibilities with this module.

BUGS AND LIMITATIONS

• The methods being wrapped shouldn't be anything more than simple accessors. They will get called an arbitrary number of times, so doing any real work, particularly anything that changes state or has side-effects, is a bad idea.

Please report any new problems to the author. Patches are welcome.

SEE ALSO

There are quite a few other packages on the CPAN for implementing polymorphic return values. You may wish to use one of these instead:

• Class::ReturnValue

• Return::Value

• Contextual::Return

AUTHOR

Dave O'Neill

MAINTAINER

Dianne Skoll (dianne@skoll.ca)

LICENCE AND COPYRIGHT

Copyright (c) 2007 Roaring Penguin Software, Inc. Copyright (c) 2022 Dianne Skoll

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

cpanm Data::ResultSet

perl -MCPAN -e shell
install Data::ResultSet