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