Commit | Line | Data |
daa0fd7d |
1 | package 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 |
12 | The Moose cookbook is a series of recipes showing various Moose |
13 | features. Most recipes present some code demonstrating some feature, |
14 | and then explain the details of the code. |
471c4f09 |
15 | |
ad248e00 |
16 | You should probably read the L<Moose::Manual> first. The manual |
17 | explains Moose concepts without being too code-heavy. |
734d1752 |
18 | |
471c4f09 |
19 | =head1 RECIPES |
20 | |
496b74ab |
21 | =head2 Basic Moose |
22 | |
1068dcb5 |
23 | These recipes will give you a good overview of Moose's capabilities, starting |
24 | with simple attribute declaration, and moving on to more powerful features like |
25 | laziness, types, type coercion, method modifiers, and more. |
4eec354b |
26 | |
471c4f09 |
27 | =over 4 |
28 | |
c4fde3b5 |
29 | =item L<Moose::Cookbook::Basics::Point_AttributesAndSubclassing> |
471c4f09 |
30 | |
c4fde3b5 |
31 | A simple Moose-based class. Demonstrates basic Moose attributes and subclassing. |
cb2478d4 |
32 | |
7b0a6766 |
33 | =item L<Moose::Cookbook::Basics::BankAccount_MethodModifiersAndSubclassing> |
471c4f09 |
34 | |
7b0a6766 |
35 | A slightly more complex Moose class. Demonstrates using a method modifier in a |
36 | subclass. |
cb2478d4 |
37 | |
ed82277c |
38 | =item L<Moose::Cookbook::Basics::BinaryTree_AttributeFeatures> |
471c4f09 |
39 | |
f7f3648d |
40 | Demonstrates several attribute features, including types, weak |
0fde1850 |
41 | references, predicates ("does this object have a foo?"), defaults, |
42 | laziness, and triggers. |
cb2478d4 |
43 | |
2326164e |
44 | =item L<Moose::Cookbook::Basics::Company_Subtypes> |
471c4f09 |
45 | |
2326164e |
46 | Introduces the creation and use of custom types, a C<BUILD> method, and the |
47 | use of C<override> in a subclass. This recipe also shows how to model a set of |
48 | classes that could be used to model companies, people, employees, etc. |
cb2478d4 |
49 | |
e5a728d9 |
50 | =item L<Moose::Cookbook::Basics::HTTP_SubtypesAndCoercion> |
471c4f09 |
51 | |
e5a728d9 |
52 | This recipe covers more subtype creation, including the use of type coercions. |
cb2478d4 |
53 | |
86fcbc7e |
54 | =item L<Moose::Cookbook::Basics::Immutable> |
496b74ab |
55 | |
5de2944f |
56 | Making a class immutable greatly increases the speed of accessors and |
57 | object construction. |
cb2478d4 |
58 | |
53a1e093 |
59 | =item L<Moose::Cookbook::Basics::BinaryTree_BuilderAndLazyBuild> - Builder methods and lazy_build |
496b74ab |
60 | |
fbd7ad7a |
61 | The builder feature provides an inheritable and role-composable way to |
62 | provide a default attribute value. |
cb2478d4 |
63 | |
cae64823 |
64 | =item L<Moose::Cookbook::Basics::Genome_OverloadingSubtypesAndCoercion> |
c2a0627f |
65 | |
48757542 |
66 | Demonstrates using operator overloading, coercion, and subtypes to |
a8b3fe62 |
67 | model how eye color is determined during reproduction. |
c2a0627f |
68 | |
89460279 |
69 | =item L<Moose::Cookbook::Basics::Person_BUILDARGSAndBUILD> |
45ef8386 |
70 | |
04d80e2a |
71 | This recipe demonstrates the use of C<BUILDARGS> and C<BUILD> to hook |
72 | into object construction. |
45ef8386 |
73 | |
22883e5b |
74 | =item L<Moose::Cookbook::Basics::DateTime_ExtendingNonMooseParent> |
5f9e373d |
75 | |
76 | In this recipe, we make a Moose-based subclass of L<DateTime>, a |
77 | module which does not use Moose itself. |
78 | |
174418c2 |
79 | =item L<Moose::Cookbook::Basics::Document_AugmentAndInner> |
80 | |
81 | Demonstrates the use of C<augment> method modifiers, a way of turning |
82 | the usual method overriding style "inside-out". |
83 | |
496b74ab |
84 | =back |
85 | |
86 | =head2 Moose Roles |
87 | |
4eec354b |
88 | These recipes will show you how to use Moose roles. |
89 | |
496b74ab |
90 | =over 4 |
91 | |
9956dcf4 |
92 | =item L<Moose::Cookbook::Roles::Comparable_CodeReuse> |
496b74ab |
93 | |
f7f3648d |
94 | Demonstrates roles, which are also sometimes known as traits or |
95 | mix-ins. Roles provide a method of code re-use which is orthogonal to |
96 | subclassing. |
cb2478d4 |
97 | |
706d2d37 |
98 | =item L<Moose::Cookbook::Roles::Restartable_AdvancedComposition> |
496b74ab |
99 | |
2e3d0a0a |
100 | Sometimes you just want to include part of a role in your |
dab94063 |
101 | class. Sometimes you want the whole role but one of its methods |
2e3d0a0a |
102 | conflicts with one in your class. With method exclusion and aliasing, |
103 | you can work around these problems. |
cb2478d4 |
104 | |
5d9d20f3 |
105 | =item L<Moose::Cookbook::Roles::ApplicationToInstance> |
104379bc |
106 | |
9a823f26 |
107 | In this recipe, we apply a role to an existing object instance. |
cb2478d4 |
108 | |
496b74ab |
109 | =back |
110 | |
111 | =head2 Meta Moose |
112 | |
4eec354b |
113 | These recipes show you how to write your own meta classes, which lets |
dab94063 |
114 | you extend the object system provided by Moose. |
4eec354b |
115 | |
496b74ab |
116 | =over 4 |
117 | |
3f36fdae |
118 | =item L<Moose::Cookbook::Meta::WhyMeta> |
496b74ab |
119 | |
38031ac8 |
120 | If you're wondering what all this "meta" stuff is, and why you should |
121 | care about it, read this "recipe". |
cb2478d4 |
122 | |
b1301316 |
123 | =item L<Moose::Cookbook::Meta::Labeled_AttributeTrait> |
a7d0cd00 |
124 | |
aff0421c |
125 | Extending Moose's attribute metaclass is a great way to add |
126 | functionality. However, attributes can only have one metaclass. |
127 | Applying roles to the attribute metaclass lets you provide |
128 | composable attribute functionality. |
cb2478d4 |
129 | |
826230c2 |
130 | =item L<Moose::Cookbook::Meta::Table_MetaclassTrait> |
24a8fe99 |
131 | |
505dcac2 |
132 | This recipe takes the class metaclass we saw in the previous recipe |
c5b9daec |
133 | and reimplements it as a metaclass trait. |
cb2478d4 |
134 | |
8a788638 |
135 | =item L<Moose::Cookbook::Meta::PrivateOrPublic_MethodMetaclass> |
505dcac2 |
136 | |
137 | This recipe shows a custom method metaclass that implements making a |
138 | method private. |
139 | |
a0582133 |
140 | =item L<Moose::Cookbook::Meta::GlobRef_InstanceMetaclass> |
505dcac2 |
141 | |
142 | This recipe shows an example of how you create your own meta-instance |
143 | class. The meta-instance determines the internal structure of object |
144 | instances and provide access to attribute slots. |
145 | |
a0582133 |
146 | In this particular instance, we use a blessed glob reference as the instance |
147 | instead of a blessed hash reference. |
148 | |
bb6c371e |
149 | =item Hooking into immutabilization (TODO) |
1acd5999 |
150 | |
151 | Moose has a feature known as "immutabilization". By calling C<< |
152 | __PACKAGE__->meta()->make_immutable() >> after defining your class |
153 | (attributes, roles, etc), you tell Moose to optimize things like |
154 | object creation, attribute access, and so on. |
155 | |
156 | If you are creating your own metaclasses, you may need to hook into |
157 | the immutabilization system. This cuts across a number of spots, |
158 | including the metaclass class, meta method classes, and possibly the |
159 | meta-instance class as well. |
160 | |
161 | This recipe shows you how to write extensions which immutabilize |
162 | properly. |
163 | |
49f6b0ac |
164 | =back |
165 | |
6fa0a13f |
166 | =head2 Extending Moose |
167 | |
4eec354b |
168 | These recipes cover some more ways to extend Moose, and will be useful |
169 | if you plan to write your own C<MooseX> module. |
170 | |
49f6b0ac |
171 | =over 4 |
172 | |
3b788714 |
173 | =item L<Moose::Cookbook::Extending::ExtensionOverview> |
c8d5f1e1 |
174 | |
dab94063 |
175 | There are quite a few ways to extend Moose. This recipe provides an |
176 | overview of each method, and provides recommendations for when each is |
177 | appropriate. |
c8d5f1e1 |
178 | |
97da20ef |
179 | =item L<Moose::Cookbook::Extending::Debugging_BaseClassRole> |
c8d5f1e1 |
180 | |
181 | Many base object class extensions can be implemented as roles. This |
f3ce0579 |
182 | example shows how to provide a base object class debugging role that |
183 | is applied to any class that uses a notional C<MooseX::Debugging> |
184 | module. |
c8d5f1e1 |
185 | |
2349e3cb |
186 | =item L<Moose::Cookbook::Extending::Mooseish_MooseSugar> |
6fa0a13f |
187 | |
c5b9daec |
188 | This recipe shows how to provide a replacement for C<Moose.pm>. You |
189 | may want to do this as part of the API for a C<MooseX> module, |
5583dc1c |
190 | especially if you want to default to a new metaclass class or base |
191 | object class. |
6fa0a13f |
192 | |
cb2478d4 |
193 | =back |
194 | |
195 | =head1 SNACKS |
196 | |
197 | =over 4 |
198 | |
f4ebf54f |
199 | =item L<Moose::Cookbook::Snack::Keywords> |
200 | |
cb2478d4 |
201 | =item L<Moose::Cookbook::Snack::Types> |
202 | |
471c4f09 |
203 | =back |
204 | |
8344c2b4 |
205 | =head1 Legacy Recipes |
206 | |
207 | These cover topics that are no longer considered best practice. We've kept |
208 | them in case in you encounter these usages in the wild. |
209 | |
210 | =over 4 |
211 | |
106ba07d |
212 | =item L<Moose::Cookbook::Legacy::Labeled_AttributeMetaclass> |
8344c2b4 |
213 | |
106ba07d |
214 | =item L<Moose::Cookbook::Legacy::Table_ClassMetaclass> |
8344c2b4 |
215 | |
cb235596 |
216 | =item L<Moose::Cookbook::Legacy::Debugging_BaseClassReplacement> |
217 | |
8344c2b4 |
218 | =back |
219 | |
471c4f09 |
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 | |
f7f3648d |
228 | =cut |