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