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