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 ProduceStore;
  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 = ProduceStore->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 = ProduceStore->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