5 Moose::Intro - What is Moose, and how do I use it?
9 Moose is a I<complete> object system for Perl 5. If you've used a
10 modern object-oriented language (which Perl 5 definitely isn't), you
11 know they provide keywords for attribute declaration, object
12 construction, and inheritance. These keywords are part of the
13 language, and you don't care how they are implemented.
15 Moose aims to do the same thing for Perl 5 OO. We can't actually
16 create new keywords, but we do offer "sugar" that looks a lot like
17 them. More importantly, with Moose, you I<declaritively define> your
18 class, without needing to know about blessed hashrefs, accessor
21 Moose lets you focus on the I<logical> structure of your classes, so
22 you can focus on "what" rather than "how". With Moose, a class
23 definition should read like a list of very concise English sentences.
25 Moose is built in top of C<Class::MOP>, a meta-object protocol (aka
26 MOP). Using the MOP, Moose provides complete introspection for all
27 Moose-using classes. This means you can ask classes about their
28 attributes, parents, children, methods, etc., all using a well-defined
29 API. The MOP abstracts away tedious digging about in the Perl symbol
30 table, looking at C<@ISA> vars, and all the other crufty Perl tricks
33 Moose is based in large part on the Perl 6 object system, as well as
34 drawing on the best ideas from CLOS, Smalltalk, and many other
39 Moose makes Perl 5 OO both simpler and more powerful. It encapsulates
40 all the tricks of Perl 5 power users in high-level declarative APIs
41 which are easy to use, and don't require any special knowledge of how
42 Perl works under the hood.
44 Moose makes Perl 5 OO fun, accessible, and powerful. And if you want
45 to dig about in the guts, Moose lets you do that too, by using and
46 extending its powerful introspection API.
64 This is a I<complete and usable> class definition!
81 handles => { 'date_of_last_login' => 'date' },
88 return 0 if $pw ne $self->password;
90 $self->last_login( DateTime->now() );
95 We'll leave the line-by-line explanation of this code to other
96 documentation, but you can see how Moose reduces common OO idioms to
97 simple declarative constructs.
99 =head2 Where's the Constructor?
101 One point of confusion that might come up with Moose is how it handles
102 object construction. B<You should not define a C<new()> method for
105 Moose will provide one for you. It will accept a hash or hash
106 reference of named parameters matching your attributes. This is just
107 another way in which Moose keeps you from worrying I<how> classes are
108 implemented. Simply define a class and you're ready to start creating
111 =head1 MOOSE CONCEPTS (VS "OLD SCHOOL" Perl)
113 In the past, you may not have thought too much about the difference
114 between packages and classes, attributes and methods, constructors and
115 methods, etc. Part of what the MOP provides is well-defined
116 introspection features for each of those things, and in turn Moose
117 provides I<distinct> sugar for each of them. Moose also introduces
118 concepts that are uncommon (or entirely new) like roles, method
119 modifiers, and declarative delegation.
121 Knowing what these concepts mean in Moose-speak, and how they used to
122 be done in old school Perl 5 OO is a good way to start learning to use
127 When you say "use Moose" in a package, you are defining your package
128 as a class. At its simplest, a class will consist simply of attributes
129 and/or methods. It can also include roles, method modifiers, and more.
131 A class I<has> zero or more B<attributes>.
133 A class I<has> zero or more B<methods>.
135 A class I<has> zero or more superclasses (aka parent classes). A
136 class inherits from its superclass(es).
138 A class I<has> zero or more B<method modifiers>. These modifiers can
139 apply to its own methods or methods that are inherited from its
142 A class may I<do> one or more B<roles>.
144 A class I<has> a B<constructor> and a B<destructor>. These are
145 provided for you "for free" by Moose.
147 The B<constructor> accepts named parameters corresponding to the
148 class's attributes and uses them to initialize an B<object instance>.
150 A class I<has> a B<metaclass>, which in turn has B<meta-attributes>,
151 B<meta-methods>, and B<meta-roles>. This metaclass I<describes> the
154 A class is usually analogous to a category of nouns, like "People" or
160 # now it's a Moose class!
164 An attribute is a property of the class that defines it. It I<always>
165 has a name, and it I<may have> a number of other defining
168 These characteristics may include a read/write flag, a B<type>,
169 accessor method names, B<delegations>, a default value, and more.
171 Attributes I<are not> methods, but defining them causes various
172 accessor methods to be created. At a minimum, a normal attribute will
173 always have a reader accessor method. Many attributes have things like
174 a writer method, clearer method, and predicate method ("has it been
177 An attribute may also define B<delegation>s, which will create
178 additional methods based on the delegation specification.
180 By default, Moose stores attributes in the object instance, which is a
181 hashref, I<but this is invisible to the author of a Moose-base class>!
182 It is best to think of Moose attributes as "properties" of the
183 I<opaque> B<object instance>. These properties are accessed through
184 well-defined accessor methods.
186 An attribute is usually analogous to a specific feature of something in
187 the class's category. For example, People have first and last
188 names. Users have passwords and last login datetimes.
190 has 'first_name' => (
197 A method is very straightforward. Any subroutine you define in your
200 Methods correspond to verbs, and are what your objects can do. For
201 example, a User can login.
207 A role is something that a class I<does>. For example, a Machine class
208 might do the Breakable role, and so could a Bone class. A role is
209 used to define some concept that cuts across multiple unrelated
210 classes, like "breakability", or "has a color".
212 A role I<has> zero or more B<attributes>.
214 A role I<has> zero or more B<methods>.
216 A role I<has> zero or more B<method modifiers>.
218 A role I<has> zero or more B<required methods>.
220 A required method is not implemented by the role. Instead, a required
221 method says "to use this Role you must implement this method".
223 Roles are I<composed> into classes (or other roles). When a role is
224 composed into a class, its attributes and methods are "flattened" into
225 the class. Roles I<do not> show up in the inheritance hierarchy. When
226 a role is composed, its attributes and methods appear as if they were
227 defined I<in the consuming class>.
229 Role are somewhat like mixins or interfaces in other OO languages.
248 =head2 Method Modifiers
250 A method modifier is a way of defining an action to be taken when a
251 named method is called. Think of it as a hook on the named method. For
252 example, you could say "before calling C<login()>, call this modifier
253 first". Modifiers come in different flavors like "before", "after",
254 "around", and "augment", and you can apply more than one modifier to
257 Method modifiers are often used as an alternative to overriding a
258 method in a parent class. They are also used in roles as a way of
259 modifying methods in the consuming class.
261 Under the hood, a method modifier is just a plain old Perl subroutine
262 that gets called before or after (or around, etc.) some named method.
264 before 'login' => sub {
268 warn "Called login() with $pw\n";
273 Moose also comes with a (miniature) type system. This allows you to
274 define types for attributes. Moose has a set of built-in types based
275 on what Perl provides, such as "Str", "Num", "Bool", "HashRef", etc.
277 In addition, every class name in your application can also be used as
278 a type name. We saw an example using "DateTime" earlier.
280 Finally, you can define your own types, either as subtypes or entirely
281 new types, with their own constraints. For example, you could define a
282 type "PosInt", a subtype of "Int" which only allows positive numbers.
286 Moose attributes provide declarative syntax for defining
287 delegations. A delegation is a method which delegates the real work to
288 some attribute of the class.
290 You saw this in the User example, where we defined a delegation for
291 the C<date_of_last_login()> method. Under the hood, this simple calls
292 C<date()> on the User object's C<last_login> attribute.
296 A constructor creates an B<object instance> for the class. In old
297 school Perl, this was usually done by defining a method called
298 C<new()> which in turn called C<bless> on a reference.
300 With Moose, this C<new()> method is created for you, and it simply
301 does the right thing. You should never need to define your own
304 Sometimes you want to do something whenever an object is created. In
305 those cases, you can provide a C<BUILD()> method in your class. Moose
306 will call this for you after creating a new object.
310 This is a special method called when an object instance goes out of
311 scope. You can specialize what your class does in this method if you
312 need to, but you usually don't.
314 With old school Perl 5, this is the C<DESTROY()> method, but with
315 Moose it is the C<DEMOLISH()> method.
317 =head2 Object Instance
319 An object instance is a specific noun in the class's "category". For
320 example, one specific Person or User. An instance is created by the
321 class's B<constructor>.
323 An instance has values for its attributes. For example, a specific
324 person has a first and last name.
326 In old school Perl 5, this is often a blessed hash reference. With
327 Moose, you should never need to know what your object instance
328 actually is. (ok, it's usually a blessed hashref with Moose too)
330 =head2 Moose VS Old School Summary
336 A package with no introspection other than mucking about in the symbol
339 With Moose, you get well-defined declaration and introspection.
343 Hand-written accessor methods, symbol table hackery, or a helper
344 module like C<Class::Accessor>.
346 With Moose, these are declaritively defined, and distinct from
351 These are pretty much the same in Moose as in old school Perl.
355 C<Class::Trait> or C<Class::Role>, or maybe C<mixin.pm>.
357 With Moose, they're part of the core feature set, and are
358 introspectable like everything else.
360 =item * Method Modifiers
362 Could only be done through serious symbol table wizardry, and you
363 probably never saw this before (at least in Perl 5).
367 Hand-written parameter checking in your C<new()> method and accessors.
369 With Moose, you define types declaratively, and then use them by name
374 C<Class::Delegation> or C<Class::Delegator>, but probably even more
377 With Moose, this is also declarative.
381 A C<new()> method which calls C<bless> on a reference.
383 Comes for free when you define a class with Moose.
387 A C<DESTROY()> method.
389 With Moose, this is called C<DEMOLISH()>.
391 =item * Object Instance
393 A blessed reference, usually a hash reference.
395 With Moose, this is an opaque thing which has a bunch of attributes
396 and methods, as defined by its class.
398 =item * Immutabilization
400 Moose comes with a feature called "immutabilization". When you make
401 your class immutable, it means you're done adding methods, attributes,
402 roles, etc. This lets Moose optimize your class with a bunch of
403 extremely dirty in-place code generation tricks that speed up things
404 like object construction and so on.
410 A metaclass is a class that describes classes. With Moose, every class
411 you define gets a C<meta()> method. It returns a L<Moose::Meta::Class>
412 object, which has an introspection API that can tell you about the
415 my $meta = User->meta();
417 for my $attribute ( $meta->compute_all_applicable_attributes ) {
418 print $attribute->name(), "\n";
420 if ( $attribute->has_type_constraint ) {
421 print " type: ", $attribute->type_constraint->name, "\n";
425 for my $method ( $meta->compute_all_applicable_methods ) {
426 print $method->name, "\n";
429 Almost every concept we defined earlier has a meta class, so we have
430 L<Moose::Meta::Class>, L<Moose::Meta::Attribute>,
431 L<Moose::Meta::Method>, L<Moose::Meta::Role>,
432 L<Moose::Meta::TypeConstraint>, L<Moose::Meta::Instance>, and so on.
434 =head1 BUT I NEED TO DO IT MY WAY!
436 One of the great things about Moose is that if you dig down and find
437 that it does something the "wrong way", you can change it by extending
438 a metaclass. For example, you can have arrayref based objects, you can
439 make your constructors strict (no unknown params allowed!), you can
440 define a naming scheme for attribute accessors, you can make a class a
441 Singleton, and much, much more.
443 Many of these extensions require surprisingly small amounts of code,
444 and once you've done it once, you'll never have to hand-code "your way
445 of doing things" again. Instead you'll just load your favorite
451 use MooseX::StrictConstructor
459 If you're still still asking yourself "Why do I need this?", then this
464 =item Another object system!?!?
466 Yes, I know there has been an explosion recently of new ways to
467 build objects in Perl 5, most of them based on inside-out objects
468 and other such things. Moose is different because it is not a new
469 object system for Perl 5, but instead an extension of the existing
472 Moose is built on top of L<Class::MOP>, which is a metaclass system
473 for Perl 5. This means that Moose not only makes building normal
474 Perl 5 objects better, but it also provides the power of metaclass
477 =item Is this for real? Or is this just an experiment?
479 Moose is I<based> on the prototypes and experiments Stevan did for the
480 Perl 6 meta-model. However, Moose is B<NOT> an experiment or
481 prototype; it is for B<real>.
483 =item Is this ready for use in production?
487 Moose has been used successfully in production environments by several
488 people and companies. There are Moose applications which have been in
489 production with little or no issue now for well over two years. We
490 consider it highly stable and we are commited to keeping it stable.
492 Of course, in the end, you need to make this call yourself. If you
493 have any questions or concerns, please feel free to email Stevan, the
494 moose@perl.org list, or just stop by irc.perl.org#moose and ask away.
496 =item Is Moose just Perl 6 in Perl 5?
498 No. While Moose is very much inspired by Perl 6, it is not itself Perl
499 6. Instead, it is an OO system for Perl 5. Stevan built Moose because
500 he was tired of writing the same old boring Perl 5 OO code, and
501 drooling over Perl 6 OO. So instead of switching to Ruby, he wrote
504 =item Wait, I<post> modern, I thought it was just I<modern>?
506 Stevan read Larry Wall's talk from the 1999 Linux World entitled
507 "Perl, the first postmodern computer language" in which he talks about
508 how he picked the features for Perl because he thought they were cool
509 and he threw out the ones that he thought sucked. This got him
510 thinking about how we have done the same thing in Moose. For Moose, we
511 have "borrowed" features from Perl 6, CLOS (LISP), Smalltalk, Java,
512 BETA, OCaml, Ruby and more, and the bits we didn't like (cause they
513 sucked) we tossed aside. So for this reason (and a few others) Stevan
514 has re-dubbed Moose a I<postmodern> object system.
522 So you're sold on Moose. Time to learn how to really use it.
524 We recommend that you start with the L<Moose::Cookbook>. If you work
525 your way through all the recipes under the basics section, you should
526 have a pretty good sense of how Moose works, and all of its basic OO
529 After that, check out the Role recipes. If you're really curious, go
530 on and read the Meta and Extending recipes, but those are mostly there
531 for people who want to be Moose wizards and change how Moose works.
533 If you want to see how Moose would translate directly old school Perl
534 5 OO code, check out the L<Moose::Unsweetened>.
538 Dave Rolsky E<lt>autarch@urth.orgE<gt> and Stevan Little
539 E<lt>stevan@iinteractive.comE<gt>
541 =head1 COPYRIGHT AND LICENSE
543 Copyright 2008 by Infinity Interactive, Inc.
545 L<http://www.iinteractive.com>
547 This library is free software; you can redistribute it and/or modify
548 it under the same terms as Perl itself.