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 indicating whether or not the array has any 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. The matching is
 118 done with a subroutine reference you pass to this method. The reference will
 119 be called against each element in the array until one matches or all elements
 120 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<sort( sub { ... } )>
 144
 145 Returns a the array in sorted order.
 146
 147 You can provide an optional subroutine reference to sort with (as you can with
 148 Perl's core C<sort> function). However, instead of using C<$a> and C<$b>, you
 149 will need to use C<$_[0]> and C<$_[1]> instead.
 150
 151    # ascending ASCIIbetical
 152    my @sorted = $stuff->sort_options();
 153
 154    # Descending alphabetical order
 155    my @sorted_options = $stuff->sort_options( sub { lc $_[1] cmp lc $_[0] } );
 156    print "@sorted_options\n"; # prints "foo boo baz bar"
 157
 158 =item B<sort_in_place>
 159
 160 Sorts the array I<in place>, modifying the value of the attribute.
 161
 162 You can provide an optional subroutine reference to sort with (as you can with
 163 Perl's core C<sort> function). However, instead of using C<$a> and C<$b>, you
 164 will need to use C<$_[0]> and C<$_[1]> instead.
 165
 166 =item B<join($str)>
 167
 168 Joins every element of the array using the separator given as argument, just
 169 like Perl's core C<join> function.
 170
 171    my $joined = $stuff->join_options( ':' );
 172    print "$joined\n"; # prints "foo:bar:baz:boo"
 173
 174 =item B<set($index, $value)>
 175
 176 Given an index and a value, sets the specified array element's value.
 177
 178 =item B<delete($index)>
 179
 180 Removes the element at the given index from the array.
 181
 182 =item B<insert($index, $value)>
 183
 184 Inserts a new element into the array at the given index.
 185
 186 =item B<clear>
 187
 188 Empties the entire array, like C<@array = ()>.
 189
 190 =item B<accessor>
 191
 192 This method provides a get/set accessor for the array, based on array indexes.
 193 If passed one argument, it returns the value at the specified index.  If
 194 passed two arguments, it sets the value of the specified index.
 195
 196 =back
 197
 198 =head1 METHODS
 199
 200 =over 4
 201
 202 =item B<meta>
 203
 204 =item B<method_provider>
 205
 206 =item B<has_method_provider>
 207
 208 =back
 209
 210 =head1 BUGS
 211
 212 All complex software has bugs lurking in it, and this module is no
 213 exception. If you find a bug please either email me, or add the bug
 214 to cpan-RT.
 215
 216 =head1 AUTHOR
 217
 218 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 219
 220 =head1 COPYRIGHT AND LICENSE
 221
 222 Copyright 2007-2009 by Infinity Interactive, Inc.
 223
 224 L<http://www.iinteractive.com>
 225
 226 This library is free software; you can redistribute it and/or modify
 227 it under the same terms as Perl itself.
 228
 229 =cut