From: Brian Manning Date: Fri, 9 May 2008 21:13:48 +0000 (+0000) Subject: - uploaded *correct* versions of HashRef/ArrayRef/Perl 5 OO vs. Moose OO pods X-Git-Tag: 0_55~188 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=6bf6edf6ba7c2f012de409a76b1ddd0455ca18f5;p=gitmo%2FMoose.git - uploaded *correct* versions of HashRef/ArrayRef/Perl 5 OO vs. Moose OO pods --- diff --git a/lib/Moose/Cookbook/Snack/ArrayRef.pod b/lib/Moose/Cookbook/Snack/ArrayRef.pod index eed72f6..744b887 100644 --- a/lib/Moose/Cookbook/Snack/ArrayRef.pod +++ b/lib/Moose/Cookbook/Snack/ArrayRef.pod @@ -12,30 +12,35 @@ L 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 or +L 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 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 C attribute, we pass an array containing both objects by reference to the C 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 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 attribute as well. If +you created two new objects, C<$grape> and C<$tomato>, and assigned them to +the C, 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 C is parameterized, meaning, that the C C can contain nothing but C 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 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 - Type constraints that Moose can use +=item L - Autoboxed wrappers for Native Perl datatypes + +=item L - Extends attribute interfaces + =back =head1 AUTHOR @@ -146,7 +153,7 @@ Brian Manning =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. diff --git a/lib/Moose/Cookbook/Snack/HashRef.pod b/lib/Moose/Cookbook/Snack/HashRef.pod index 4282dcb..94494c0 100644 --- a/lib/Moose/Cookbook/Snack/HashRef.pod +++ b/lib/Moose/Cookbook/Snack/HashRef.pod @@ -12,51 +12,35 @@ L classes. package Fruit; use Moose; - has q(species) => ( is => q(rw), required => 1 ); + has 'species' => ( is => '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 + has 'fruit_aisle' => ( is => 'rw', isa => 'HashRef[Fruit]' ); 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 $orange = Fruit->new( species => 'C. sinensis' ); + my $apple = Fruit->new( species => '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 Disclaimer + +The code in this document will work on Moose as advertised, but the developers +strongly recommend using something like L or +L when working with array references in order to +help keep your Moose objects nice and encapsulated. + =head2 Assigning hashes to a HashRef attribute Once a Moose-based object with a C attribute has been created, you @@ -68,9 +52,10 @@ reference to the C attribute: my %fruit = ( orange => $orange, apple => $apple ); my $store = ProduceStoreHash->new( fruit_aisle => \%fruit ); -Or you can pass an anonymous hash to the C 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 hash to the C attribute as well. If you +created two new objects, C<$grape> and C<$tomato>, and assigned them to the +C, they would replace the apple and the orange in the store's fruit +aisle: $store->fruit_aisle( { grape => $grape, tomato => $tomato } ); @@ -81,30 +66,6 @@ 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 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 object attribute, you must first @@ -112,8 +73,8 @@ de-reference the C, 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); + print "Item: $item, type: " . $fruit->meta->name + . " species: " . $fruit->species . "\n"; } # foreach my $item If the above de-referencing of the C C is a little too @@ -125,6 +86,17 @@ noisy, you could create a copy of it, and then enumerate over that copy: # 'print' statement from above example goes here } +=head2 Assigning to a HashRef attribute will overwrite + +Once you create an object containing a C attribute, if you assign a +new hash reference to that attribute, it will replace any existing hash +reference: + + # this replaces the existing HashRef contents + my $grape = Fruit->new( species => 'V. vinifera' ); + my $tomato = Fruit->new( species => 'S. lycopersicum'); + $store->fruit_aisle( { grape => $grape, tomato => $tomato } ); + =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 @@ -133,7 +105,7 @@ delete the desired key/value pairs, then assign your modified copy back to the C 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) ); + my $avocado = Fruit->new( species => 'P. americana) ); $fruit_aisle_copy{avocado} = $avocado; $store->fruit_aisle( \%fruit_aisle_copy ); @@ -177,7 +149,7 @@ Brian Manning =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. diff --git a/lib/Moose/Cookbook/Snack/Perl5ObjsVsMooseObjs.pod b/lib/Moose/Cookbook/Snack/Perl5ObjsVsMooseObjs.pod index 3c17875..51518ec 100644 --- a/lib/Moose/Cookbook/Snack/Perl5ObjsVsMooseObjs.pod +++ b/lib/Moose/Cookbook/Snack/Perl5ObjsVsMooseObjs.pod @@ -11,16 +11,15 @@ objects and Moose objects package Moose::Demo; use Moose; # automagically sets 'strict' and 'warnings' - has q(script_name) => ( is => q(rw), required => 1); + has 'script_name' => ( is => 'rw', required => 1); package main; - use Moose; # needed for the call to 'blessed' below # '$0' is the name of this script, set automatically by Perl my $demo = Moose::Demo->new( script_name => $0 ); - print qq(My name is ) . $demo->script_name . qq(\n); - print qq(I am a ) . blessed $demo . qq( type of object\n); + print "My name is " . $demo->script_name . "\n"; + print "I am a " . $demo->meta->name . " type of object\n"; =head1 DESCRIPTION @@ -51,7 +50,7 @@ Let's take a look and find out... if ( exists $args{script_name} ) { $self->script_name($args{script_name}); } else { - die q(ERROR: can't create object without 'script_name' ); + die "ERROR: can't create object without 'script_name' "; } # if ( exists $args{script_name} ) # return the object reference back to the caller @@ -72,8 +71,8 @@ Let's take a look and find out... my $demo = Perl5::Demo->new( script_name => $0 ); - print qq(My name is ) . $demo->script_name . qq(\n); - print qq(I am a ) . ref($demo) . qq( type of object\n); + print "My name is " . $demo->script_name . "\n"; + print "I am a " . ref($demo) . " type of object\n"; Looks more complex, right? Moose does a lot of the labor when working with Perl objects, so that you don't have to. What are some of the specific @@ -104,14 +103,13 @@ to do this for ourselves in the Perl 5 example. =head3 Difference #3 - Determining an object's class name The C function in Perl 5 is how you determine an object's class name. -The proper way to do this with Moose is C<$object-Emeta-Ename> -B $obj->meta->name +The proper way to do this with Moose is C<$object-Emeta-Ename>; # an object's class name in Perl 5 OO - print qq(I am a ) . ref($demo) . qq( type of object\n); + print "I am a " . ref($demo) . " type of object\n"; # an object's class name in Moose - print qq(I am a ) . blessed $demo->meta->name . qq( type of object\n); + print "I am a " . $demo->meta->name . " type of object\n"; =head3 Difference #4 - Assigning values to Moose object attributes @@ -119,7 +117,7 @@ When you wish to assign a value directly to an object attribute for a Perl 5 object, you can either create an object method that handles the value for you; package Perl5Object; - sub set_x { # some code here } + sub set_x { # some code here that sets 'x' } package main; # later on... $self->set_x(0); @@ -168,7 +166,7 @@ Brian Manning =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.