Commit | Line | Data |
daa0fd7d |
1 | package Moose::Manual::FAQ; |
e67a0fca |
2 | |
daa0fd7d |
3 | # ABSTRACT: Frequently asked questions about Moose |
4 | |
5 | __END__ |
e67a0fca |
6 | |
e67a0fca |
7 | |
daa0fd7d |
8 | =pod |
e67a0fca |
9 | |
10 | =head1 FREQUENTLY ASKED QUESTIONS |
11 | |
2a0f3bd3 |
12 | =head2 Module Stability |
13 | |
14 | =head3 Is Moose "production ready"? |
15 | |
2222bdc4 |
16 | Yes! Many sites with household names are using Moose to build |
19440c7c |
17 | high-traffic services. Countless others are using Moose in production. |
40340d0d |
18 | See L<http://moose.iinteractive.com/about.html#organizations> for |
7ff43c21 |
19 | a partial list. |
734d1752 |
20 | |
2222bdc4 |
21 | As of this writing, Moose is a dependency of several hundred CPAN |
40340d0d |
22 | modules. L<https://metacpan.org/requires/module/Moose> |
2a0f3bd3 |
23 | |
24 | =head3 Is Moose's API stable? |
25 | |
c698114d |
26 | Yes. The sugary API, the one 95% of users will interact with, is |
27 | B<very stable>. Any changes will be B<100% backwards compatible>. |
28 | |
29 | The meta API is less set in stone. We reserve the right to tweak |
30 | parts of it to improve efficiency or consistency. This will not be |
31 | done lightly. We do perform deprecation cycles. We I<really> |
32 | do not like making ourselves look bad by breaking your code. |
33 | Submitting test cases is the best way to ensure that your code is not |
7fe3cafa |
34 | inadvertently broken by refactoring. |
2a0f3bd3 |
35 | |
734d1752 |
36 | =head3 I heard Moose is slow, is this true? |
2a0f3bd3 |
37 | |
38 | Again, this one is tricky, so Yes I<and> No. |
39 | |
19440c7c |
40 | Firstly, I<nothing> in life is free, and some Moose features do cost |
41 | more than others. It is also the policy of Moose to B<only charge you |
42 | for the features you use>, and to do our absolute best to not place |
43 | any extra burdens on the execution of your code for features you are |
44 | not using. Of course using Moose itself does involve some overhead, |
45 | but it is mostly compile time. At this point we do have some options |
46 | available for getting the speed you need. |
c32ff715 |
47 | |
19440c7c |
48 | Currently we provide the option of making your classes immutable as a |
49 | means of boosting speed. This will mean a slightly larger compile time |
50 | cost, but the runtime speed increase (especially in object |
51 | construction) is pretty significant. This can be done with the |
52 | following code: |
53 | |
54 | MyClass->meta->make_immutable(); |
c32ff715 |
55 | |
e67a0fca |
56 | =head2 Constructors |
57 | |
58 | =head3 How do I write custom constructors with Moose? |
59 | |
19440c7c |
60 | Ideally, you should never write your own C<new> method, and should use |
61 | Moose's other features to handle your specific object construction |
e67a0fca |
62 | needs. Here are a few scenarios, and the Moose way to solve them; |
63 | |
d03bd989 |
64 | If you need to call initialization code post instance construction, |
19440c7c |
65 | then use the C<BUILD> method. This feature is taken directly from Perl |
66 | 6. Every C<BUILD> method in your inheritance chain is called (in the |
67 | correct order) immediately after the instance is constructed. This |
68 | allows you to ensure that all your superclasses are initialized |
e67a0fca |
69 | properly as well. This is the best approach to take (when possible) |
dab94063 |
70 | because it makes subclassing your class much easier. |
e67a0fca |
71 | |
d03bd989 |
72 | If you need to affect the constructor's parameters prior to the |
e67a0fca |
73 | instance actually being constructed, you have a number of options. |
74 | |
19440c7c |
75 | To change the parameter processing as a whole, you can use the |
76 | C<BUILDARGS> method. The default implementation accepts key/value |
77 | pairs or a hash reference. You can override it to take positional |
78 | args, or any other format |
ce21ecc5 |
79 | |
e5a728d9 |
80 | To change the handling of individual parameters, there are I<coercions> (See |
81 | the L<Moose::Cookbook::Basics::HTTP_SubtypesAndCoercion> for a complete |
82 | example and explanation of coercions). With coercions it is possible to morph |
83 | argument values into the correct expected types. This approach is the most |
84 | flexible and robust, but does have a slightly higher learning curve. |
e67a0fca |
85 | |
d03bd989 |
86 | =head3 How do I make non-Moose constructors work with Moose? |
e67a0fca |
87 | |
6c17df8f |
88 | Usually the correct approach to subclassing a non-Moose class is |
e760b278 |
89 | delegation. Moose makes this easy using the C<handles> keyword, |
19440c7c |
90 | coercions, and C<lazy_build>, so subclassing is often not the ideal |
91 | route. |
e760b278 |
92 | |
fe4975b3 |
93 | That said, if you really need to inherit from a non-Moose class, see |
22883e5b |
94 | L<Moose::Cookbook::Basics::DateTime_ExtendingNonMooseParent> for an example of how to do it, |
cc7dafef |
95 | or take a look at L<Moose::Manual::MooseX/"MooseX::NonMoose">. |
e67a0fca |
96 | |
97 | =head2 Accessors |
98 | |
99 | =head3 How do I tell Moose to use get/set accessors? |
100 | |
d03bd989 |
101 | The easiest way to accomplish this is to use the C<reader> and |
6c17df8f |
102 | C<writer> attribute options: |
e67a0fca |
103 | |
104 | has 'bar' => ( |
105 | isa => 'Baz', |
d03bd989 |
106 | reader => 'get_bar', |
e67a0fca |
107 | writer => 'set_bar', |
108 | ); |
109 | |
d03bd989 |
110 | Moose will still take advantage of type constraints, triggers, etc. |
111 | when creating these methods. |
e67a0fca |
112 | |
19440c7c |
113 | If you do not like this much typing, and wish it to be a default for |
114 | your classes, please see L<MooseX::FollowPBP>. This extension will |
115 | allow you to write: |
e67a0fca |
116 | |
117 | has 'bar' => ( |
118 | isa => 'Baz', |
119 | is => 'rw', |
120 | ); |
121 | |
19440c7c |
122 | Moose will create separate C<get_bar> and C<set_bar> methods instead |
123 | of a single C<bar> method. |
124 | |
125 | If you like C<bar> and C<set_bar>, see |
126 | L<MooseX::SemiAffordanceAccessor>. |
e67a0fca |
127 | |
d03bd989 |
128 | NOTE: This B<cannot> be set globally in Moose, as that would break |
6c17df8f |
129 | other classes which are built with Moose. You can still save on typing |
6f970df6 |
130 | by defining a new C<MyApp::Moose> that exports Moose's sugar and then |
19440c7c |
131 | turns on L<MooseX::FollowPBP>. See |
2349e3cb |
132 | L<Moose::Cookbook::Extending::Mooseish_MooseSugar>. |
e67a0fca |
133 | |
6c17df8f |
134 | =head3 How can I inflate/deflate values in accessors? |
e67a0fca |
135 | |
d03bd989 |
136 | Well, the first question to ask is if you actually need both inflate |
e67a0fca |
137 | and deflate. |
138 | |
8b870d0e |
139 | If you only need to inflate, then we suggest using coercions. Here is |
807f6b7c |
140 | some basic sample code for inflating a L<DateTime> object: |
e67a0fca |
141 | |
6c17df8f |
142 | class_type 'DateTime'; |
d03bd989 |
143 | |
e67a0fca |
144 | coerce 'DateTime' |
145 | => from 'Str' |
d8e332d5 |
146 | => via { DateTime::Format::MySQL->parse_datetime($_) }; |
d03bd989 |
147 | |
e67a0fca |
148 | has 'timestamp' => (is => 'rw', isa => 'DateTime', coerce => 1); |
149 | |
6c17df8f |
150 | This creates a custom type for L<DateTime> objects, then attaches |
151 | a coercion to that type. The C<timestamp> attribute is then told |
807f6b7c |
152 | to expect a C<DateTime> type, and to try to coerce it. When a C<Str> |
d03bd989 |
153 | type is given to the C<timestamp> accessor, it will attempt to |
154 | coerce the value into a C<DateTime> object using the code in found |
155 | in the C<via> block. |
e67a0fca |
156 | |
807f6b7c |
157 | For a more comprehensive example of using coercions, see the |
e5a728d9 |
158 | L<Moose::Cookbook::Basics::HTTP_SubtypesAndCoercion>. |
e67a0fca |
159 | |
19440c7c |
160 | If you need to deflate your attribute's value, the current best |
161 | practice is to add an C<around> modifier to your accessor: |
e67a0fca |
162 | |
d03bd989 |
163 | # a timestamp which stores as |
e67a0fca |
164 | # seconds from the epoch |
165 | has 'timestamp' => (is => 'rw', isa => 'Int'); |
d03bd989 |
166 | |
e67a0fca |
167 | around 'timestamp' => sub { |
168 | my $next = shift; |
24d8fc0d |
169 | my $self = shift; |
170 | |
171 | return $self->$next unless @_; |
172 | |
e67a0fca |
173 | # assume we get a DateTime object ... |
24d8fc0d |
174 | my $timestamp = shift; |
175 | return $self->$next( $timestamp->epoch ); |
e67a0fca |
176 | }; |
177 | |
19440c7c |
178 | It is also possible to do deflation using coercion, but this tends to |
179 | get quite complex and require many subtypes. An example of this is |
180 | outside the scope of this document, ask on #moose or send a mail to |
181 | the list. |
e67a0fca |
182 | |
d03bd989 |
183 | Still another option is to write a custom attribute metaclass, which |
8b870d0e |
184 | is also outside the scope of this document, but we would be happy to |
e67a0fca |
185 | explain it on #moose or the mailing list. |
186 | |
4711f5f7 |
187 | =head2 Method Modifiers |
e67a0fca |
188 | |
189 | =head3 How can I affect the values in C<@_> using C<before>? |
190 | |
19440c7c |
191 | You can't, actually: C<before> only runs before the main method, and |
192 | it cannot easily affect the method's execution. |
e30e57c6 |
193 | |
194 | You similarly can't use C<after> to affect the return value of a |
195 | method. |
196 | |
197 | We limit C<before> and C<after> because this lets you write more |
198 | concise code. You do not have to worry about passing C<@_> to the |
6c17df8f |
199 | original method, or forwarding its return value (being careful to |
200 | preserve context). |
e30e57c6 |
201 | |
19440c7c |
202 | The C<around> method modifier has neither of these limitations, but is |
203 | a little more verbose. |
e67a0fca |
204 | |
5e8927d6 |
205 | Alternatively, the L<MooseX::Mangle> extension provides the |
206 | C<mangle_args> function, which does allow you to affect C<@_>. |
207 | |
e67a0fca |
208 | =head3 Can I use C<before> to stop execution of a method? |
209 | |
d03bd989 |
210 | Yes, but only if you throw an exception. If this is too drastic a |
8b870d0e |
211 | measure then we suggest using C<around> instead. The C<around> method |
d03bd989 |
212 | modifier is the only modifier which can gracefully prevent execution |
e67a0fca |
213 | of the main method. Here is an example: |
214 | |
6c17df8f |
215 | around 'baz' => sub { |
216 | my $next = shift; |
217 | my ($self, %options) = @_; |
218 | unless ($options->{bar} eq 'foo') { |
219 | return 'bar'; |
220 | } |
3ae20eb6 |
221 | $self->$next(%options); |
6c17df8f |
222 | }; |
e67a0fca |
223 | |
d03bd989 |
224 | By choosing not to call the C<$next> method, you can stop the |
e67a0fca |
225 | execution of the main method. |
226 | |
5e8927d6 |
227 | Alternatively, the L<MooseX::Mangle> extension provides the |
228 | C<guard> function, which will conditionally prevent execution |
229 | of the original method. |
230 | |
19440c7c |
231 | =head3 Why can't I see return values in an C<after> modifier? |
232 | |
233 | As with the C<before> modifier, the C<after> modifier is simply called |
234 | I<after> the main method. It is passed the original contents of C<@_> |
235 | and B<not> the return values of the main method. |
236 | |
237 | Again, the arguments are too lengthy as to why this has to be. And as |
238 | with C<before> I recommend using an C<around> modifier instead. Here |
239 | is some sample code: |
240 | |
241 | around 'foo' => sub { |
242 | my $next = shift; |
243 | my ($self, @args) = @_; |
244 | my @rv = $next->($self, @args); |
245 | # do something silly with the return values |
246 | return reverse @rv; |
247 | }; |
248 | |
5e8927d6 |
249 | Alternatively, the L<MooseX::Mangle> extension provides the |
250 | C<mangle_return> function, which allows modifying the return values |
251 | of the original method. |
252 | |
e67a0fca |
253 | =head2 Type Constraints |
254 | |
6c17df8f |
255 | =head3 How can I provide a custom error message for a type constraint? |
e67a0fca |
256 | |
6c17df8f |
257 | Use the C<message> option when building the subtype: |
e67a0fca |
258 | |
d03bd989 |
259 | subtype 'NaturalLessThanTen' |
e67a0fca |
260 | => as 'Natural' |
261 | => where { $_ < 10 } |
262 | => message { "This number ($_) is not less than ten!" }; |
263 | |
6c17df8f |
264 | This C<message> block will be called when a value fails to pass the |
265 | C<NaturalLessThanTen> constraint check. |
e67a0fca |
266 | |
807f6b7c |
267 | =head3 Can I turn off type constraint checking? |
734d1752 |
268 | |
9a4046d2 |
269 | There's no support for it in the core of Moose yet. This option may |
270 | come in a future release. |
271 | |
272 | Meanwhile there's a L<MooseX |
273 | extension|MooseX::Attribute::TypeConstraint::CustomizeFatal> that |
274 | allows you to do this on a per-attribute basis, and if it doesn't do |
275 | what you it's easy to write one that fits your use case. |
734d1752 |
276 | |
6b5a29f4 |
277 | =head3 My coercions stopped working with recent Moose, why did you break it? |
278 | |
ed809fa3 |
279 | Moose 0.76 fixed a case where coercions were being applied even if the original |
280 | constraint passed. This has caused some edge cases to fail where people were |
281 | doing something like |
6b5a29f4 |
282 | |
ed809fa3 |
283 | subtype 'Address', as 'Str'; |
284 | coerce 'Address', from 'Str', via { get_address($_) }; |
cc7dafef |
285 | |
ed809fa3 |
286 | This is not what they intended, because the type constraint C<Address> is too |
287 | loose in this case. It is saying that all strings are Addresses, which is |
288 | obviously not the case. The solution is to provide a C<where> clause that |
289 | properly restricts the type constraint: |
6b5a29f4 |
290 | |
ed809fa3 |
291 | subtype 'Address', as 'Str', where { looks_like_address($_) }; |
6b5a29f4 |
292 | |
ed809fa3 |
293 | This will allow the coercion to apply only to strings that fail to look like an |
294 | Address. |
6b5a29f4 |
295 | |
b36c8076 |
296 | =head2 Roles |
297 | |
19440c7c |
298 | =head3 Why is BUILD not called for my composed roles? |
299 | |
beb804d9 |
300 | C<BUILD> is never called in composed roles. The primary reason is that |
19440c7c |
301 | roles are B<not> order sensitive. Roles are composed in such a way |
302 | that the order of composition does not matter (for information on the |
303 | deeper theory of this read the original traits papers here |
304 | L<http://www.iam.unibe.ch/~scg/Research/Traits/>). |
305 | |
306 | Because roles are essentially unordered, it would be impossible to |
beb804d9 |
307 | determine the order in which to execute the C<BUILD> methods. |
19440c7c |
308 | |
309 | As for alternate solutions, there are a couple. |
310 | |
311 | =over 4 |
b36c8076 |
312 | |
19440c7c |
313 | =item * |
314 | |
315 | Using a combination of lazy and default in your attributes to defer |
ed82277c |
316 | initialization (see the Binary Tree example in the cookbook for a good example |
317 | of lazy/default usage |
318 | L<Moose::Cookbook::Basics::BinaryTree_AttributeFeatures>) |
19440c7c |
319 | |
320 | =item * |
321 | |
322 | Use attribute triggers, which fire after an attribute is set, to |
323 | facilitate initialization. These are described in the L<Moose> docs, |
324 | and examples can be found in the test suite. |
325 | |
326 | =back |
327 | |
328 | In general, roles should not I<require> initialization; they should |
329 | either provide sane defaults or should be documented as needing |
330 | specific initialization. One such way to "document" this is to have a |
331 | separate attribute initializer which is required for the role. Here is |
332 | an example of how to do this: |
333 | |
334 | package My::Role; |
335 | use Moose::Role; |
336 | |
337 | has 'height' => ( |
338 | is => 'rw', |
339 | isa => 'Int', |
340 | lazy => 1, |
341 | default => sub { |
342 | my $self = shift; |
343 | $self->init_height; |
344 | } |
345 | ); |
346 | |
347 | requires 'init_height'; |
348 | |
349 | In this example, the role will not compose successfully unless the |
350 | class provides a C<init_height> method. |
351 | |
352 | If none of those solutions work, then it is possible that a role is |
353 | not the best tool for the job, and you really should be using |
354 | classes. Or, at the very least, you should reduce the amount of |
355 | functionality in your role so that it does not require initialization. |
b36c8076 |
356 | |
0c13ed90 |
357 | =head3 What are traits, and how are they different from roles? |
a8de15f8 |
358 | |
457ad5fc |
359 | In Moose, a trait is almost exactly the same thing as a role, except |
360 | that traits typically register themselves, which allows you to refer |
361 | to them by a short name ("Big" vs "MyApp::Role::Big"). |
362 | |
363 | In Moose-speak, a I<Role> is usually composed into a I<class> at |
364 | compile time, whereas a I<Trait> is usually composed into an instance |
19440c7c |
365 | of a class at runtime to add or modify the behavior of B<just that |
366 | instance>. |
367 | |
368 | Outside the context of Moose, traits and roles generally mean exactly |
0c13ed90 |
369 | the same thing. The original paper called them traits, but Perl 6 |
370 | will call them roles. |
19440c7c |
371 | |
be2630cf |
372 | =head3 Can an attribute-generated method (e.g. an accessor) satisfy requires? |
373 | |
374 | Yes, just be sure to consume the role I<after> declaring your |
aa0e1400 |
375 | attribute. L<Moose::Manual::Roles/Required Attributes> provides |
be2630cf |
376 | an example: |
377 | |
378 | package Breakable; |
379 | use Moose::Role; |
380 | requires 'stress'; |
381 | |
382 | package Car; |
383 | use Moose; |
be2630cf |
384 | has 'stress' => ( is => 'rw', isa => 'Int' ); |
5d299768 |
385 | with 'Breakable'; |
be2630cf |
386 | |
387 | If you mistakenly consume the C<Breakable> role before declaring your |
388 | C<stress> attribute, you would see an error like this: |
389 | |
390 | 'Breakable' requires the method 'stress' to be implemented by 'Car' at... |
391 | |
19440c7c |
392 | =head2 Moose and Subroutine Attributes |
393 | |
394 | =head3 Why don't subroutine attributes I inherited from a superclass work? |
395 | |
0c13ed90 |
396 | Currently when subclassing a module is done at runtime with the |
397 | C<extends> keyword, but attributes are checked at compile time by |
19440c7c |
398 | Perl. To make attributes work, you must place C<extends> in a C<BEGIN> |
0c13ed90 |
399 | block so that the attribute handlers will be available at compile time, |
19440c7c |
400 | like this: |
401 | |
402 | BEGIN { extends qw/Foo/ } |
403 | |
404 | Note that we're talking about Perl's subroutine attributes here, not |
405 | Moose attributes: |
a8de15f8 |
406 | |
19440c7c |
407 | sub foo : Bar(27) { ... } |
a8de15f8 |
408 | |
e760b278 |
409 | =cut |