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