- initial commit of new snacks (short documents) for ArrayRef's, HashRef's and

[gitmo/Moose.git] / lib / Moose / Cookbook / Snack / HashRef.pod

#!/usr/bin/env perl
=pod

=head1 NAME

Moose::Cookbook::Snack::HashRef - (Ab)using the HashRef type constraint
provided by the L<Moose::Util::TypeConstraint> and/or 
L<Moose::Util::TypeConstraints::OptimizedConstraints> classes.

=head1 SYNOPSIS

    package Fruit;
    use Moose;

    has q(species) => ( is => q(rw), required => 1 );

    package ProduceStoreHash;
    use Moose;
    use Moose::Util::TypeConstraints;

    has q(fruit_aisle) => ( is => q(rw), isa => q(HashRef[Fruit]) );

    sub show_inventory {
        my $self = shift;
        foreach my $item ( keys(%{$self->fruit_aisle}) ) {
            my $fruit = $self->{fruit_aisle}{$item};
            print qq(Item: $item, type: ) . blessed($fruit)
                . q( species: ) . $fruit->species . qq(\n);
        } # foreach my $item
    } # sub show_inventory

    package main;
    use Moose;

    # we need something to put in the fruit aisle
    my $orange = Fruit->new( species => q(C. sinensis) );
    my $apple = Fruit->new( species => q(M. domestica) );
    my %fruit = ( orange => $orange, apple => $apple );
    my $store = ProduceStoreHash->new( fruit_aisle => \%fruit );
    print qq(First inventory:\n);
    $store->show_inventory;

    # this replaces the existing HashRef contents
    my $grape = Fruit->new( species => q(V. vinifera) );
    my $tomato = Fruit->new( species => q(S. lycopersicum));
    $store->fruit_aisle( { grape => $grape, tomato => $tomato } );
    print qq(Second inventory:\n);
    $store->show_inventory;

    # this clears the HashRef
    $store->fruit_aisle( { } );
    print qq(Third inventory:\n);
    $store->show_inventory;

=head1 DESCRIPTION

The HashRef type constraint is used to store a reference to a Perl hash
variable as an attribute of a Moose object.

=head2 Assigning hashes to a HashRef attribute

Once a Moose-based object with a C<HashRef> attribute has been created, you
can pass a hash (by reference) to that attribute using that attribute's
accessor.  This is how we assign the apple and orange to the store's
C<fruit_aisle> C<HashRef> attribute, we pass a hash containing both objects by
reference to the C<fruit_aisle> attribute:

    my %fruit = ( orange => $orange, apple => $apple );
    my $store = ProduceStoreHash->new( fruit_aisle => \%fruit );

Or you can pass an anonymous hash to the C<HashRef> attribute as well.
This is shown in the example when the grape and tomato replace the apple
and the orange in the store's fruit aisle.

    $store->fruit_aisle( { grape => $grape, tomato => $tomato } );

Our C<fruit_aisle> C<HashRef> example is parameterized, meaning, that the
C<fruit_aisle> C<HashRef> can contain nothing but C<Fruit> objects as hash
values.  If you try to pass in a reference to a hash using C<Int> objects as
hash values for example, Moose will complain:

    Attribute (fruit_aisle) does not pass the type constraint (HashRef[Int])

=head2 Assigning to a HashRef attribute will overwrite

Once you create an object containing a C<HashRef> attribute, if you assign a
new hash reference to that attribute, it will replace any existing hash
reference:

    print qq(First inventory:\n);
    $store->show_inventory;
    # First inventory:
    # Item: apple, type: Fruit species: M. domestica
    # Item: orange, type: Fruit species: C. sinensis


    # this replaces the existing HashRef contents
    my $grape = Fruit->new( species => q(V. vinifera) );
    my $tomato = Fruit->new( species => q(S. lycopersicum));
    $store->fruit_aisle( { grape => $grape, tomato => $tomato } );

    print qq(Second inventory:\n);
    $store->show_inventory;
    # Second inventory:
    # Item: tomato, type: Fruit species: S. lycopersicum
    # Item: grape, type: Fruit species: V. vinifera

=head2 Dumping the contents of the HashRef

In order to dump the contents of a C<HashRef> object attribute, you must first
de-reference the C<HashRef>, and then enumerate over it's keys.  

    foreach my $item ( keys(%{$self->fruit_aisle}) ) {
        my $fruit = $self->{fruit_aisle}{$item};
        print qq(Item: $item, type: ) . blessed($fruit)
            . q( species: ) . $fruit->species . qq(\n);
    } # foreach my $item

If the above de-referencing of the C<fruit_aisle> C<HashRef> is a little too
noisy, you could create a copy of it, and then enumerate over that copy:

    my %fruit_aisle_copy = %{$self->fruit_aisle};
    foreach my $item ( keys(%fruit_aisle_copy) ) {
        my $fruit = $fruit_aisle_copy{$item};
        # 'print' statement from above example goes here
    } 

=head2 Appending/Deleting key/value pairs to a HashRef

In order to append or delete key/value pairs to the hash referred to by the
C<HashRef> attribute, you will need to make a copy of the hash first, add or
delete the desired key/value pairs, then assign your modified copy back to the
C<HashRef> attribute.  Here's an example of appending new key/value pars:

    my %fruit_aisle_copy = %{$store->fruit_aisle};
    my $avocado = Fruit->new( species => q(P. americana) );
    $fruit_aisle_copy{avocado} = $avocado;
    $store->fruit_aisle( \%fruit_aisle_copy );

And here's an example of deleting existing key/value pairs:

    # delete an attribute from the HashRef
    %fruit_aisle_copy = %{$store->fruit_aisle};
    delete($fruit_aisle_copy{tomato});
    $store->fruit_aisle( \%fruit_aisle_copy );

Putting the above code into their own object methods would make appending to
and deleting from a C<HashRef> a trivial operation.

=head2 Clearing the HashRef

Assigning C<undef> to clear a C<HashRef> will not work because the attribute
was originally defined with a type constraint, meaning that attribute must have
0 or more of that type of value to be valid.  B<undef> in Perl is not a value,
so it won't work for clearing the C<HashRef>.

If you assign an empty anonymous hash to a C<HashRef> attribute, this will
clear out that attribute yet still satisfy the type constraint.

    # this clears the HashRef
    $store->fruit_aisle( { } );

=head1 SEE ALSO

=over 4

=item L<Moose::Cookbook::Snack::Types> - Snippets of code for using Types and
Type Constraints

=item L<Moose::Util::TypeConstraints> - Type constraints system for Moose

=back

=head1 AUTHOR

Brian Manning <elspicyjack at gmail dot com>

=head1 COPYRIGHT AND LICENSE

Copyright (c)2008 by Brian Manning

This documentation is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=cut