lib/Moose/Meta/Attribute/Native/Trait/Array.pm

   1
   2 package Moose::Meta::Attribute::Native::Trait::Array;
   3 use Moose::Role;
   4
   5 our $VERSION   = '1.15';
   6 $VERSION = eval $VERSION;
   7 our $AUTHORITY = 'cpan:STEVAN';
   8
   9 use Moose::Meta::Method::Accessor::Native::Array::accessor;
  10 use Moose::Meta::Method::Accessor::Native::Array::clear;
  11 use Moose::Meta::Method::Accessor::Native::Array::count;
  12 use Moose::Meta::Method::Accessor::Native::Array::delete;
  13 use Moose::Meta::Method::Accessor::Native::Array::elements;
  14 use Moose::Meta::Method::Accessor::Native::Array::first;
  15 use Moose::Meta::Method::Accessor::Native::Array::get;
  16 use Moose::Meta::Method::Accessor::Native::Array::grep;
  17 use Moose::Meta::Method::Accessor::Native::Array::insert;
  18 use Moose::Meta::Method::Accessor::Native::Array::is_empty;
  19 use Moose::Meta::Method::Accessor::Native::Array::join;
  20 use Moose::Meta::Method::Accessor::Native::Array::map;
  21 use Moose::Meta::Method::Accessor::Native::Array::natatime;
  22 use Moose::Meta::Method::Accessor::Native::Array::pop;
  23 use Moose::Meta::Method::Accessor::Native::Array::push;
  24 use Moose::Meta::Method::Accessor::Native::Array::reduce;
  25 use Moose::Meta::Method::Accessor::Native::Array::set;
  26 use Moose::Meta::Method::Accessor::Native::Array::shift;
  27 use Moose::Meta::Method::Accessor::Native::Array::shuffle;
  28 use Moose::Meta::Method::Accessor::Native::Array::splice;
  29 use Moose::Meta::Method::Accessor::Native::Array::sort;
  30 use Moose::Meta::Method::Accessor::Native::Array::sort_in_place;
  31 use Moose::Meta::Method::Accessor::Native::Array::uniq;
  32 use Moose::Meta::Method::Accessor::Native::Array::unshift;
  33
  34 with 'Moose::Meta::Attribute::Native::Trait';
  35
  36 sub _helper_type { 'ArrayRef' }
  37
  38 no Moose::Role;
  39
  40 1;
  41
  42 __END__
  43
  44 =pod
  45
  46 =head1 NAME
  47
  48 Moose::Meta::Attribute::Native::Trait::Array - Helper trait for ArrayRef attributes
  49
  50 =head1 SYNOPSIS
  51
  52     package Stuff;
  53     use Moose;
  54
  55     has 'options' => (
  56        traits     => ['Array'],
  57        is         => 'ro',
  58        isa        => 'ArrayRef[Str]',
  59        default    => sub { [] },
  60        handles    => {
  61            all_options    => 'elements',
  62            add_option     => 'push',
  63            map_options    => 'map',
  64            filter_options => 'grep',
  65            find_option    => 'first',
  66            get_option     => 'get',
  67            join_options   => 'join',
  68            count_options  => 'count',
  69            has_options    => 'count',
  70            has_no_options => 'is_empty',
  71            sorted_options => 'sort',
  72        },
  73     );
  74
  75     no Moose;
  76     1;
  77
  78 =head1 DESCRIPTION
  79
  80 This module provides an Array attribute which provides a number of
  81 array operations.
  82
  83 =head1 PROVIDED METHODS
  84
  85 =over 4
  86
  87 =item B<count>
  88
  89 Returns the number of elements in the array.
  90
  91    $stuff = Stuff->new;
  92    $stuff->options(["foo", "bar", "baz", "boo"]);
  93
  94    my $count = $stuff->count_options;
  95    print "$count\n"; # prints 4
  96
  97 =item B<is_empty>
  98
  99 Returns a boolean value that is true when the array has no elements.
 100
 101    $stuff->has_no_options ? die "No options!\n" : print "Good boy.\n";
 102
 103 =item B<elements>
 104
 105 Returns all of the elements of the array.
 106
 107    my @option = $stuff->all_options;
 108    print "@options\n"; # prints "foo bar baz boo"
 109
 110 =item B<get($index)>
 111
 112 Returns an element of the array by its index. You can also use negative index
 113 numbers, just as with Perl's core array handling.
 114
 115    my $option = $stuff->get_option(1);
 116    print "$option\n"; # prints "bar"
 117
 118 =item B<pop>
 119
 120 =item B<push($value1, $value2, value3 ...)>
 121
 122 =item B<shift>
 123
 124 =item B<unshift($value1, $value2, value3 ...)>
 125
 126 =item B<splice($offset, $length, @values)>
 127
 128 These methods are all equivalent to the Perl core functions of the same name.
 129
 130 =item B<first( sub { ... } )>
 131
 132 This method returns the first item matching item in the array, just like
 133 L<List::Util>'s C<first> function. The matching is done with a subroutine
 134 reference you pass to this method. The reference will be called against each
 135 element in the array until one matches or all elements have been checked.
 136
 137    my $found = $stuff->find_option( sub { /^b/ } );
 138    print "$found\n"; # prints "bar"
 139
 140 =item B<grep( sub { ... } )>
 141
 142 This method returns every element matching a given criteria, just like Perl's
 143 core C<grep> function. This method requires a subroutine which implements the
 144 matching logic.
 145
 146    my @found = $stuff->filter_options( sub { /^b/ } );
 147    print "@found\n"; # prints "bar baz boo"
 148
 149 =item B<map( sub { ... } )>
 150
 151 This method transforms every element in the array and returns a new array,
 152 just like Perl's core C<map> function. This method requires a subroutine which
 153 implements the transformation.
 154
 155    my @mod_options = $stuff->map_options( sub { $_ . "-tag" } );
 156    print "@mod_options\n"; # prints "foo-tag bar-tag baz-tag boo-tag"
 157
 158 =item B<reduce( sub { ... } )>
 159
 160 This method condenses an array into a single value, by passing a function the
 161 value so far and the next value in the array, just like L<List::Util>'s
 162 C<reduce> function. The reducing is done with a subroutine reference you pass
 163 to this method.
 164
 165    my $found = $stuff->reduce_options( sub { $_[0] . $_[1] } );
 166    print "$found\n"; # prints "foobarbazboo"
 167
 168 =item B<sort( sub { ... } )>
 169
 170 Returns a the array in sorted order.
 171
 172 You can provide an optional subroutine reference to sort with (as you can with
 173 Perl's core C<sort> function). However, instead of using C<$a> and C<$b>, you
 174 will need to use C<$_[0]> and C<$_[1]> instead.
 175
 176    # ascending ASCIIbetical
 177    my @sorted = $stuff->sort_options();
 178
 179    # Descending alphabetical order
 180    my @sorted_options = $stuff->sort_options( sub { lc $_[1] cmp lc $_[0] } );
 181    print "@sorted_options\n"; # prints "foo boo baz bar"
 182
 183 =item B<sort_in_place>
 184
 185 Sorts the array I<in place>, modifying the value of the attribute.
 186
 187 You can provide an optional subroutine reference to sort with (as you can with
 188 Perl's core C<sort> function). However, instead of using C<$a> and C<$b>, you
 189 will need to use C<$_[0]> and C<$_[1]> instead.
 190
 191 =item B<shuffle>
 192
 193 Returns the array, with indices in random order, like C<shuffle> from
 194 L<List::Util>.
 195
 196 =item B<uniq>
 197
 198 Returns the array, with all duplicate elements removed, like C<uniq> from
 199 L<List::MoreUtils>.
 200
 201 =item B<join($str)>
 202
 203 Joins every element of the array using the separator given as argument, just
 204 like Perl's core C<join> function.
 205
 206    my $joined = $stuff->join_options( ':' );
 207    print "$joined\n"; # prints "foo:bar:baz:boo"
 208
 209 =item B<set($index, $value)>
 210
 211 Given an index and a value, sets the specified array element's value.
 212
 213 =item B<delete($index)>
 214
 215 Removes the element at the given index from the array.
 216
 217 =item B<insert($index, $value)>
 218
 219 Inserts a new element into the array at the given index.
 220
 221 =item B<clear>
 222
 223 Empties the entire array, like C<@array = ()>.
 224
 225 =item B<accessor>
 226
 227 This method provides a get/set accessor for the array, based on array indexes.
 228 If passed one argument, it returns the value at the specified index.  If
 229 passed two arguments, it sets the value of the specified index.
 230
 231 =item B<natatime($n, $code)>
 232
 233 This method returns an iterator which, on each call, returns C<$n> more items
 234 from the array, in order, like C<natatime> from L<List::MoreUtils>. A coderef
 235 can optionally be provided; it will be called on each group of C<$n> elements
 236 in the array.
 237
 238 =back
 239
 240 =head1 METHODS
 241
 242 =over 4
 243
 244 =item B<meta>
 245
 246 =back
 247
 248 =head1 BUGS
 249
 250 See L<Moose/BUGS> for details on reporting bugs.
 251
 252 =head1 AUTHOR
 253
 254 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 255
 256 =head1 COPYRIGHT AND LICENSE
 257
 258 Copyright 2007-2009 by Infinity Interactive, Inc.
 259
 260 L<http://www.iinteractive.com>
 261
 262 This library is free software; you can redistribute it and/or modify
 263 it under the same terms as Perl itself.
 264
 265 =cut