6 Moose::Cookbook::Snack::HashRef - Using the HashRef type constraint
13 has 'species' => ( is => 'rw', required => 1 );
17 use Moose::Util::TypeConstraints;
19 has 'fruit_aisle' => ( is => 'rw', isa => 'HashRef[Fruit]' );
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 = ProduceStore->new( fruit_aisle => \%fruit );
32 The HashRef type constraint is used to store a reference to a Perl hash
33 variable as an attribute of a Moose object.
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. The reason why this POD
41 exists is to show potential users of L<Moose> that Moose objects are just like
42 Plain Ol' Perl Objects (POPO), albeit with some extra metadata syntatic sugar.
44 =head2 Assigning hashes to a HashRef attribute
46 Once a Moose-based object with a C<HashRef> attribute has been created, you
47 can pass a hash (by reference) to that attribute using that attribute's
48 accessor. This is how we assign the apple and orange to the store's
49 C<fruit_aisle> C<HashRef> attribute, we pass a hash containing both objects by
50 reference to the C<fruit_aisle> attribute:
52 my %fruit = ( orange => $orange, apple => $apple );
53 my $store = ProduceStore->new( fruit_aisle => \%fruit );
55 Or you can pass an anonymous hash to the C<HashRef> attribute as well. If you
56 created two new objects, C<$grape> and C<$tomato>, and assigned them to the
57 C<HashRef>, they would replace the apple and the orange in the store's fruit
60 $store->fruit_aisle( { grape => $grape, tomato => $tomato } );
62 Our C<fruit_aisle> C<HashRef> example is parameterized, meaning, that the
63 C<fruit_aisle> C<HashRef> can contain nothing but C<Fruit> objects as hash
64 values. If you try to pass in a reference to a hash using C<Int> objects as
65 hash values for example, Moose will complain:
67 Attribute (fruit_aisle) does not pass the type constraint (HashRef[Int])
69 =head2 Dumping the contents of the HashRef
71 In order to dump the contents of a C<HashRef> object attribute, you must first
72 de-reference the C<HashRef>, and then enumerate over it's keys.
74 foreach my $item ( keys(%{$self->fruit_aisle}) ) {
75 my $fruit = $self->{fruit_aisle}{$item};
76 print "Item: $item, type: " . $fruit->meta->name
77 . " species: " . $fruit->species . "\n";
80 If the above de-referencing of the C<fruit_aisle> C<HashRef> is a little too
81 noisy, you could create a copy of it, and then enumerate over that copy:
83 my %fruit_aisle_copy = %{$self->fruit_aisle};
84 foreach my $item ( keys(%fruit_aisle_copy) ) {
85 my $fruit = $fruit_aisle_copy{$item};
86 print "Item: $item, type: " . $fruit->meta->name
87 . " species: " . $fruit->species . "\n";
90 =head2 Assigning to a HashRef attribute will overwrite
92 Once you create an object containing a C<HashRef> attribute, if you assign a
93 new hash reference to that attribute, it will replace any existing hash
96 # this replaces the existing HashRef contents
97 my $grape = Fruit->new( species => 'V. vinifera' );
98 my $tomato = Fruit->new( species => 'S. lycopersicum');
99 $store->fruit_aisle( { grape => $grape, tomato => $tomato } );
101 =head2 Appending/Deleting key/value pairs to a HashRef
103 In order to append or delete key/value pairs to the hash referred to by the
104 C<HashRef> attribute, you will need to make a copy of the hash first, add or
105 delete the desired key/value pairs, then assign your modified copy back to the
106 C<HashRef> attribute. Here's an example of appending new key/value pars:
108 my %fruit_aisle_copy = %{$store->fruit_aisle};
109 my $avocado = Fruit->new( species => 'P. americana' );
110 $fruit_aisle_copy{avocado} = $avocado;
111 $store->fruit_aisle( \%fruit_aisle_copy );
112 $store->fruit_aisle->{avocado};
114 And here's an example of deleting existing key/value pairs:
116 # delete an attribute from the HashRef
117 %fruit_aisle_copy = %{$store->fruit_aisle};
118 delete($fruit_aisle_copy{tomato});
119 $store->fruit_aisle( \%fruit_aisle_copy );
120 delete $mooseObj->hashref->{foo};
122 Putting the above code into their own object methods would make appending to
123 and deleting from a C<HashRef> a trivial operation.
125 =head2 Clearing the HashRef
127 Assigning C<undef> to clear a C<HashRef> will not work because the attribute
128 was originally defined with a type constraint, meaning that attribute must have
129 0 or more of that type of value to be valid. B<undef> in Perl is not a value,
130 so it won't work for clearing the C<HashRef>.
132 If you assign an empty anonymous hash to a C<HashRef> attribute, this will
133 clear out that attribute yet still satisfy the type constraint.
135 # this clears the HashRef
136 $store->fruit_aisle( { } );
142 =item L<Moose::Cookbook::Snack::Types> - Snippets of code for using Types and
145 =item L<Moose::Util::TypeConstraints> - Type constraints that Moose can use
146 and the tools to extend them or create your own.
148 =item L<Moose::Autobox> - Autoboxed wrappers for Native Perl datatypes
150 =item L<MooseX::AttributeHelpers> - Extends attribute interfaces
156 Brian Manning <elspicyjack at gmail dot com>
158 =head1 COPYRIGHT AND LICENSE
160 Copyright 2006-2008 by Infinity Interactive, Inc.
162 L<http://www.iinteractive.com>
164 This library is free software; you can redistribute it and/or modify
165 it under the same terms as Perl itself.