- uploaded *correct* versions of HashRef/ArrayRef/Perl 5 OO vs. Moose OO pods

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

diff --git a/lib/Moose/Cookbook/Snack/ArrayRef.pod b/lib/Moose/Cookbook/Snack/ArrayRef.pod
index eed72f6..744b887 100644 (file)
--- a/lib/Moose/Cookbook/Snack/ArrayRef.pod
+++ b/lib/Moose/Cookbook/Snack/ArrayRef.pod
@@ -12,30 +12,35 @@ L<Moose::Util::TypeConstraints::OptimizedConstraints> classes.
     package Fruit;
     use Moose;
 
-    has q(name) => ( is => q(rw), required => 1 );
-    has q(species) => ( is => q(rw), required => 1 );
+    has 'name' => (is => 'rw', required => 1);
+    has 'species' => (is => 'rw', required => 1);
 
     package ProduceStoreArray;
     use Moose;
     use Moose::Util::TypeConstraints;
 
-    has q(fruit_aisle) => ( is => q(rw), isa => q(ArrayRef[Fruit]) );
+    has 'fruit_aisle' => (isa => 'ArrayRef[Fruit]', is => 'rw');
 
     package main;
 
     # we need something to put in the fruit aisle
-    my $orange = Fruit->new( 
-        name => q(orange), species => q(C. sinensis) );
-    my $apple = Fruit->new( 
-        name => q(apple), species => q(M. domestica) );
-    my @fruit = ( $apple, $orange );
-    my $store = ProduceStore->new( fruit_aisle => \@fruit );
+    my $orange = Fruit->new(name => 'orange', species => 'C. sinensis');
+    my $apple = Fruit->new(name => 'apple', species => 'M. domestica');
+    my @fruit = ($apple, $orange);
+    my $store = ProduceStore->new(fruit_aisle => \@fruit);
     
 =head1 DESCRIPTION
 
 The ArrayRef type constraint is used to store a reference to a Perl list or
 array variable as an attribute of a Moose object.
 
+=head2 Disclaimer
+
+The code in this document will work on Moose as advertised, but the developers
+strongly recommend using something like L<Moose::Autobox> or
+L<MooseX::AttributeHelpers> when working with array references in order to
+help keep your Moose objects nice and encapsulated.
+
 =head2 Assigning arrays to an ArrayRef attribute
 
 Once a Moose-based object with an C<ArrayRef> attribute has been created, you
@@ -44,14 +49,15 @@ attribute's accessor.  This is how we assign the apple and orange to the
 store's C<fruit_aisle> C<ArrayRef> attribute, we pass an array containing both
 objects by reference to the C<fruit_aisle> attribute:
 
-    my @fruit = ( $apple, $orange );
-    my $store = ProduceStore->new( fruit_aisle => \@fruit );
+    my @fruit = ($apple, $orange);
+    my $store = ProduceStore->new(fruit_aisle => \@fruit);
 
-Or you can pass an anonymous array to the C<ArrayRef> 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.
+Or you can pass an anonymous array to the C<ArrayRef> attribute as well.  If
+you created two new objects, C<$grape> and C<$tomato>, and assigned them to
+the C<ArrayRef>, they would replace the apple and the orange in the store's
+fruit aisle:
 
-    $store->fruit_aisle( [ $grape, $tomato ] );
+    $store->fruit_aisle( [$grape, $tomato] );
 
 Our C<fruit_aisle> C<ArrayRef> is parameterized, meaning, that the
 C<fruit_aisle> C<ArrayRef> can contain nothing but C<Fruit> objects as array
@@ -81,11 +87,9 @@ new array reference to that attribute, it will replace any existing array
 reference:
 
     # replace existing inventory
-    my $grape = Fruit->new( 
-        name => q(grape), species => q(V. vinifera) );
-    my $tomato = Fruit->new( 
-        name => q(tomato), species => q(S. lycopersicum));
-    $store->fruit_aisle( [ $grape, $tomato ] ); 
+    my $grape = Fruit->new(name => 'grape', species => 'V. vinifera');
+    my $tomato = Fruit->new(name => 'tomato', species => 'S. lycopersicum');
+    $store->fruit_aisle( [$grape, $tomato] ); 
 
 =head2 Appending/Deleting values to/from an ArrayRef
 
@@ -94,8 +98,7 @@ attribute, you will need to make a copy of the array first, add your new array
 elements, then assign your modified copy back to the C<ArrayRef> attribute:
 
     my @fruit_aisle_copy = @{$store->fruit_aisle};
-    my $avocado = Fruit->new( 
-        name => q(avocado), species => q(P. americana) );
+    my $avocado = Fruit->new(name => 'avocado', species => 'P. americana');
     push(@fruit_aisle_copy, $avocado);
     $store->fruit_aisle( \@fruit_aisle_copy );
 
@@ -105,9 +108,9 @@ And here's an example of deleting an object stored in an ArrayRef:
     # new array to hold the fruit objects that won't be deleted
     my @reworked_fruit_aisle;
     for my $fruit_obj ( @fruit_aisle_copy ) {
-        if ( $fruit_obj->name ne q(tomato) ) {
+        if ( $fruit_obj->name ne 'tomato' ) {
             push(@reworked_fruit_aisle, $fruit_obj);
-        } # if ( $fruit_obj->name ne q(tomato) )
+        } # if ( $fruit_obj->name ne 'tomato' )
     } # for my $fruit_obj ( @fruit_aisle_copy )
     $store->fruit_aisle( \@reworked_fruit_aisle );
 
@@ -138,6 +141,10 @@ Type Constraints
 
 =item L<Moose::Util::TypeConstraints> - Type constraints that Moose can use
 
+=item L<Moose::Autobox> - Autoboxed wrappers for Native Perl datatypes
+
+=item L<MooseX::AttributeHelpers> - Extends attribute interfaces
+
 =back
 
 =head1 AUTHOR
@@ -146,7 +153,7 @@ Brian Manning <elspicyjack at gmail dot com>
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright (c)2008 by Brian Manning
+Copyright (c)2008 by Infinity Interactive, Inc., Brian Manning
 
 This documentation is free software; you can redistribute it and/or modify
 it under the same terms as Perl itself.