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