+package Moose::Cookbook::Extending::Recipe1;
-=pod
+# ABSTRACT: Moose extension overview
+
+__END__
-=head1 NAME
-Moose::Cookbook::Extending::Recipe1 - Moose extension overview
+=pod
=head1 DESCRIPTION
metaclass extension. For example, the L<MooseX::AttributeHelpers>
distribution provides a new attribute metaclass that lets you delegate
behavior to a non-object attribute (a hashref or simple number).
+(MooseX::AttributeHelpers has been deprecated in favour of
+L<Moose::Meta::Attribute::Native>, but can still serve as an example).
A metaclass extension can be packaged as a subclass or a
role/trait. If you can, we recommend using traits instead of
-subclasses, since it's much easier to combine disparate traits then it
+subclasses, since it's much easier to combine disparate traits than it
is to combine a bunch of subclasses.
When your extensions are implemented as roles, you can apply them with
=head1 ROLES VS TRAITS VS SUBCLASSES
-It is important to understand that B<roles and traits are the same
-thing>. A role can be used as a trait, and a trait is a role. The only
-thing that distinguishes the two is that a trait is packaged in a way
-that lets Moose resolve a short name to a class name. In other words,
-with a trait, the caller can refer to it by a short name like "Big",
-and Moose will resolve it to a class like
-C<MooseX::Embiggen::Meta::Attribute::Role::Big>.
+It is important to understand that B<roles and traits are the same thing>. A
+trait is simply a role applied to a instance. The only thing that may
+distinguish the two is that a trait can be packaged in a way that lets Moose
+resolve a short name to a class name. In other words, with a trait, the caller
+can refer to it by a short name like "Big", and Moose will resolve it to a
+class like C<MooseX::Embiggen::Meta::Attribute::Role::Big>.
See L<Moose::Cookbook::Meta::Recipe3> and
L<Moose::Cookbook::Meta::Recipe5> for examples of traits in action. In
);
}
+NOTE: Make sure that your C<init_meta> returns the metaclass object, just as
+C<< Moose->init_meta >> does.
+
=head2 Extensions as Metaclass (and Base Object) Roles
Implementing your extensions as metaclass roles makes your extensions
using this module is that I<it preserves any subclassing or roles
already applied to the user's metaclasses>. This means that your
extension is cooperative I<by default>, and consumers of your
-extension can easily use it with other role-based extensions.
+extension can easily use it with other role-based extensions. Most
+uses of L<Moose::Util::MetaRole> can be handled by L<Moose::Exporter>
+directly; see the L<Moose::Exporter> docs.
package MooseX::Embiggen;
use Moose ();
use Moose::Exporter;
- use Moose::Util::MetaRole;
use MooseX::Embiggen::Role::Meta::Class;
use MooseX::Embiggen::Role::Meta::Attribute;
use MooseX::Embiggen::Role::Meta::Method::Constructor;
use MooseX::Embiggen::Role::Object;
- Moose::Exporter->setup_import_methods( also => 'Moose' );
+ my ( $import, $unimport, $init_meta ) = Moose::Exporter->build_import_methods(
+ also => ['Moose'] metaclass_roles =>
+ ['MooseX::Embiggen::Role::Meta::Class'],
+ attribute_metaclass_roles => ['MooseX::Embiggen::Role::Meta::Attribute'],
+ constructor_class_roles =>
+ ['MooseX::Embiggen::Role::Meta::Method::Constructor'],
+ base_class_roles => ['MooseX::Embiggen::Role::Object'],
+ install => [qw(import unimport)],
+ );
sub init_meta {
- shift; # just your package name
+ my $package = shift;
my %options = @_;
-
Moose->init_meta(%options);
-
- my $meta = Moose::Util::MetaRole::apply_metaclass_roles(
- for_class => $options{for_class},
- metaclass_roles => ['MooseX::Embiggen::Role::Meta::Class'],
- attribute_metaclass_roles =>
- ['MooseX::Embiggen::Role::Meta::Attribute'],
- constructor_class_roles =>
- ['MooseX::Embiggen::Role::Meta::Method::Constructor'],
- );
-
- Moose::Util::MetaRole::apply_base_class_roles(
- for_class => $options{for_class},
- roles => ['MooseX::Embiggen::Role::Object'],
- );
-
- return $meta;
+ return $package->$init_meta(%options);
}
As you can see from this example, you can use L<Moose::Util::MetaRole>
use Moose::Exporter;
Moose::Exporter->setup_import_methods(
- with_caller => ['embiggen'],
- also => 'Moose',
+ with_meta => ['embiggen'],
+ also => 'Moose',
);
- sub init_meta { ... }
-
sub embiggen {
- my $caller = shift;
- $caller->meta()->embiggen(@_);
+ my $meta = shift;
+ $meta->embiggen(@_);
}
And then the consumer of your extension can use your C<embiggen> sub:
object roles, please consider doing so. Make sure to read the docs for
L<Moose::Exporter> and L<Moose::Util::MetaRole> as well.
-=head1 AUTHOR
-
-Dave Rolsky E<lt>autarch@urth.orgE<gt>
-
-=head1 COPYRIGHT AND LICENSE
-
-Copyright 2009 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