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 your 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 vs
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<may have> one or more superclasses (aka parent classes). A
136 class inherits from its superclass(es).
138 A class may I<have> B<method modifiers>. These modifiers can apply to
139 its own methods or methods that are inherited from its ancestors.
141 A class may I<do> one or more B<roles>.
143 A class I<has> a B<constructor> and a B<destructor>. These are
144 provided for you "for free" by Moose.
146 The B<constructor> accepts named parameters corresponding to the
147 class's attributes and uses them to initialize an B<object instances>.
149 A class I<has> a B<metaclass>, which in turn has B<meta-attributes>,
150 B<meta-methods>, and B<meta-roles>. This metaclass I<describes> the
153 A class is usually analogous to a category of nouns, like "People" or
159 # now it's a Moose class!
163 An attribute is a property of the class that defines it. It I<always>
164 has a name, and it I<may have> a number of other defining
167 These characteristics may include a read/write flag, a B<type>,
168 accessor method names, B<delegations>, a default value, and more.
170 Attributes I<are not> methods, but defining them causes various
171 accessor methods to be created. At a minimum, a normal attribute will
172 always have a reader accessor method. Many attributes have things like
173 a writer method, clearer method, and predicate method ("has it been
176 An attribute may also define B<delegation>s, which will create
177 additional methods based on the delegation specification.
179 By default, Moose stores attributes in the object instance, which is a
180 hashref, I<but this is invisible to the author of a Moose-base class>!
181 It is best to think of Moose attributes as "properties" of the
182 I<opaque> B<object instance>. These properties are accessed through
183 well-defined accessor methods.
185 An attribute is usually analagous to specific feature of something in
186 the class's category. For example, People have first and last
187 names. Users have passwords and last login datetimes.
189 has 'first_name' => (
196 A method is very straightforward. Any subroutine you define in your
199 Methods correspond to verbs, and are what your objects can do. For
200 example, a User can login.
206 A role is something that a class I<does>. For example, a Machine class
207 might do the Breakable role, and a so could a Bone class. A role is
208 used to define some concept that cuts across multiple unrelated
209 classes, like "breakability", or "has a color".
211 A role I<has> zero or more B<attributes>.
213 A role I<has> zero or more B<methods>.
215 A role I<has> zero or more B<method modifiers>.
217 A role I<has> zero or more B<required methods>.
219 A required method is not implemented by the role. Instead, a required
220 method says "to use this Role you must implement this method".
222 Roles are I<composed> into classes (or other roles). When a role is
223 composed into a class, its attributes and methods are "flattened" into
224 the class. Roles I<do not> show up in the inheritance hierarchy. When
225 a role is composed, it's attributes and methods appear as if they were
226 defined I<in the consuming class>.
228 Role are somewhat like mixins or interfaces in other OO languages.
247 =head2 Method Modifiers
249 A method modifier is a way of defining an action to be taken when a
250 named method is called. Think of it as a hook on the named method. For
251 example, you could say "before calling C<login()>, call this modifier
252 first". Modifiers come in different flavors like "before", "after",
253 "around", and "augment", and you can apply more than one modifier to
256 Method modifiers are often used as an alternative to overriding a
257 method in a parent class. They are also used in roles as a way of
258 modifying methods in the consuming class.
260 Under the hood, a method modifier is just a plain old Perl subroutine
261 that gets called before or after (or around, etc.) some named method.
263 before 'login' => sub {
267 warn "Called login() with $pw\n";
272 Moose also comes with a (miniature) type system. This allows you to
273 define types for attributes. Moose has a set of built-in types based
274 on what Perl provides, such as "Str", "Num", "Bool", "HashRef", etc.
276 In addition, every class name in your application can also be used as
277 a type name. We saw an example using "DateTime" earlier.
279 Finally, you can define your own types, either as subtypes or entirely
280 new types, with their own constraints. For example, you could define a
281 type "PosInt", a subtype of "Int" which only allows positive numbers.
285 Moose attributes provide declarative syntax for defining
286 delegations. A delegation is a method which delegates the real work to
287 some attribute of the class.
289 You saw this in the User example, where we defined a delegation for
290 the C<date_of_last_login()> method. Under the hood, this simple calls
291 C<date()> on the User object's C<last_login> attribute.
295 A constructor creates an B<object instance> for the class. In old
296 school Perl, this was usually done by defining a method called
297 C<new()> which in turn called C<bless> on a reference.
299 With Moose, this C<new()> method is created for you, and it simply
300 does the right thing. You should never need to define your own
305 This is a special method called when an object instance goes out of
306 scope. You can specialize what your class does in this method if you
307 need to, but you usually don't.
309 With old school Perl 5, this is the C<DESTROY()> method, but with
310 Moose it is the C<DEMOLISH()> method.
312 =head2 Object Instance
314 An object instance is a specific noun in the class's "category". For
315 example, one specific Person or User. An instance is created by the
316 class's B<constructor>.
318 An instance has values for its attributes. For example, a specific
319 person has a first and last name,
321 In old school Perl 5, this is often a blessed hash reference. With
322 Moose, you should never need to know what your object instance
323 actually is. (ok, it's usually a blessed hashref with Moose too)
325 =head2 Moose VS Old School Summary
331 A package with no introspection other than mucking about in the symbol
334 With Moose, you get well-defined declaration and introspection.
338 Hand-written accessor methods, symbol table hackery, or a helper
339 module like C<Class::Accessor>.
341 With Moose, these are declaritively defined, and distinct from
346 These are pretty much the same in Moose as in old school Perl.
350 C<Class::Trait> or C<Class::Role>, or maybe C<mixin.pm>.
352 With Moose, they're part of the core feature set, and are
353 introspectable like everything else.
355 =item * Method Modifiers
357 Could only be done through serious symbol table wizardry, and you
358 probably never saw this before (at least in Perl 5).
362 Hand-written parameter checking in your C<new()> method and accessors.
364 With Moose, you define types declaratively, and then use them by name
369 C<Class::Delegation> or C<Class::Delegator>, but probably even more
372 With Moose, this is also declarative.
376 A C<new()> method which calls C<bless> on a reference.
378 Comes for free when you define a class with Moose.
382 A C<DESTROY()> method.
384 With Moose, this is called C<DEMOLISH()>.
386 =item * Object Instance
388 A blessed reference, usually a hash reference.
390 With Moose, this is an opaque thing which has a bunch of attributes
391 and methods, as defined by its class.
393 =item * Immutabilization
395 Moose comes with a feature called "immutabilization". When you make
396 your class immutable, it means you're done adding methods, attributes,
397 roles, etc. This lets Moose optimize your class with a bunch of
398 extremely dirty in-place code generation tricks that speed up things
399 like object construction and so on.
405 A metaclass is a class that describes classes. With Moose, every class
406 you define gets a C<meta()> method. It returns a L<Moose::Meta::Class>
407 object, which has an introspection API that can tell you about the
410 my $meta = User->meta();
412 for my $attribute ( $meta->compute_all_applicable_attributes ) {
413 print $attribute->name(), "\n";
415 if ( $attribute->has_type_constraint ) {
416 print " type: ", $attribute->type_constraint->name, "\n";
420 for my $method ( $meta->compute_all_applicable_methods ) {
421 print $method->name, "\n";
424 Almost every concept we defined earlier has a meta class, so we have
425 L<Moose::Meta::Class>, L<Moose::Meta::Attribute>,
426 L<Moose::Meta::Method>, L<Moose::Meta::Role>,
427 L<Moose::Meta::TypeConstraint>, L<Moose::Meta::Instance>, and so on.
429 =head1 BUT I NEED TO DO IT MY WAY!
431 One of the great things about Moose, is that if you dig down and find
432 that it does something the "wrong way", you can change it by extending
433 a metaclass. For example, you can have arrayref based objects, you can
434 make your constructors strict (no unknown params allowed!), you can
435 define a naming scheme for attribute accessors, you can make a class a
436 Singleton, and much, much more.
438 Many of these extensions require surprisingly small amounts of code,
439 and once you've done it once, you'll never have to hand-code "your way
440 of doing things" again. Instead you ll just load your favorite
446 use MooseX::StrictConstructor
454 If you're still still asking yourself "Why do I need this?", then this
459 =item Another object system!?!?
461 Yes, I know there has been an explosion recently of new ways to
462 build objects in Perl 5, most of them based on inside-out objects
463 and other such things. Moose is different because it is not a new
464 object system for Perl 5, but instead an extension of the existing
467 Moose is built on top of L<Class::MOP>, which is a metaclass system
468 for Perl 5. This means that Moose not only makes building normal
469 Perl 5 objects better, but it also provides the power of metaclass
472 =item Is this for real? Or is this just an experiment?
474 Moose is I<based> on the prototypes and experiments Stevan did for the
475 Perl 6 meta-model. However, Moose is B<NOT> an experiment or
476 prototype; it is for B<real>.
478 =item Is this ready for use in production?
482 Moose has been used successfully in production environments by several
483 people and companies. There are Moose applications which have been in
484 production with little or no issue now for well over two years. We
485 consider it highly stable and we are commited to keeping it stable.
487 Of course, in the end, you need to make this call yourself. If you
488 have any questions or concerns, please feel free to email Stevan, the
489 moose@perl.org list, or just stop by irc.perl.org#moose and ask away.
491 =item Is Moose just Perl 6 in Perl 5?
493 No. While Moose is very much inspired by Perl 6, it is not itself Perl
494 6. Instead, it is an OO system for Perl 5. Stevan built Moose because
495 he was tired of writing the same old boring Perl 5 OO code, and
496 drooling over Perl 6 OO. So instead of switching to Ruby, he wrote
499 =item Wait, I<post> modern, I thought it was just I<modern>?
501 Stevan read Larry Wall's talk from the 1999 Linux World entitled
502 "Perl, the first postmodern computer language" in which he talks about
503 how he picked the features for Perl because he thought they were cool
504 and he threw out the ones that he thought sucked. This got him
505 thinking about how we have done the same thing in Moose. For Moose, we
506 have "borrowed" features from Perl 6, CLOS (LISP), Smalltalk, Java,
507 BETA, OCaml, Ruby and more, and the bits we didn't like (cause they
508 sucked) we tossed aside. So for this reason (and a few others) Stevan
509 has re-dubbed Moose a I<postmodern> object system.
517 So you're sold on Moose. Time to learn how to really use it.
519 We recommend that you start with the L<Moose::Cookbook>. If you work
520 your way through all the recipes under the basics section, you should
521 have a pretty good sense of how Moose works, and all of its basic OO
524 After that, check out the Role recipes. If you're really curious, go
525 on and read the Meta and Extending recipes, but those are mostly there
526 for people who want to be Moose wizards and change how Moose works.
530 Dave Rolsky E<lt>autarch@urth.orgE<gt> and Stevan Little
531 E<lt>stevan@iinteractive.comE<gt>
533 =head1 COPYRIGHT AND LICENSE
535 Copyright 2008 by Infinity Interactive, Inc.
537 L<http://www.iinteractive.com>
539 This library is free software; you can redistribute it and/or modify
540 it under the same terms as Perl itself.