X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMoose%2FMeta%2FAttribute%2FNative%2FTrait%2FArray.pm;h=a7046a2e51e75a40653bee5f5a066b4e82c09192;hb=e4fdfb589a1c4b66e5cbb3098d1137e1715a3261;hp=5f9b8e92d967a6c7444a3a32639ab4005bfa95e6;hpb=276828facdc18a4702606e51d475ce7cd6643ac8;p=gitmo%2FMoose.git

diff --git a/lib/Moose/Meta/Attribute/Native/Trait/Array.pm b/lib/Moose/Meta/Attribute/Native/Trait/Array.pm
index 5f9b8e9..a7046a2 100644
--- a/lib/Moose/Meta/Attribute/Native/Trait/Array.pm
+++ b/lib/Moose/Meta/Attribute/Native/Trait/Array.pm
@@ -2,56 +2,43 @@
 package Moose::Meta::Attribute::Native::Trait::Array;
 use Moose::Role;
 
-our $VERSION   = '0.89_01';
-$VERSION = eval $VERSION;
-our $AUTHORITY = 'cpan:STEVAN';
-
-use Moose::Meta::Attribute::Native::MethodProvider::Array;
-
 with 'Moose::Meta::Attribute::Native::Trait';
 
-has 'method_provider' => (
-    is        => 'ro',
-    isa       => 'ClassName',
-    predicate => 'has_method_provider',
-    default   => 'Moose::Meta::Attribute::Native::MethodProvider::Array'
-);
-
 sub _helper_type { 'ArrayRef' }
 
 no Moose::Role;
 
 1;
 
+# ABSTRACT: Helper trait for ArrayRef attributes
+
 __END__
 
 =pod
 
-=head1 NAME
-
-Moose::Meta::Attribute::Native::Trait::Array
-
 =head1 SYNOPSIS
 
     package Stuff;
     use Moose;
 
     has 'options' => (
-       traits     => ['Array'],
-       is         => 'ro',
-       isa        => 'ArrayRef[Str]',
-       default    => sub { [] },
-       handles    => {
-           all_options    => 'elements',
-           map_options    => 'map',
-           filter_options => 'grep',
-           find_option    => 'first',
-           get_option     => 'get',
-           join_options   => 'join',
-           count_options  => 'count',
-           has_no_options => 'is_empty',
-           sorted_options => 'sort',
-       },
+        traits  => ['Array'],
+        is      => 'ro',
+        isa     => 'ArrayRef[Str]',
+        default => sub { [] },
+        handles => {
+            all_options    => 'elements',
+            add_option     => 'push',
+            map_options    => 'map',
+            filter_options => 'grep',
+            find_option    => 'first',
+            get_option     => 'get',
+            join_options   => 'join',
+            count_options  => 'count',
+            has_options    => 'count',
+            has_no_options => 'is_empty',
+            sorted_options => 'sort',
+        },
     );
 
     no Moose;
@@ -59,113 +46,169 @@ Moose::Meta::Attribute::Native::Trait::Array
 
 =head1 DESCRIPTION
 
-This module provides an Array attribute which provides a number of
-array operations.
+This trait provides native delegation methods for array references.
 
-=head1 PROVIDED METHODS
+=head1 DEFAULT TYPE
 
-These methods are implemented in
-L<Moose::Meta::Attribute::Native::MethodProvider::Array>.
+If you don't provide an C<isa> value for your attribute, it will default to
+C<ArrayRef>.
+
+=head1 PROVIDED METHODS
 
 =over 4
 
-=item B<count>
+=item * B<count>
 
 Returns the number of elements in the array.
 
-   $stuff = Stuff->new;
-   $stuff->options(["foo", "bar", "baz", "boo"]);
+  $stuff = Stuff->new;
+  $stuff->options( [ "foo", "bar", "baz", "boo" ] );
+
+  print $stuff->count_options; # prints 4
 
-   my $count = $stuff->count_options;
-   print "$count\n"; # prints 4
+This method does not accept any arguments.
 
-=item B<is_empty>
+=item * B<is_empty>
 
 Returns a boolean value that is true when the array has no elements.
 
-   $stuff->has_no_options ? die "No options!\n" : print "Good boy.\n";
+  $stuff->has_no_options ? die "No options!\n" : print "Good boy.\n";
+
+This method does not accept any arguments.
+
+=item * B<elements>
 
-=item B<elements>
+Returns all of the elements of the array as an array (not an array reference).
 
-Returns all of the elements of the array.
+  my @option = $stuff->all_options;
+  print "@options\n";    # prints "foo bar baz boo"
 
-   my @option = $stuff->all_options;
-   print "@options\n"; # prints "foo bar baz boo"
+This method does not accept any arguments.
 
-=item B<get($index)>
+=item * B<get($index)>
 
 Returns an element of the array by its index. You can also use negative index
 numbers, just as with Perl's core array handling.
 
-   my $option = $stuff->get_option(1);
-   print "$option\n"; # prints "bar"
+  my $option = $stuff->get_option(1);
+  print "$option\n";    # prints "bar"
+
+If the specified element does not exist, this will return C<undef>.
+
+This method accepts just one argument.
+
+=item * B<pop>
 
-=item B<pop>
+Just like Perl's builtin C<pop>.
 
-=item B<push($value)>
+This method does not accept any arguments.
 
-=item B<shift>
+=item * B<push($value1, $value2, value3 ...)>
 
-=item B<unshift($value)>
+Just like Perl's builtin C<push>. Returns the number of elements in the new
+array.
 
-=item B<splice($offset, $length, @values)>
+This method accepts any number of arguments.
 
-These methods are all equivalent to the Perl core functions of the same name.
+=item * B<shift>
 
-=item B<first( sub { ... } )>
+Just like Perl's builtin C<shift>.
 
-This method returns the first item matching item in the array, just like
+This method does not accept any arguments.
+
+=item * B<unshift($value1, $value2, value3 ...)>
+
+Just like Perl's builtin C<unshift>. Returns the number of elements in the new
+array.
+
+This method accepts any number of arguments.
+
+=item * B<splice($offset, $length, @values)>
+
+Just like Perl's builtin C<splice>. In scalar context, this returns the last
+element removed, or C<undef> if no elements were removed. In list context,
+this returns all the elements removed from the array.
+
+This method requires at least one argument.
+
+=item * B<first( sub { ... } )>
+
+This method returns the first matching item in the array, just like
 L<List::Util>'s C<first> function. The matching is done with a subroutine
-reference you pass to this method. The reference will be called against each
+reference you pass to this method. The subroutine will be called against each
 element in the array until one matches or all elements have been checked.
 
-   my $found = $stuff->find_option( sub { /^b/ } );
-   print "$found\n"; # prints "bar"
+  my $found = $stuff->find_option( sub {/^b/} );
+  print "$found\n";    # prints "bar"
 
-=item B<grep( sub { ... } )>
+This method requires a single argument.
+
+=item * B<first_index( sub { ... } )>
+
+This method returns the index of the first matching item in the array, just
+like L<List::MoreUtils>'s C<first_index> function. The matching is done with a
+subroutine reference you pass to this method. The subroutine will be called
+against each element in the array until one matches or all elements have been
+checked.
+
+This method requires a single argument.
+
+=item * B<grep( sub { ... } )>
 
 This method returns every element matching a given criteria, just like Perl's
 core C<grep> function. This method requires a subroutine which implements the
 matching logic.
 
-   my @found = $stuff->filter_options( sub { /^b/ } );
-   print "@found\n"; # prints "bar baz boo"
+  my @found = $stuff->filter_options( sub {/^b/} );
+  print "@found\n";    # prints "bar baz boo"
 
-=item B<map( sub { ... } )>
+This method requires a single argument.
+
+=item * B<map( sub { ... } )>
 
 This method transforms every element in the array and returns a new array,
 just like Perl's core C<map> function. This method requires a subroutine which
 implements the transformation.
 
-   my @mod_options = $stuff->map_options( sub { $_ . "-tag" } );
-   print "@mod_options\n"; # prints "foo-tag bar-tag baz-tag boo-tag"
+  my @mod_options = $stuff->map_options( sub { $_ . "-tag" } );
+  print "@mod_options\n";    # prints "foo-tag bar-tag baz-tag boo-tag"
+
+This method requires a single argument.
 
-=item B<reduce( sub { ... } )>
+=item * B<reduce( sub { ... } )>
 
-This method condenses an array into a single value, by passing a function the
+This method turns an array into a single value, by passing a function the
 value so far and the next value in the array, just like L<List::Util>'s
 C<reduce> function. The reducing is done with a subroutine reference you pass
 to this method.
 
-   my $found = $stuff->reduce_options( sub { $_[0] . $_[1] } );
-   print "$found\n"; # prints "foobarbazboo"
+  my $found = $stuff->reduce_options( sub { $_[0] . $_[1] } );
+  print "$found\n";    # prints "foobarbazboo"
+
+This method requires a single argument.
 
-=item B<sort( sub { ... } )>
+=item * B<sort>
 
-Returns a the array in sorted order.
+=item * B<sort( sub { ... } )>
+
+Returns the elements of the array in sorted order.
 
 You can provide an optional subroutine reference to sort with (as you can with
-Perl's core C<sort> function). However, instead of using C<$a> and C<$b>, you
-will need to use C<$_[0]> and C<$_[1]> instead.
+Perl's core C<sort> function). However, instead of using C<$a> and C<$b> in
+this subroutine, you will need to use C<$_[0]> and C<$_[1]>.
+
+  # ascending ASCIIbetical
+  my @sorted = $stuff->sort_options();
 
-   # ascending ASCIIbetical
-   my @sorted = $stuff->sort_options();
+  # Descending alphabetical order
+  my @sorted_options = $stuff->sort_options( sub { lc $_[1] cmp lc $_[0] } );
+  print "@sorted_options\n";    # prints "foo boo baz bar"
 
-   # Descending alphabetical order
-   my @sorted_options = $stuff->sort_options( sub { lc $_[1] cmp lc $_[0] } );
-   print "@sorted_options\n"; # prints "foo boo baz bar"
+This method accepts a single argument.
 
-=item B<sort_in_place>
+=item * B<sort_in_place>
+
+=item * B<sort_in_place( sub { ... } )>
 
 Sorts the array I<in place>, modifying the value of the attribute.
 
@@ -173,84 +216,103 @@ You can provide an optional subroutine reference to sort with (as you can with
 Perl's core C<sort> function). However, instead of using C<$a> and C<$b>, you
 will need to use C<$_[0]> and C<$_[1]> instead.
 
-=item B<shuffle>
+This method does not define a return value.
+
+This method accepts a single argument.
 
-Returns the array, with indices in random order, like C<shuffle> from
+=item * B<shuffle>
+
+Returns the elements of the array in random order, like C<shuffle> from
 L<List::Util>.
 
-=item B<uniq>
+This method does not accept any arguments.
+
+=item * B<uniq>
 
-Returns the array, with all duplicate elements removed, like C<uniq> from
+Returns the array with all duplicate elements removed, like C<uniq> from
 L<List::MoreUtils>.
 
-=item B<join($str)>
+This method does not accept any arguments.
+
+=item * B<join($str)>
 
 Joins every element of the array using the separator given as argument, just
 like Perl's core C<join> function.
 
-   my $joined = $stuff->join_options( ':' );
-   print "$joined\n"; # prints "foo:bar:baz:boo"
+  my $joined = $stuff->join_options(':');
+  print "$joined\n";    # prints "foo:bar:baz:boo"
+
+This method requires a single argument.
 
-=item B<set($index, $value)>
+=item * B<set($index, $value)>
 
 Given an index and a value, sets the specified array element's value.
 
-=item B<delete($index)>
+This method returns the value at C<$index> after the set.
+
+This method requires two arguments.
+
+=item * B<delete($index)>
 
 Removes the element at the given index from the array.
 
-=item B<insert($index, $value)>
+This method returns the deleted value. Note that if no value exists, it will
+return C<undef>.
+
+This method requires one argument.
+
+=item * B<insert($index, $value)>
 
 Inserts a new element into the array at the given index.
 
-=item B<clear>
+This method returns the new value at C<$index>.
 
-Empties the entire array, like C<@array = ()>.
+This method requires two arguments.
 
-=item B<accessor>
+=item * B<clear>
 
-This method provides a get/set accessor for the array, based on array indexes.
-If passed one argument, it returns the value at the specified index.  If
-passed two arguments, it sets the value of the specified index.
+Empties the entire array, like C<@array = ()>.
 
-=item B<natatime($n, $code)>
+This method does not define a return value.
 
-This method returns an iterator which, on each call, returns C<$n> more items
-from the array, in order, like C<natatime> from L<List::MoreUtils>. A coderef
-can optionally be provided; it will be called on each group of C<$n> elements
-in the array.
+This method does not accept any arguments.
 
-=back
+=item * B<accessor($index)>
 
-=head1 METHODS
+=item * B<accessor($index, $value)>
 
-=over 4
+This method provides a get/set accessor for the array, based on array indexes.
+If passed one argument, it returns the value at the specified index.  If
+passed two arguments, it sets the value of the specified index.
 
-=item B<meta>
+When called as a setter, this method returns the new value at C<$index>.
 
-=item B<method_provider>
+This method accepts one or two arguments.
 
-=item B<has_method_provider>
+=item * B<natatime($n)>
 
-=back
+=item * B<natatime($n, $code)>
 
-=head1 BUGS
+This method returns an iterator which, on each call, returns C<$n> more items
+from the array, in order, like C<natatime> from L<List::MoreUtils>.
 
-All complex software has bugs lurking in it, and this module is no
-exception. If you find a bug please either email me, or add the bug
-to cpan-RT.
+If you pass a coderef as the second argument, then this code ref will be
+called on each group of C<$n> elements in the array until the array is
+exhausted.
 
-=head1 AUTHOR
+This method accepts one or two arguments.
 
-Stevan Little E<lt>stevan@iinteractive.comE<gt>
+=item * B<shallow_clone>
 
-=head1 COPYRIGHT AND LICENSE
+This method returns a shallow clone of the array reference.  The return value
+is a reference to a new array with the same elements.  It is I<shallow>
+because any elements that were references in the original will be the I<same>
+references in the clone.
 
-Copyright 2007-2009 by Infinity Interactive, Inc.
+=back
 
-L<http://www.iinteractive.com>
+=head1 BUGS
 
-This library is free software; you can redistribute it and/or modify
-it under the same terms as Perl itself.
+See L<Moose/BUGS> for details on reporting bugs.
 
 =cut