Commit | Line | Data |
270df362 |
1 | =pod |
2 | |
3 | =head1 NAME |
4 | |
5 | Moose::Intro - What is Moose, and how do I use it? |
6 | |
7 | =head1 WHAT IS MOOSE? |
8 | |
9 | Moose is a I<complete> object system for Perl 5. If you've used a |
10821858 |
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. |
270df362 |
14 | |
15 | Moose aims to do the same thing for Perl 5 OO. We can't actually |
10821858 |
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 |
19 | methods, and so on. |
270df362 |
20 | |
10821858 |
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. |
270df362 |
24 | |
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 |
10821858 |
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 |
31 | we know and love (?). |
270df362 |
32 | |
10821858 |
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 |
35 | languages. |
270df362 |
36 | |
37 | =head1 WHY MOOSE? |
38 | |
10821858 |
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. |
270df362 |
43 | |
44 | Moose makes Perl 5 OO fun, accessible, and powerful. And if you want |
10821858 |
45 | to dig about in the guts, Moose lets you do that too, by using and |
46 | extending its powerful introspection API. |
270df362 |
47 | |
48 | =head1 AN EXAMPLE |
49 | |
50 | package Person; |
51 | |
52 | use Moose; |
53 | |
54 | has 'first_name' => ( |
55 | is => 'rw', |
56 | isa => 'Str', |
57 | ); |
58 | |
59 | has 'last_name' => ( |
60 | is => 'rw', |
61 | isa => 'Str', |
62 | ); |
63 | |
64 | This is a I<complete and usable> class definition! |
65 | |
66 | package User; |
67 | |
68 | use DateTime; |
69 | use Moose; |
70 | |
71 | extends 'Person'; |
72 | |
73 | has 'password' => ( |
74 | is => 'rw', |
75 | isa => Str ', |
76 | ); |
77 | |
78 | has 'last_login' => ( |
79 | is => 'rw', |
80 | isa => 'DateTime', |
81 | handles => { 'last_login_date' => 'date' }, |
82 | ); |
83 | |
84 | sub login { |
85 | my $self = shift; |
86 | my $pw = shift; |
87 | |
88 | return 0 if $pw ne $self->password; |
89 | |
90 | $self->last_login( DateTime->now() ); |
91 | |
92 | return 1; |
93 | } |
94 | |
95 | We'll leave the line-by-line explanation of this code to other |
10821858 |
96 | documentation, but you can see how Moose reduces common OO idioms to |
97 | simple declarative constructs. |
270df362 |
98 | |
99 | =head2 Where's the Constructor? |
100 | |
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 |
103 | your classes!> |
104 | |
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 |
109 | objects! |
110 | |
10821858 |
111 | =head1 MOOSE CONCEPTS (VS "OLD SCHOOL" Perl) |
270df362 |
112 | |
10821858 |
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. |
270df362 |
120 | |
10821858 |
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 |
123 | Moose. |
270df362 |
124 | |
125 | =head2 Class |
126 | |
127 | When you say "use Moose" in a package, you are defining your package |
10821858 |
128 | as a class. At its simplest, a class will consist simply of attributes |
270df362 |
129 | and/or methods. It can also include roles, method modifiers, and more. |
130 | |
10821858 |
131 | A class I<has> zero or more B<attributes>. |
270df362 |
132 | |
133 | A class I<has> zero or more B<methods>. |
134 | |
135 | A class I<may have> one or more superclasses (aka parent classes). A |
136 | class inherits from its superclass(es). |
137 | |
138 | A class may I<have> B<method modifiers>. These modifiers can apply to |
10821858 |
139 | its own methods or methods that are inherited from its ancestors. |
270df362 |
140 | |
141 | A class may I<do> one or more B<roles>. |
142 | |
10821858 |
143 | A class I<has> a B<constructor> and a B<destructor>. These are |
144 | provided for you "for free" by Moose. |
145 | |
146 | The B<constructor> accepts named parameters corresponding to the |
147 | class's attributes and uses them to initialize an B<object instances>. |
270df362 |
148 | |
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 |
151 | class. |
152 | |
153 | A class is usually analogous to a category of nouns, like "People" or |
154 | "Users". |
155 | |
10821858 |
156 | package Person; |
157 | |
158 | use Moose; |
159 | # now it's a Moose class! |
160 | |
270df362 |
161 | =head2 Attribute |
162 | |
163 | An attribute is a property of the class that defines it. It I<always> |
10821858 |
164 | has a name, and it I<may have> a number of other defining |
165 | characteristics. |
270df362 |
166 | |
10821858 |
167 | These characteristics may include a read/write flag, a B<type>, |
168 | accessor method names, B<delegations>, a default value, and more. |
270df362 |
169 | |
10821858 |
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 |
174 | set?"). |
175 | |
176 | An attribute may also define B<delegation>s, which will create |
177 | additional methods based on the delegation specification. |
270df362 |
178 | |
179 | By default, Moose stores attributes in the object instance, which is a |
10821858 |
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. |
270df362 |
184 | |
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. |
188 | |
10821858 |
189 | has 'first_name' => ( |
190 | is => 'rw', |
191 | isa => 'Str', |
192 | ); |
193 | |
270df362 |
194 | =head2 Method |
195 | |
196 | A method is very straightforward. Any subroutine you define in your |
197 | class is a method. |
198 | |
199 | Methods correspond to verbs, and are what your objects can do. For |
200 | example, a User can login. |
201 | |
10821858 |
202 | sub login { ... } |
203 | |
270df362 |
204 | =head2 Roles |
205 | |
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 |
10821858 |
209 | classes, like "breakability", or "has a color". |
270df362 |
210 | |
211 | A role I<has> zero or more B<attributes>. |
212 | |
213 | A role I<has> zero or more B<methods>. |
214 | |
215 | A role I<has> zero or more B<method modifiers>. |
216 | |
217 | A role I<has> zero or more B<required methods>. |
218 | |
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". |
221 | |
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>. |
227 | |
228 | Role are somewhat like mixins or interfaces in other OO languages. |
229 | |
230 | package Breakable; |
231 | |
232 | use Moose::Role; |
233 | |
234 | has is_broken => ( |
235 | is => 'rw', |
236 | isa => 'Bool', |
237 | ); |
238 | |
239 | requires 'break'; |
240 | |
241 | before 'break' => { |
242 | my $self = shift; |
243 | |
244 | $self->is_broken(1); |
245 | }; |
246 | |
247 | =head2 Method Modifiers |
248 | |
249 | A method modifier is a way of defining an action to be taken when a |
10821858 |
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 |
254 | a single method. |
270df362 |
255 | |
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. |
259 | |
260 | Under the hood, a method modifier is just a plain old Perl subroutine |
10821858 |
261 | that gets called before or after (or around, etc.) some named method. |
270df362 |
262 | |
263 | before 'login' => sub { |
264 | my $self = shift; |
265 | my $pw = shift; |
266 | |
267 | warn "Called login() with $pw\n"; |
268 | }; |
269 | |
270 | =head2 Type |
271 | |
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. |
275 | |
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. |
278 | |
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 |
10821858 |
281 | type "PosInt", a subtype of "Int" which only allows positive numbers. |
270df362 |
282 | |
283 | =head2 Delegation |
284 | |
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. |
288 | |
10821858 |
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 |
270df362 |
291 | C<date()> on the User object's C<last_login_datetime> attribute. |
292 | |
293 | =head2 Constructor |
294 | |
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. |
298 | |
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 |
10821858 |
301 | constructor! |
270df362 |
302 | |
303 | =head2 Destructor |
304 | |
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. |
308 | |
309 | With old school Perl 5, this is the C<DESTROY()> method, but with |
310 | Moose it is the C<DEMOLISH()> method. |
311 | |
312 | =head2 Object Instance |
313 | |
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>. |
317 | |
318 | An instance has values for its attributes. For example, a specific |
319 | person has a first and last name, |
320 | |
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) |
324 | |
325 | =head2 Moose VS Old School Summary |
326 | |
327 | =over 4 |
328 | |
10821858 |
329 | =item * Class |
270df362 |
330 | |
331 | A package with no introspection other than mucking about in the symbol |
332 | table. |
333 | |
334 | With Moose, you get well-defined declaration and introspection. |
335 | |
10821858 |
336 | =item * Attributes |
270df362 |
337 | |
338 | Hand-written accessor methods, symbol table hackery, or a helper |
339 | module like C<Class::Accessor>. |
340 | |
341 | With Moose, these are declaritively defined, and distinct from |
342 | methods. |
343 | |
10821858 |
344 | =item * Method |
270df362 |
345 | |
10821858 |
346 | These are pretty much the same in Moose as in old school Perl. |
270df362 |
347 | |
348 | =item * Roles |
349 | |
350 | C<Class::Trait> or C<Class::Role>, or maybe C<mixin.pm>. |
351 | |
352 | With Moose, they're part of the core feature set, and are |
353 | introspectable like everything else. |
354 | |
355 | =item * Method Modifiers |
356 | |
357 | Could only be done through serious symbol table wizardry, and you |
358 | probably never saw this before (at least in Perl 5). |
359 | |
360 | =item * Type |
361 | |
362 | Hand-written parameter checking in your C<new()> method and accessors. |
363 | |
364 | With Moose, you define types declaratively, and then use them by name |
365 | in your attributes. |
366 | |
367 | =item * Delegation |
368 | |
369 | C<Class::Delegation> or C<Class::Delegator>, but probably even more |
370 | hand-written code. |
371 | |
372 | With Moose, this is also declarative. |
373 | |
374 | =item * Constructor |
375 | |
376 | A C<new()> method which calls C<bless> on a reference. |
377 | |
10821858 |
378 | Comes for free when you define a class with Moose. |
270df362 |
379 | |
380 | =item * Destructor |
381 | |
382 | A C<DESTROY()> method. |
383 | |
384 | With Moose, this is called C<DEMOLISH()>. |
385 | |
386 | =item * Object Instance |
387 | |
388 | A blessed reference, usually a hash reference. |
389 | |
390 | With Moose, this is an opaque thing which has a bunch of attributes |
391 | and methods, as defined by its class. |
392 | |
393 | =back |
394 | |
395 | =head1 META WHAT? |
396 | |
397 | A metaclass is a class that describes classes. With Moose, every class |
10821858 |
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 |
400 | class it represents. |
270df362 |
401 | |
402 | my $meta = User->meta(); |
403 | |
404 | for my $attribute ( $meta->compute_all_applicable_attributes ) { |
405 | print $attribute->name(), "\n"; |
406 | |
407 | if ( $attribute->has_type_constraint ) { |
408 | print " type: ", $attribute->type_constraint->name, "\n"; |
409 | } |
410 | } |
411 | |
412 | for my $method ( $meta->compute_all_applicable_methods ) { |
413 | print $method->name, "\n"; |
414 | } |
415 | |
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. |
420 | |
421 | =head1 BUT I NEED TO DO IT MY WAY! |
422 | |
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 |
10821858 |
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. |
270df362 |
429 | |
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 |
10821858 |
432 | of doing things" again. Instead you ll just load your favorite |
433 | extensions. |
434 | |
435 | package MyWay::User; |
436 | |
437 | use Moose; |
438 | use MooseX::StrictConstructor |
439 | use MooseX::MyWay; |
440 | |
441 | has ...; |
442 | |
270df362 |
443 | |
444 | =head1 JUSTIFICATION |
445 | |
446 | If you're still still asking yourself "Why do I need this?", then this |
447 | section is for you. |
448 | |
449 | =over 4 |
450 | |
451 | =item Another object system!?!? |
452 | |
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 |
457 | object system. |
458 | |
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 |
462 | programming. |
463 | |
464 | =item Is this for real? Or is this just an experiment? |
465 | |
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>. |
469 | |
470 | =item Is this ready for use in production? |
471 | |
472 | Yes. |
473 | |
10821858 |
474 | Moose has been used successfully in production environments by several |
270df362 |
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. |
478 | |
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. |
482 | |
483 | =item Is Moose just Perl 6 in Perl 5? |
484 | |
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 |
489 | Moose :) |
490 | |
491 | =item Wait, I<post> modern, I thought it was just I<modern>? |
492 | |
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. |
502 | |
503 | Nuff Said. |
504 | |
505 | =back |
506 | |
507 | =head1 AUTHOR |
508 | |
10821858 |
509 | Dave Rolsky E<lt>autarch@urth.orgE<gt> and Stevan Little |
270df362 |
510 | E<lt>stevan@iinteractive.comE<gt> |
511 | |
512 | =head1 COPYRIGHT AND LICENSE |
513 | |
514 | Copyright 2008 by Infinity Interactive, Inc. |
515 | |
516 | L<http://www.iinteractive.com> |
517 | |
518 | This library is free software; you can redistribute it and/or modify |
519 | it under the same terms as Perl itself. |
520 | |
521 | =cut |