Commit | Line | Data |
6c40a460 |
1 | =pod |
2 | |
3 | =head1 NAME |
4 | |
5 | Moose::Manual::Classes - Making your classes use Moose (and subclassing) |
6 | |
7 | =head1 USING MOOSE |
8 | |
9 | Using Moose is very simple, you just C<use Moose>: |
10 | |
11 | package Person; |
12 | |
13 | use Moose; |
14 | |
3ac9038a |
15 | That's it, you've made a class with Moose! |
6c40a460 |
16 | |
17 | There's actually a lot going on here under the hood, so let's step |
3ac9038a |
18 | through it. |
6c40a460 |
19 | |
c460adf1 |
20 | When you load L<Moose>, a bunch of sugar functions are exported into your |
21 | class, such as C<extends>, C<has>, C<with>, and more. These functions are what |
22 | you use to define your class. For example, you might define an attribute ... |
6c40a460 |
23 | |
24 | package Person; |
25 | |
26 | use Moose; |
27 | |
28 | has 'ssn' => ( is => 'rw' ); |
29 | |
30 | Attributes are described in the L<Moose::Manual::Attributes> |
31 | documentation. |
32 | |
c460adf1 |
33 | Loading Moose also enables the C<strict> and C<warnings> pragmas in your |
dab94063 |
34 | class. |
6c40a460 |
35 | |
36 | When you load Moose, your class will become a subclass of |
37 | L<Moose::Object>. The L<Moose::Object> class provides a default |
dab94063 |
38 | constructor and destructor, as well as object construction helper |
6c40a460 |
39 | methods. You can read more about this in the |
40 | L<Moose::Manual::Construction> document. |
41 | |
3ac9038a |
42 | As a convenience, Moose creates a new class type for your class. See |
43 | the L<Moose::Manual::Types> document to learn more about types. |
6c40a460 |
44 | |
056348be |
45 | It also creates a L<Moose::Meta::Class> object for your class. This |
46 | metaclass object is now available by calling a C<meta> method on your |
47 | class, for example C<< Person->meta >>. |
48 | |
3ac9038a |
49 | The metaclass object provides an introspection API for your class. It |
50 | is also used by Moose itself under the hood to add attributes, define |
51 | parent classes, and so on. In fact, all of Moose's sugar does the real |
52 | work by calling methods on this metaclass object (and other meta API |
53 | objects). |
54 | |
6c40a460 |
55 | =head1 SUBCLASSING |
56 | |
57 | Moose provides a simple sugar function for declaring your parent |
58 | classes, C<extends>: |
59 | |
60 | package User; |
61 | |
62 | use Moose; |
63 | |
64 | extends 'Person'; |
65 | |
66 | has 'username' => ( is => 'rw' ); |
67 | |
0f62a437 |
68 | Note that each call to C<extends> will I<reset> your parents. For |
3ac9038a |
69 | multiple inheritance you must provide all the parents at once, |
70 | C<extends 'Foo', 'Bar'>. |
6c40a460 |
71 | |
72 | You can use Moose to extend a non-Moose parent. However, when you do |
73 | this, you will inherit the parent class's constructor (assuming it is |
74 | also called C<new>). In that case, you will have to take care of |
75 | initializing attributes manually, either in the parent's constructor, |
3ac9038a |
76 | or in your subclass, and you will lose a lot of Moose magic. |
6c40a460 |
77 | |
c460adf1 |
78 | See the L<MooseX::NonMoose> module on CPAN if you're interested in extending |
79 | non-Moose parent classes with Moose child classes. |
6c40a460 |
80 | |
c460adf1 |
81 | =head1 CLEANING UP MOOSE DROPPINGS |
82 | |
83 | Moose exports a number of functions into your class. It's a good idea to |
84 | remove these sugar functions from your class's namespace, so that C<< |
85 | Person->can('has') >> will no longer return true. |
86 | |
87 | There are several ways to do this. We recommend using L<namespace::autoclean>, |
88 | a CPAN module. Not only will it remove Moose exports, it will also remove |
89 | any other exports. |
6c40a460 |
90 | |
adf8494e |
91 | package Person; |
92 | |
c460adf1 |
93 | use namespace::autoclean; |
94 | |
adf8494e |
95 | use Moose; |
96 | |
c460adf1 |
97 | If you absolutely can't use a CPAN module (but can use Moose?), you can write |
98 | C<no Moose> at the end of your class. This will remove any Moose exports in |
99 | your class. |
adf8494e |
100 | |
c460adf1 |
101 | package Person; |
adf8494e |
102 | |
c460adf1 |
103 | use Moose; |
6c40a460 |
104 | |
c460adf1 |
105 | has 'ssn' => ( is => 'rw' ); |
106 | |
107 | no Moose; |
9e25a72a |
108 | |
6c40a460 |
109 | =head1 MAKING IT FASTER |
110 | |
111 | Moose has a feature called "immutabilization" that you can use to |
c460adf1 |
112 | greatly speed up your classes at runtime. However, using it incurs |
6c40a460 |
113 | a cost when your class is first being loaded. When you make your class |
3ac9038a |
114 | immutable you tell Moose that you will not be changing it in the |
9e25a72a |
115 | future. You will not be adding any more attributes, methods, roles, etc. |
6c40a460 |
116 | |
3ac9038a |
117 | This allows Moose to generate code specific to your class. In |
118 | particular, it creates an "inline" constructor, making object |
119 | construction much faster. |
6c40a460 |
120 | |
121 | To make your class immutable you simply call C<make_immutable> on your |
122 | class's metaclass object. |
123 | |
3ac9038a |
124 | __PACKAGE__->meta->make_immutable; |
125 | |
1a5d5ecd |
126 | =head2 Immutabilization and C<new()> |
127 | |
128 | If you override C<new()> in your class, then the immutabilization code |
129 | will not be able to provide an optimized constructor for your |
dab94063 |
130 | class. Instead, you should use a C<BUILD()> method, which will be |
131 | called from the inlined constructor. |
1a5d5ecd |
132 | |
133 | Alternately, if you really need to provide a different C<new()>, you |
134 | can also provide your own immutabilization method. Doing so requires |
135 | extending the Moose metaclasses, and is well beyond the scope of this |
136 | manual. |
137 | |
6c40a460 |
138 | =head1 AUTHOR |
139 | |
140 | Dave Rolsky E<lt>autarch@urth.orgE<gt> |
141 | |
142 | =head1 COPYRIGHT AND LICENSE |
143 | |
3ac9038a |
144 | Copyright 2008-2009 by Infinity Interactive, Inc. |
6c40a460 |
145 | |
146 | L<http://www.iinteractive.com> |
147 | |
148 | This library is free software; you can redistribute it and/or modify |
149 | it under the same terms as Perl itself. |
150 | |
151 | =cut |