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