=head2 Basic Moose
-These recipes will give you a good idea of what Moose is capable,
+These recipes will give you a good idea of what Moose is capable of,
starting with simple attribute declaration, and moving on to more
powerful features like laziness, types, type coercion, method
modifiers, and more.
=item L<Moose::Cookbook::Basics::Recipe1> - The (always classic) B<Point> example
-A simple Moose-based class. Demonstrated Moose attributes and subclassing.
+A simple Moose-based class. Demonstrates Moose attributes and subclassing.
=item L<Moose::Cookbook::Basics::Recipe2> - A simple B<BankAccount> example
=item L<Moose::Cookbook::Roles::Recipe2> - Advanced Role Composition - method exclusion and aliasing
Sometimes you just want to include part of a role in your
-class. Sometimes you want the whole role but one if its methods
+class. Sometimes you want the whole role but one of its methods
conflicts with one in your class. With method exclusion and aliasing,
you can work around these problems.
=head2 Meta Moose
These recipes show you how to write your own meta classes, which lets
-you extend the object system provide by Moose.
+you extend the object system provided by Moose.
=over 4
=item L<Moose::Cookbook::Extending::Recipe1> - Moose extension overview
-There are quite a number of ways to extend Moose. This recipe explains
-provides an overview of each method, and provides recommendations for
-when each is appropriate.
+There are quite a few ways to extend Moose. This recipe provides an
+overview of each method, and provides recommendations for when each is
+appropriate.
=item L<Moose::Cookbook::Extending::Recipe2> - Providing a base object class role
(in the correct order) immediately after the instance is constructed.
This allows you to ensure that all your superclasses are initialized
properly as well. This is the best approach to take (when possible)
-because it makes sub classing your class much easier.
+because it makes subclassing your class much easier.
If you need to affect the constructor's parameters prior to the
instance actually being constructed, you have a number of options.
=head3 How do I get Moose to call BUILD in all my composed roles?
-See L<Moose::Cookbook::WTF> and specifically the B<How come BUILD
-is not called for my composed roles?> question in the B<Roles> section.
+See L<Moose::Cookbook::WTF> and specifically the B<Why is BUILD
+not called for my composed roles?> question in the B<Roles> section.
-=head3 What are Traits, and how are they different to Roles?
+=head3 What are Traits, and how are they different from Roles?
In Moose, a trait is almost exactly the same thing as a role, except
that traits typically register themselves, which allows you to refer
=head2 Constructors & Immutability
-=head3 I made my class immutable, but C<new> it is still slow!
+=head3 I made my class immutable, but C<new> is still slow!
Do you have a custom C<new> method in your class? Moose
will not overwrite your custom C<new> method, you would
around) C<new> is not being called?
Making a I<before>, I<after> or I<around> wrap around the
-C<new> method, will actually create a C<new> method within
+C<new> method will actually create a C<new> method within
your class. This will prevent Moose from creating one itself
when you make the class immutable.
has 'foo' => (isa => 'Bar', is => 'rw');
-The reason this is so, is because it is a perfectly valid use
+The reason this is so is because it is a perfectly valid use
case to I<not> have an accessor. The simplest one is that you
-want to write your own. If Moose created on automatically, then
+want to write your own. If Moose created one automatically, then
because of the order in which classes are constructed, Moose
would overwrite your custom accessor. You wouldn't want that
would you?
=head2 Method Modifiers
-=head3 How come I can't change C<@_> in a C<before> modifier?
+=head3 Why can't I change C<@_> in a C<before> modifier?
-The C<before> modifier simply is called I<before> the main method.
+The C<before> modifier is called I<before> the main method.
Its return values are simply ignored, and are B<not> passed onto
the main method body.
$next->($self, reverse(@args));
};
-=head3 How come I can't see return values in an C<after> modifier?
+=head3 Why can't I see return values in an C<after> modifier?
As with the C<before> modifier, the C<after> modifier is simply
called I<after> the main method. It is passed the original contents
=head2 Roles
-=head3 How come BUILD is not called for my composed roles?
+=head3 Why is BUILD not called for my composed roles?
BUILD is never called in composed roles. The primary reason is that
roles are B<not> order sensitive. Roles are composed in such a way
=item *
-Use attributes triggers, which fire after an attribute it set, to facilitate
-initialization. These are described in the L<Moose> docs and examples can be
+Use attribute triggers, which fire after an attribute is set, to facilitate
+initialization. These are described in the L<Moose> docs, and examples can be
found in the test suite.
=back
-In general, roles should not I<require> initialization, they should either
+In general, roles should not I<require> initialization; they should either
provide sane defaults or should be documented as needing specific
initialization. One such way to "document" this is to have a separate
attribute initializer which is required for the role. Here is an example of
classes, focusing on "what" rather than "how". A class definition with
Moose reads like a list of very concise English sentences.
-Moose is built in top of C<Class::MOP>, a meta-object protocol (aka
+Moose is built on top of C<Class::MOP>, a meta-object protocol (aka
MOP). Using the MOP, Moose provides complete introspection for all
Moose-using classes. This means you can ask classes about their
attributes, parents, children, methods, etc., all using a well-defined
=item L<Moose::Manual::Delegation>
-Delegation is a powerful way to make use of attribute which are
+Delegation is a powerful way to make use of attributes which are
themselves objects.
=item L<Moose::Manual::Construction>
=item L<Moose::Manual::MooseX>
-This document shows a few of the most useful Moose extensions on CPAN.
+This document describes a few of the most useful Moose extensions on
+CPAN.
=item L<Moose::Manual::BestPractices>
=head1 JUSTIFICATION
-If you're still still asking yourself "Why do I need this?", then this
+If you're still asking yourself "Why do I need this?", then this
section is for you.
=over 4
highly stable and we are committed to keeping it stable.
Of course, in the end, you need to make this call yourself. If you
-have any questions or concerns, please feel free to email Stevan, the
-moose@perl.org list, or just stop by irc.perl.org#moose and ask away.
+have any questions or concerns, please feel free to email Stevan or
+the moose@perl.org list, or just stop by irc.perl.org#moose and ask
+away.
=item Is Moose just Perl 6 in Perl 5?
This says that all C<Person> objects have an optional read-write
"first_name" attribute.
-=head2 Read-write Vs read-only
+=head2 Read-write vs. read-only
The options passed to C<has> define the properties of the
-attribute. There are a many options, but in the simplest form you just
+attribute. There are many options, but in the simplest form you just
need to set C<is>, which can be either C<rw> (read-write) or C<ro>
(read-only).
readable, but only privately settable. For example:
has 'weight' => (
- is => 'rw',
+ is => 'ro',
writer => '_set_weight',
);
-This might be useful if weight is calculated based on other methods,
-for example every time the C<eat> method is called, we might adjust
+This might be useful if weight is calculated based on other methods.
+For example, every time the C<eat> method is called, we might adjust
weight. This lets us hide the implementation details of weight
changes, but still provide the weight value to users of the class.
If you're thinking that doing this over and over would be insanely
tedious, you're right! Fortunately, Moose provides a powerful
-extension system that lets override the default naming
+extension system that lets you override the default naming
conventions. See L<Moose::Manual::MooseX> for more details.
=head2 Predicate and clearer methods
predicate methods for an attribute.
A predicate method tells you whether or not a given attribute is
-currently set. Note an attribute can be explicitly set to C<undef> or
-some other false value, but the predicate will return true.
+currently set. Note that an attribute can be explicitly set to
+C<undef> or some other false value, but the predicate will return
+true.
The clearer method unsets the attribute. This is I<not> the
same as setting the value to C<undef>, but you can only distinguish
This differs from an after method modifier in two ways. First, a
trigger is only called when the attribute is set, as opposed to
whenever the accessor method is called (for reading or
-writing). Second, it is also called if the when an attribute's value
-is passed to the constructor.
+writing). Second, it is also called when an attribute's value is
+passed to the constructor.
However, triggers are I<not> called when an attribute is populated
from a C<default> or C<builder>
=head1 MORE ON ATTRIBUTES
Moose attributes are a big topic, and this document glosses over a few
-aspects of their aspects. We recommend that you read the
-L<Moose::Manual::Delegation> and L<Moose::Manual::Types> documents to
-get a more complete understanding of attribute features.
+aspects. We recommend that you read the L<Moose::Manual::Delegation>
+and L<Moose::Manual::Types> documents to get a more complete
+understanding of attribute features.
=head1 A FEW MORE OPTIONS
Many of these practices also help get the most out of meta
programming. If you used an overridden C<new> to do type coercion by
hand, rather than defining a real coercion, there is no introspectable
-metadata. This sort of thing is particularly problematic MooseX
+metadata. This sort of thing is particularly problematic for MooseX
extensions which rely on introspection to do the right thing.
=head1 AUTHOR
Attributes are described in the L<Moose::Manual::Attributes>
documentation.
-Loading Moose also turns enables C<strict> and C<warnings> pragmas in
-your class.
+Loading Moose also enables C<strict> and C<warnings> pragmas in your
+class.
When you load Moose, your class will become a subclass of
L<Moose::Object>. The L<Moose::Object> class provides a default
-constructor, destructor, as well as object construction helper
+constructor and destructor, as well as object construction helper
methods. You can read more about this in the
L<Moose::Manual::Construction> document.
If you override C<new()> in your class, then the immutabilization code
will not be able to provide an optimized constructor for your
-class. Instead, you should use C<BUILD()> method, which will be called
-from the inlined constructor.
+class. Instead, you should use a C<BUILD()> method, which will be
+called from the inlined constructor.
Alternately, if you really need to provide a different C<new()>, you
can also provide your own immutabilization method. Doing so requires
Attributes I<are not> methods, but defining them causes various
accessor methods to be created. At a minimum, a normal attribute will
-always have a reader accessor method. Many attributes also other
-methods such as a writer method, clearer method, and predicate method
+always have a reader accessor method. Many attributes also have other
+methods, such as a writer method, clearer method, and predicate method
("has it been set?").
An attribute may also define B<delegations>, which will create
on what Perl provides, such as C<Str>, C<Num>, C<Bool>, C<HashRef>, etc.
In addition, every class name in your application can also be used as
-a type name. We saw an example using C<DateTime> earlier.
+a type name.
Finally, you can define your own types, either as subtypes or entirely
new types, with their own constraints. For example, you could define a
So you're sold on Moose. Time to learn how to really use it.
-If you want to see how Moose would translate directly old school Perl
-5 OO code, check out L<Moose::Unsweetened>. This might be helpful for
-quickly wrapping your brain around some aspects of "the Moose way".
+If you want to see how Moose would translate directly into old school
+Perl 5 OO code, check out L<Moose::Unsweetened>. This might be
+helpful for quickly wrapping your brain around some aspects of "the
+Moose way".
Obviously, the next thing to read is the rest of the L<Moose::Manual>.
=head2 BUILD
The C<BUILD> method is called I<after> an object is created. There are
-ways to use a C<BUILD> method. One of the most common is to check that
-the object state is valid. While we can validate individual attributes
-through the use of types, we can't validate the state of a whole
-object that way.
+several ways to use a C<BUILD> method. One of the most common is to
+check that the object state is valid. While we can validate individual
+attributes through the use of types, we can't validate the state of a
+whole object that way.
sub BUILD {
my $self = shift;
rather than Moose itself.
The MOP provides more than just I<read-only> introspection. It also
-lets you add attributes, method, apply roles, and much more. In fact,
-all of the declarative Moose sugar is simply a thin layer on top of
-the MOP API.
+lets you add attributes and methods, apply roles, and much more. In
+fact, all of the declarative Moose sugar is simply a thin layer on top
+of the MOP API.
If you want to write Moose extensions, you'll need to learn some of
the MOP API. The introspection methods are also handy if you want to
You can also get a list of methods:
for my $method ( $meta->get_all_methods ) {
- print $meth->fully_qualified_name, "\n";
+ print $method->fully_qualified_name, "\n";
}
Now we're looping over a list of L<Moose::Meta::Method> objects. Note
=head1 GOING FURTHER
-If you're interested in extending moose, we recommend reading all of
+If you're interested in extending Moose, we recommend reading all of
the "Meta" and "Extending" recipes in the L<Moose::Cookbook>. Those
recipes show various practical applications of the MOP.
lets roles alter the behavior of methods in the classes that use
them. See L<Moose::Manual::Roles> for more information about roles.
-Most of the modifiers are most useful in roles, so some of the
-examples below are a bit artificial. They're intended to give you an
-idea of how modifiers work, but may not be the most natural usage.
+Since modifiers are mostly useful in roles, some of the examples below
+are a bit artificial. They're intended to give you an idea of how
+modifiers work, but may not be the most natural usage.
=head1 BEFORE, AFTER, AND AROUND
-Method modifiers can also be used to add behavior to a method that
-Moose generates for you, such as an attribute accessor:
+Method modifiers can be used to add behavior to a method that Moose
+generates for you, such as an attribute accessor:
has 'size' => ( is => 'rw' );
An around modifier is a bit more powerful than either a before or
after modifier. It can modify the arguments being passed to the
original method, and you can even decide to simply not call the
-original method at all. Finally, you can modify the return value with
-an around modifier.
+original method at all. You can also modify the return value with an
+around modifier.
An around modifier receives the original method as its first argument,
I<then> the object, and finally any arguments passed to the method.
Writing your own extensions does require a good understanding of the
meta-model. You can start learning about this with the
-L<Moose::Manual::MOP> docs. There are also several extensions recipes
+L<Moose::Manual::MOP> docs. There are also several extension recipes
in the L<Moose::Cookbook>.
Explaining how to write extensions is beyond the scope of this
the same name, we will have a conflict. In that case, the composing
class is required to provide its I<own> method of the same name.
- package Breakdances;
+ package Breakdancer;
use Moose::Role
conceptual. C<Item> is used as the top-level type in the hierarchy.
The rest of these types correspond to existing Perl concepts. For
-example, a C<Num> is anything that Perl thinks looks like a number. An
+example, a C<Num> is anything that Perl thinks looks like a number, an
C<Object> is a blessed reference, etc.
The types followed by "[`a]" can be parameterized. So instead of just
=head1 SUBTYPES
-Moose uses subtypes in its built-in hierarchy. C<Int> is a child of
-C<Num> for example.
+Moose uses subtypes in its built-in hierarchy. For example, C<Int> is
+a child of C<Num>.
A subtype is defined in terms of a parent type and a constraint. Any
-constraints defined by the parent(s) will be checked first, and then
-the the subtype's. A value must pass I<all> of these checks to be
-valid for the subtype.
+constraints defined by the parent(s) will be checked first, followed by
+constraints defined by the subtype. A value must pass I<all> of these
+checks to be valid for the subtype.
Typically, a subtype takes the parent's constraint and makes it more
specific.
enum 'RGB' => qw( red green blue );
-This creates a type named C<RGB>
+This creates a type named C<RGB>.
=head1 ANONYMOUS TYPES
Also, did you spot the (intentional) bug?
It's in the C<_validate_birth_date()> method. We should check that
-that value in C<$birth_date> is actually defined and object before we
-go and call C<isa()> on it! Leaving out those checks means our data
+the value in C<$birth_date> is actually defined and an object before
+we go and call C<isa()> on it! Leaving out those checks means our data
validation code could actually cause our program to die. Oops.
Note that if we add a superclass to Person we'll have to change the
projects / gitmo/Moose.git / commitdiff