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
  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            do_i_have_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 If the array is populated, returns true. Otherwise, returns false.
  87
  88    $stuff->do_i_have_options ? print "Good boy.\n" : die "No options!\n" ;
  89
  90 =item B<find>
  91
  92 This method accepts a subroutine reference as its argument. That sub
  93 will receive each element of the array in turn. If it returns true for
  94 an element, that element will be returned by the C<find> method.
  95
  96    my $found = $stuff->find_option( sub { $_[0] =~ /^b/ } );
  97    print "$found\n"; # prints "bar"
  98
  99 =item B<grep>
 100
 101 This method accepts a subroutine reference as its argument. This
 102 method returns every element for which that subroutine reference
 103 returns a true value.
 104
 105    my @found = $stuff->filter_options( sub { $_[0] =~ /^b/ } );
 106    print "@found\n"; # prints "bar baz boo"
 107
 108 =item B<map>
 109
 110 This method accepts a subroutine reference as its argument. The
 111 subroutine will be executed for each element of the array. It is
 112 expected to return a modified version of that element. The return
 113 value of the method is a list of the modified options.
 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 Sorts and returns the elements of the array.
 121
 122 You can provide an optional subroutine reference to sort with (as you
 123 can with the core C<sort> function). However, instead of using C<$a>
 124 and C<$b>, you 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.
 143
 144    my $joined = $stuff->join_options( ':' );
 145    print "$joined\n"; # prints "foo:bar:baz:boo"
 146
 147 =item B<get>
 148
 149 Returns an element of the array by its index.
 150
 151    my $option = $stuff->get_option(1);
 152    print "$option\n"; # prints "bar"
 153
 154 =item B<first>
 155
 156 Returns the first element of the array.
 157
 158    my $first = $stuff->first_option;
 159    print "$first\n"; # prints "foo"
 160
 161 =item B<last>
 162
 163 Returns the last element of the array.
 164
 165    my $last = $stuff->last_option;
 166    print "$last\n"; # prints "boo"
 167
 168 =item B<pop>
 169
 170 =item B<push>
 171
 172 =item B<set>
 173
 174 =item B<shift>
 175
 176 =item B<unshift>
 177
 178 =item B<clear>
 179
 180 =item B<delete>
 181
 182 =item B<insert>
 183
 184 =item B<splice>
 185
 186 =item B<sort_in_place>
 187
 188 Sorts the array I<in place>, modifying the value of the attribute.
 189
 190 You can provide an optional subroutine reference to sort with (as you
 191 can with the core C<sort> function). However, instead of using C<$a>
 192 and C<$b>, you will need to use C<$_[0]> and C<$_[1]> instead.
 193
 194 =item B<accessor>
 195
 196 If passed one argument, returns the value of the requested element.
 197 If passed two arguments, sets the value of the requested element.
 198
 199 =back
 200
 201 =head1 METHODS
 202
 203 =over 4
 204
 205 =item B<meta>
 206
 207 =item B<method_provider>
 208
 209 =item B<has_method_provider>
 210
 211 =back
 212
 213 =head1 BUGS
 214
 215 All complex software has bugs lurking in it, and this module is no
 216 exception. If you find a bug please either email me, or add the bug
 217 to cpan-RT.
 218
 219 =head1 AUTHOR
 220
 221 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 222
 223 =head1 COPYRIGHT AND LICENSE
 224
 225 Copyright 2007-2009 by Infinity Interactive, Inc.
 226
 227 L<http://www.iinteractive.com>
 228
 229 This library is free software; you can redistribute it and/or modify
 230 it under the same terms as Perl itself.
 231
 232 =cut