5 Moose::Manual::Concepts - Moose OO Concepts
7 =head1 MOOSE CONCEPTS (VS "OLD SCHOOL" Perl)
9 In the past, you may not have thought too much about the difference
10 between packages and classes, attributes and methods, constructors and
11 methods, etc. With Moose, these are all conceptually separate things,
12 even though under the hood they're implemented with plain old Perl.
14 Our meta-object protocol (aka MOP) provides a well-defined
15 introspection features for each of those concepts, and Moose in turn
16 provides I<distinct> sugar for each of them. Moose also introduces
17 additional concepts such as roles, method modifiers, and declarative
20 Knowing what these concepts mean in Moose-speak, and how they used to
21 be done in old school Perl 5 OO is a good way to start learning to use
26 When you say "use Moose" in a package, you are making your package a
27 class. At its simplest, a class will consist simply of attributes
28 and/or methods. It can also include roles, method modifiers, and more.
30 A class I<has> zero or more B<attributes>.
32 A class I<has> zero or more B<methods>.
34 A class I<has> zero or more superclasses (aka parent classes). A
35 class inherits from its superclass(es).
37 A class I<has> zero or more B<method modifiers>. These modifiers can
38 apply to its own methods or methods that are inherited from its
41 A class I<does> zero or more B<roles>.
43 A class I<has> a B<constructor> and a B<destructor>. These are
44 provided for you "for free" by Moose.
46 The B<constructor> accepts named parameters corresponding to the
47 class's attributes and uses them to initialize an B<object instance>.
49 A class I<has> a B<metaclass>, which in turn has B<meta-attributes>,
50 B<meta-methods>, and B<meta-roles>. This metaclass I<describes> the
53 A class is usually analogous to a category of nouns, like "People" or
59 # now it's a Moose class!
63 An attribute is a property of the class that defines it. It I<always>
64 has a name, and it I<may have> a number of other defining
67 These characteristics may include a read/write flag, a B<type>,
68 accessor method names, B<delegations>, a default value, and more.
70 Attributes I<are not> methods, but defining them causes various
71 accessor methods to be created. At a minimum, a normal attribute will
72 always have a reader accessor method. Many attributes have things like
73 a writer method, clearer method, and predicate method ("has it been
76 An attribute may also define B<delegation>s, which will create
77 additional methods based on the delegation specification.
79 By default, Moose stores attributes in the object instance, which is a
80 hashref, I<but this is invisible to the author of a Moose-base class>!
81 It is best to think of Moose attributes as "properties" of the
82 I<opaque> B<object instance>. These properties are accessed through
83 well-defined accessor methods.
85 An attribute is something that the class's members have. For example,
86 People have first and last names. Users have passwords and last login
96 A method is very straightforward. Any subroutine you define in your
99 Methods correspond to verbs, and are what your objects can do. For
100 example, a User can login.
106 A role is something that a class I<does>. For example, a Machine class
107 might do the Breakable role, and so could a Bone class. A role is
108 used to define some concept that cuts across multiple unrelated
109 classes, like "breakability", or "has a color".
111 A role I<has> zero or more B<attributes>.
113 A role I<has> zero or more B<methods>.
115 A role I<has> zero or more B<method modifiers>.
117 A role I<has> zero or more B<required methods>.
119 A required method is not implemented by the role. Required methods say
120 "to use this Role you must implement this method".
122 Roles are I<composed> into classes (or other roles). When a role is
123 composed into a class, its attributes and methods are "flattened" into
124 the class. Roles I<do not> show up in the inheritance hierarchy. When
125 a role is composed, its attributes and methods appear as if they were
126 defined I<in the consuming class>.
128 Role are somewhat like mixins or interfaces in other OO languages.
147 =head2 Method Modifiers
149 A method modifier is a hook that is called when a named method is
150 called. For example, you could say "before calling C<login()>, call
151 this modifier first". Modifiers come in different flavors like
152 "before", "after", "around", and "augment", and you can apply more
153 than one modifier to a single method.
155 Method modifiers are often used as an alternative to overriding a
156 method in a parent class. They are also used in roles as a way of
157 modifying methods in the consuming class.
159 Under the hood, a method modifier is just a plain old Perl subroutine
160 that gets called before or after (or around, etc.) some named method.
162 before 'login' => sub {
166 warn "Called login() with $pw\n";
171 Moose also comes with a (miniature) type system. This allows you to
172 define types for attributes. Moose has a set of built-in types based
173 on what Perl provides, such as "Str", "Num", "Bool", "HashRef", etc.
175 In addition, every class name in your application can also be used as
176 a type name. We saw an example using "DateTime" earlier.
178 Finally, you can define your own types, either as subtypes or entirely
179 new types, with their own constraints. For example, you could define a
180 type "PosInt", a subtype of "Int" which only allows positive numbers.
184 Moose attributes provide declarative syntax for defining
185 delegations. A delegation is a method which calls some method on an
186 attribute to do its real work.
190 A constructor creates an B<object instance> for the class. In old
191 school Perl, this was usually done by defining a method called
192 C<new()> which in turn called C<bless> on a reference.
194 With Moose, this C<new()> method is created for you, and it simply
195 does the right thing. You should never need to define your own
198 Sometimes you want to do something whenever an object is created. In
199 those cases, you can provide a C<BUILD()> method in your class. Moose
200 will call this for you after creating a new object.
204 This is a special method called when an object instance goes out of
205 scope. You can specialize what your class does in this method if you
206 need to, but you usually don't.
208 With old school Perl 5, this is the C<DESTROY()> method, but with
209 Moose it is the C<DEMOLISH()> method.
211 =head2 Object Instance
213 An object instance is a specific noun in the class's "category". For
214 example, one specific Person or User. An instance is created by the
215 class's B<constructor>.
217 An instance has values for its attributes. For example, a specific
218 person has a first and last name.
220 In old school Perl 5, this is often a blessed hash reference. With
221 Moose, you should never need to know what your object instance
222 actually is. (ok, it's usually a blessed hashref with Moose too)
224 =head2 Moose VS Old School Summary
230 A package with no introspection other than mucking about in the symbol
233 With Moose, you get well-defined declaration and introspection.
237 Hand-written accessor methods, symbol table hackery, or a helper
238 module like C<Class::Accessor>.
240 With Moose, these are declaratively defined, and distinct from
245 These are pretty much the same in Moose as in old school Perl.
249 C<Class::Trait> or C<Class::Role>, or maybe C<mixin.pm>.
251 With Moose, they're part of the core feature set, and are
252 introspectable like everything else.
254 =item * Method Modifiers
256 Could only be done through serious symbol table wizardry, and you
257 probably never saw this before (at least in Perl 5).
261 Hand-written parameter checking in your C<new()> method and accessors.
263 With Moose, you define types declaratively, and then use them by name
268 C<Class::Delegation> or C<Class::Delegator>, but probably even more
271 With Moose, this is also declarative.
275 A C<new()> method which calls C<bless> on a reference.
277 Comes for free when you define a class with Moose.
281 A C<DESTROY()> method.
283 With Moose, this is called C<DEMOLISH()>.
285 =item * Object Instance
287 A blessed reference, usually a hash reference.
289 With Moose, this is an opaque thing which has a bunch of attributes
290 and methods, as defined by its class.
292 =item * Immutabilization
294 Moose comes with a feature called "immutabilization". When you make
295 your class immutable, it means you're done adding methods, attributes,
296 roles, etc. This lets Moose optimize your class with a bunch of
297 extremely dirty in-place code generation tricks that speed up things
298 like object construction and so on.
304 A metaclass is a class that describes classes. With Moose, every class
305 you define gets a C<meta()> method. It returns a L<Moose::Meta::Class>
306 object, which has an introspection API that can tell you about the
309 my $meta = User->meta();
311 for my $attribute ( $meta->compute_all_applicable_attributes ) {
312 print $attribute->name(), "\n";
314 if ( $attribute->has_type_constraint ) {
315 print " type: ", $attribute->type_constraint->name, "\n";
319 for my $method ( $meta->compute_all_applicable_methods ) {
320 print $method->name, "\n";
323 Almost every concept we defined earlier has a meta class, so we have
324 L<Moose::Meta::Class>, L<Moose::Meta::Attribute>,
325 L<Moose::Meta::Method>, L<Moose::Meta::Role>,
326 L<Moose::Meta::TypeConstraint>, L<Moose::Meta::Instance>, and so on.
328 =head1 BUT I NEED TO DO IT MY WAY!
330 One of the great things about Moose is that if you dig down and find
331 that it does something the "wrong way", you can change it by extending
332 a metaclass. For example, you can have arrayref based objects, you can
333 make your constructors strict (no unknown params allowed!), you can
334 define a naming scheme for attribute accessors, you can make a class a
335 Singleton, and much, much more.
337 Many of these extensions require surprisingly small amounts of code,
338 and once you've done it once, you'll never have to hand-code "your way
339 of doing things" again. Instead you'll just load your favorite
345 use MooseX::StrictConstructor
352 So you're sold on Moose. Time to learn how to really use it.
354 If you want to see how Moose would translate directly old school Perl
355 5 OO code, check out L<Moose::Unsweetened>. This might be helpful for
356 quickly wrapping your brain around some aspects of "the Moose way".
358 Obviously, the next thing to read is the rest of the L<Moose::Manual>.
360 After that we recommend that you start with the L<Moose::Cookbook>. If
361 you work your way through all the recipes under the basics section,
362 you should have a pretty good sense of how Moose works, and all of its
365 After that, check out the Role recipes. If you're really curious, go
366 on and read the Meta and Extending recipes, but those are mostly there
367 for people who want to be Moose wizards and change how Moose works.
371 Dave Rolsky E<lt>autarch@urth.orgE<gt>
373 =head1 COPYRIGHT AND LICENSE
375 Copyright 2008 by Infinity Interactive, Inc.
377 L<http://www.iinteractive.com>
379 This library is free software; you can redistribute it and/or modify
380 it under the same terms as Perl itself.