+package Moose::Manual::FAQ;
-=pod
+# ABSTRACT: Frequently asked questions about Moose
+
+__END__
-=head1 NAME
-Moose::Manual::FAQ - Frequently asked questions about Moose
+=pod
=head1 FREQUENTLY ASKED QUESTIONS
Yes! Many sites with household names are using Moose to build
high-traffic services. Countless others are using Moose in production.
+See L<http://moose.iinteractive.com/about.html#organizations> for
+a partial list.
As of this writing, Moose is a dependency of several hundred CPAN
-modules. L<http://cpants.perl.org/dist/used_by/Moose>
+modules. L<https://metacpan.org/requires/module/Moose>
=head3 Is Moose's API stable?
MyClass->meta->make_immutable();
-We are regularly converting the hotspots of L<Class::MOP> to XS.
-Florian Ragwitz and Yuval Kogman are currently working on a way to
-compile your accessors and instances directly into C, so that everyone
-can enjoy blazing fast OO.
-
-=head3 When will Moose 1.0 be ready?
-
-Moose is ready now! Stevan Little declared 0.18, released in March
-2007, to be "ready to use".
-
=head2 Constructors
=head3 How do I write custom constructors with Moose?
pairs or a hash reference. You can override it to take positional
args, or any other format
-To change the handling of individual parameters, there are
-I<coercions> (See the L<Moose::Cookbook::Basics::Recipe5> for a
-complete example and explanation of coercions). With coercions it is
-possible to morph argument values into the correct expected
-types. This approach is the most flexible and robust, but does have a
-slightly higher learning curve.
+To change the handling of individual parameters, there are I<coercions> (See
+the L<Moose::Cookbook::Basics::HTTP_SubtypesAndCoercion> for a complete
+example and explanation of coercions). With coercions it is possible to morph
+argument values into the correct expected types. This approach is the most
+flexible and robust, but does have a slightly higher learning curve.
=head3 How do I make non-Moose constructors work with Moose?
route.
That said, if you really need to inherit from a non-Moose class, see
-L<Moose::Cookbook::Basics::Recipe11> for an example of how to do it,
+L<Moose::Cookbook::Basics::DateTime_ExtendingNonMooseParent> for an example of how to do it,
or take a look at L<Moose::Manual::MooseX/"MooseX::NonMoose">.
=head2 Accessors
NOTE: This B<cannot> be set globally in Moose, as that would break
other classes which are built with Moose. You can still save on typing
-by defining a new L<MyApp::Moose> that exports Moose's sugar and then
+by defining a new C<MyApp::Moose> that exports Moose's sugar and then
turns on L<MooseX::FollowPBP>. See
-L<Moose::Cookbook::Extending::Recipe4>.
+L<Moose::Cookbook::Extending::Mooseish_MooseSugar>.
=head3 How can I inflate/deflate values in accessors?
in the C<via> block.
For a more comprehensive example of using coercions, see the
-L<Moose::Cookbook::Basics::Recipe5>.
+L<Moose::Cookbook::Basics::HTTP_SubtypesAndCoercion>.
If you need to deflate your attribute's value, the current best
practice is to add an C<around> modifier to your accessor:
is also outside the scope of this document, but we would be happy to
explain it on #moose or the mailing list.
-=head3 I created an attribute, where are my accessors?
-
-Accessors are B<not> created implicitly, you B<must> ask Moose to
-create them for you. My guess is that you have this:
-
- has 'foo' => (isa => 'Bar');
-
-when what you really want to say is:
-
- has 'foo' => (isa => 'Bar', is => 'rw');
-
-The reason this is so is because it is a perfectly valid use case to
-I<not> have an accessor. The simplest one is that you want to write
-your own. If Moose created one automatically, then because of the
-order in which classes are constructed, Moose would overwrite your
-custom accessor. You wouldn't want that would you?
-
=head2 Method Modifiers
=head3 How can I affect the values in C<@_> using C<before>?
The C<around> method modifier has neither of these limitations, but is
a little more verbose.
+Alternatively, the L<MooseX::Mangle> extension provides the
+C<mangle_args> function, which does allow you to affect C<@_>.
+
=head3 Can I use C<before> to stop execution of a method?
Yes, but only if you throw an exception. If this is too drastic a
By choosing not to call the C<$next> method, you can stop the
execution of the main method.
+Alternatively, the L<MooseX::Mangle> extension provides the
+C<guard> function, which will conditionally prevent execution
+of the original method.
+
=head3 Why can't I see return values in an C<after> modifier?
As with the C<before> modifier, the C<after> modifier is simply called
return reverse @rv;
};
+Alternatively, the L<MooseX::Mangle> extension provides the
+C<mangle_return> function, which allows modifying the return values
+of the original method.
+
=head2 Type Constraints
=head3 How can I provide a custom error message for a type constraint?
=head3 Can I turn off type constraint checking?
-Not yet. This option may come in a future release.
+There's no support for it in the core of Moose yet. This option may
+come in a future release.
+
+Meanwhile there's a L<MooseX
+extension|MooseX::Attribute::TypeConstraint::CustomizeFatal> that
+allows you to do this on a per-attribute basis, and if it doesn't do
+what you it's easy to write one that fits your use case.
=head3 My coercions stopped working with recent Moose, why did you break it?
-Moose 0.76 fixed a case where Coercions were being applied even if the original constraint passed. This has caused some edge cases to fail where people were doing something like
+Moose 0.76 fixed a case where coercions were being applied even if the original
+constraint passed. This has caused some edge cases to fail where people were
+doing something like
- subtype Address => as 'Str';
- coerce Address => from Str => via { get_address($_) };
+ subtype 'Address', as 'Str';
+ coerce 'Address', from 'Str', via { get_address($_) };
-Which is not what they intended. The Type Constraint C<Address> is too loose in this case, it is saying that all Strings are Addresses, which is obviously not the case. The solution is to provide a where clause that properly restricts the Type Constraint.
+This is not what they intended, because the type constraint C<Address> is too
+loose in this case. It is saying that all strings are Addresses, which is
+obviously not the case. The solution is to provide a C<where> clause that
+properly restricts the type constraint:
- subtype Address => as Str => where { looks_like_address($_) };
+ subtype 'Address', as 'Str', where { looks_like_address($_) };
-This will allow the coercion to apply only to strings that fail to look like an Address.
+This will allow the coercion to apply only to strings that fail to look like an
+Address.
=head2 Roles
=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<Moose::Cookbook::Basics::Recipe3>)
+initialization (see the Binary Tree example in the cookbook for a good example
+of lazy/default usage
+L<Moose::Cookbook::Basics::BinaryTree_AttributeFeatures>)
=item *
classes. Or, at the very least, you should reduce the amount of
functionality in your role so that it does not require initialization.
-=head3 What are Traits, and how are they different from Roles?
+=head3 What are traits, and how are they different from roles?
In Moose, a trait is almost exactly the same thing as a role, except
that traits typically register themselves, which allows you to refer
instance>.
Outside the context of Moose, traits and roles generally mean exactly
-the same thing. The original paper called them Traits, however Perl 6
-will call them Roles.
+the same thing. The original paper called them traits, but Perl 6
+will call them roles.
+
+=head3 Can an attribute-generated method (e.g. an accessor) satisfy requires?
+
+Yes, just be sure to consume the role I<after> declaring your
+attribute. L<Moose::Manual::Roles/Required Attributes> provides
+an example:
+
+ package Breakable;
+ use Moose::Role;
+ requires 'stress';
+
+ package Car;
+ use Moose;
+ has 'stress' => ( is => 'rw', isa => 'Int' );
+ with 'Breakable';
+
+If you mistakenly consume the C<Breakable> role before declaring your
+C<stress> attribute, you would see an error like this:
+
+ 'Breakable' requires the method 'stress' to be implemented by 'Car' at...
=head2 Moose and Subroutine Attributes
=head3 Why don't subroutine 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
+Currently when subclassing a module 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
+block so that the attribute handlers will be available at compile time,
like this:
BEGIN { extends qw/Foo/ }
sub foo : Bar(27) { ... }
-=head1 AUTHOR
-
-Stevan Little E<lt>stevan@iinteractive.comE<gt>
-
-=head1 COPYRIGHT AND LICENSE
-
-Copyright 2006-2010 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
projects / gitmo/Moose.git / blobdiff