From: Chris Prather Date: Sun, 9 Aug 2009 20:22:55 +0000 (-0400) Subject: update documentation for Array so I can run it past confound and doy before doing... X-Git-Tag: 0.89_02~79 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=33f819e155571b2becb24b564622ca799893914c;p=gitmo%2FMoose.git update documentation for Array so I can run it past confound and doy before doing more work --- diff --git a/lib/Moose/Meta/Attribute/Native/MethodProvider/Array.pm b/lib/Moose/Meta/Attribute/Native/MethodProvider/Array.pm index d387e78..c07cf13 100644 --- a/lib/Moose/Meta/Attribute/Native/MethodProvider/Array.pm +++ b/lib/Moose/Meta/Attribute/Native/MethodProvider/Array.pm @@ -1,7 +1,7 @@ package Moose::Meta::Attribute::Native::MethodProvider::Array; use Moose::Role; -our $VERSION = '0.87'; +our $VERSION = '0.87'; $VERSION = eval $VERSION; our $AUTHORITY = 'cpan:STEVAN'; @@ -43,7 +43,7 @@ sub sort : method { return sub { my ( $instance, $predicate ) = @_; die "Argument must be a code reference" - if $predicate && ref $predicate ne 'CODE'; + if $predicate && ref $predicate ne 'CODE'; if ($predicate) { CORE::sort { $predicate->( $a, $b ) } @{ $reader->($instance) }; @@ -99,16 +99,16 @@ sub push : method { $attr->has_type_constraint && $attr->type_constraint->isa( 'Moose::Meta::TypeConstraint::Parameterized') - ) { - my $container_type_constraint - = $attr->type_constraint->type_parameter; + ) + { + my $container_type_constraint = $attr->type_constraint->type_parameter; return sub { my $instance = CORE::shift; $container_type_constraint->check($_) - || confess "Value " - . ( $_ || 'undef' ) - . " did not pass container type constraint '$container_type_constraint'" - foreach @_; + || confess "Value " + . ( $_ || 'undef' ) + . " did not pass container type constraint '$container_type_constraint'" + foreach @_; CORE::push @{ $reader->($instance) } => @_; }; } @@ -133,16 +133,16 @@ sub unshift : method { $attr->has_type_constraint && $attr->type_constraint->isa( 'Moose::Meta::TypeConstraint::Parameterized') - ) { - my $container_type_constraint - = $attr->type_constraint->type_parameter; + ) + { + my $container_type_constraint = $attr->type_constraint->type_parameter; return sub { my $instance = CORE::shift; $container_type_constraint->check($_) - || confess "Value " - . ( $_ || 'undef' ) - . " did not pass container type constraint '$container_type_constraint'" - foreach @_; + || confess "Value " + . ( $_ || 'undef' ) + . " did not pass container type constraint '$container_type_constraint'" + foreach @_; CORE::unshift @{ $reader->($instance) } => @_; }; } @@ -174,14 +174,14 @@ sub set : method { $attr->has_type_constraint && $attr->type_constraint->isa( 'Moose::Meta::TypeConstraint::Parameterized') - ) { - my $container_type_constraint - = $attr->type_constraint->type_parameter; + ) + { + my $container_type_constraint = $attr->type_constraint->type_parameter; return sub { ( $container_type_constraint->check( $_[2] ) ) - || confess "Value " - . ( $_[2] || 'undef' ) - . " did not pass container type constraint '$container_type_constraint'"; + || confess "Value " + . ( $_[2] || 'undef' ) + . " did not pass container type constraint '$container_type_constraint'"; $reader->( $_[0] )->[ $_[1] ] = $_[2]; }; } @@ -199,9 +199,9 @@ sub accessor : method { $attr->has_type_constraint && $attr->type_constraint->isa( 'Moose::Meta::TypeConstraint::Parameterized') - ) { - my $container_type_constraint - = $attr->type_constraint->type_parameter; + ) + { + my $container_type_constraint = $attr->type_constraint->type_parameter; return sub { my $self = shift; @@ -210,9 +210,9 @@ sub accessor : method { } elsif ( @_ == 2 ) { # writer ( $container_type_constraint->check( $_[1] ) ) - || confess "Value " - . ( $_[1] || 'undef' ) - . " did not pass container type constraint '$container_type_constraint'"; + || confess "Value " + . ( $_[1] || 'undef' ) + . " did not pass container type constraint '$container_type_constraint'"; $reader->($self)->[ $_[0] ] = $_[1]; } else { @@ -248,7 +248,7 @@ sub delete : method { my ( $attr, $reader, $writer ) = @_; return sub { CORE::splice @{ $reader->( $_[0] ) }, $_[1], 1; - } + } } sub insert : method { @@ -257,14 +257,14 @@ sub insert : method { $attr->has_type_constraint && $attr->type_constraint->isa( 'Moose::Meta::TypeConstraint::Parameterized') - ) { - my $container_type_constraint - = $attr->type_constraint->type_parameter; + ) + { + my $container_type_constraint = $attr->type_constraint->type_parameter; return sub { ( $container_type_constraint->check( $_[2] ) ) - || confess "Value " - . ( $_[2] || 'undef' ) - . " did not pass container type constraint '$container_type_constraint'"; + || confess "Value " + . ( $_[2] || 'undef' ) + . " did not pass container type constraint '$container_type_constraint'"; CORE::splice @{ $reader->( $_[0] ) }, $_[1], 0, $_[2]; }; } @@ -281,16 +281,16 @@ sub splice : method { $attr->has_type_constraint && $attr->type_constraint->isa( 'Moose::Meta::TypeConstraint::Parameterized') - ) { - my $container_type_constraint - = $attr->type_constraint->type_parameter; + ) + { + my $container_type_constraint = $attr->type_constraint->type_parameter; return sub { my ( $self, $i, $j, @elems ) = @_; ( $container_type_constraint->check($_) ) - || confess "Value " - . ( defined($_) ? $_ : 'undef' ) - . " did not pass container type constraint '$container_type_constraint'" - for @elems; + || confess "Value " + . ( defined($_) ? $_ : 'undef' ) + . " did not pass container type constraint '$container_type_constraint'" + for @elems; CORE::splice @{ $reader->($self) }, $i, $j, @elems; }; } @@ -308,12 +308,12 @@ sub sort_in_place : method { my ( $instance, $predicate ) = @_; die "Argument must be a code reference" - if $predicate && ref $predicate ne 'CODE'; + if $predicate && ref $predicate ne 'CODE'; my @sorted; if ($predicate) { - @sorted = CORE::sort { $predicate->( $a, $b ) } - @{ $reader->($instance) }; + @sorted = + CORE::sort { $predicate->( $a, $b ) } @{ $reader->($instance) }; } else { @sorted = CORE::sort @{ $reader->($instance) }; @@ -340,7 +340,7 @@ Moose::Meta::Attribute::Native::MethodProvider::Array use Moose::AttributeHelpers; has 'options' => ( - metaclass => 'Array', + traits => ['Array'], is => 'rw', isa => 'ArrayRef[Str]', default => sub { [] }, @@ -366,7 +366,7 @@ Moose::Meta::Attribute::Native::MethodProvider::Array =head1 DESCRIPTION This is a role which provides the method generators for -L. +L. Please check there for documentation on what methods are provided. =head1 METHODS @@ -376,137 +376,6 @@ L. =back -=head1 PROVIDED METHODS - -=over 4 - -=item B - -Returns the number of elements in the array. - - $stuff = Stuff->new; - $stuff->options(["foo", "bar", "baz", "boo"]); - - my $count = $stuff->count_options; - print "$count\n"; # prints 4 - -=item B - -If the array is populated, returns true. Otherwise, returns false. - - $stuff->do_i_have_options ? print "Good boy.\n" : die "No options!\n" ; - -=item B - -This method accepts a subroutine reference as its argument. That sub -will receive each element of the array in turn. If it returns true for -an element, that element will be returned by the C method. - - my $found = $stuff->find_option( sub { $_[0] =~ /^b/ } ); - print "$found\n"; # prints "bar" - -=item B - -This method accepts a subroutine reference as its argument. This -method returns every element for which that subroutine reference -returns a true value. - - my @found = $stuff->filter_options( sub { $_[0] =~ /^b/ } ); - print "@found\n"; # prints "bar baz boo" - -=item B - -This method accepts a subroutine reference as its argument. The -subroutine will be executed for each element of the array. It is -expected to return a modified version of that element. The return -value of the method is a list of the modified options. - - my @mod_options = $stuff->map_options( sub { $_[0] . "-tag" } ); - print "@mod_options\n"; # prints "foo-tag bar-tag baz-tag boo-tag" - -=item B - -Sorts and returns the elements of the array. - -You can provide an optional subroutine reference to sort with (as you -can with the core C function). However, instead of using C<$a> -and C<$b>, you will need to use C<$_[0]> and C<$_[1]> instead. - - # 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" - -=item B - -Returns all of the elements of the array - - my @option = $stuff->all_options; - print "@options\n"; # prints "foo bar baz boo" - -=item B - -Joins every element of the array using the separator given as argument. - - my $joined = $stuff->join_options( ':' ); - print "$joined\n"; # prints "foo:bar:baz:boo" - -=item B - -Returns an element of the array by its index. - - my $option = $stuff->get_option(1); - print "$option\n"; # prints "bar" - -=item B - -Returns the first element of the array. - - my $first = $stuff->first_option; - print "$first\n"; # prints "foo" - -=item B - -Returns the last element of the array. - - my $last = $stuff->last_option; - print "$last\n"; # prints "boo" - -=item B - -=item B - -=item B - -=item B - -=item B - -=item B - -=item B - -=item B - -=item B - -=item B - -Sorts the array I, modifying the value of the attribute. - -You can provide an optional subroutine reference to sort with (as you -can with the core C function). However, instead of using C<$a> -and C<$b>, you will need to use C<$_[0]> and C<$_[1]> instead. - -=item B - -If passed one argument, returns the value of the requested element. -If passed two arguments, sets the value of the requested element. - -=back - =head1 BUGS All complex software has bugs lurking in it, and this module is no diff --git a/lib/Moose/Meta/Attribute/Native/Trait/Array.pm b/lib/Moose/Meta/Attribute/Native/Trait/Array.pm index 5693035..f910a9f 100644 --- a/lib/Moose/Meta/Attribute/Native/Trait/Array.pm +++ b/lib/Moose/Meta/Attribute/Native/Trait/Array.pm @@ -33,26 +33,171 @@ Moose::Meta::Attribute::Native::Trait::Array =head1 SYNOPSIS - package Stuff; - use Moose; - use Moose::AttributeHelpers; - - has 'options' => ( - metaclass => 'Array', - is => 'ro', - isa => 'ArrayRef[Int]', - default => sub { [] }, - handles => { - add_options => 'push', - remove_last_option => 'pop', - } - ); - + package Stuff; + use Moose; + use Moose::AttributeHelpers; + + has 'options' => ( + traits => ['Array'], + is => 'ro', + isa => 'ArrayRef[Str]', + default => sub { [] }, + handles => { + all_options => 'elements', + map_options => 'map', + filter_options => 'grep', + find_option => 'find', + first_option => 'first', + last_option => 'last', + get_option => 'get', + join_options => 'join', + count_options => 'count', + do_i_have_options => 'empty', + sorted_options => 'sort', + } + ); + + no Moose; + 1; + =head1 DESCRIPTION This module provides an Array attribute which provides a number of -array operations. See L -for more details. +array operations. + +=head1 PROVIDED METHODS + +These methods are implemented in +L. + +=over 4 + +=item B + +Returns the number of elements in the array. + + $stuff = Stuff->new; + $stuff->options(["foo", "bar", "baz", "boo"]); + + my $count = $stuff->count_options; + print "$count\n"; # prints 4 + +=item B + +If the array is populated, returns true. Otherwise, returns false. + + $stuff->do_i_have_options ? print "Good boy.\n" : die "No options!\n" ; + +=item B + +This method accepts a subroutine reference as its argument. That sub +will receive each element of the array in turn. If it returns true for +an element, that element will be returned by the C method. + + my $found = $stuff->find_option( sub { $_[0] =~ /^b/ } ); + print "$found\n"; # prints "bar" + +=item B + +This method accepts a subroutine reference as its argument. This +method returns every element for which that subroutine reference +returns a true value. + + my @found = $stuff->filter_options( sub { $_[0] =~ /^b/ } ); + print "@found\n"; # prints "bar baz boo" + +=item B + +This method accepts a subroutine reference as its argument. The +subroutine will be executed for each element of the array. It is +expected to return a modified version of that element. The return +value of the method is a list of the modified options. + + my @mod_options = $stuff->map_options( sub { $_[0] . "-tag" } ); + print "@mod_options\n"; # prints "foo-tag bar-tag baz-tag boo-tag" + +=item B + +Sorts and returns the elements of the array. + +You can provide an optional subroutine reference to sort with (as you +can with the core C function). However, instead of using C<$a> +and C<$b>, you will need to use C<$_[0]> and C<$_[1]> instead. + + # 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" + +=item B + +Returns all of the elements of the array + + my @option = $stuff->all_options; + print "@options\n"; # prints "foo bar baz boo" + +=item B + +Joins every element of the array using the separator given as argument. + + my $joined = $stuff->join_options( ':' ); + print "$joined\n"; # prints "foo:bar:baz:boo" + +=item B + +Returns an element of the array by its index. + + my $option = $stuff->get_option(1); + print "$option\n"; # prints "bar" + +=item B + +Returns the first element of the array. + + my $first = $stuff->first_option; + print "$first\n"; # prints "foo" + +=item B + +Returns the last element of the array. + + my $last = $stuff->last_option; + print "$last\n"; # prints "boo" + +=item B + +=item B + +=item B + +=item B + +=item B + +=item B + +=item B + +=item B + +=item B + +=item B + +Sorts the array I, modifying the value of the attribute. + +You can provide an optional subroutine reference to sort with (as you +can with the core C function). However, instead of using C<$a> +and C<$b>, you will need to use C<$_[0]> and C<$_[1]> instead. + +=item B + +If passed one argument, returns the value of the requested element. +If passed two arguments, sets the value of the requested element. + +=back =head1 METHODS