Ah.. it was called ProduceStoreArray because there's also a ProduceStoreHash.. well...
[gitmo/Moose.git] / lib / Moose / Cookbook / Snack / ArrayRef.pod
CommitLineData
3a0c064a 1
686a7f09 2=pod
3
4=head1 NAME
5
3a0c064a 6Moose::Cookbook::Snack::ArrayRef - Using the ArrayRef type constraint
686a7f09 7
8=head1 SYNOPSIS
9
10 package Fruit;
11 use Moose;
12
6bf6edf6 13 has 'name' => (is => 'rw', required => 1);
14 has 'species' => (is => 'rw', required => 1);
686a7f09 15
09c00dab 16 package ProduceStore;
686a7f09 17 use Moose;
18 use Moose::Util::TypeConstraints;
19
6bf6edf6 20 has 'fruit_aisle' => (isa => 'ArrayRef[Fruit]', is => 'rw');
686a7f09 21
22 package main;
23
24 # we need something to put in the fruit aisle
6bf6edf6 25 my $orange = Fruit->new(name => 'orange', species => 'C. sinensis');
26 my $apple = Fruit->new(name => 'apple', species => 'M. domestica');
27 my @fruit = ($apple, $orange);
09c00dab 28 my $store = ProduceStore->new(fruit_aisle => \@fruit);
686a7f09 29
30=head1 DESCRIPTION
31
32The ArrayRef type constraint is used to store a reference to a Perl list or
33array variable as an attribute of a Moose object.
34
6bf6edf6 35=head2 Disclaimer
36
37The code in this document will work on Moose as advertised, but the developers
38strongly recommend using something like L<Moose::Autobox> or
39L<MooseX::AttributeHelpers> when working with array references in order to
40help keep your Moose objects nice and encapsulated.
41
686a7f09 42=head2 Assigning arrays to an ArrayRef attribute
43
44Once a Moose-based object with an C<ArrayRef> attribute has been created, you
45can pass an array (by reference) to that object attribute using that
46attribute's accessor. This is how we assign the apple and orange to the
47store's C<fruit_aisle> C<ArrayRef> attribute, we pass an array containing both
48objects by reference to the C<fruit_aisle> attribute:
49
6bf6edf6 50 my @fruit = ($apple, $orange);
09c00dab 51 my $store = ProduceStore->new(fruit_aisle => \@fruit);
686a7f09 52
6bf6edf6 53Or you can pass an anonymous array to the C<ArrayRef> attribute as well. If
54you created two new objects, C<$grape> and C<$tomato>, and assigned them to
55the C<ArrayRef>, they would replace the apple and the orange in the store's
56fruit aisle:
686a7f09 57
6bf6edf6 58 $store->fruit_aisle( [$grape, $tomato] );
686a7f09 59
60Our C<fruit_aisle> C<ArrayRef> is parameterized, meaning, that the
61C<fruit_aisle> C<ArrayRef> can contain nothing but C<Fruit> objects as array
62values. If you try to pass in a reference to a array using C<Str> objects as
63array values for example, Moose will complain:
64
65 Attribute (fruit_aisle) does not pass the type constraint (ArrayRef[Str])
66
67=head2 Dumping the contents of an ArrayRef
68
69In order to dump the contents of a C<ArrayRef> object attribute, you must first
70de-reference the C<ArrayRef>, and then enumerate over it's keys. You can add
09c00dab 71this method for showing the store's inventory to the C<ProduceStore>
686a7f09 72object shown in the SYNOPSIS:
73
74 sub show_inventory {
75 my $self = shift;
76 foreach my $item ( @{$self->fruit_aisle} ) {
3a0c064a 77 # ... access each Fruit object
78 }
686a7f09 79 }
80
81=head2 Assigning arrays to an ArrayRef will overwrite existing arrays
82
83Once you create an object containing a C<ArrayRef> attribute, if you assign a
84new array reference to that attribute, it will replace any existing array
85reference:
86
87 # replace existing inventory
6bf6edf6 88 my $grape = Fruit->new(name => 'grape', species => 'V. vinifera');
89 my $tomato = Fruit->new(name => 'tomato', species => 'S. lycopersicum');
90 $store->fruit_aisle( [$grape, $tomato] );
686a7f09 91
92=head2 Appending/Deleting values to/from an ArrayRef
93
94In order to append new elements to an array referred to by the C<ArrayRef>
95attribute, you will need to make a copy of the array first, add your new array
96elements, then assign your modified copy back to the C<ArrayRef> attribute:
97
98 my @fruit_aisle_copy = @{$store->fruit_aisle};
6bf6edf6 99 my $avocado = Fruit->new(name => 'avocado', species => 'P. americana');
686a7f09 100 push(@fruit_aisle_copy, $avocado);
101 $store->fruit_aisle( \@fruit_aisle_copy );
102
103And here's an example of deleting an object stored in an ArrayRef:
104
105 my @fruit_aisle_copy = @{$store->fruit_aisle};
106 # new array to hold the fruit objects that won't be deleted
107 my @reworked_fruit_aisle;
108 for my $fruit_obj ( @fruit_aisle_copy ) {
6bf6edf6 109 if ( $fruit_obj->name ne 'tomato' ) {
686a7f09 110 push(@reworked_fruit_aisle, $fruit_obj);
3a0c064a 111 }
112 }
686a7f09 113 $store->fruit_aisle( \@reworked_fruit_aisle );
114
115Putting the above code into their own object methods would make appending to or deleting from an C<ArrayRef> a trivial operation.
116
117=head2 Clearing an ArrayRef
118
119Assigning C<undef> to clear an C<ArrayRef> will not work because the attribute
120was originally defined with a type constraint, meaning that attribute must have
1210 or more of that type of value to be valid. C<undef> in Perl is not a value,
122so it won't work for clearing the C<ArrayRef>.
123
124If you assign an empty anonymous hash to a C<ArrayRef> attribute, this will
125clear out that attribute yet still satisfy the type constraint.
126
127 # this clears the ArrayRef
128 $store->fruit_aisle( [ ] );
129
130=head1 SEE ALSO
131
132=over 4
133
134=item L<Moose::Cookbook::Recipe4> - Subtypes, and modeling a simple Company
135class hierarchy
136
137=item L<Moose::Cookbook::Snack::Types> - Snippets of code for using Types and
138Type Constraints
139
140=item L<Moose::Util::TypeConstraints> - Type constraints that Moose can use
3a0c064a 141and the tools to extend them or create your own.
686a7f09 142
6bf6edf6 143=item L<Moose::Autobox> - Autoboxed wrappers for Native Perl datatypes
144
145=item L<MooseX::AttributeHelpers> - Extends attribute interfaces
146
686a7f09 147=back
148
149=head1 AUTHOR
150
151Brian Manning <elspicyjack at gmail dot com>
152
153=head1 COPYRIGHT AND LICENSE
154
3a0c064a 155Copyright 2006-2008 by Infinity Interactive, Inc.
156
157L<http://www.iinteractive.com>
686a7f09 158
3a0c064a 159This library is free software; you can redistribute it and/or modify
686a7f09 160it under the same terms as Perl itself.
161
162=cut