package Moose::Meta::Attribute::Native::Trait::Array;
use Moose::Role;
-our $VERSION = '0.87';
+our $VERSION = '1.15';
$VERSION = eval $VERSION;
our $AUTHORITY = 'cpan:STEVAN';
-use Moose::Meta::Attribute::Native::MethodProvider::Array;
+use Moose::Meta::Method::Accessor::Native::Array::accessor;
+use Moose::Meta::Method::Accessor::Native::Array::clear;
+use Moose::Meta::Method::Accessor::Native::Array::count;
+use Moose::Meta::Method::Accessor::Native::Array::delete;
+use Moose::Meta::Method::Accessor::Native::Array::elements;
+use Moose::Meta::Method::Accessor::Native::Array::first;
+use Moose::Meta::Method::Accessor::Native::Array::get;
+use Moose::Meta::Method::Accessor::Native::Array::grep;
+use Moose::Meta::Method::Accessor::Native::Array::insert;
+use Moose::Meta::Method::Accessor::Native::Array::is_empty;
+use Moose::Meta::Method::Accessor::Native::Array::join;
+use Moose::Meta::Method::Accessor::Native::Array::map;
+use Moose::Meta::Method::Accessor::Native::Array::natatime;
+use Moose::Meta::Method::Accessor::Native::Array::pop;
+use Moose::Meta::Method::Accessor::Native::Array::push;
+use Moose::Meta::Method::Accessor::Native::Array::reduce;
+use Moose::Meta::Method::Accessor::Native::Array::set;
+use Moose::Meta::Method::Accessor::Native::Array::shift;
+use Moose::Meta::Method::Accessor::Native::Array::shuffle;
+use Moose::Meta::Method::Accessor::Native::Array::splice;
+use Moose::Meta::Method::Accessor::Native::Array::sort;
+use Moose::Meta::Method::Accessor::Native::Array::sort_in_place;
+use Moose::Meta::Method::Accessor::Native::Array::uniq;
+use Moose::Meta::Method::Accessor::Native::Array::unshift;
with 'Moose::Meta::Attribute::Native::Trait';
-has 'method_provider' => (
- is => 'ro',
- isa => 'ClassName',
- predicate => 'has_method_provider',
- default => 'Moose::Meta::Attribute::Native::MethodProvider::Array'
-);
-
sub _helper_type { 'ArrayRef' }
no Moose::Role;
=head1 NAME
-Moose::Meta::Attribute::Native::Trait::Array
+Moose::Meta::Attribute::Native::Trait::Array - Helper trait for array delegation
=head1 SYNOPSIS
use Moose;
has 'options' => (
- traits => ['Array'],
- is => 'ro',
- isa => 'ArrayRef[Str]',
- default => sub { [] },
- handles => {
- all_options => 'elements',
- map_options => 'map',
- filter_options => 'grep',
- find_option => 'find',
- first_option => 'first',
- last_option => 'last',
- get_option => 'get',
- join_options => 'join',
- count_options => 'count',
- do_i_have_options => 'empty',
- sorted_options => 'sort',
- }
+ traits => ['Array'],
+ is => 'ro',
+ isa => 'ArrayRef[Str]',
+ default => sub { [] },
+ handles => {
+ all_options => 'elements',
+ add_option => 'push',
+ map_options => 'map',
+ filter_options => 'grep',
+ find_option => 'first',
+ get_option => 'get',
+ join_options => 'join',
+ count_options => 'count',
+ has_options => 'count',
+ has_no_options => 'is_empty',
+ sorted_options => 'sort',
+ },
);
no Moose;
1;
-
+
=head1 DESCRIPTION
-This module provides an Array attribute which provides a number of
-array operations.
+This trait provides native delegation methods for array references.
-=head1 PROVIDED METHODS
+=head1 DEFAULT TYPE
-These methods are implemented in
-L<Moose::Meta::Attribute::Native::MethodProvider::Array>.
+If you don't provide an C<isa> value for your attribute, it will default to
+C<ArrayRef>.
+
+=head1 PROVIDED METHODS
=over 4
-=item B<count>
+=item * B<count>
Returns the number of elements in the array.
- $stuff = Stuff->new;
- $stuff->options(["foo", "bar", "baz", "boo"]);
+ $stuff = Stuff->new;
+ $stuff->options( [ "foo", "bar", "baz", "boo" ] );
+
+ print $stuff->count_options; # prints 4
+
+This method does not accept any arguments.
+
+=item * B<is_empty>
+
+Returns a boolean value that is true when the array has no elements.
+
+ $stuff->has_no_options ? die "No options!\n" : print "Good boy.\n";
+
+This method does not accept any arguments.
+
+=item * B<elements>
- my $count = $stuff->count_options;
- print "$count\n"; # prints 4
+Returns all of the elements of the array as an array (not an array reference).
-=item B<empty>
+ my @option = $stuff->all_options;
+ print "@options\n"; # prints "foo bar baz boo"
-If the array is populated, returns true. Otherwise, returns false.
+This method does not accept any arguments.
- $stuff->do_i_have_options ? print "Good boy.\n" : die "No options!\n" ;
+=item * B<get($index)>
-=item B<find>
+Returns an element of the array by its index. You can also use negative index
+numbers, just as with Perl's core array handling.
-This method accepts a subroutine reference as its argument. That sub
-will receive each element of the array in turn. If it returns true for
-an element, that element will be returned by the C<find> method.
+ my $option = $stuff->get_option(1);
+ print "$option\n"; # prints "bar"
- my $found = $stuff->find_option( sub { $_[0] =~ /^b/ } );
- print "$found\n"; # prints "bar"
+If the specified element does not exist, this will return C<undef>.
-=item B<grep>
+This method does accepts just one argument.
-This method accepts a subroutine reference as its argument. This
-method returns every element for which that subroutine reference
-returns a true value.
+=item * B<pop>
- my @found = $stuff->filter_options( sub { $_[0] =~ /^b/ } );
- print "@found\n"; # prints "bar baz boo"
+Just like Perl's builtin C<pop>.
-=item B<map>
+This method does not accept any arguments.
-This method accepts a subroutine reference as its argument. The
-subroutine will be executed for each element of the array. It is
-expected to return a modified version of that element. The return
-value of the method is a list of the modified options.
+=item * B<push($value1, $value2, value3 ...)>
- my @mod_options = $stuff->map_options( sub { $_[0] . "-tag" } );
- print "@mod_options\n"; # prints "foo-tag bar-tag baz-tag boo-tag"
+Just like Perl's builtin C<push>. Returns the number of elements in the new
+array.
-=item B<sort>
+This method accepts any number of arguments.
-Sorts and returns the elements of the array.
+=item * B<shift>
-You can provide an optional subroutine reference to sort with (as you
-can with the core C<sort> function). However, instead of using C<$a>
-and C<$b>, you will need to use C<$_[0]> and C<$_[1]> instead.
+Just like Perl's builtin C<shift>.
- # ascending ASCIIbetical
- my @sorted = $stuff->sort_options();
+This method does not accept any arguments.
- # Descending alphabetical order
- my @sorted_options = $stuff->sort_options( sub { lc $_[1] cmp lc $_[0] } );
- print "@sorted_options\n"; # prints "foo boo baz bar"
+=item * B<unshift($value1, $value2, value3 ...)>
-=item B<elements>
+Just like Perl's builtin C<unshift>. Returns the number of elements in the new
+array.
-Returns all of the elements of the array
+This method accepts any number of arguments.
- my @option = $stuff->all_options;
- print "@options\n"; # prints "foo bar baz boo"
+=item * B<splice($offset, $length, @values)>
-=item B<join>
+Just like Perl's builtin C<splice>. In scalar context, this returns the last
+element removed, or C<undef> if no elements were removed. In list context,
+this returns all the elements removed from the array.
-Joins every element of the array using the separator given as argument.
+This method requires at least one argument.
- my $joined = $stuff->join_options( ':' );
- print "$joined\n"; # prints "foo:bar:baz:boo"
+=item * B<first( sub { ... } )>
-=item B<get>
+This method returns the first item matching item in the array, just like
+L<List::Util>'s C<first> function. The matching is done with a subroutine
+reference you pass to this method. The subroutine will be called against each
+element in the array until one matches or all elements have been checked.
-Returns an element of the array by its index.
+ my $found = $stuff->find_option( sub {/^b/} );
+ print "$found\n"; # prints "bar"
- my $option = $stuff->get_option(1);
- print "$option\n"; # prints "bar"
+This method requires a single argument.
-=item B<first>
+=item * B<grep( sub { ... } )>
-Returns the first element of the array.
+This method returns every element matching a given criteria, just like Perl's
+core C<grep> function. This method requires a subroutine which implements the
+matching logic.
- my $first = $stuff->first_option;
- print "$first\n"; # prints "foo"
+ my @found = $stuff->filter_options( sub {/^b/} );
+ print "@found\n"; # prints "bar baz boo"
-=item B<last>
+This method requires a single argument.
-Returns the last element of the array.
+=item * B<map( sub { ... } )>
- my $last = $stuff->last_option;
- print "$last\n"; # prints "boo"
+This method transforms every element in the array and returns a new array,
+just like Perl's core C<map> function. This method requires a subroutine which
+implements the transformation.
-=item B<pop>
+ my @mod_options = $stuff->map_options( sub { $_ . "-tag" } );
+ print "@mod_options\n"; # prints "foo-tag bar-tag baz-tag boo-tag"
-=item B<push>
+This method requires a single argument.
-=item B<set>
+=item * B<reduce( sub { ... } )>
-=item B<shift>
+This method turns an array into a single value, by passing a function the
+value so far and the next value in the array, just like L<List::Util>'s
+C<reduce> function. The reducing is done with a subroutine reference you pass
+to this method.
-=item B<unshift>
+ my $found = $stuff->reduce_options( sub { $_[0] . $_[1] } );
+ print "$found\n"; # prints "foobarbazboo"
-=item B<clear>
+This method requires a single argument.
-=item B<delete>
+=item * B<sort>
-=item B<insert>
+=item * B<sort( sub { ... } )>
-=item B<splice>
+Returns the elements of the array in sorted order.
-=item B<sort_in_place>
+You can provide an optional subroutine reference to sort with (as you can with
+Perl's core C<sort> function). However, instead of using C<$a> and C<$b> in
+this subroutine, you will need to use C<$_[0]> and C<$_[1]>.
+
+ # ascending ASCIIbetical
+ my @sorted = $stuff->sort_options();
+
+ # Descending alphabetical order
+ my @sorted_options = $stuff->sort_options( sub { lc $_[1] cmp lc $_[0] } );
+ print "@sorted_options\n"; # prints "foo boo baz bar"
+
+This method accepts a single argument.
+
+=item * B<sort_in_place>
+
+=item * B<sort_in_place( sub { ... } )>
Sorts the array I<in place>, modifying the value of the attribute.
-You can provide an optional subroutine reference to sort with (as you
-can with the core C<sort> function). However, instead of using C<$a>
-and C<$b>, you will need to use C<$_[0]> and C<$_[1]> instead.
+You can provide an optional subroutine reference to sort with (as you can with
+Perl's core C<sort> function). However, instead of using C<$a> and C<$b>, you
+will need to use C<$_[0]> and C<$_[1]> instead.
-=item B<accessor>
+This method does not define a return value.
-If passed one argument, returns the value of the requested element.
-If passed two arguments, sets the value of the requested element.
+This method accepts a single argument.
-=back
+=item * B<shuffle>
-=head1 METHODS
+Returns the elements of the array in random order, like C<shuffle> from
+L<List::Util>.
-=over 4
+This method does not accept any arguments.
+
+=item * B<uniq>
+
+Returns the array with all duplicate elements removed, like C<uniq> from
+L<List::MoreUtils>.
+
+This method does not accept any arguments.
+
+=item * B<join($str)>
+
+Joins every element of the array using the separator given as argument, just
+like Perl's core C<join> function.
+
+ my $joined = $stuff->join_options(':');
+ print "$joined\n"; # prints "foo:bar:baz:boo"
+
+This method requires a single argument.
+
+=item * B<set($index, $value)>
+
+Given an index and a value, sets the specified array element's value.
+
+This method returns the value at C<$index> after the set.
+
+This method requires two arguments.
+
+=item * B<delete($index)>
+
+Removes the element at the given index from the array.
+
+This method returns the deleted value. Note that if no value exists, it will
+return C<undef>.
+
+This method requires one argument.
+
+=item * B<insert($index, $value)>
+
+Inserts a new element into the array at the given index.
+
+This method returns the new value at C<$index>.
+
+This method requires two arguments.
+
+=item * B<clear>
+
+Empties the entire array, like C<@array = ()>.
+
+This method does not define a return value.
+
+This method does not accept any arguments.
+
+=item * B<accessor($index)>
+
+=item * B<accessor($index, $value)>
+
+This method provides a get/set accessor for the array, based on array indexes.
+If passed one argument, it returns the value at the specified index. If
+passed two arguments, it sets the value of the specified index.
+
+When called as a setter, this method returns the new value at C<$index>.
+
+This method accepts one or two arguments.
+
+=item * B<natatime($n)>
-=item B<meta>
+=item * B<natatime($n, $code)>
-=item B<method_provider>
+This method returns an iterator which, on each call, returns C<$n> more items
+from the array, in order, like C<natatime> from L<List::MoreUtils>. A coderef
+can optionally be provided; it will be called on each group of C<$n> elements
+in the array.
-=item B<has_method_provider>
+This method accepts one or two arguments.
=back
=head1 BUGS
-All complex software has bugs lurking in it, and this module is no
-exception. If you find a bug please either email me, or add the bug
-to cpan-RT.
+See L<Moose/BUGS> for details on reporting bugs.
=head1 AUTHOR