Remove references to
[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
4711f5f7 10The Moose cookbook is a series of recipes taken from the Moose
471c4f09 11test suite. Each recipe presents some code, which demonstrates
12some of the features of Moose, and then proceeds to explain the
13details of the code.
14
734d1752 15We also provide a L<Moose::Cookbook::FAQ> and a L<Moose::Cookbook::WTF>
16for common questions and problems people have with Moose.
17
471c4f09 18=head1 RECIPES
19
496b74ab 20=head2 Basic Moose
21
4eec354b 22These recipes will give you a good idea of what Moose is capable,
23starting with simple attribute declaration, and moving on to more
24powerful features like laziness, types, type coercion, method
25modifiers, and more.
26
471c4f09 27=over 4
28
021b8139 29=item L<Moose::Cookbook::Basics::Recipe1> - The (always classic) B<Point> example
471c4f09 30
f7f3648d 31A simple Moose-based class. Demonstrated 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
41references, predicates ("does this object have a foo?"), defaults, and
5cfe3805 42lazy attribute uction.
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
021b8139 63=item L<Moose::Cookbook::Basics::Recipe8> - Managing complex relations with trigger (TODO)
496b74ab 64
cb2478d4 65I<abstract goes here>
66
2be55428 67Work off of this http://code2.0beta.co.uk/moose/svn/Moose/trunk/t/200_examples/007_Child_Parent_attr_inherit.t
68
021b8139 69=item L<Moose::Cookbook::Basics::Recipe9> - Builder methods and lazy_build
496b74ab 70
fbd7ad7a 71The builder feature provides an inheritable and role-composable way to
72provide a default attribute value.
cb2478d4 73
58d129ba 74=item L<Moose::Cookbook::Basics::Recipe10> - Operator overloading, subtypes, and coercion
c2a0627f 75
48757542 76Demonstrates using operator overloading, coercion, and subtypes to
a8b3fe62 77model how eye color is determined during reproduction.
c2a0627f 78
496b74ab 79=back
80
81=head2 Moose Roles
82
4eec354b 83These recipes will show you how to use Moose roles.
84
496b74ab 85=over 4
86
021b8139 87=item L<Moose::Cookbook::Role::Recipe1> - The Moose::Role example
496b74ab 88
f7f3648d 89Demonstrates roles, which are also sometimes known as traits or
90mix-ins. Roles provide a method of code re-use which is orthogonal to
91subclassing.
cb2478d4 92
021b8139 93=item L<Moose::Cookbook::Role::Recipe2> - Advanced Role Composition - method exclusion and aliasing
496b74ab 94
2e3d0a0a 95Sometimes you just want to include part of a role in your
96class. Sometimes you want the whole role but one if its methods
97conflicts with one in your class. With method exclusion and aliasing,
98you can work around these problems.
cb2478d4 99
021b8139 100=item L<Moose::Cookbook::Role::Recipe3> - Runtime Role Composition (TODO)
104379bc 101
cb2478d4 102I<abstract goes here>
103
496b74ab 104=back
105
106=head2 Meta Moose
107
4eec354b 108These recipes show you how to write your own meta classes, which lets
109you extend the object system provide by Moose.
110
496b74ab 111=over 4
112
17a65b17 113=item L<Moose::Cookbook::Meta::Recipe1> - Welcome to the meta-world (Why Go Meta?)
496b74ab 114
38031ac8 115If you're wondering what all this "meta" stuff is, and why you should
116care about it, read this "recipe".
cb2478d4 117
43aa5bf9 118=item L<Moose::Cookbook::Meta::Recipe2> - A meta-attribute, attributes with labels
496b74ab 119
f7f3648d 120One way to extend Moose is to provide your own attribute
121metaclasses. Attribute metaclasses let you extend attribute
122declarations (with C<has>) and behavior to provide additional
123attribute functionality.
cb2478d4 124
43aa5bf9 125=item L<Moose::Cookbook::Meta::Recipe3> - Labels implemented via attribute traits
a7d0cd00 126
aff0421c 127Extending Moose's attribute metaclass is a great way to add
128functionality. However, attributes can only have one metaclass.
129Applying roles to the attribute metaclass lets you provide
130composable attribute functionality.
cb2478d4 131
3f002851 132=item L<Moose::Cookbook::Meta::Recipe4> - Adding a "table" attribute to the metaclass
133
134If you want to store more information about your classes, you'll have
135to extend C<Moose::Meta::Class>. Doing so is simple, but you'll
136probably also want to provide some sugar, so see
c5b9daec 137L<Moose::Cookbook::Extending::Recipe2> as well.
3f002851 138
c5b9daec 139=item L<Moose::Cookbook::Meta::Recipe5> - The "table" attribute implemented as a metaclass trait
24a8fe99 140
c5b9daec 141This example takes the class metaclass we saw in the previous recipe
142and reimplements it as a metaclass trait.
cb2478d4 143
1acd5999 144=item L<Moose::Cookbook::Meta::Recipe6> - Hooking into the immutabilization system (TODO)
145
146Moose has a feature known as "immutabilization". By calling C<<
147__PACKAGE__->meta()->make_immutable() >> after defining your class
148(attributes, roles, etc), you tell Moose to optimize things like
149object creation, attribute access, and so on.
150
151If you are creating your own metaclasses, you may need to hook into
152the immutabilization system. This cuts across a number of spots,
153including the metaclass class, meta method classes, and possibly the
154meta-instance class as well.
155
156This recipe shows you how to write extensions which immutabilize
157properly.
158
159=item L<Moose::Cookbook::Meta::Recipe7> - I<meta-instance> (TODO)
1edfdf1c 160
cb2478d4 161I<abstract goes here>
162
49f6b0ac 163=back
164
6fa0a13f 165=head2 Extending Moose
166
4eec354b 167These recipes cover some more ways to extend Moose, and will be useful
168if you plan to write your own C<MooseX> module.
169
49f6b0ac 170=over 4
171
c8d5f1e1 172=item L<Moose::Cookbook::Extending::Recipe1> - Moose extension overview
173
174There are quite a number of ways to extend Moose. This recipe explains
175provides an overview of each method, and provides recommendations for
176when each is appropriate.
177
f3ce0579 178=item L<Moose::Cookbook::Extending::Recipe2> - Providing a base object class role
c8d5f1e1 179
180Many base object class extensions can be implemented as roles. This
f3ce0579 181example shows how to provide a base object class debugging role that
182is applied to any class that uses a notional C<MooseX::Debugging>
183module.
c8d5f1e1 184
185=item L<Moose::Cookbook::Extending::Recipe3> - Providing an alternate base object class
6fa0a13f 186
187You may find that you want to provide an alternate base object class
188along with a meta extension, or maybe you just want to add some
189functionality to all your classes without typing C<extends
190'MyApp::Base'> over and over.
191
c8d5f1e1 192=item L<Moose::Cookbook::Extending::Recipe4> - Acting like Moose.pm and providing sugar Moose-style
6fa0a13f 193
c5b9daec 194This recipe shows how to provide a replacement for C<Moose.pm>. You
195may want to do this as part of the API for a C<MooseX> module,
5583dc1c 196especially if you want to default to a new metaclass class or base
197object class.
6fa0a13f 198
cb2478d4 199=back
200
201=head1 SNACKS
202
203=over 4
204
f4ebf54f 205=item L<Moose::Cookbook::Snack::Keywords>
206
cb2478d4 207=item L<Moose::Cookbook::Snack::Types>
208
471c4f09 209=back
210
211=head1 SEE ALSO
212
213=over 4
214
8bdc7f13 215=item L<http://www.gsph.com/index.php?Lang=En&ID=291>
471c4f09 216
217=back
218
219=head1 AUTHOR
220
221Stevan Little E<lt>stevan@iinteractive.comE<gt>
222
223=head1 COPYRIGHT AND LICENSE
224
778db3ac 225Copyright 2006-2008 by Infinity Interactive, Inc.
471c4f09 226
227L<http://www.iinteractive.com>
228
229This library is free software; you can redistribute it and/or modify
230it under the same terms as Perl itself.
231
f7f3648d 232=cut