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 | |
3ac9038a |
20 | When you load L<Moose>, a bunch of sugar functions are exported into |
6c40a460 |
21 | your class. These include things like C<extends>, C<has>, C<with>, and |
22 | more. These functions are what you use to define your class. For |
23 | example, you might define an attribute ... |
24 | |
25 | package Person; |
26 | |
27 | use Moose; |
28 | |
29 | has 'ssn' => ( is => 'rw' ); |
30 | |
31 | Attributes are described in the L<Moose::Manual::Attributes> |
32 | documentation. |
33 | |
3ac9038a |
34 | Loading Moose also turns enables C<strict> and C<warnings> pragmas in |
35 | your class. |
6c40a460 |
36 | |
37 | When you load Moose, your class will become a subclass of |
38 | L<Moose::Object>. The L<Moose::Object> class provides a default |
39 | constructor, destructor, as well as object construction helper |
40 | methods. You can read more about this in the |
41 | L<Moose::Manual::Construction> document. |
42 | |
3ac9038a |
43 | As a convenience, Moose creates a new class type for your class. See |
44 | the L<Moose::Manual::Types> document to learn more about types. |
6c40a460 |
45 | |
056348be |
46 | It also creates a L<Moose::Meta::Class> object for your class. This |
47 | metaclass object is now available by calling a C<meta> method on your |
48 | class, for example C<< Person->meta >>. |
49 | |
3ac9038a |
50 | The metaclass object provides an introspection API for your class. It |
51 | is also used by Moose itself under the hood to add attributes, define |
52 | parent classes, and so on. In fact, all of Moose's sugar does the real |
53 | work by calling methods on this metaclass object (and other meta API |
54 | objects). |
55 | |
6c40a460 |
56 | =head1 SUBCLASSING |
57 | |
58 | Moose provides a simple sugar function for declaring your parent |
59 | classes, C<extends>: |
60 | |
61 | package User; |
62 | |
63 | use Moose; |
64 | |
65 | extends 'Person'; |
66 | |
67 | has 'username' => ( is => 'rw' ); |
68 | |
0f62a437 |
69 | Note that each call to C<extends> will I<reset> your parents. For |
3ac9038a |
70 | multiple inheritance you must provide all the parents at once, |
71 | C<extends 'Foo', 'Bar'>. |
6c40a460 |
72 | |
73 | You can use Moose to extend a non-Moose parent. However, when you do |
74 | this, you will inherit the parent class's constructor (assuming it is |
75 | also called C<new>). In that case, you will have to take care of |
76 | initializing attributes manually, either in the parent's constructor, |
3ac9038a |
77 | or in your subclass, and you will lose a lot of Moose magic. |
6c40a460 |
78 | |
79 | =head1 NO MOOSE |
80 | |
81 | Moose also allows you to remove its sugar functions from your class's |
82 | namespace. We recommend that you take advantage of this feature, since |
83 | it just makes your classes "cleaner". You can do this by simply adding |
84 | C<no Moose> at the end of your module file. |
85 | |
3ac9038a |
86 | This deletes Moose's sugar functions from your class's namespace, so |
6c40a460 |
87 | that C<< Person->can('has') >> will no longer return true. |
88 | |
89 | =head1 MAKING IT FASTER |
90 | |
91 | Moose has a feature called "immutabilization" that you can use to |
92 | greatly speed up your classes at runtime. However, using it does incur |
93 | a cost when your class is first being loaded. When you make your class |
3ac9038a |
94 | immutable you tell Moose that you will not be changing it in the |
95 | future. You will not adding any more attributes, methods, roles, etc. |
6c40a460 |
96 | |
3ac9038a |
97 | This allows Moose to generate code specific to your class. In |
98 | particular, it creates an "inline" constructor, making object |
99 | construction much faster. |
6c40a460 |
100 | |
101 | To make your class immutable you simply call C<make_immutable> on your |
102 | class's metaclass object. |
103 | |
3ac9038a |
104 | __PACKAGE__->meta->make_immutable; |
105 | |
1a5d5ecd |
106 | =head2 Immutabilization and C<new()> |
107 | |
108 | If you override C<new()> in your class, then the immutabilization code |
109 | will not be able to provide an optimized constructor for your |
110 | class. Instead, you should use C<BUILD()> method, which will be called |
111 | from the inlined constructor. |
112 | |
113 | Alternately, if you really need to provide a different C<new()>, you |
114 | can also provide your own immutabilization method. Doing so requires |
115 | extending the Moose metaclasses, and is well beyond the scope of this |
116 | manual. |
117 | |
6c40a460 |
118 | =head1 AUTHOR |
119 | |
120 | Dave Rolsky E<lt>autarch@urth.orgE<gt> |
121 | |
122 | =head1 COPYRIGHT AND LICENSE |
123 | |
3ac9038a |
124 | Copyright 2008-2009 by Infinity Interactive, Inc. |
6c40a460 |
125 | |
126 | L<http://www.iinteractive.com> |
127 | |
128 | This library is free software; you can redistribute it and/or modify |
129 | it under the same terms as Perl itself. |
130 | |
131 | =cut |