X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMoose%2FCookbook%2FWTF.pod;h=84762eb4140dceb19f877a50653dce1d41d28b4d;hb=bb6c833559f9e6ac403628d8ec4d09af2a0477e1;hp=0a6e85de4fe1d295bb81aad3d702289f54d0bba9;hpb=b77fdbed20f583feab7a3990da4ebc04898217fc;p=gitmo%2FMoose.git

diff --git a/lib/Moose/Cookbook/WTF.pod b/lib/Moose/Cookbook/WTF.pod
index 0a6e85d..84762eb 100644
--- a/lib/Moose/Cookbook/WTF.pod
+++ b/lib/Moose/Cookbook/WTF.pod
@@ -11,10 +11,10 @@ Moose::Cookbook::WTF - For when things go wrong with Moose
 
 =head3 Why is my code taking so long to load?
 
-Moose has a fairly heavy compile time burden, which it 
-inherits from Class::MOP. If load/compile time is a 
-concern for your application, Moose may not be the 
-right tool for you. 
+Moose does have a compile time performance burden, 
+which it inherits from Class::MOP. If load/compile 
+time is a concern for your application, Moose may not 
+be the right tool for you. 
 
 Although, you should note that we are exploring the 
 use of L<Module::Compile> to try and reduce this problem, 
@@ -23,12 +23,34 @@ but nothing is ready yet.
 =head3 Why are my objects taking so long to construct?
 
 Moose uses a lot of introspection when constructing an 
-instance, and introspection can be slow. However, this 
-is a temporary problem, and is already solved in 
-Class::MOP by making classes immutable. However immutable 
-support in Moose is not ready yet, but will be soon.
+instance, and introspection can be slow. This problem 
+can be solved by making your class immutable. This can 
+be done with the following code:
 
-=head2 Constructors
+  MyClass->meta->make_immutable();
+
+Moose will then memoize a number of meta-level methods
+and inline a constructor for you. For more information 
+on this see the L<Constructors> section below and in the 
+L<Moose::Cookbook::FAQ>.
+
+=head2 Constructors & Immutability
+
+=head3 I made my class immutable, but C<new> it is still slow!
+
+Do you have a custom C<new> method in your class? Moose 
+will not overwrite your custom C<new> method, you would 
+probably do better to try and convert this to use the 
+C<BUILD> method or possibly set C<default> values in 
+the attribute declaration. 
+
+=head3 I made my class immutable, and now my (before | after | 
+       around) C<new> is not being called?
+
+Making a I<before>, I<after> or I<around> wrap around the 
+C<new> method, will actually create a C<new> method within 
+your class. This will prevent Moose from creating one itself
+when you make the class immutable. 
 
 =head2 Accessors
 
@@ -50,7 +72,7 @@ because of the order in which classes are constructed, Moose
 would overwrite your custom accessor. You wouldn't want that 
 would you?
 
-=head2 Method Modfiers
+=head2 Method Modifiers
 
 =head3 How come I can't change C<@_> in a C<before> modifier?
 
@@ -87,17 +109,98 @@ Here is some sample code:
       return reverse @rv;
   };
 
+=head2 Moose and Attributes
+
+=head3 Why don't attributes I inherited from a superclass work?
+
+Currently when you subclass a module, this is done at runtime with
+the C<extends> keyword but attributes are checked at compile time
+by Perl. To make attributes work, you must place C<extends> in a
+C<BEGIN> block so that the attribute handlers will be available at
+compile time like this:
+
+  BEGIN { extends qw/Foo/ } 
+
+=head2 Moose and Other Modules
+
+=head3 Why can't I get Catalyst and Moose to work together?
+
+See L<Moose and Attributes>.
+
+=head2 Roles
+
+=head3 How come BUILD is not called for my composed roles?
+
+BUILD is never called in composed roles. The primary reason is that 
+roles are B<not> order sensitive. Roles are composed in such a way 
+that the order of composition does not matter (for information on 
+the deeper theory of this read the original traits papers here 
+L<http://www.iam.unibe.ch/~scg/Research/Traits/>). 
+
+Because roles are essentially un-ordered, it would be impossible to 
+determine the order in which to execute the BUILD methods. 
+
+As for alternate solutions, there are a couple.
+
+=over 4
+
+=item * 
+
+Using a combination of lazy and default in your attributes to 
+defer initialization (see the Binary Tree example in the cookbook
+for a good example of lazy/default usage
+L<http://search.cpan.org/~stevan/Moose-0.21/lib/Moose/Cookbook/Recipe3.pod>)
+
+=item *
+
+Use attibutes triggers, which fire after an attribute it set, to faciliate 
+initialization. These are described in the L<Moose> docs and examples can be 
+found in the test suite.
+
+=back
+
+In general, roles should not I<require> intialization, they should either 
+provide sane defaults or should be documented as needing specific 
+initialization. One such way to "document" this is to have a seperate
+attribute initializer which is required for the role. Here is an example of 
+how to do this:
+
+  package My::Role;
+  use Moose::Role;
+  
+  has 'height' => (
+      is      => 'rw',
+      isa     => 'Int',
+      lazy    => 1,
+      default => sub {
+          my $self = shift;
+          $self->init_height;
+      } 
+  );
+  
+  requires 'init_height';
+
+In this example, the role will not compose successfully unless the class 
+provides a C<init_height> method. 
+
+If none of those solutions work, then it is possible that a role is not 
+the best tool for the job, and you really should be using classes. Or, at
+the very least, you should reduce the amount of functionality in your role
+so that it does not require initialization.
+
 =head1 AUTHOR
 
 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 
+Anders Nor Berle E<lt>debolaz@gmail.comE<gt>
+
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2006, 2007 by Infinity Interactive, Inc.
+Copyright 2006-2008 by Infinity Interactive, Inc.
 
 L<http://www.iinteractive.com>
 
 This library is free software; you can redistribute it and/or modify
 it under the same terms as Perl itself.
 
-=cut
\ No newline at end of file
+=cut