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 => { 'last_login_date' => '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<last_login_date()> method. Under the hood, this simple calls
291 C<date()> on the User object's C<last_login_datetime> 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.
397 A metaclass is a class that describes classes. With Moose, every class
398 you define gets a C<meta()> method. It returns a L<Moose::Meta::Class>
399 object, which has an introspection API that can tell you about the
402 my $meta = User->meta();
404 for my $attribute ( $meta->compute_all_applicable_attributes ) {
405 print $attribute->name(), "\n";
407 if ( $attribute->has_type_constraint ) {
408 print " type: ", $attribute->type_constraint->name, "\n";
412 for my $method ( $meta->compute_all_applicable_methods ) {
413 print $method->name, "\n";
416 Almost every concept we defined earlier has a meta class, so we have
417 L<Moose::Meta::Class>, L<Moose::Meta::Attribute>,
418 L<Moose::Meta::Method>, L<Moose::Meta::Role>,
419 L<Moose::Meta::TypeConstraint>, L<Moose::Meta::Instance>, and so on.
421 =head1 BUT I NEED TO DO IT MY WAY!
423 One of the great things about Moose, is that if you dig down and find
424 that it does something the "wrong way", you can change it by extending
425 a metaclass. For example, you can have arrayref based objects, you can
426 make your constructors strict (no unknown params allowed!), you can
427 define a naming scheme for attribute accessors, you can make a class a
428 Singleton, and much, much more.
430 Many of these extensions require surprisingly small amounts of code,
431 and once you've done it once, you'll never have to hand-code "your way
432 of doing things" again. Instead you ll just load your favorite
438 use MooseX::StrictConstructor
446 If you're still still asking yourself "Why do I need this?", then this
451 =item Another object system!?!?
453 Yes, I know there has been an explosion recently of new ways to
454 build objects in Perl 5, most of them based on inside-out objects
455 and other such things. Moose is different because it is not a new
456 object system for Perl 5, but instead an extension of the existing
459 Moose is built on top of L<Class::MOP>, which is a metaclass system
460 for Perl 5. This means that Moose not only makes building normal
461 Perl 5 objects better, but it also provides the power of metaclass
464 =item Is this for real? Or is this just an experiment?
466 Moose is I<based> on the prototypes and experiments Stevan did for the
467 Perl 6 meta-model. However, Moose is B<NOT> an experiment or
468 prototype; it is for B<real>.
470 =item Is this ready for use in production?
474 Moose has been used successfully in production environments by several
475 people and companies. There are Moose applications which have been in
476 production with little or no issue now for well over two years. We
477 consider it highly stable and we are commited to keeping it stable.
479 Of course, in the end, you need to make this call yourself. If you
480 have any questions or concerns, please feel free to email Stevan, the
481 moose@perl.org list, or just stop by irc.perl.org#moose and ask away.
483 =item Is Moose just Perl 6 in Perl 5?
485 No. While Moose is very much inspired by Perl 6, it is not itself Perl
486 6. Instead, it is an OO system for Perl 5. Stevan built Moose because
487 he was tired of writing the same old boring Perl 5 OO code, and
488 drooling over Perl 6 OO. So instead of switching to Ruby, he wrote
491 =item Wait, I<post> modern, I thought it was just I<modern>?
493 Stevan read Larry Wall's talk from the 1999 Linux World entitled
494 "Perl, the first postmodern computer language" in which he talks about
495 how he picked the features for Perl because he thought they were cool
496 and he threw out the ones that he thought sucked. This got him
497 thinking about how we have done the same thing in Moose. For Moose, we
498 have "borrowed" features from Perl 6, CLOS (LISP), Smalltalk, Java,
499 BETA, OCaml, Ruby and more, and the bits we didn't like (cause they
500 sucked) we tossed aside. So for this reason (and a few others) Stevan
501 has re-dubbed Moose a I<postmodern> object system.
509 Dave Rolsky E<lt>autarch@urth.orgE<gt> and Stevan Little
510 E<lt>stevan@iinteractive.comE<gt>
512 =head1 COPYRIGHT AND LICENSE
514 Copyright 2008 by Infinity Interactive, Inc.
516 L<http://www.iinteractive.com>
518 This library is free software; you can redistribute it and/or modify
519 it under the same terms as Perl itself.