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