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> it 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 on 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 How come I can't change C<@_> in a C<before> modifier?
  78
  79 The C<before> modifier simply 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 How come I can't 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 Attributes
 113
 114 =head3 Why don't 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 =head2 Moose and Other Modules
 125
 126 =head3 Why can't I get Catalyst and Moose to work together?
 127
 128 See L<Moose and Attributes>.
 129
 130 =head2 Roles
 131
 132 =head3 How come BUILD is not called for my composed roles?
 133
 134 BUILD is never called in composed roles. The primary reason is that
 135 roles are B<not> order sensitive. Roles are composed in such a way
 136 that the order of composition does not matter (for information on
 137 the deeper theory of this read the original traits papers here
 138 L<http://www.iam.unibe.ch/~scg/Research/Traits/>).
 139
 140 Because roles are essentially un-ordered, it would be impossible to
 141 determine the order in which to execute the BUILD methods.
 142
 143 As for alternate solutions, there are a couple.
 144
 145 =over 4
 146
 147 =item *
 148
 149 Using a combination of lazy and default in your attributes to
 150 defer initialization (see the Binary Tree example in the cookbook
 151 for a good example of lazy/default usage
 152 L<Moose::Cookbook::Basics::Recipe3>)
 153
 154 =item *
 155
 156 Use attibutes triggers, which fire after an attribute it set, to faciliate
 157 initialization. These are described in the L<Moose> docs and examples can be
 158 found in the test suite.
 159
 160 =back
 161
 162 In general, roles should not I<require> intialization, they should either
 163 provide sane defaults or should be documented as needing specific
 164 initialization. One such way to "document" this is to have a seperate
 165 attribute initializer which is required for the role. Here is an example of
 166 how to do this:
 167
 168   package My::Role;
 169   use Moose::Role;
 170
 171   has 'height' => (
 172       is      => 'rw',
 173       isa     => 'Int',
 174       lazy    => 1,
 175       default => sub {
 176           my $self = shift;
 177           $self->init_height;
 178       }
 179   );
 180
 181   requires 'init_height';
 182
 183 In this example, the role will not compose successfully unless the class
 184 provides a C<init_height> method.
 185
 186 If none of those solutions work, then it is possible that a role is not
 187 the best tool for the job, and you really should be using classes. Or, at
 188 the very least, you should reduce the amount of functionality in your role
 189 so that it does not require initialization.
 190
 191 =head1 AUTHOR
 192
 193 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 194
 195 Anders Nor Berle E<lt>debolaz@gmail.comE<gt>
 196
 197 =head1 COPYRIGHT AND LICENSE
 198
 199 Copyright 2006-2009 by Infinity Interactive, Inc.
 200
 201 L<http://www.iinteractive.com>
 202
 203 This library is free software; you can redistribute it and/or modify
 204 it under the same terms as Perl itself.
 205
 206 =cut