# NAME

List::Objects::WithUtils - Object interfaces to lists with useful methods

# SYNOPSIS

    use List::Objects::WithUtils;

    # Chained array operations:
    array(qw/ aa Ab bb Bc bc /)
      ->grep(sub { $_[0] =~ /^b/i })
      ->map( sub { uc $_[0] })
      ->uniq
      ->all;     # ( 'BB', 'BC' )

    # Sample hash operations:
    my $hash  = hash( foo => 'bar', snacks => 'cake' );  

    $hash->set( foobar => 'baz', pie => 'tasty' );

    my $snacks = $hash->get('snacks');

    my $slice = $hash->sliced('foo', 'pie');

    my @matching = $hash->keys->grep(sub { $_[0] =~ /foo/ })->all;

    if ( $hash->keys->any_items eq 'snacks' ) {
      ...    
    }

# DESCRIPTION

A small set of roles and classes defining an object-oriented interface to Perl
hashes and arrays. Originally derived from [Data::Perl](http://search.cpan.org/perldoc?Data::Perl).

Some commonly used functions from [List::Util](http://search.cpan.org/perldoc?List::Util), [List::MoreUtils](http://search.cpan.org/perldoc?List::MoreUtils), and
[List::UtilsBy](http://search.cpan.org/perldoc?List::UtilsBy) are conveniently provided as methods. Junctions, 
as provided by [Syntax::Keyword::Junction](http://search.cpan.org/perldoc?Syntax::Keyword::Junction), are also available.

__array__ is imported from [List::Objects::WithUtils::Array](http://search.cpan.org/perldoc?List::Objects::WithUtils::Array) and creates a new
ARRAY-type object. 
Behavior is defined by [List::Objects::WithUtils::Role::Array](http://search.cpan.org/perldoc?List::Objects::WithUtils::Role::Array); look
there for documentation on available methods.

__immarray__ is imported from [List::Objects::WithUtils::Array::Immutable](http://search.cpan.org/perldoc?List::Objects::WithUtils::Array::Immutable) and
operates much like an __array__, except methods that mutate the list are not
available and the backing ARRAY is marked read-only; using immutable arrays 
promotes safer functional patterns.

__hash__ is imported from [List::Objects::WithUtils::Hash](http://search.cpan.org/perldoc?List::Objects::WithUtils::Hash); see  
[List::Objects::WithUtils::Role::Hash](http://search.cpan.org/perldoc?List::Objects::WithUtils::Role::Hash) for documentation.

__Why another object-oriented list module?__

There are a fair few object-oriented approaches to lists on CPAN, none of
which were quite what I needed. [Data::Perl](http://search.cpan.org/perldoc?Data::Perl) comes the closest -- but is
primarily targetting MooX::HandlesVia and cannot guarantee a stable API at the
time this was written (plus, I don't need the other data types).

This module aims to provide a consistent, natural interface to hashes and
arrays exclusively, with convenient access to common tools. The interface is
expected to remain stable; methods may be added but are
not expected to be removed (or experience incompatible interface changes, barring
serious bugs).

# SEE ALSO

[List::Objects::WithUtils::Role::Array](http://search.cpan.org/perldoc?List::Objects::WithUtils::Role::Array) for documentation on `array()`
methods.

[List::Objects::WithUtils::Role::WithJunctions](http://search.cpan.org/perldoc?List::Objects::WithUtils::Role::WithJunctions) for details regarding using 
junctions on an `array()`.

[List::Objects::WithUtils::Role::Hash](http://search.cpan.org/perldoc?List::Objects::WithUtils::Role::Hash) for documentation on `hash()`
methods.

# AUTHOR

Jon Portnoy <avenj@cobaltirc.org>

Significant portions of this code are derived from [Data::Perl](http://search.cpan.org/perldoc?Data::Perl) 
by Matthew Phillips (CPAN: MATTP), haarg, and others.

Licensed under the same terms as Perl.
