lib/Moose/Cookbook/Snack/HashRef.pod

   1 #!/usr/bin/env perl
   2 =pod
   3
   4 =head1 NAME
   5
   6 Moose::Cookbook::Snack::HashRef - (Ab)using the HashRef type constraint
   7 provided by the L<Moose::Util::TypeConstraint> and/or
   8 L<Moose::Util::TypeConstraints::OptimizedConstraints> classes.
   9
  10 =head1 SYNOPSIS
  11
  12     package Fruit;
  13     use Moose;
  14
  15     has 'species' => ( is => 'rw', required => 1 );
  16
  17     package ProduceStoreHash;
  18     use Moose;
  19     use Moose::Util::TypeConstraints;
  20
  21     has 'fruit_aisle' => ( is => 'rw', isa => 'HashRef[Fruit]' );
  22
  23     package main;
  24     use Moose;
  25
  26     # we need something to put in the fruit aisle
  27     my $orange = Fruit->new( species => 'C. sinensis' );
  28     my $apple = Fruit->new( species => 'M. domestica' );
  29     my %fruit = ( orange => $orange, apple => $apple );
  30     my $store = ProduceStoreHash->new( fruit_aisle => \%fruit );
  31
  32 =head1 DESCRIPTION
  33
  34 The HashRef type constraint is used to store a reference to a Perl hash
  35 variable as an attribute of a Moose object.
  36
  37 =head2 Disclaimer
  38
  39 The code in this document will work on Moose as advertised, but the developers
  40 strongly recommend using something like L<Moose::Autobox> or
  41 L<MooseX::AttributeHelpers> when working with array references in order to
  42 help keep your Moose objects nice and encapsulated.
  43
  44 =head2 Assigning hashes to a HashRef attribute
  45
  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:
  51
  52     my %fruit = ( orange => $orange, apple => $apple );
  53     my $store = ProduceStoreHash->new( fruit_aisle => \%fruit );
  54
  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
  58 aisle:
  59
  60     $store->fruit_aisle( { grape => $grape, tomato => $tomato } );
  61
  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:
  66
  67     Attribute (fruit_aisle) does not pass the type constraint (HashRef[Int])
  68
  69 =head2 Dumping the contents of the HashRef
  70
  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.
  73
  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";
  78     } # foreach my $item
  79
  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:
  82
  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' statement from above example goes here
  87     }
  88
  89 =head2 Assigning to a HashRef attribute will overwrite
  90
  91 Once you create an object containing a C<HashRef> attribute, if you assign a
  92 new hash reference to that attribute, it will replace any existing hash
  93 reference:
  94
  95     # this replaces the existing HashRef contents
  96     my $grape = Fruit->new( species => 'V. vinifera' );
  97     my $tomato = Fruit->new( species => 'S. lycopersicum');
  98     $store->fruit_aisle( { grape => $grape, tomato => $tomato } );
  99
 100 =head2 Appending/Deleting key/value pairs to a HashRef
 101
 102 In order to append or delete key/value pairs to the hash referred to by the
 103 C<HashRef> attribute, you will need to make a copy of the hash first, add or
 104 delete the desired key/value pairs, then assign your modified copy back to the
 105 C<HashRef> attribute.  Here's an example of appending new key/value pars:
 106
 107     my %fruit_aisle_copy = %{$store->fruit_aisle};
 108     my $avocado = Fruit->new( species => 'P. americana) );
 109     $fruit_aisle_copy{avocado} = $avocado;
 110     $store->fruit_aisle( \%fruit_aisle_copy );
 111
 112 And here's an example of deleting existing key/value pairs:
 113
 114     # delete an attribute from the HashRef
 115     %fruit_aisle_copy = %{$store->fruit_aisle};
 116     delete($fruit_aisle_copy{tomato});
 117     $store->fruit_aisle( \%fruit_aisle_copy );
 118
 119 Putting the above code into their own object methods would make appending to
 120 and deleting from a C<HashRef> a trivial operation.
 121
 122 =head2 Clearing the HashRef
 123
 124 Assigning C<undef> to clear a C<HashRef> will not work because the attribute
 125 was originally defined with a type constraint, meaning that attribute must have
 126 0 or more of that type of value to be valid.  B<undef> in Perl is not a value,
 127 so it won't work for clearing the C<HashRef>.
 128
 129 If you assign an empty anonymous hash to a C<HashRef> attribute, this will
 130 clear out that attribute yet still satisfy the type constraint.
 131
 132     # this clears the HashRef
 133     $store->fruit_aisle( { } );
 134
 135 =head1 SEE ALSO
 136
 137 =over 4
 138
 139 =item L<Moose::Cookbook::Snack::Types> - Snippets of code for using Types and
 140 Type Constraints
 141
 142 =item L<Moose::Util::TypeConstraints> - Type constraints system for Moose
 143
 144 =back
 145
 146 =head1 AUTHOR
 147
 148 Brian Manning <elspicyjack at gmail dot com>
 149
 150 =head1 COPYRIGHT AND LICENSE
 151
 152 Copyright (c)2008 by  Infinity Interactive, Inc., Brian Manning
 153
 154 This documentation is free software; you can redistribute it and/or modify
 155 it under the same terms as Perl itself.
 156
 157 =cut