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