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.87';
   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     use Moose::AttributeHelpers;
  39
  40     has 'options' => (
  41        traits     => ['Array'],
  42        is         => 'ro',
  43        isa        => 'ArrayRef[Str]',
  44        default    => sub { [] },
  45        handles   => {
  46            all_options       => 'elements',
  47            map_options       => 'map',
  48            filter_options    => 'grep',
  49            find_option       => 'find',
  50            first_option      => 'first',
  51            last_option       => 'last',
  52            get_option        => 'get',
  53            join_options      => 'join',
  54            count_options     => 'count',
  55            do_i_have_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 If the array is populated, returns true. Otherwise, returns false.
  88
  89    $stuff->do_i_have_options ? print "Good boy.\n" : die "No options!\n" ;
  90
  91 =item B<find>
  92
  93 This method accepts a subroutine reference as its argument. That sub
  94 will receive each element of the array in turn. If it returns true for
  95 an element, that element will be returned by the C<find> method.
  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 accepts a subroutine reference as its argument. This
 103 method returns every element for which that subroutine reference
 104 returns a true value.
 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 accepts a subroutine reference as its argument. The
 112 subroutine will be executed for each element of the array. It is
 113 expected to return a modified version of that element. The return
 114 value of the method is a list of the modified options.
 115
 116    my @mod_options = $stuff->map_options( sub { $_[0] . "-tag" } );
 117    print "@mod_options\n"; # prints "foo-tag bar-tag baz-tag boo-tag"
 118
 119 =item B<sort>
 120
 121 Sorts and returns the elements of the array.
 122
 123 You can provide an optional subroutine reference to sort with (as you
 124 can with the core C<sort> function). However, instead of using C<$a>
 125 and C<$b>, you will need to use C<$_[0]> and C<$_[1]> instead.
 126
 127    # ascending ASCIIbetical
 128    my @sorted = $stuff->sort_options();
 129
 130    # Descending alphabetical order
 131    my @sorted_options = $stuff->sort_options( sub { lc $_[1] cmp lc $_[0] } );
 132    print "@sorted_options\n"; # prints "foo boo baz bar"
 133
 134 =item B<elements>
 135
 136 Returns all of the elements of the array
 137
 138    my @option = $stuff->all_options;
 139    print "@options\n"; # prints "foo bar baz boo"
 140
 141 =item B<join>
 142
 143 Joins every element of the array using the separator given as argument.
 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.
 151
 152    my $option = $stuff->get_option(1);
 153    print "$option\n"; # prints "bar"
 154
 155 =item B<first>
 156
 157 Returns the first element of the array.
 158
 159    my $first = $stuff->first_option;
 160    print "$first\n"; # prints "foo"
 161
 162 =item B<last>
 163
 164 Returns the last element of the array.
 165
 166    my $last = $stuff->last_option;
 167    print "$last\n"; # prints "boo"
 168
 169 =item B<pop>
 170
 171 =item B<push>
 172
 173 =item B<set>
 174
 175 =item B<shift>
 176
 177 =item B<unshift>
 178
 179 =item B<clear>
 180
 181 =item B<delete>
 182
 183 =item B<insert>
 184
 185 =item B<splice>
 186
 187 =item B<sort_in_place>
 188
 189 Sorts the array I<in place>, modifying the value of the attribute.
 190
 191 You can provide an optional subroutine reference to sort with (as you
 192 can with the core C<sort> function). However, instead of using C<$a>
 193 and C<$b>, you will need to use C<$_[0]> and C<$_[1]> instead.
 194
 195 =item B<accessor>
 196
 197 If passed one argument, returns the value of the requested element.
 198 If passed two arguments, sets the value of the requested element.
 199
 200 =back
 201
 202 =head1 METHODS
 203
 204 =over 4
 205
 206 =item B<meta>
 207
 208 =item B<method_provider>
 209
 210 =item B<has_method_provider>
 211
 212 =back
 213
 214 =head1 BUGS
 215
 216 All complex software has bugs lurking in it, and this module is no
 217 exception. If you find a bug please either email me, or add the bug
 218 to cpan-RT.
 219
 220 =head1 AUTHOR
 221
 222 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 223
 224 =head1 COPYRIGHT AND LICENSE
 225
 226 Copyright 2007-2009 by Infinity Interactive, Inc.
 227
 228 L<http://www.iinteractive.com>
 229
 230 This library is free software; you can redistribute it and/or modify
 231 it under the same terms as Perl itself.
 232
 233 =cut