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