- changed snack description to better describe how Moose works
[gitmo/Moose.git] / lib / Moose / Cookbook / Snack / HashRef.pod
1
2 =pod
3
4 =head1 NAME
5
6 Moose::Cookbook::Snack::HashRef - Using the HashRef type constraint
7
8 =head1 SYNOPSIS
9
10     package Fruit;
11     use Moose;
12
13     has 'species' => ( is => 'rw', required => 1 );
14
15     package ProduceStoreHash;
16     use Moose;
17     use Moose::Util::TypeConstraints;
18
19     has 'fruit_aisle' => ( is => 'rw', isa => 'HashRef[Fruit]' );
20
21     package main;
22     use Moose;
23
24     # we need something to put in the fruit aisle
25     my $orange = Fruit->new( species => 'C. sinensis' );
26     my $apple = Fruit->new( species => 'M. domestica' );
27     my %fruit = ( orange => $orange, apple => $apple );
28     my $store = ProduceStoreHash->new( fruit_aisle => \%fruit );
29
30 =head1 DESCRIPTION
31
32 The HashRef type constraint is used to store a reference to a Perl hash
33 variable as an attribute of a Moose object.
34
35 =head2 Disclaimer
36
37 The code in this document will work on Moose as advertised, but the developers
38 strongly recommend using something like L<Moose::Autobox> or
39 L<MooseX::AttributeHelpers> when working with hash references in order to
40 help keep your Moose objects nice and encapsulated.
41
42 =head2 Assigning hashes to a HashRef attribute
43
44 Once a Moose-based object with a C<HashRef> attribute has been created, you
45 can pass a hash (by reference) to that attribute using that attribute's
46 accessor.  This is how we assign the apple and orange to the store's
47 C<fruit_aisle> C<HashRef> attribute, we pass a hash containing both objects by
48 reference to the C<fruit_aisle> attribute:
49
50     my %fruit = ( orange => $orange, apple => $apple );
51     my $store = ProduceStoreHash->new( fruit_aisle => \%fruit );
52
53 Or you can pass an anonymous hash to the C<HashRef> attribute as well.  If you
54 created two new objects, C<$grape> and C<$tomato>, and assigned them to the
55 C<HashRef>, they would replace the apple and the orange in the store's fruit
56 aisle:
57
58     $store->fruit_aisle( { grape => $grape, tomato => $tomato } );
59
60 Our C<fruit_aisle> C<HashRef> example is parameterized, meaning, that the
61 C<fruit_aisle> C<HashRef> can contain nothing but C<Fruit> objects as hash
62 values.  If you try to pass in a reference to a hash using C<Int> objects as
63 hash values for example, Moose will complain:
64
65     Attribute (fruit_aisle) does not pass the type constraint (HashRef[Int])
66
67 =head2 Dumping the contents of the HashRef
68
69 In order to dump the contents of a C<HashRef> object attribute, you must first
70 de-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};
74         print "Item: $item, type: " . $fruit->meta->name
75             . " species: " . $fruit->species . "\n";
76     }
77
78 If the above de-referencing of the C<fruit_aisle> C<HashRef> is a little too
79 noisy, 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};
84         print "Item: $item, type: " . $fruit->meta->name
85             . " species: " . $fruit->species . "\n";
86     } 
87
88 =head2 Assigning to a HashRef attribute will overwrite
89
90 Once you create an object containing a C<HashRef> attribute, if you assign a
91 new hash reference to that attribute, it will replace any existing hash
92 reference:
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
99 =head2 Appending/Deleting key/value pairs to a HashRef
100
101 In order to append or delete key/value pairs to the hash referred to by the
102 C<HashRef> attribute, you will need to make a copy of the hash first, add or
103 delete the desired key/value pairs, then assign your modified copy back to the
104 C<HashRef> attribute.  Here's an example of appending new key/value pars:
105
106     my %fruit_aisle_copy = %{$store->fruit_aisle};
107     my $avocado = Fruit->new( species => 'P. americana' );
108     $fruit_aisle_copy{avocado} = $avocado;
109     $store->fruit_aisle( \%fruit_aisle_copy );
110
111 And 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
118 Putting the above code into their own object methods would make appending to
119 and deleting from a C<HashRef> a trivial operation.
120
121 =head2 Clearing the HashRef
122
123 Assigning C<undef> to clear a C<HashRef> will not work because the attribute
124 was originally defined with a type constraint, meaning that attribute must have
125 0 or more of that type of value to be valid.  B<undef> in Perl is not a value,
126 so it won't work for clearing the C<HashRef>.
127
128 If you assign an empty anonymous hash to a C<HashRef> attribute, this will
129 clear 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
139 Type Constraints
140
141 =item L<Moose::Util::TypeConstraints> - Type constraints that Moose can use
142 and 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
147
148 =back
149
150 =head1 AUTHOR
151
152 Brian Manning <elspicyjack at gmail dot com>
153
154 =head1 COPYRIGHT AND LICENSE
155
156 Copyright 2006-2008 by Infinity Interactive, Inc.
157
158 L<http://www.iinteractive.com>
159
160 This library is free software; you can redistribute it and/or modify
161 it under the same terms as Perl itself.
162
163 =cut