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       => 'find',
  49            first_option      => 'first',
  50            last_option       => 'last',
  51            get_option        => 'get',
  52            join_options      => 'join',
  53            count_options     => 'count',
  54            has_no_options    => '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<empty>
  85
  86 Returns a boolean value indicating whether or not the array has any elements.
  87
  88    $stuff->has_no_options ? die "No options!\n" : print "Good boy.\n";
  89
  90 =item B<find>
  91
  92 This method returns the first item matching item in the array. The matching is
  93 done with a subroutine reference you pass to this method. The reference will
  94 be called against each element in the array until one matches or all elements
  95 have been checked.
  96
  97    my $found = $stuff->find_option( sub { $_[0] =~ /^b/ } );
  98    print "$found\n"; # prints "bar"
  99
 100 =item B<grep>
 101
 102 This method returns every element matching a given criteria, just like Perl's
 103 core C<grep> function. This method requires a subroutine which implements the
 104 matching logic.
 105
 106    my @found = $stuff->filter_options( sub { $_[0] =~ /^b/ } );
 107    print "@found\n"; # prints "bar baz boo"
 108
 109 =item B<map>
 110
 111 This method transforms every element in the array and returns a new array,
 112 just like Perl's core C<map> function. This method requires a subroutine which
 113 implements the transformation.
 114
 115    my @mod_options = $stuff->map_options( sub { $_[0] . "-tag" } );
 116    print "@mod_options\n"; # prints "foo-tag bar-tag baz-tag boo-tag"
 117
 118 =item B<sort>
 119
 120 Returns a the array in sorted order.
 121
 122 You can provide an optional subroutine reference to sort with (as you can with
 123 Perl's core C<sort> function). However, instead of using C<$a> and C<$b>, you
 124 will need to use C<$_[0]> and C<$_[1]> instead.
 125
 126    # ascending ASCIIbetical
 127    my @sorted = $stuff->sort_options();
 128
 129    # Descending alphabetical order
 130    my @sorted_options = $stuff->sort_options( sub { lc $_[1] cmp lc $_[0] } );
 131    print "@sorted_options\n"; # prints "foo boo baz bar"
 132
 133 =item B<elements>
 134
 135 Returns all of the elements of the array.
 136
 137    my @option = $stuff->all_options;
 138    print "@options\n"; # prints "foo bar baz boo"
 139
 140 =item B<join>
 141
 142 Joins every element of the array using the separator given as argument, just
 143 like Perl's core C<join> function.
 144
 145    my $joined = $stuff->join_options( ':' );
 146    print "$joined\n"; # prints "foo:bar:baz:boo"
 147
 148 =item B<get>
 149
 150 Returns an element of the array by its index. You can also use negative index
 151 numbers, just as with Perl's core array handling.
 152
 153    my $option = $stuff->get_option(1);
 154    print "$option\n"; # prints "bar"
 155
 156 =item B<first>
 157
 158 Returns the first element of the array.
 159
 160    my $first = $stuff->first_option;
 161    print "$first\n"; # prints "foo"
 162
 163 =item B<last>
 164
 165 Returns the last element of the array.
 166
 167    my $last = $stuff->last_option;
 168    print "$last\n"; # prints "boo"
 169
 170 =item B<pop>
 171
 172 =item B<push>
 173
 174 =item B<set>
 175
 176 =item B<shift>
 177
 178 =item B<unshift>
 179
 180 =item B<clear>
 181
 182 =item B<delete>
 183
 184 =item B<insert>
 185
 186 =item B<splice>
 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<accessor>
 197
 198 This method provides a get/set accessor for the array, based on array indexes.
 199 If passed one argument, it returns the value at the specified index.  If
 200 passed two arguments, it sets the value of the specified index.
 201
 202 =back
 203
 204 =head1 METHODS
 205
 206 =over 4
 207
 208 =item B<meta>
 209
 210 =item B<method_provider>
 211
 212 =item B<has_method_provider>
 213
 214 =back
 215
 216 =head1 BUGS
 217
 218 All complex software has bugs lurking in it, and this module is no
 219 exception. If you find a bug please either email me, or add the bug
 220 to cpan-RT.
 221
 222 =head1 AUTHOR
 223
 224 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 225
 226 =head1 COPYRIGHT AND LICENSE
 227
 228 Copyright 2007-2009 by Infinity Interactive, Inc.
 229
 230 L<http://www.iinteractive.com>
 231
 232 This library is free software; you can redistribute it and/or modify
 233 it under the same terms as Perl itself.
 234
 235 =cut