view release on metacpan or  search on metacpan

lib/Moose.pm  view on Meta::CPAN

=head2 confess

This is the C<Carp::confess> function, and exported here for historical
reasons.

=head1 METACLASS

When you use Moose, you can specify traits which will be applied to your
metaclass:

    use Moose -traits => 'My::Trait';

This is very similar to the attribute traits feature. When you do
this, your class's C<meta> object will have the specified traits
applied to it.

=head2 Metaclass and Trait Name Resolution

By default, when given a trait name, Moose simply tries to load a
class of the same name. If such a class does not exist, it then looks
for a class matching
B<Moose::Meta::$type::Custom::Trait::$trait_name>. The C<$type>
variable here will be one of B<Attribute> or B<Class>, depending on
what the trait is being applied to.

If a class with this long name exists, Moose checks to see if it has
the method C<register_implementation>. This method is expected to
return the I<real> class name of the trait. If there is no
C<register_implementation> method, it will fall back to using
B<Moose::Meta::$type::Custom::Trait::$trait> as the trait name.

The lookup method for metaclasses is the same, except that it looks
for a class matching B<Moose::Meta::$type::Custom::$metaclass_name>.

If all this is confusing, take a look at
L<Moose::Cookbook::Meta::Labeled_AttributeTrait>, which demonstrates how to
create an attribute trait.

=head1 UNIMPORTING FUNCTIONS

=head2 B<unimport>

Moose offers a way to remove the keywords it exports, through the C<unimport>
method. You simply have to say C<no Moose> at the bottom of your code for this
to work. Here is an example:

    package Person;
    use Moose;

    has 'first_name' => (is => 'rw', isa => 'Str');
    has 'last_name'  => (is => 'rw', isa => 'Str');

    sub full_name {
        my $self = shift;
        $self->first_name . ' ' . $self->last_name
    }

    no Moose; # keywords are removed from the Person package

=head1 EXTENDING AND EMBEDDING MOOSE

To learn more about extending Moose, we recommend checking out the
"Extending" recipes in the L<Moose::Cookbook>, starting with
L<Moose::Cookbook::Extending::ExtensionOverview>, which provides an overview of
all the different ways you might extend Moose. L<Moose::Exporter> and
L<Moose::Util::MetaRole> are the modules which provide the majority of the
extension functionality, so reading their documentation should also be helpful.

=head2 The MooseX:: namespace

Generally if you're writing an extension I<for> Moose itself you'll want
to put your extension in the C<MooseX::> namespace. This namespace is
specifically for extensions that make Moose better or different in some
fundamental way. It is traditionally B<not> for a package that just happens
to use Moose. This namespace follows from the examples of the C<LWPx::>
and C<DBIx::> namespaces that perform the same function for C<LWP> and C<DBI>
respectively.

=head1 METACLASS COMPATIBILITY AND MOOSE

Metaclass compatibility is a thorny subject. You should start by
reading the "About Metaclass compatibility" section in the
L<Class::MOP> docs.

Moose will attempt to resolve a few cases of metaclass incompatibility
when you set the superclasses for a class, in addition to the cases that
L<Class::MOP> handles.

Moose tries to determine if the metaclasses only "differ by roles". This
means that the parent and child's metaclass share a common ancestor in
their respective hierarchies, and that the subclasses under the common
ancestor are only different because of role applications. This case is
actually fairly common when you mix and match various C<MooseX::*>
modules, many of which apply roles to the metaclass.

If the parent and child do differ by roles, Moose replaces the
metaclass in the child with a newly created metaclass. This metaclass
is a subclass of the parent's metaclass which does all of the roles that
the child's metaclass did before being replaced. Effectively, this
means the new metaclass does all of the roles done by both the
parent's and child's original metaclasses.

Ultimately, this is all transparent to you except in the case of an
unresolvable conflict.

=head1 CAVEATS

It should be noted that C<super> and C<inner> B<cannot> be used in the same
method. However, they may be combined within the same class hierarchy; see
F<t/basics/override_augment_inner_super.t> for an example.

The reason for this is that C<super> is only valid within a method
with the C<override> modifier, and C<inner> will never be valid within an
C<override> method. In fact, C<augment> will skip over any C<override> methods
when searching for its appropriate C<inner>.

This might seem like a restriction, but I am of the opinion that keeping these
two features separate (yet interoperable) actually makes them easy to use, since
their behavior is then easier to predict. Time will tell whether I am right or
not (UPDATE: so far so good).