Add a simple code example for "no Moose".
[gitmo/Moose.git] / lib / Moose / Cookbook / WTF.pod
1
2 =pod
3
4 =head1 NAME
5
6 Moose::Cookbook::WTF - For when things go wrong with Moose
7
8 =head1 COMMON PROBLEMS
9
10 =head2 Speed
11
12 =head3 Why is my code taking so long to load?
13
14 Moose does have a compile time performance burden,
15 which it inherits from Class::MOP. If load/compile
16 time is a concern for your application, Moose may not
17 be the right tool for you.
18
19 Although, you should note that we are exploring the
20 use of L<Module::Compile> to try and reduce this problem,
21 but nothing is ready yet.
22
23 =head3 Why are my objects taking so long to construct?
24
25 Moose uses a lot of introspection when constructing an
26 instance, and introspection can be slow. This problem
27 can be solved by making your class immutable. This can
28 be done with the following code:
29
30   MyClass->meta->make_immutable();
31
32 Moose will then memoize a number of meta-level methods
33 and inline a constructor for you. For more information
34 on this see the L<Constructors> section below and in the
35 L<Moose::Cookbook::FAQ>.
36
37 =head2 Constructors & Immutability
38
39 =head3 I made my class immutable, but C<new> is still slow!
40
41 Do you have a custom C<new> method in your class? Moose
42 will not overwrite your custom C<new> method, you would
43 probably do better to try and convert this to use the
44 C<BUILD> method or possibly set C<default> values in
45 the attribute declaration.
46
47 =head3 I made my class immutable, and now my (before | after |
48        around) C<new> is not being called?
49
50 Making a I<before>, I<after> or I<around> wrap around the
51 C<new> method will actually create a C<new> method within
52 your class. This will prevent Moose from creating one itself
53 when you make the class immutable.
54
55 =head2 Accessors
56
57 =head3 I created an attribute, where are my accessors?
58
59 Accessors are B<not> created implicitly, you B<must> ask Moose
60 to create them for you. My guess is that you have this:
61
62   has 'foo' => (isa => 'Bar');
63
64 when what you really want to say is:
65
66   has 'foo' => (isa => 'Bar', is => 'rw');
67
68 The reason this is so is because it is a perfectly valid use
69 case to I<not> have an accessor. The simplest one is that you
70 want to write your own. If Moose created one automatically, then
71 because of the order in which classes are constructed, Moose
72 would overwrite your custom accessor. You wouldn't want that
73 would you?
74
75 =head2 Method Modifiers
76
77 =head3 Why can't I change C<@_> in a C<before> modifier?
78
79 The C<before> modifier is called I<before> the main method.
80 Its return values are simply ignored, and are B<not> passed onto
81 the main method body.
82
83 There are a number of reasons for this, but those arguments are
84 too lengthy for this document. Instead, I suggest using an C<around>
85 modifier instead. Here is some sample code:
86
87   around 'foo' => sub {
88       my $next = shift;
89       my ($self, @args) = @_;
90       # do something silly here to @args
91       $next->($self, reverse(@args));
92   };
93
94 =head3 Why can't I see return values in an C<after> modifier?
95
96 As with the C<before> modifier, the C<after> modifier is simply
97 called I<after> the main method. It is passed the original contents
98 of C<@_> and B<not> the return values of the main method.
99
100 Again, the arguments are too lengthy as to why this has to be. And
101 as with C<before> I recommend using an C<around> modifier instead.
102 Here is some sample code:
103
104   around 'foo' => sub {
105       my $next = shift;
106       my ($self, @args) = @_;
107       my @rv = $next->($self, @args);
108       # do something silly with the return values
109       return reverse @rv;
110   };
111
112 =head2 Moose and Subroutine Attributes
113
114 =head3 Why don't subroutine attributes I inherited from a superclass work?
115
116 Currently when you subclass a module, this is done at runtime with
117 the C<extends> keyword but attributes are checked at compile time
118 by Perl. To make attributes work, you must place C<extends> in a
119 C<BEGIN> block so that the attribute handlers will be available at
120 compile time like this:
121
122   BEGIN { extends qw/Foo/ }
123
124 Note that we're talking about Perl's subroutine attributes here, not
125 Moose attributes:
126
127   sub foo : Bar(27) { ... }
128
129 =head2 Moose and Other Modules
130
131 =head3 Why can't I get Catalyst and Moose to work together?
132
133 See L<Moose and Attributes>.
134
135 =head2 Roles
136
137 =head3 Why is BUILD not called for my composed roles?
138
139 BUILD is never called in composed roles. The primary reason is that
140 roles are B<not> order sensitive. Roles are composed in such a way
141 that the order of composition does not matter (for information on
142 the deeper theory of this read the original traits papers here
143 L<http://www.iam.unibe.ch/~scg/Research/Traits/>).
144
145 Because roles are essentially unordered, it would be impossible to
146 determine the order in which to execute the BUILD methods.
147
148 As for alternate solutions, there are a couple.
149
150 =over 4
151
152 =item *
153
154 Using a combination of lazy and default in your attributes to
155 defer initialization (see the Binary Tree example in the cookbook
156 for a good example of lazy/default usage
157 L<Moose::Cookbook::Basics::Recipe3>)
158
159 =item *
160
161 Use attribute triggers, which fire after an attribute is set, to facilitate
162 initialization. These are described in the L<Moose> docs, and examples can be
163 found in the test suite.
164
165 =back
166
167 In general, roles should not I<require> initialization; they should either
168 provide sane defaults or should be documented as needing specific
169 initialization. One such way to "document" this is to have a separate
170 attribute initializer which is required for the role. Here is an example of
171 how to do this:
172
173   package My::Role;
174   use Moose::Role;
175
176   has 'height' => (
177       is      => 'rw',
178       isa     => 'Int',
179       lazy    => 1,
180       default => sub {
181           my $self = shift;
182           $self->init_height;
183       }
184   );
185
186   requires 'init_height';
187
188 In this example, the role will not compose successfully unless the class
189 provides a C<init_height> method.
190
191 If none of those solutions work, then it is possible that a role is not
192 the best tool for the job, and you really should be using classes. Or, at
193 the very least, you should reduce the amount of functionality in your role
194 so that it does not require initialization.
195
196 =head1 AUTHOR
197
198 Stevan Little E<lt>stevan@iinteractive.comE<gt>
199
200 Anders Nor Berle E<lt>debolaz@gmail.comE<gt>
201
202 =head1 COPYRIGHT AND LICENSE
203
204 Copyright 2006-2009 by Infinity Interactive, Inc.
205
206 L<http://www.iinteractive.com>
207
208 This library is free software; you can redistribute it and/or modify
209 it under the same terms as Perl itself.
210
211 =cut