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
303 Sometimes you want to do something whenever an object is created. In
304 those cases, you can provide a C<BUILD()> method in your class. Moose
305 will call this for you after creating a new object.
309 This is a special method called when an object instance goes out of
310 scope. You can specialize what your class does in this method if you
311 need to, but you usually don't.
313 With old school Perl 5, this is the C<DESTROY()> method, but with
314 Moose it is the C<DEMOLISH()> method.
316 =head2 Object Instance
318 An object instance is a specific noun in the class's "category". For
319 example, one specific Person or User. An instance is created by the
320 class's B<constructor>.
322 An instance has values for its attributes. For example, a specific
323 person has a first and last name,
325 In old school Perl 5, this is often a blessed hash reference. With
326 Moose, you should never need to know what your object instance
327 actually is. (ok, it's usually a blessed hashref with Moose too)
329 =head2 Moose VS Old School Summary
335 A package with no introspection other than mucking about in the symbol
338 With Moose, you get well-defined declaration and introspection.
342 Hand-written accessor methods, symbol table hackery, or a helper
343 module like C<Class::Accessor>.
345 With Moose, these are declaritively defined, and distinct from
350 These are pretty much the same in Moose as in old school Perl.
354 C<Class::Trait> or C<Class::Role>, or maybe C<mixin.pm>.
356 With Moose, they're part of the core feature set, and are
357 introspectable like everything else.
359 =item * Method Modifiers
361 Could only be done through serious symbol table wizardry, and you
362 probably never saw this before (at least in Perl 5).
366 Hand-written parameter checking in your C<new()> method and accessors.
368 With Moose, you define types declaratively, and then use them by name
373 C<Class::Delegation> or C<Class::Delegator>, but probably even more
376 With Moose, this is also declarative.
380 A C<new()> method which calls C<bless> on a reference.
382 Comes for free when you define a class with Moose.
386 A C<DESTROY()> method.
388 With Moose, this is called C<DEMOLISH()>.
390 =item * Object Instance
392 A blessed reference, usually a hash reference.
394 With Moose, this is an opaque thing which has a bunch of attributes
395 and methods, as defined by its class.
397 =item * Immutabilization
399 Moose comes with a feature called "immutabilization". When you make
400 your class immutable, it means you're done adding methods, attributes,
401 roles, etc. This lets Moose optimize your class with a bunch of
402 extremely dirty in-place code generation tricks that speed up things
403 like object construction and so on.
409 A metaclass is a class that describes classes. With Moose, every class
410 you define gets a C<meta()> method. It returns a L<Moose::Meta::Class>
411 object, which has an introspection API that can tell you about the
414 my $meta = User->meta();
416 for my $attribute ( $meta->compute_all_applicable_attributes ) {
417 print $attribute->name(), "\n";
419 if ( $attribute->has_type_constraint ) {
420 print " type: ", $attribute->type_constraint->name, "\n";
424 for my $method ( $meta->compute_all_applicable_methods ) {
425 print $method->name, "\n";
428 Almost every concept we defined earlier has a meta class, so we have
429 L<Moose::Meta::Class>, L<Moose::Meta::Attribute>,
430 L<Moose::Meta::Method>, L<Moose::Meta::Role>,
431 L<Moose::Meta::TypeConstraint>, L<Moose::Meta::Instance>, and so on.
433 =head1 BUT I NEED TO DO IT MY WAY!
435 One of the great things about Moose, is that if you dig down and find
436 that it does something the "wrong way", you can change it by extending
437 a metaclass. For example, you can have arrayref based objects, you can
438 make your constructors strict (no unknown params allowed!), you can
439 define a naming scheme for attribute accessors, you can make a class a
440 Singleton, and much, much more.
442 Many of these extensions require surprisingly small amounts of code,
443 and once you've done it once, you'll never have to hand-code "your way
444 of doing things" again. Instead you ll just load your favorite
450 use MooseX::StrictConstructor
458 If you're still still asking yourself "Why do I need this?", then this
463 =item Another object system!?!?
465 Yes, I know there has been an explosion recently of new ways to
466 build objects in Perl 5, most of them based on inside-out objects
467 and other such things. Moose is different because it is not a new
468 object system for Perl 5, but instead an extension of the existing
471 Moose is built on top of L<Class::MOP>, which is a metaclass system
472 for Perl 5. This means that Moose not only makes building normal
473 Perl 5 objects better, but it also provides the power of metaclass
476 =item Is this for real? Or is this just an experiment?
478 Moose is I<based> on the prototypes and experiments Stevan did for the
479 Perl 6 meta-model. However, Moose is B<NOT> an experiment or
480 prototype; it is for B<real>.
482 =item Is this ready for use in production?
486 Moose has been used successfully in production environments by several
487 people and companies. There are Moose applications which have been in
488 production with little or no issue now for well over two years. We
489 consider it highly stable and we are commited to keeping it stable.
491 Of course, in the end, you need to make this call yourself. If you
492 have any questions or concerns, please feel free to email Stevan, the
493 moose@perl.org list, or just stop by irc.perl.org#moose and ask away.
495 =item Is Moose just Perl 6 in Perl 5?
497 No. While Moose is very much inspired by Perl 6, it is not itself Perl
498 6. Instead, it is an OO system for Perl 5. Stevan built Moose because
499 he was tired of writing the same old boring Perl 5 OO code, and
500 drooling over Perl 6 OO. So instead of switching to Ruby, he wrote
503 =item Wait, I<post> modern, I thought it was just I<modern>?
505 Stevan read Larry Wall's talk from the 1999 Linux World entitled
506 "Perl, the first postmodern computer language" in which he talks about
507 how he picked the features for Perl because he thought they were cool
508 and he threw out the ones that he thought sucked. This got him
509 thinking about how we have done the same thing in Moose. For Moose, we
510 have "borrowed" features from Perl 6, CLOS (LISP), Smalltalk, Java,
511 BETA, OCaml, Ruby and more, and the bits we didn't like (cause they
512 sucked) we tossed aside. So for this reason (and a few others) Stevan
513 has re-dubbed Moose a I<postmodern> object system.
521 So you're sold on Moose. Time to learn how to really use it.
523 We recommend that you start with the L<Moose::Cookbook>. If you work
524 your way through all the recipes under the basics section, you should
525 have a pretty good sense of how Moose works, and all of its basic OO
528 After that, check out the Role recipes. If you're really curious, go
529 on and read the Meta and Extending recipes, but those are mostly there
530 for people who want to be Moose wizards and change how Moose works.
532 If you want to see how Moose would translate directly old school Perl
533 5 OO code, check out the L<Moose::Unsweetened>.
537 Dave Rolsky E<lt>autarch@urth.orgE<gt> and Stevan Little
538 E<lt>stevan@iinteractive.comE<gt>
540 =head1 COPYRIGHT AND LICENSE
542 Copyright 2008 by Infinity Interactive, Inc.
544 L<http://www.iinteractive.com>
546 This library is free software; you can redistribute it and/or modify
547 it under the same terms as Perl itself.