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