Commit | Line | Data |
99ece779 |
1 | |
cde84af5 |
2 | |
3 | =head1 NAME |
4 | |
d67ce58f |
5 | Moose::Manual::Concepts - Moose OO concepts |
cde84af5 |
6 | |
7 | =head1 MOOSE CONCEPTS (VS "OLD SCHOOL" Perl) |
8 | |
9 | In the past, you may not have thought too much about the difference |
10 | between packages and classes, attributes and methods, constructors and |
8f765b9e |
11 | methods, etc. With Moose, these are all conceptually separate things, |
12 | even though under the hood they're implemented with plain old Perl. |
13 | |
cb8ad101 |
14 | Our meta-object protocol (aka MOP) provides well-defined introspection |
15 | features for each of those concepts, and Moose in turn provides |
16 | distinct sugar for each of them. Moose also introduces additional |
17 | concepts such as roles, method modifiers, and declarative delegation. |
cde84af5 |
18 | |
19 | Knowing what these concepts mean in Moose-speak, and how they used to |
20 | be done in old school Perl 5 OO is a good way to start learning to use |
21 | Moose. |
22 | |
23 | =head2 Class |
24 | |
8f765b9e |
25 | When you say "use Moose" in a package, you are making your package a |
26 | class. At its simplest, a class will consist simply of attributes |
cde84af5 |
27 | and/or methods. It can also include roles, method modifiers, and more. |
28 | |
29 | A class I<has> zero or more B<attributes>. |
30 | |
31 | A class I<has> zero or more B<methods>. |
32 | |
33 | A class I<has> zero or more superclasses (aka parent classes). A |
34 | class inherits from its superclass(es). |
35 | |
36 | A class I<has> zero or more B<method modifiers>. These modifiers can |
37 | apply to its own methods or methods that are inherited from its |
38 | ancestors. |
39 | |
cb8ad101 |
40 | A class I<does> (and I<consumes>) zero or more B<roles>. |
cde84af5 |
41 | |
42 | A class I<has> a B<constructor> and a B<destructor>. These are |
43 | provided for you "for free" by Moose. |
44 | |
45 | The B<constructor> accepts named parameters corresponding to the |
46 | class's attributes and uses them to initialize an B<object instance>. |
47 | |
48 | A class I<has> a B<metaclass>, which in turn has B<meta-attributes>, |
49 | B<meta-methods>, and B<meta-roles>. This metaclass I<describes> the |
50 | class. |
51 | |
52 | A class is usually analogous to a category of nouns, like "People" or |
53 | "Users". |
54 | |
55 | package Person; |
56 | |
57 | use Moose; |
58 | # now it's a Moose class! |
59 | |
60 | =head2 Attribute |
61 | |
62 | An attribute is a property of the class that defines it. It I<always> |
cb8ad101 |
63 | has a name, and it I<may have> a number of other properties. |
cde84af5 |
64 | |
cb8ad101 |
65 | These properties can include a read/write flag, a B<type>, accessor |
66 | method names, B<delegations>, a default value, and more. |
cde84af5 |
67 | |
68 | Attributes I<are not> methods, but defining them causes various |
69 | accessor methods to be created. At a minimum, a normal attribute will |
dab94063 |
70 | always have a reader accessor method. Many attributes also have other |
71 | methods, such as a writer method, clearer method, and predicate method |
cb8ad101 |
72 | ("has it been set?"). |
cde84af5 |
73 | |
cb8ad101 |
74 | An attribute may also define B<delegations>, which will create |
75 | additional methods based on the delegation mapping. |
cde84af5 |
76 | |
77 | By default, Moose stores attributes in the object instance, which is a |
cb8ad101 |
78 | hashref, I<but this is invisible to the author of a Moose-based |
79 | class>! It is best to think of Moose attributes as "properties" of |
80 | the I<opaque> B<object instance>. These properties are accessed |
81 | through well-defined accessor methods. |
cde84af5 |
82 | |
8f765b9e |
83 | An attribute is something that the class's members have. For example, |
84 | People have first and last names. Users have passwords and last login |
85 | datetimes. |
cde84af5 |
86 | |
87 | has 'first_name' => ( |
88 | is => 'rw', |
89 | isa => 'Str', |
90 | ); |
91 | |
92 | =head2 Method |
93 | |
cb8ad101 |
94 | A B<method> is very straightforward. Any subroutine you define in your |
cde84af5 |
95 | class is a method. |
96 | |
cb8ad101 |
97 | B<Methods> correspond to verbs, and are what your objects can do. For |
cde84af5 |
98 | example, a User can login. |
99 | |
100 | sub login { ... } |
101 | |
102 | =head2 Roles |
103 | |
cb8ad101 |
104 | A role is something that a class I<does>. We also say that classes |
105 | I<consume> roles. For example, a Machine class might do the Breakable |
106 | role, and so could a Bone class. A role is used to define some concept |
107 | that cuts across multiple unrelated classes, like "breakability", or |
108 | "has a color". |
cde84af5 |
109 | |
110 | A role I<has> zero or more B<attributes>. |
111 | |
112 | A role I<has> zero or more B<methods>. |
113 | |
114 | A role I<has> zero or more B<method modifiers>. |
115 | |
116 | A role I<has> zero or more B<required methods>. |
117 | |
8f765b9e |
118 | A required method is not implemented by the role. Required methods say |
119 | "to use this Role you must implement this method". |
cde84af5 |
120 | |
cb8ad101 |
121 | A role I<has> zero or more B<excluded roles>. |
122 | |
123 | An excluded role is a role that the role doing the excluding says it |
124 | cannot be combined with. |
125 | |
cde84af5 |
126 | Roles are I<composed> into classes (or other roles). When a role is |
127 | composed into a class, its attributes and methods are "flattened" into |
128 | the class. Roles I<do not> show up in the inheritance hierarchy. When |
129 | a role is composed, its attributes and methods appear as if they were |
130 | defined I<in the consuming class>. |
131 | |
132 | Role are somewhat like mixins or interfaces in other OO languages. |
133 | |
134 | package Breakable; |
135 | |
136 | use Moose::Role; |
137 | |
138 | has is_broken => ( |
139 | is => 'rw', |
140 | isa => 'Bool', |
141 | ); |
142 | |
143 | requires 'break'; |
144 | |
145 | before 'break' => { |
146 | my $self = shift; |
147 | |
148 | $self->is_broken(1); |
149 | }; |
150 | |
d67ce58f |
151 | =head2 Method modifiers |
cde84af5 |
152 | |
cb8ad101 |
153 | A B<method modifier> is a hook that is called when a named method is |
8f765b9e |
154 | called. For example, you could say "before calling C<login()>, call |
155 | this modifier first". Modifiers come in different flavors like |
156 | "before", "after", "around", and "augment", and you can apply more |
157 | than one modifier to a single method. |
cde84af5 |
158 | |
159 | Method modifiers are often used as an alternative to overriding a |
160 | method in a parent class. They are also used in roles as a way of |
161 | modifying methods in the consuming class. |
162 | |
163 | Under the hood, a method modifier is just a plain old Perl subroutine |
164 | that gets called before or after (or around, etc.) some named method. |
165 | |
166 | before 'login' => sub { |
167 | my $self = shift; |
168 | my $pw = shift; |
169 | |
170 | warn "Called login() with $pw\n"; |
171 | }; |
172 | |
173 | =head2 Type |
174 | |
175 | Moose also comes with a (miniature) type system. This allows you to |
176 | define types for attributes. Moose has a set of built-in types based |
6549b0d1 |
177 | on what Perl provides, such as C<Str>, C<Num>, C<Bool>, C<HashRef>, etc. |
cde84af5 |
178 | |
179 | In addition, every class name in your application can also be used as |
dab94063 |
180 | a type name. |
cde84af5 |
181 | |
182 | Finally, you can define your own types, either as subtypes or entirely |
183 | new types, with their own constraints. For example, you could define a |
6549b0d1 |
184 | type C<PosInt>, a subtype of C<Int> which only allows positive numbers. |
cde84af5 |
185 | |
186 | =head2 Delegation |
187 | |
188 | Moose attributes provide declarative syntax for defining |
8f765b9e |
189 | delegations. A delegation is a method which calls some method on an |
190 | attribute to do its real work. |
cde84af5 |
191 | |
192 | =head2 Constructor |
193 | |
194 | A constructor creates an B<object instance> for the class. In old |
195 | school Perl, this was usually done by defining a method called |
196 | C<new()> which in turn called C<bless> on a reference. |
197 | |
198 | With Moose, this C<new()> method is created for you, and it simply |
199 | does the right thing. You should never need to define your own |
200 | constructor! |
201 | |
202 | Sometimes you want to do something whenever an object is created. In |
203 | those cases, you can provide a C<BUILD()> method in your class. Moose |
204 | will call this for you after creating a new object. |
205 | |
206 | =head2 Destructor |
207 | |
208 | This is a special method called when an object instance goes out of |
209 | scope. You can specialize what your class does in this method if you |
210 | need to, but you usually don't. |
211 | |
212 | With old school Perl 5, this is the C<DESTROY()> method, but with |
213 | Moose it is the C<DEMOLISH()> method. |
214 | |
d67ce58f |
215 | =head2 Object instance |
cde84af5 |
216 | |
217 | An object instance is a specific noun in the class's "category". For |
218 | example, one specific Person or User. An instance is created by the |
219 | class's B<constructor>. |
220 | |
221 | An instance has values for its attributes. For example, a specific |
222 | person has a first and last name. |
223 | |
224 | In old school Perl 5, this is often a blessed hash reference. With |
225 | Moose, you should never need to know what your object instance |
6549b0d1 |
226 | actually is. (Okay, it's usually a blessed hashref with Moose, too.) |
cde84af5 |
227 | |
d67ce58f |
228 | =head2 Moose vs old school summary |
cde84af5 |
229 | |
230 | =over 4 |
231 | |
232 | =item * Class |
233 | |
234 | A package with no introspection other than mucking about in the symbol |
235 | table. |
236 | |
237 | With Moose, you get well-defined declaration and introspection. |
238 | |
239 | =item * Attributes |
240 | |
241 | Hand-written accessor methods, symbol table hackery, or a helper |
242 | module like C<Class::Accessor>. |
243 | |
244 | With Moose, these are declaratively defined, and distinct from |
245 | methods. |
246 | |
247 | =item * Method |
248 | |
249 | These are pretty much the same in Moose as in old school Perl. |
250 | |
251 | =item * Roles |
252 | |
253 | C<Class::Trait> or C<Class::Role>, or maybe C<mixin.pm>. |
254 | |
255 | With Moose, they're part of the core feature set, and are |
256 | introspectable like everything else. |
257 | |
258 | =item * Method Modifiers |
259 | |
260 | Could only be done through serious symbol table wizardry, and you |
261 | probably never saw this before (at least in Perl 5). |
262 | |
263 | =item * Type |
264 | |
265 | Hand-written parameter checking in your C<new()> method and accessors. |
266 | |
267 | With Moose, you define types declaratively, and then use them by name |
268 | in your attributes. |
269 | |
270 | =item * Delegation |
271 | |
272 | C<Class::Delegation> or C<Class::Delegator>, but probably even more |
273 | hand-written code. |
274 | |
275 | With Moose, this is also declarative. |
276 | |
277 | =item * Constructor |
278 | |
279 | A C<new()> method which calls C<bless> on a reference. |
280 | |
281 | Comes for free when you define a class with Moose. |
282 | |
283 | =item * Destructor |
284 | |
285 | A C<DESTROY()> method. |
286 | |
287 | With Moose, this is called C<DEMOLISH()>. |
288 | |
289 | =item * Object Instance |
290 | |
291 | A blessed reference, usually a hash reference. |
292 | |
293 | With Moose, this is an opaque thing which has a bunch of attributes |
294 | and methods, as defined by its class. |
295 | |
296 | =item * Immutabilization |
297 | |
298 | Moose comes with a feature called "immutabilization". When you make |
299 | your class immutable, it means you're done adding methods, attributes, |
300 | roles, etc. This lets Moose optimize your class with a bunch of |
301 | extremely dirty in-place code generation tricks that speed up things |
302 | like object construction and so on. |
303 | |
304 | =back |
305 | |
306 | =head1 META WHAT? |
307 | |
308 | A metaclass is a class that describes classes. With Moose, every class |
309 | you define gets a C<meta()> method. It returns a L<Moose::Meta::Class> |
310 | object, which has an introspection API that can tell you about the |
311 | class it represents. |
312 | |
313 | my $meta = User->meta(); |
314 | |
b2df9268 |
315 | for my $attribute ( $meta->get_all_attributes ) { |
cde84af5 |
316 | print $attribute->name(), "\n"; |
317 | |
318 | if ( $attribute->has_type_constraint ) { |
319 | print " type: ", $attribute->type_constraint->name, "\n"; |
320 | } |
321 | } |
322 | |
b2df9268 |
323 | for my $method ( $meta->get_all_methods ) { |
cde84af5 |
324 | print $method->name, "\n"; |
325 | } |
326 | |
327 | Almost every concept we defined earlier has a meta class, so we have |
328 | L<Moose::Meta::Class>, L<Moose::Meta::Attribute>, |
329 | L<Moose::Meta::Method>, L<Moose::Meta::Role>, |
330 | L<Moose::Meta::TypeConstraint>, L<Moose::Meta::Instance>, and so on. |
331 | |
332 | =head1 BUT I NEED TO DO IT MY WAY! |
333 | |
334 | One of the great things about Moose is that if you dig down and find |
335 | that it does something the "wrong way", you can change it by extending |
336 | a metaclass. For example, you can have arrayref based objects, you can |
6549b0d1 |
337 | make your constructors strict (no unknown parameters allowed!), you can |
cde84af5 |
338 | define a naming scheme for attribute accessors, you can make a class a |
339 | Singleton, and much, much more. |
340 | |
341 | Many of these extensions require surprisingly small amounts of code, |
342 | and once you've done it once, you'll never have to hand-code "your way |
343 | of doing things" again. Instead you'll just load your favorite |
344 | extensions. |
345 | |
346 | package MyWay::User; |
347 | |
348 | use Moose; |
349 | use MooseX::StrictConstructor |
350 | use MooseX::MyWay; |
351 | |
352 | has ...; |
353 | |
354 | =head1 WHAT NEXT? |
355 | |
356 | So you're sold on Moose. Time to learn how to really use it. |
357 | |
dab94063 |
358 | If you want to see how Moose would translate directly into old school |
d68b26d1 |
359 | Perl 5 OO code, check out L<Moose::Manual::Unsweetened>. This might be |
dab94063 |
360 | helpful for quickly wrapping your brain around some aspects of "the |
361 | Moose way". |
cde84af5 |
362 | |
d68b26d1 |
363 | Or you can skip that and jump straight to L<Moose::Manual::Classes> |
364 | and the rest of the L<Moose::Manual>. |
cde84af5 |
365 | |
366 | After that we recommend that you start with the L<Moose::Cookbook>. If |
367 | you work your way through all the recipes under the basics section, |
368 | you should have a pretty good sense of how Moose works, and all of its |
369 | basic OO features. |
370 | |
371 | After that, check out the Role recipes. If you're really curious, go |
372 | on and read the Meta and Extending recipes, but those are mostly there |
373 | for people who want to be Moose wizards and change how Moose works. |
374 | |
375 | =head1 AUTHOR |
376 | |
377 | Dave Rolsky E<lt>autarch@urth.orgE<gt> |
378 | |
379 | =head1 COPYRIGHT AND LICENSE |
380 | |
cb8ad101 |
381 | Copyright 2008-2009 by Infinity Interactive, Inc. |
cde84af5 |
382 | |
383 | L<http://www.iinteractive.com> |
384 | |
385 | This library is free software; you can redistribute it and/or modify |
386 | it under the same terms as Perl itself. |
387 | |
388 | =cut |