=head1 NAME
-Moose::Cookbook::Recipe1 - The (always classic) cartesian point example.
+Moose::Cookbook::Recipe1 - The (always classic) B<Point> example.
=head1 SYNOPSIS
package Point;
- use strict;
- use warnings;
use Moose;
has 'x' => (isa => 'Int', is => 'ro');
}
package Point3D;
- use strict;
- use warnings;
use Moose;
extends 'Point';
places. And now, onto the code:
As with all Perl 5 classes, a Moose class is defined in a package.
-Of course we always use C<strict> and C<warnings> (don't forget
-that a kitten will die if you don't) and then we C<use Moose>.
+Moose now handles turning on C<strict> and C<warnings> for you, so
+all you need to do is say C<use Moose>, and no kittens will die.
-By loading Moose, we are enabeling the Moose "environment" to be
-loaded within our package. This means that we export some functions
-which serve as Moose "keywords". This is nothing fancier than that,
-just plain old exported functions.
+By loading Moose, we are enabling the loading of the Moose
+"environment" into our package. This means that we import some
+functions which serve as Moose "keywords". These aren't anything
+fancy, just plain old exported functions.
Another important thing happens at this stage as well. Moose will
automatically set your package's superclass to be L<Moose::Object>.
-The reason we do this, is so that we can be sure that you will
-inherit from L<Moose::Object> and get the benefits that provides
-(see the L<Moose::Object> for those details). However, you don't
-actually I<have> to inherit from L<Moose::Object> if you don't
-want to, all other features of Moose are still accessible to you.
+The reason we do this, is so that we can be sure that your class
+will inherit from L<Moose::Object> and get the benefits that
+provides (such as a constructor; see L<Moose::Object> for details).
+However, you don't actually I<have> to inherit from L<Moose::Object>
+if you don't want to. All Moose features will still be accessible to
+you.
Now, onto the keywords. The first one we see here is C<has>, which
-defines an instance attribute in your class.
+defines an instance attribute in your class:
has 'x' => (isa => 'Int', is => 'ro');
-This will create an attribute named C<x>, it will expect that the
+This will create an attribute named C<x>, which will expect the
value stored in the attribute to pass the type constraint C<Int> (1),
and the accessor generated for this attribute will be read-only
(abbreviated as C<ro>).
-The next C<has> line is very similar, with only one difference.
+The next C<has> line is very similar, with only one difference:
has 'y' => (isa => 'Int', is => 'rw');
-For the C<y> attribute a read/write accessor will be generated
-(abbreviated as C<rw>).
+A read/write (abbreviated as C<rw>) accessor will be generated for
+the C<y> attribute.
At this point the attributes have been defined, and it is time to
define our methods. In Moose, as with regular Perl 5 OO, a method
is my opinion that the behavior of C<extends> is more intuitive in
that it is more explicit about defining the superclass relationship.
-A small digression here, both Moose and C<extends> support multiple
-inheritence. You simply pass all the superclasses to C<extends>,
+A small digression here: both Moose and C<extends> support multiple
+inheritance. You simply pass all the superclasses to C<extends>,
like so:
extends 'Foo', 'Bar', 'Baz';
As with B<Point>'s C<x> and C<y> attributes, this attribute has a
type constraint of C<Int>, but it differs in that it does B<not>
ask for any autogenerated accessors. The result being (aside from
-breaking object encapsulation), that C<x> is a private attribute.
+broken object encapsulation) that C<z> is a private attribute.
Next comes another Moose feature which we call method "modifiers"
(or method "advice" for the AOP inclined). The modifier used here
}
You could also use another Moose method modifier, C<override> here,
-and get the same results again. Here is how that would look.
+and get the same results again. Here is how that would look:
override 'clear' => sub {
my $self = shift;
within it to dispatch to the superclass's method in a very Ruby-ish
style.
-Now of course, what use is a class if you cant instantiate objects
-with it. Now since B<Point> inherits from L<Moose::Object>, it will
-inherit the default L<Moose::Object> constructor called C<new>. Here
+Now, of course, what use is a class if you can't instantiate objects
+with it? Since B<Point> inherits from L<Moose::Object>, it will also
+inherit the default L<Moose::Object> constructor: C<new>. Here
are two examples of how that is used:
my $point = Point->new(x => 1, y => 2);
attributes, and it will politely ignore any named arguments it does
not recognize.
-From here, you can use C<$point> and C<$point3d> just as you would
-any other Perl 5 object.
+From here on, you can use C<$point> and C<$point3d> just as you would
+any other Perl 5 object. For a more detailed example of what can be
+done, you can refer to the F<t/000_recipes/001_recipe.t> test file.
=head1 CONCLUSION
-I hope this recipe has given you some explaination of how to use
-Moose to build you Perl 5 classes. The next recipe will build upon
+I hope this recipe has given you some explanation of how to use
+Moose to build your Perl 5 classes. The next recipe will build upon
the basics shown here with more complex attributes and methods.
Please read on :)
=item (1)
Several default type constraints are provided by Moose, of which
-C<Int> is one. For more information on the built-in type constraints
+C<Int> is one. For more information on the builtin type constraints
and the type constraint system in general, see the
L<Moose::Util::TypeConstraints> documentation.
=item (2)
-Future plans for Moose include allowing for alternate instance
-structures such as blessed ARRAY refs and such. If you want you Moose
-classes to be interchangable, it is advised that you avoid direct
-instance access, like that which is shown above.
+Moose supports using instance structures other than blessed hash
+references (such as in a glob reference -- see
+L<MooseX::GlobRef::Object>). If you want your Moose classes to
+be interchangeable, it is advisable to avoid direct instance
+access, like that shown above. Moose does let you get and set
+attributes directly without exposing the instance structure, but
+that's an advanced topic (intrepid readers should refer to the
+L<Moose::Meta::Attribute documentation>).
=back
=item Method Modifiers
The concept of method modifiers is directly ripped off from CLOS. A
-great explaination of them can be found by following this link.
+great explanation of them can be found by following this link.
L<http://www.gigamonkeys.com/book/object-reorientation-generic-functions.html>
=head1 COPYRIGHT AND LICENSE
-Copyright 2006 by Infinity Interactive, Inc.
+Copyright 2006-2008 by Infinity Interactive, Inc.
L<http://www.iinteractive.com>
projects / gitmo/Moose.git / blobdiff