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