File Coverage

blib/lib/Moose/Meta/Attribute/Native/Trait/Array.pm
Criterion Covered Total %
statement 7 7 100.0
branch n/a
condition n/a
subroutine 3 3 100.0
pod n/a
total 10 10 100.0


line stmt bran cond sub pod time code
1             package Moose::Meta::Attribute::Native::Trait::Array;
2             our $VERSION = '2.2205';
3              
4 33     33   25686 use Moose::Role;
  33         111  
  33         275  
5             with 'Moose::Meta::Attribute::Native::Trait';
6              
7 679     679   3630 sub _helper_type { 'ArrayRef' }
8              
9 33     33   297 no Moose::Role;
  33         89  
  33         203  
10              
11             1;
12              
13             # ABSTRACT: Helper trait for ArrayRef attributes
14              
15             __END__
16              
17             =pod
18              
19             =encoding UTF-8
20              
21             =head1 NAME
22              
23             Moose::Meta::Attribute::Native::Trait::Array - Helper trait for ArrayRef attributes
24              
25             =head1 VERSION
26              
27             version 2.2205
28              
29             =head1 SYNOPSIS
30              
31             package Stuff;
32             use Moose;
33              
34             has 'options' => (
35             traits => ['Array'],
36             is => 'ro',
37             isa => 'ArrayRef[Str]',
38             default => sub { [] },
39             handles => {
40             all_options => 'elements',
41             add_option => 'push',
42             map_options => 'map',
43             filter_options => 'grep',
44             find_option => 'first',
45             get_option => 'get',
46             join_options => 'join',
47             count_options => 'count',
48             has_options => 'count',
49             has_no_options => 'is_empty',
50             sorted_options => 'sort',
51             },
52             );
53              
54             no Moose;
55             1;
56              
57             =head1 DESCRIPTION
58              
59             This trait provides native delegation methods for array references.
60              
61             =head1 DEFAULT TYPE
62              
63             If you don't provide an C<isa> value for your attribute, it will default to
64             C<ArrayRef>.
65              
66             =head1 PROVIDED METHODS
67              
68             =over 4
69              
70             =item * B<count>
71              
72             Returns the number of elements in the array.
73              
74             $stuff = Stuff->new;
75             $stuff->options( [ "foo", "bar", "baz", "boo" ] );
76              
77             print $stuff->count_options; # prints 4
78              
79             This method does not accept any arguments.
80              
81             =item * B<is_empty>
82              
83             Returns a boolean value that is true when the array has no elements.
84              
85             $stuff->has_no_options ? die "No options!\n" : print "Good boy.\n";
86              
87             This method does not accept any arguments.
88              
89             =item * B<elements>
90              
91             In list context, returns all of the elements of the array as a list.
92              
93             In scalar context, returns the number of elements in the array.
94              
95             my @options = $stuff->all_options;
96             print "@options"; # prints "foo bar baz boo"
97             print scalar $stuff->all_options; # prints 4
98              
99             This method does not accept any arguments.
100              
101             =item * B<get($index)>
102              
103             Returns an element of the array by its index. You can also use negative index
104             numbers, just as with Perl's core array handling.
105              
106             my $option = $stuff->get_option(1);
107             print "$option\n"; # prints "bar"
108              
109             If the specified element does not exist, this will return C<undef>.
110              
111             This method accepts just one argument.
112              
113             =item * B<pop>
114              
115             Just like Perl's builtin C<pop>.
116              
117             This method does not accept any arguments.
118              
119             =item * B<push($value1, $value2, value3 ...)>
120              
121             Just like Perl's builtin C<push>. Returns the number of elements in the new
122             array.
123              
124             This method accepts any number of arguments.
125              
126             =item * B<shift>
127              
128             Just like Perl's builtin C<shift>.
129              
130             This method does not accept any arguments.
131              
132             =item * B<unshift($value1, $value2, value3 ...)>
133              
134             Just like Perl's builtin C<unshift>. Returns the number of elements in the new
135             array.
136              
137             This method accepts any number of arguments.
138              
139             =item * B<splice($offset, $length, @values)>
140              
141             Just like Perl's builtin C<splice>. In scalar context, this returns the last
142             element removed, or C<undef> if no elements were removed. In list context,
143             this returns all the elements removed from the array.
144              
145             This method requires at least one argument.
146              
147             =item * B<first( sub { ... } )>
148              
149             This method returns the first matching item in the array, just like
150             L<List::Util>'s C<first> function. The matching is done with a subroutine
151             reference you pass to this method. The subroutine will be called against each
152             element in the array until one matches or all elements have been checked.
153             Each list element will be available to the sub in C<$_>.
154              
155             my $found = $stuff->find_option( sub {/^b/} );
156             print "$found\n"; # prints "bar"
157              
158             This method requires a single argument.
159              
160             =item * B<first_index( sub { ... } )>
161              
162             This method returns the index of the first matching item in the array, just
163             like L<List::SomeUtils/first_index>. The matching is done with a
164             subroutine reference you pass to this method. The subroutine will be called
165             against each element in the array until one matches or all elements have been
166             checked. Each list element will be available to the sub in C<$_>.
167             If no match is made, -1 is returned.
168              
169             This method requires a single argument.
170              
171             =item * B<grep( sub { ... } )>
172              
173             This method returns every element matching a given criteria, just like Perl's
174             core C<grep> function. This method requires a subroutine which implements the
175             matching logic; each list element will be available to the sub in C<$_>.
176              
177             my @found = $stuff->filter_options( sub {/^b/} );
178             print "@found\n"; # prints "bar baz boo"
179              
180             This method requires a single argument.
181              
182             =item * B<map( sub { ... } )>
183              
184             This method transforms every element in the array and returns a new array,
185             just like Perl's core C<map> function. This method requires a subroutine which
186             implements the transformation; each list element will be available to the sub
187             in C<$_>.
188              
189             my @mod_options = $stuff->map_options( sub { $_ . "-tag" } );
190             print "@mod_options\n"; # prints "foo-tag bar-tag baz-tag boo-tag"
191              
192             This method requires a single argument.
193              
194             =item * B<reduce( sub { ... } )>
195              
196             This method turns an array into a single value, by passing a function the
197             value so far and the next value in the array, just like L<List::Util>'s
198             C<reduce> function. The reducing is done with a subroutine reference you pass
199             to this method; each list element will be available to the sub in C<$_>.
200              
201             my $found = $stuff->reduce_options( sub { $_[0] . $_[1] } );
202             print "$found\n"; # prints "foobarbazboo"
203              
204             This method requires a single argument.
205              
206             =item * B<sort>
207              
208             =item * B<sort( sub { ... } )>
209              
210             Returns the elements of the array (not an array reference) in sorted order,
211             or, like C<elements>, returns the number of elements in the array in scalar context.
212              
213             You can provide an optional subroutine reference to sort with (as you can with
214             Perl's core C<sort> function). However, instead of using C<$a> and C<$b> in
215             this subroutine, you will need to use C<$_[0]> and C<$_[1]>.
216              
217             # ascending ASCIIbetical
218             my @sorted = $stuff->sort_options();
219              
220             # Descending alphabetical order
221             my @sorted_options = $stuff->sort_options( sub { lc $_[1] cmp lc $_[0] } );
222             print "@sorted_options\n"; # prints "foo boo baz bar"
223              
224             This method accepts a single argument.
225              
226             =item * B<sort_in_place>
227              
228             =item * B<sort_in_place( sub { ... } )>
229              
230             Sorts the array I<in place>, modifying the value of the attribute.
231              
232             You can provide an optional subroutine reference to sort with (as you can with
233             Perl's core C<sort> function). However, instead of using C<$a> and C<$b>, you
234             will need to use C<$_[0]> and C<$_[1]> instead.
235              
236             This method does not define a return value.
237              
238             This method accepts a single argument.
239              
240             =item * B<shuffle>
241              
242             Returns the elements of the array in random order, like C<shuffle> from
243             L<List::Util>.
244              
245             This method does not accept any arguments.
246              
247             =item * B<uniq>
248              
249             Returns the array with all duplicate elements removed, like L<List::Util/uniq>.
250              
251             This method does not accept any arguments.
252              
253             =item * B<join($str)>
254              
255             Joins every element of the array using the separator given as argument, just
256             like Perl's core C<join> function.
257              
258             my $joined = $stuff->join_options(':');
259             print "$joined\n"; # prints "foo:bar:baz:boo"
260              
261             This method requires a single argument.
262              
263             =item * B<set($index, $value)>
264              
265             Given an index and a value, sets the specified array element's value.
266              
267             This method returns the value at C<$index> after the set.
268              
269             This method requires two arguments.
270              
271             =item * B<delete($index)>
272              
273             Removes the element at the given index from the array.
274              
275             This method returns the deleted value. Note that if no value exists, it will
276             return C<undef>.
277              
278             This method requires one argument.
279              
280             =item * B<insert($index, $value)>
281              
282             Inserts a new element into the array at the given index.
283              
284             This method returns the new value at C<$index>.
285              
286             This method requires two arguments.
287              
288             =item * B<clear>
289              
290             Empties the entire array, like C<@array = ()>.
291              
292             This method does not define a return value.
293              
294             This method does not accept any arguments.
295              
296             =item * B<accessor($index)>
297              
298             =item * B<accessor($index, $value)>
299              
300             This method provides a get/set accessor for the array, based on array indexes.
301             If passed one argument, it returns the value at the specified index. If
302             passed two arguments, it sets the value of the specified index.
303              
304             When called as a setter, this method returns the new value at C<$index>.
305              
306             This method accepts one or two arguments.
307              
308             =item * B<natatime($n)>
309              
310             =item * B<natatime($n, $code)>
311              
312             This method returns an iterator which, on each call, returns C<$n> more items
313             from the array, in order, like L<List::SomeUtils/natatime>.
314              
315             If you pass a coderef as the second argument, then this code ref will be
316             called on each group of C<$n> elements in the array until the array is
317             exhausted.
318              
319             This method accepts one or two arguments.
320              
321             =item * B<shallow_clone>
322              
323             This method returns a shallow clone of the array reference. The return value
324             is a reference to a new array with the same elements. It is I<shallow>
325             because any elements that were references in the original will be the I<same>
326             references in the clone.
327              
328             =back
329              
330             =head1 BUGS
331              
332             See L<Moose/BUGS> for details on reporting bugs.
333              
334             =head1 AUTHORS
335              
336             =over 4
337              
338             =item *
339              
340             Stevan Little <stevan@cpan.org>
341              
342             =item *
343              
344             Dave Rolsky <autarch@urth.org>
345              
346             =item *
347              
348             Jesse Luehrs <doy@cpan.org>
349              
350             =item *
351              
352             Shawn M Moore <sartak@cpan.org>
353              
354             =item *
355              
356             יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
357              
358             =item *
359              
360             Karen Etheridge <ether@cpan.org>
361              
362             =item *
363              
364             Florian Ragwitz <rafl@debian.org>
365              
366             =item *
367              
368             Hans Dieter Pearcey <hdp@cpan.org>
369              
370             =item *
371              
372             Chris Prather <chris@prather.org>
373              
374             =item *
375              
376             Matt S Trout <mstrout@cpan.org>
377              
378             =back
379              
380             =head1 COPYRIGHT AND LICENSE
381              
382             This software is copyright (c) 2006 by Infinity Interactive, Inc.
383              
384             This is free software; you can redistribute it and/or modify it under
385             the same terms as the Perl 5 programming language system itself.
386              
387             =cut