lib/Moose/Cookbook/FAQ.pod

   1
   2 =pod
   3
   4 =head1 NAME
   5
   6 Moose::Cookbook::FAQ - Frequently asked questions about Moose
   7
   8 =head1 FREQUENTLY ASKED QUESTIONS
   9
  10 =head2 Module Stability
  11
  12 =head3 Is Moose "production ready"?
  13
  14 Yes! Many sites with household names are using Moose to build
  15 high-traffic services. Countless others are using Moose in
  16 production.
  17
  18 As of this writing, Moose is a dependency of several hundred CPAN
  19 modules. L<http://cpants.perl.org/dist/used_by/Moose>
  20
  21 =head3 Is Moose's API stable?
  22
  23 Yes. The sugary API, the one 95% of users will interact with, is
  24 B<very stable>. Any changes will be B<100% backwards compatible>.
  25
  26 The meta API is less set in stone. We reserve the right to tweak
  27 parts of it to improve efficiency or consistency. This will not be
  28 done lightly. We do perform deprecation cycles. We I<really>
  29 do not like making ourselves look bad by breaking your code.
  30 Submitting test cases is the best way to ensure that your code is not
  31 inadvertantly broken by refactoring.
  32
  33 =head3 I heard Moose is slow, is this true?
  34
  35 Again, this one is tricky, so Yes I<and> No.
  36
  37 Firstly, I<nothing> in life is free, and some Moose features
  38 do cost more than others. It is also the policy of Moose to
  39 B<only charge you for the features you use>, and to do our
  40 absolute best to not place any extra burdens on the execution
  41 of your code for features you are not using. Of course using
  42 Moose itself does involve some overhead, but it is mostly
  43 compile time. At this point we do have some options available
  44 for getting the speed you need.
  45
  46 Currently we provide the option of making your classes immutable
  47 as a means of boosting speed. This will mean a slightly larger compile
  48 time cost, but the runtime speed increase (especially in object
  49 construction) is pretty significant.
  50
  51 We are regularly converting the hotspots of L<Class::MOP> to XS.
  52 Florian Ragwitz and Yuval Kogman are currently working on a way
  53 to compile your accessors and instances directly into C, so that
  54 everyone can enjoy blazing fast OO.
  55
  56 =head3 When will Moose 1.0 be ready?
  57
  58 Moose is ready now! Stevan Little declared 0.18, released in March 2007,
  59 to be "ready to use".
  60
  61 =head2 Constructors
  62
  63 =head3 How do I write custom constructors with Moose?
  64
  65 Ideally, you should never write your own C<new> method, and should
  66 use Moose's other features to handle your specific object construction
  67 needs. Here are a few scenarios, and the Moose way to solve them;
  68
  69 If you need to call initialization code post instance construction,
  70 then use the C<BUILD> method. This feature is taken directly from
  71 Perl 6. Every C<BUILD> method in your inheritance chain is called
  72 (in the correct order) immediately after the instance is constructed.
  73 This allows you to ensure that all your superclasses are initialized
  74 properly as well. This is the best approach to take (when possible)
  75 because it makes subclassing your class much easier.
  76
  77 If you need to affect the constructor's parameters prior to the
  78 instance actually being constructed, you have a number of options.
  79
  80 To change the parameter processing as a whole, you can use
  81 the C<BUILDARGS> method. The default implementation accepts key/value
  82 pairs or a hash reference. You can override it to take positional args,
  83 or any other format
  84
  85 To change the handling of individual parameters, there are I<coercions>
  86 (See the L<Moose::Cookbook::Basics::Recipe5> for a complete example and
  87 explanation of coercions). With coercions it is possible to morph
  88 argument values into the correct expected types. This approach is the
  89 most flexible and robust, but does have a slightly higher learning
  90 curve.
  91
  92 =head3 How do I make non-Moose constructors work with Moose?
  93
  94 Usually the correct approach to subclassing a non-Moose class is
  95 delegation.  Moose makes this easy using the C<handles> keyword,
  96 coercions, and C<lazy_build>, so subclassing is often not the
  97 ideal route.
  98
  99 That said, if you really need to inherit from a non-Moose class, see
 100 L<Moose::Cookbook::Basics::Recipe12> for an example of how to do it.
 101
 102 =head2 Accessors
 103
 104 =head3 How do I tell Moose to use get/set accessors?
 105
 106 The easiest way to accomplish this is to use the C<reader> and
 107 C<writer> attribute options:
 108
 109   has 'bar' => (
 110       isa    => 'Baz',
 111       reader => 'get_bar',
 112       writer => 'set_bar',
 113   );
 114
 115 Moose will still take advantage of type constraints, triggers, etc.
 116 when creating these methods.
 117
 118 If you do not like this much typing, and wish it to be a default for your
 119 classes, please see L<MooseX::FollowPBP>. This extension will allow you to
 120 write:
 121
 122   has 'bar' => (
 123       isa => 'Baz',
 124       is  => 'rw',
 125   );
 126
 127 Moose will create separate C<get_bar> and C<set_bar> methods
 128 instead of a single C<bar> method.
 129
 130 NOTE: This B<cannot> be set globally in Moose, as that would break
 131 other classes which are built with Moose. You can still save on typing
 132 by defining a new L<MyApp::Moose> that exports Moose's sugar and then
 133 turns on L<MooseX::FollowPBP>. See L<Moose::Cookbook::Extending::Recipe4>.
 134
 135 =head3 How can I inflate/deflate values in accessors?
 136
 137 Well, the first question to ask is if you actually need both inflate
 138 and deflate.
 139
 140 If you only need to inflate, then we suggest using coercions. Here is
 141 some basic sample code for inflating a L<DateTime> object:
 142
 143   class_type 'DateTime';
 144
 145   coerce 'DateTime'
 146       => from 'Str'
 147         => via { DateTime::Format::MySQL->parse_datetime($_) };
 148
 149   has 'timestamp' => (is => 'rw', isa => 'DateTime', coerce => 1);
 150
 151 This creates a custom type for L<DateTime> objects, then attaches
 152 a coercion to that type. The C<timestamp> attribute is then told
 153 to expect a C<DateTime> type, and to try to coerce it. When a C<Str>
 154 type is given to the C<timestamp> accessor, it will attempt to
 155 coerce the value into a C<DateTime> object using the code in found
 156 in the C<via> block.
 157
 158 For a more comprehensive example of using coercions, see the
 159 L<Moose::Cookbook::Basics::Recipe5>.
 160
 161 If you need to deflate your attribute's value, the current best practice
 162 is to add an C<around> modifier to your accessor:
 163
 164   # a timestamp which stores as
 165   # seconds from the epoch
 166   has 'timestamp' => (is => 'rw', isa => 'Int');
 167
 168   around 'timestamp' => sub {
 169       my $next = shift;
 170       my ($self, $timestamp) = @_;
 171       # assume we get a DateTime object ...
 172       $next->($self, $timestamp->epoch);
 173   };
 174
 175 It is also possible to do deflation using coercion, but this tends
 176 to get quite complex and require many subtypes. An example of this
 177 is outside the scope of this document, ask on #moose or send a mail
 178 to the list.
 179
 180 Still another option is to write a custom attribute metaclass, which
 181 is also outside the scope of this document, but we would be happy to
 182 explain it on #moose or the mailing list.
 183
 184 =head2 Method Modifiers
 185
 186 =head3 How can I affect the values in C<@_> using C<before>?
 187
 188 You can't, actually: C<before> only runs before the main method,
 189 and it cannot easily affect the method's execution.
 190
 191 You similarly can't use C<after> to affect the return value of a
 192 method.
 193
 194 We limit C<before> and C<after> because this lets you write more
 195 concise code. You do not have to worry about passing C<@_> to the
 196 original method, or forwarding its return value (being careful to
 197 preserve context).
 198
 199 The C<around> method modifier has neither of these limitations, but
 200 is a little more verbose.
 201
 202 =head3 Can I use C<before> to stop execution of a method?
 203
 204 Yes, but only if you throw an exception. If this is too drastic a
 205 measure then we suggest using C<around> instead. The C<around> method
 206 modifier is the only modifier which can gracefully prevent execution
 207 of the main method. Here is an example:
 208
 209     around 'baz' => sub {
 210         my $next = shift;
 211         my ($self, %options) = @_;
 212         unless ($options->{bar} eq 'foo') {
 213             return 'bar';
 214         }
 215         $next->($self, %options);
 216     };
 217
 218 By choosing not to call the C<$next> method, you can stop the
 219 execution of the main method.
 220
 221 =head2 Type Constraints
 222
 223 =head3 How can I provide a custom error message for a type constraint?
 224
 225 Use the C<message> option when building the subtype:
 226
 227   subtype 'NaturalLessThanTen'
 228       => as 'Natural'
 229       => where { $_ < 10 }
 230       => message { "This number ($_) is not less than ten!" };
 231
 232 This C<message> block will be called when a value fails to pass the
 233 C<NaturalLessThanTen> constraint check.
 234
 235 =head3 Can I turn off type constraint checking?
 236
 237 Not yet. This option will likely come in a future release.
 238
 239 =head2 Roles
 240
 241 =head3 How do I get Moose to call BUILD in all my composed roles?
 242
 243 See L<Moose::Cookbook::WTF> and specifically the
 244 B<Why is BUILD not called for my composed roles?> question in the
 245 B<Roles> section.
 246
 247 =head3 What are Traits, and how are they different from Roles?
 248
 249 In Moose, a trait is almost exactly the same thing as a role, except
 250 that traits typically register themselves, which allows you to refer
 251 to them by a short name ("Big" vs "MyApp::Role::Big").
 252
 253 In Moose-speak, a I<Role> is usually composed into a I<class> at
 254 compile time, whereas a I<Trait> is usually composed into an instance
 255 of a class at runtime to add or modify the behavior of
 256 B<just that instance>.
 257
 258 Outside the context of Moose, traits and roles generally mean exactly the
 259 same thing. The original paper called them Traits, however Perl 6 will call
 260 them Roles.
 261
 262 =head1 AUTHOR
 263
 264 Stevan Little E<lt>stevan@iinteractive.comE<gt>
 265
 266 =head1 COPYRIGHT AND LICENSE
 267
 268 Copyright 2006-2009 by Infinity Interactive, Inc.
 269
 270 L<http://www.iinteractive.com>
 271
 272 This library is free software; you can redistribute it and/or modify
 273 it under the same terms as Perl itself.
 274
 275 =cut