Commit | Line | Data |
e67a0fca |
1 | |
2 | =pod |
3 | |
4 | =head1 NAME |
5 | |
4711f5f7 |
6 | Moose::Cookbook::FAQ - Frequently asked questions about Moose |
e67a0fca |
7 | |
8 | =head1 FREQUENTLY ASKED QUESTIONS |
9 | |
2a0f3bd3 |
10 | =head2 Module Stability |
11 | |
12 | =head3 Is Moose "production ready"? |
13 | |
2222bdc4 |
14 | Yes! Many sites with household names are using Moose to build |
15 | high-traffic services. Countless others are using Moose in |
16 | production. |
734d1752 |
17 | |
2222bdc4 |
18 | As of this writing, Moose is a dependency of several hundred CPAN |
19 | modules. L<http://cpants.perl.org/dist/used_by/Moose> |
2a0f3bd3 |
20 | |
21 | =head3 Is Moose's API stable? |
22 | |
c698114d |
23 | Yes. The sugary API, the one 95% of users will interact with, is |
24 | B<very stable>. Any changes will be B<100% backwards compatible>. |
25 | |
26 | The meta API is less set in stone. We reserve the right to tweak |
27 | parts of it to improve efficiency or consistency. This will not be |
28 | done lightly. We do perform deprecation cycles. We I<really> |
29 | do not like making ourselves look bad by breaking your code. |
30 | Submitting test cases is the best way to ensure that your code is not |
31 | inadvertantly broken by refactoring. |
2a0f3bd3 |
32 | |
734d1752 |
33 | =head3 I heard Moose is slow, is this true? |
2a0f3bd3 |
34 | |
35 | Again, this one is tricky, so Yes I<and> No. |
36 | |
c32ff715 |
37 | Firstly, I<nothing> in life is free, and some Moose features |
38 | do cost more than others. It is also the policy of Moose to |
39 | B<only charge you for the features you use>, and to do our |
40 | absolute best to not place any extra burdens on the execution |
41 | of your code for features you are not using. Of course using |
42 | Moose itself does involve some overhead, but it is mostly |
43 | compile time. At this point we do have some options available |
44 | for getting the speed you need. |
45 | |
46 | Currently we provide the option of making your classes immutable |
d03bd989 |
47 | as a means of boosting speed. This will mean a slightly larger compile |
734d1752 |
48 | time cost, but the runtime speed increase (especially in object |
c32ff715 |
49 | construction) is pretty significant. |
50 | |
51 | We are regularly converting the hotspots of L<Class::MOP> to XS. |
52 | Florian Ragwitz and Yuval Kogman are currently working on a way |
53 | to compile your accessors and instances directly into C, so that |
54 | everyone can enjoy blazing fast OO. |
2a0f3bd3 |
55 | |
807f6b7c |
56 | =head3 When will Moose 1.0 be ready? |
2a0f3bd3 |
57 | |
37a9448b |
58 | Moose is ready now! Stevan Little declared 0.18, released in March 2007, |
afc402d9 |
59 | to be "ready to use". |
2a0f3bd3 |
60 | |
e67a0fca |
61 | =head2 Constructors |
62 | |
63 | =head3 How do I write custom constructors with Moose? |
64 | |
65 | Ideally, you should never write your own C<new> method, and should |
66 | use Moose's other features to handle your specific object construction |
67 | needs. Here are a few scenarios, and the Moose way to solve them; |
68 | |
d03bd989 |
69 | If you need to call initialization code post instance construction, |
70 | then use the C<BUILD> method. This feature is taken directly from |
71 | Perl 6. Every C<BUILD> method in your inheritance chain is called |
72 | (in the correct order) immediately after the instance is constructed. |
73 | This allows you to ensure that all your superclasses are initialized |
e67a0fca |
74 | properly as well. This is the best approach to take (when possible) |
dab94063 |
75 | because it makes subclassing your class much easier. |
e67a0fca |
76 | |
d03bd989 |
77 | If you need to affect the constructor's parameters prior to the |
e67a0fca |
78 | instance actually being constructed, you have a number of options. |
79 | |
ce21ecc5 |
80 | To change the parameter processing as a whole, you can use |
81 | the C<BUILDARGS> method. The default implementation accepts key/value |
82 | pairs or a hash reference. You can override it to take positional args, |
83 | or any other format |
84 | |
85 | To change the handling of individual parameters, there are I<coercions> |
5cfe3805 |
86 | (See the L<Moose::Cookbook::Basics::Recipe5> for a complete example and |
a8de15f8 |
87 | explanation of coercions). With coercions it is possible to morph |
ce21ecc5 |
88 | argument values into the correct expected types. This approach is the |
89 | most flexible and robust, but does have a slightly higher learning |
90 | curve. |
e67a0fca |
91 | |
d03bd989 |
92 | =head3 How do I make non-Moose constructors work with Moose? |
e67a0fca |
93 | |
6c17df8f |
94 | Usually the correct approach to subclassing a non-Moose class is |
e760b278 |
95 | delegation. Moose makes this easy using the C<handles> keyword, |
96 | coercions, and C<lazy_build>, so subclassing is often not the |
97 | ideal route. |
98 | |
00157674 |
99 | That said, the default Moose constructor is inherited from |
e760b278 |
100 | L<Moose::Object>. When inheriting from a non-Moose class, the |
101 | inheritance chain to L<Moose::Object> is broken. The simplest way |
102 | to fix this is to simply explicitly inherit from L<Moose::Object> |
103 | yourself. |
104 | |
105 | However, this does not always fix the issue of actually calling the Moose |
3f4a85d3 |
106 | constructor. Fortunately, the modules L<MooseX::NonMoose> and |
107 | L<MooseX::Alien> aim to make subclassing non-Moose classes easier. |
108 | |
109 | If neither extension fills your specific needs, you can use |
110 | L<Class::MOP::Class/new_object>. This low-level constructor accepts the |
111 | special C<__INSTANCE__> parameter, allowing you to instantiate your Moose |
112 | attributes: |
e67a0fca |
113 | |
114 | package My::HTML::Template; |
115 | use Moose; |
d03bd989 |
116 | |
117 | # explicit inheritance |
e67a0fca |
118 | extends 'HTML::Template', 'Moose::Object'; |
d03bd989 |
119 | |
e67a0fca |
120 | # explicit constructor |
121 | sub new { |
122 | my $class = shift; |
123 | # call HTML::Template's constructor |
124 | my $obj = $class->SUPER::new(@_); |
125 | return $class->meta->new_object( |
126 | # pass in the constructed object |
127 | # using the special key __INSTANCE__ |
e760b278 |
128 | __INSTANCE__ => $obj, |
129 | @_, # pass in the normal args |
e67a0fca |
130 | ); |
131 | } |
132 | |
d03bd989 |
133 | Of course, this only works if both your Moose class and the |
134 | inherited non-Moose class use the same instance type (typically |
e760b278 |
135 | HASH refs). |
136 | |
137 | Note that this doesn't call C<BUILDALL> automatically, you must do that |
138 | yourself. |
e67a0fca |
139 | |
d03bd989 |
140 | Other techniques can be used as well, such as creating the object |
141 | using C<Moose::Object::new>, but calling the inherited non-Moose |
142 | class's initialization methods (if available). |
e67a0fca |
143 | |
3f4a85d3 |
144 | In short, there are several ways to extend non-Moose classes. It is |
145 | best to evaluate each case based on the class you wish to extend, |
146 | and the features you wish to employ. As always, both IRC and the |
147 | mailing list are great ways to get help finding the best approach. |
e67a0fca |
148 | |
149 | =head2 Accessors |
150 | |
151 | =head3 How do I tell Moose to use get/set accessors? |
152 | |
d03bd989 |
153 | The easiest way to accomplish this is to use the C<reader> and |
6c17df8f |
154 | C<writer> attribute options: |
e67a0fca |
155 | |
156 | has 'bar' => ( |
157 | isa => 'Baz', |
d03bd989 |
158 | reader => 'get_bar', |
e67a0fca |
159 | writer => 'set_bar', |
160 | ); |
161 | |
d03bd989 |
162 | Moose will still take advantage of type constraints, triggers, etc. |
163 | when creating these methods. |
e67a0fca |
164 | |
1a835594 |
165 | If you do not like this much typing, and wish it to be a default for your |
6c17df8f |
166 | classes, please see L<MooseX::FollowPBP>. This extension will allow you to |
167 | write: |
e67a0fca |
168 | |
169 | has 'bar' => ( |
170 | isa => 'Baz', |
171 | is => 'rw', |
172 | ); |
173 | |
6c17df8f |
174 | Moose will create separate C<get_bar> and C<set_bar> methods |
807f6b7c |
175 | instead of a single C<bar> method. |
e67a0fca |
176 | |
d03bd989 |
177 | NOTE: This B<cannot> be set globally in Moose, as that would break |
6c17df8f |
178 | other classes which are built with Moose. You can still save on typing |
179 | by defining a new L<MyApp::Moose> that exports Moose's sugar and then |
180 | turns on L<MooseX::FollowPBP>. See L<Moose::Cookbook::Extending::Recipe4>. |
e67a0fca |
181 | |
6c17df8f |
182 | =head3 How can I inflate/deflate values in accessors? |
e67a0fca |
183 | |
d03bd989 |
184 | Well, the first question to ask is if you actually need both inflate |
e67a0fca |
185 | and deflate. |
186 | |
8b870d0e |
187 | If you only need to inflate, then we suggest using coercions. Here is |
807f6b7c |
188 | some basic sample code for inflating a L<DateTime> object: |
e67a0fca |
189 | |
6c17df8f |
190 | class_type 'DateTime'; |
d03bd989 |
191 | |
e67a0fca |
192 | coerce 'DateTime' |
193 | => from 'Str' |
194 | => via { DateTime::Format::MySQL->parse_datetime($_) }; |
d03bd989 |
195 | |
e67a0fca |
196 | has 'timestamp' => (is => 'rw', isa => 'DateTime', coerce => 1); |
197 | |
6c17df8f |
198 | This creates a custom type for L<DateTime> objects, then attaches |
199 | a coercion to that type. The C<timestamp> attribute is then told |
807f6b7c |
200 | to expect a C<DateTime> type, and to try to coerce it. When a C<Str> |
d03bd989 |
201 | type is given to the C<timestamp> accessor, it will attempt to |
202 | coerce the value into a C<DateTime> object using the code in found |
203 | in the C<via> block. |
e67a0fca |
204 | |
807f6b7c |
205 | For a more comprehensive example of using coercions, see the |
5cfe3805 |
206 | L<Moose::Cookbook::Basics::Recipe5>. |
e67a0fca |
207 | |
6c17df8f |
208 | If you need to deflate your attribute's value, the current best practice |
209 | is to add an C<around> modifier to your accessor: |
e67a0fca |
210 | |
d03bd989 |
211 | # a timestamp which stores as |
e67a0fca |
212 | # seconds from the epoch |
213 | has 'timestamp' => (is => 'rw', isa => 'Int'); |
d03bd989 |
214 | |
e67a0fca |
215 | around 'timestamp' => sub { |
216 | my $next = shift; |
217 | my ($self, $timestamp) = @_; |
218 | # assume we get a DateTime object ... |
219 | $next->($self, $timestamp->epoch); |
220 | }; |
221 | |
d03bd989 |
222 | It is also possible to do deflation using coercion, but this tends |
223 | to get quite complex and require many subtypes. An example of this |
224 | is outside the scope of this document, ask on #moose or send a mail |
e67a0fca |
225 | to the list. |
226 | |
d03bd989 |
227 | Still another option is to write a custom attribute metaclass, which |
8b870d0e |
228 | is also outside the scope of this document, but we would be happy to |
e67a0fca |
229 | explain it on #moose or the mailing list. |
230 | |
4711f5f7 |
231 | =head2 Method Modifiers |
e67a0fca |
232 | |
233 | =head3 How can I affect the values in C<@_> using C<before>? |
234 | |
d03bd989 |
235 | You can't, actually: C<before> only runs before the main method, |
e30e57c6 |
236 | and it cannot easily affect the method's execution. |
237 | |
238 | You similarly can't use C<after> to affect the return value of a |
239 | method. |
240 | |
241 | We limit C<before> and C<after> because this lets you write more |
242 | concise code. You do not have to worry about passing C<@_> to the |
6c17df8f |
243 | original method, or forwarding its return value (being careful to |
244 | preserve context). |
e30e57c6 |
245 | |
6c17df8f |
246 | The C<around> method modifier has neither of these limitations, but |
247 | is a little more verbose. |
e67a0fca |
248 | |
249 | =head3 Can I use C<before> to stop execution of a method? |
250 | |
d03bd989 |
251 | Yes, but only if you throw an exception. If this is too drastic a |
8b870d0e |
252 | measure then we suggest using C<around> instead. The C<around> method |
d03bd989 |
253 | modifier is the only modifier which can gracefully prevent execution |
e67a0fca |
254 | of the main method. Here is an example: |
255 | |
6c17df8f |
256 | around 'baz' => sub { |
257 | my $next = shift; |
258 | my ($self, %options) = @_; |
259 | unless ($options->{bar} eq 'foo') { |
260 | return 'bar'; |
261 | } |
262 | $next->($self, %options); |
263 | }; |
e67a0fca |
264 | |
d03bd989 |
265 | By choosing not to call the C<$next> method, you can stop the |
e67a0fca |
266 | execution of the main method. |
267 | |
268 | =head2 Type Constraints |
269 | |
6c17df8f |
270 | =head3 How can I provide a custom error message for a type constraint? |
e67a0fca |
271 | |
6c17df8f |
272 | Use the C<message> option when building the subtype: |
e67a0fca |
273 | |
d03bd989 |
274 | subtype 'NaturalLessThanTen' |
e67a0fca |
275 | => as 'Natural' |
276 | => where { $_ < 10 } |
277 | => message { "This number ($_) is not less than ten!" }; |
278 | |
6c17df8f |
279 | This C<message> block will be called when a value fails to pass the |
280 | C<NaturalLessThanTen> constraint check. |
e67a0fca |
281 | |
807f6b7c |
282 | =head3 Can I turn off type constraint checking? |
734d1752 |
283 | |
6c17df8f |
284 | Not yet. This option will likely come in a future release. |
734d1752 |
285 | |
b36c8076 |
286 | =head2 Roles |
287 | |
288 | =head3 How do I get Moose to call BUILD in all my composed roles? |
289 | |
6c17df8f |
290 | See L<Moose::Cookbook::WTF> and specifically the |
291 | B<Why is BUILD not called for my composed roles?> question in the |
292 | B<Roles> section. |
b36c8076 |
293 | |
dab94063 |
294 | =head3 What are Traits, and how are they different from Roles? |
a8de15f8 |
295 | |
457ad5fc |
296 | In Moose, a trait is almost exactly the same thing as a role, except |
297 | that traits typically register themselves, which allows you to refer |
298 | to them by a short name ("Big" vs "MyApp::Role::Big"). |
299 | |
300 | In Moose-speak, a I<Role> is usually composed into a I<class> at |
301 | compile time, whereas a I<Trait> is usually composed into an instance |
6c17df8f |
302 | of a class at runtime to add or modify the behavior of |
303 | B<just that instance>. |
a8de15f8 |
304 | |
305 | Outside the context of Moose, traits and roles generally mean exactly the |
306 | same thing. The original paper called them Traits, however Perl 6 will call |
307 | them Roles. |
308 | |
e67a0fca |
309 | =head1 AUTHOR |
310 | |
311 | Stevan Little E<lt>stevan@iinteractive.comE<gt> |
312 | |
313 | =head1 COPYRIGHT AND LICENSE |
314 | |
2840a3b2 |
315 | Copyright 2006-2009 by Infinity Interactive, Inc. |
e67a0fca |
316 | |
317 | L<http://www.iinteractive.com> |
318 | |
319 | This library is free software; you can redistribute it and/or modify |
320 | it under the same terms as Perl itself. |
321 | |
e760b278 |
322 | =cut |