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