Dzil-ize all the .pod files so they can be pod-woven
[gitmo/Moose.git] / lib / Moose / Cookbook.pod
CommitLineData
daa0fd7d 1package Moose::Cookbook;
471c4f09 2
daa0fd7d 3# ABSTRACT: How to cook a Moose
4
5__END__
471c4f09 6
471c4f09 7
daa0fd7d 8=pod
471c4f09 9
10=head1 DESCRIPTION
11
ad248e00 12The Moose cookbook is a series of recipes showing various Moose
13features. Most recipes present some code demonstrating some feature,
14and then explain the details of the code.
471c4f09 15
ad248e00 16You should probably read the L<Moose::Manual> first. The manual
17explains Moose concepts without being too code-heavy.
734d1752 18
471c4f09 19=head1 RECIPES
20
496b74ab 21=head2 Basic Moose
22
1068dcb5 23These recipes will give you a good overview of Moose's capabilities, starting
24with simple attribute declaration, and moving on to more powerful features like
25laziness, types, type coercion, method modifiers, and more.
4eec354b 26
471c4f09 27=over 4
28
021b8139 29=item L<Moose::Cookbook::Basics::Recipe1> - The (always classic) B<Point> example
471c4f09 30
dab94063 31A simple Moose-based class. Demonstrates Moose attributes and subclassing.
cb2478d4 32
021b8139 33=item L<Moose::Cookbook::Basics::Recipe2> - A simple B<BankAccount> example
471c4f09 34
f7f3648d 35A slightly more complex Moose class. Demonstrates using a method
36modifier in a subclass.
cb2478d4 37
021b8139 38=item L<Moose::Cookbook::Basics::Recipe3> - A lazy B<BinaryTree> example
471c4f09 39
f7f3648d 40Demonstrates several attribute features, including types, weak
0fde1850 41references, predicates ("does this object have a foo?"), defaults,
42laziness, and triggers.
cb2478d4 43
021b8139 44=item L<Moose::Cookbook::Basics::Recipe4> - Subtypes, and modeling a simple B<Company> class hierarchy
471c4f09 45
f7f3648d 46Introduces the creation and use of custom types, a C<BUILD> method,
47and the use of C<override> in a subclass.
cb2478d4 48
021b8139 49=item L<Moose::Cookbook::Basics::Recipe5> - More subtypes, coercion in a B<Request> class
471c4f09 50
f7f3648d 51More type examples, including the use of type coercions.
cb2478d4 52
021b8139 53=item L<Moose::Cookbook::Basics::Recipe6> - The augment/inner example
496b74ab 54
f7f3648d 55Demonstrates the use of C<augment> method modifiers, a way of turning
56the usual method overriding style "inside-out".
cb2478d4 57
021b8139 58=item L<Moose::Cookbook::Basics::Recipe7> - Making Moose fast with immutable
496b74ab 59
5de2944f 60Making a class immutable greatly increases the speed of accessors and
61object construction.
cb2478d4 62
1f476b5f 63=item L<Moose::Cookbook::Basics::Recipe8> - Builder methods and lazy_build
496b74ab 64
fbd7ad7a 65The builder feature provides an inheritable and role-composable way to
66provide a default attribute value.
cb2478d4 67
1f476b5f 68=item L<Moose::Cookbook::Basics::Recipe9> - Operator overloading, subtypes, and coercion
c2a0627f 69
48757542 70Demonstrates using operator overloading, coercion, and subtypes to
a8b3fe62 71model how eye color is determined during reproduction.
c2a0627f 72
1f476b5f 73=item L<Moose::Cookbook::Basics::Recipe10> - Using BUILDARGS and BUILD to hook into object construction
45ef8386 74
04d80e2a 75This recipe demonstrates the use of C<BUILDARGS> and C<BUILD> to hook
76into object construction.
45ef8386 77
1f476b5f 78=item L<Moose::Cookbook::Basics::Recipe11> - Extending a non-Moose base class
5f9e373d 79
80In this recipe, we make a Moose-based subclass of L<DateTime>, a
81module which does not use Moose itself.
82
496b74ab 83=back
84
85=head2 Moose Roles
86
4eec354b 87These recipes will show you how to use Moose roles.
88
496b74ab 89=over 4
90
13dbfe49 91=item L<Moose::Cookbook::Roles::Recipe1> - The Moose::Role example
496b74ab 92
f7f3648d 93Demonstrates roles, which are also sometimes known as traits or
94mix-ins. Roles provide a method of code re-use which is orthogonal to
95subclassing.
cb2478d4 96
13dbfe49 97=item L<Moose::Cookbook::Roles::Recipe2> - Advanced Role Composition - method exclusion and aliasing
496b74ab 98
2e3d0a0a 99Sometimes you just want to include part of a role in your
dab94063 100class. Sometimes you want the whole role but one of its methods
2e3d0a0a 101conflicts with one in your class. With method exclusion and aliasing,
102you can work around these problems.
cb2478d4 103
9a823f26 104=item L<Moose::Cookbook::Roles::Recipe3> - Applying a role to an object instance
104379bc 105
9a823f26 106In this recipe, we apply a role to an existing object instance.
cb2478d4 107
496b74ab 108=back
109
110=head2 Meta Moose
111
4eec354b 112These recipes show you how to write your own meta classes, which lets
dab94063 113you extend the object system provided by Moose.
4eec354b 114
496b74ab 115=over 4
116
17a65b17 117=item L<Moose::Cookbook::Meta::Recipe1> - Welcome to the meta-world (Why Go Meta?)
496b74ab 118
38031ac8 119If you're wondering what all this "meta" stuff is, and why you should
120care about it, read this "recipe".
cb2478d4 121
43aa5bf9 122=item L<Moose::Cookbook::Meta::Recipe2> - A meta-attribute, attributes with labels
496b74ab 123
f7f3648d 124One way to extend Moose is to provide your own attribute
125metaclasses. Attribute metaclasses let you extend attribute
126declarations (with C<has>) and behavior to provide additional
127attribute functionality.
cb2478d4 128
43aa5bf9 129=item L<Moose::Cookbook::Meta::Recipe3> - Labels implemented via attribute traits
a7d0cd00 130
aff0421c 131Extending Moose's attribute metaclass is a great way to add
132functionality. However, attributes can only have one metaclass.
133Applying roles to the attribute metaclass lets you provide
134composable attribute functionality.
cb2478d4 135
3f002851 136=item L<Moose::Cookbook::Meta::Recipe4> - Adding a "table" attribute to the metaclass
137
138If you want to store more information about your classes, you'll have
139to extend C<Moose::Meta::Class>. Doing so is simple, but you'll
140probably also want to provide some sugar, so see
c5b9daec 141L<Moose::Cookbook::Extending::Recipe2> as well.
3f002851 142
c5b9daec 143=item L<Moose::Cookbook::Meta::Recipe5> - The "table" attribute implemented as a metaclass trait
24a8fe99 144
505dcac2 145This recipe takes the class metaclass we saw in the previous recipe
c5b9daec 146and reimplements it as a metaclass trait.
cb2478d4 147
505dcac2 148=item L<Moose::Cookbook::Meta::Recipe6> - A method metaclass for marking methods public or private
149
150This recipe shows a custom method metaclass that implements making a
151method private.
152
153=item L<Moose::Cookbook::Meta::Recipe7> - Using a blessed array reference as an object instance
154
155This recipe shows an example of how you create your own meta-instance
156class. The meta-instance determines the internal structure of object
157instances and provide access to attribute slots.
158
19768d67 159=item Moose::Cookbook::Meta::Recipe8 - Hooking into immutabilization (TODO)
1acd5999 160
161Moose has a feature known as "immutabilization". By calling C<<
162__PACKAGE__->meta()->make_immutable() >> after defining your class
163(attributes, roles, etc), you tell Moose to optimize things like
164object creation, attribute access, and so on.
165
166If you are creating your own metaclasses, you may need to hook into
167the immutabilization system. This cuts across a number of spots,
168including the metaclass class, meta method classes, and possibly the
169meta-instance class as well.
170
171This recipe shows you how to write extensions which immutabilize
172properly.
173
49f6b0ac 174=back
175
6fa0a13f 176=head2 Extending Moose
177
4eec354b 178These recipes cover some more ways to extend Moose, and will be useful
179if you plan to write your own C<MooseX> module.
180
49f6b0ac 181=over 4
182
c8d5f1e1 183=item L<Moose::Cookbook::Extending::Recipe1> - Moose extension overview
184
dab94063 185There are quite a few ways to extend Moose. This recipe provides an
186overview of each method, and provides recommendations for when each is
187appropriate.
c8d5f1e1 188
f3ce0579 189=item L<Moose::Cookbook::Extending::Recipe2> - Providing a base object class role
c8d5f1e1 190
191Many base object class extensions can be implemented as roles. This
f3ce0579 192example shows how to provide a base object class debugging role that
193is applied to any class that uses a notional C<MooseX::Debugging>
194module.
c8d5f1e1 195
196=item L<Moose::Cookbook::Extending::Recipe3> - Providing an alternate base object class
6fa0a13f 197
198You may find that you want to provide an alternate base object class
199along with a meta extension, or maybe you just want to add some
200functionality to all your classes without typing C<extends
201'MyApp::Base'> over and over.
202
c8d5f1e1 203=item L<Moose::Cookbook::Extending::Recipe4> - Acting like Moose.pm and providing sugar Moose-style
6fa0a13f 204
c5b9daec 205This recipe shows how to provide a replacement for C<Moose.pm>. You
206may want to do this as part of the API for a C<MooseX> module,
5583dc1c 207especially if you want to default to a new metaclass class or base
208object class.
6fa0a13f 209
cb2478d4 210=back
211
212=head1 SNACKS
213
214=over 4
215
f4ebf54f 216=item L<Moose::Cookbook::Snack::Keywords>
217
cb2478d4 218=item L<Moose::Cookbook::Snack::Types>
219
471c4f09 220=back
221
222=head1 SEE ALSO
223
224=over 4
225
8bdc7f13 226=item L<http://www.gsph.com/index.php?Lang=En&ID=291>
471c4f09 227
228=back
229
f7f3648d 230=cut