6 Moose::Cookbook::Extending::Recipe1 - Moose extension overview
10 Moose provides several ways in which extensions can hook into Moose
11 and change its behavior. Moose also has a lot of behavior that can be
12 changed. This recipe will provide an overview of each extension method
13 and give you some recommendations on what tools to use.
15 If you haven't yet read the recipes on metaclasses, go read those
16 first. You can't write Moose extensions without understanding the
17 metaclasses, and those recipes also demonstrate some basic extension
18 mechanisms, such as metaclass subclasses and traits.
20 =head2 Playing Nice With Others
22 One of the goals of this overview is to help you build extensions that
23 cooperate well with other extensions. This is especially important if
24 you plan to release your extension to CPAN.
26 Moose comes with several modules that exist to help your write
27 cooperative extensions. These are L<Moose::Exporter> and
28 L<Moose::Util::MetaRole>. By using these two modules, you will ensure
29 that your extension works with both the Moose core features and any
30 other CPAN extension using those modules.
32 =head1 PARTS OF Moose YOU CAN EXTEND
34 The types of things you might want to do in Moose extensions fall into
35 a few broad categories.
37 =head2 Metaclass Extensions
39 One way of extending Moose is by extending one or more Moose
40 metaclasses. For example, in L<Moose::Cookbook::Meta::Recipe4> we saw
41 a metaclass subclass that added a C<table> attribute to the
42 metaclass. If you were writing an ORM, this would be a logical
45 Many of the Moose extensions on CPAN work by providing an attribute
46 metaclass extension. For example, the L<MooseX::AttributeHelpers>
47 distribution provides a new attribute metaclass that lets you delegate
48 behavior to a non-object attribute (a hashref or simple number).
50 A metaclass extension can be packaged as a subclass or a
51 role/trait. If you can, we recommend using traits instead of
52 subclasses, since it's much easier to combine disparate traits than it
53 is to combine a bunch of subclasses.
55 When your extensions are implemented as roles, you can apply them with
56 the L<Moose::Util::MetaRole> module.
58 =head2 Providing Sugar Functions
60 As part of a metaclass extension, you may also want to provide some
61 sugar functions, just like L<Moose.pm|Moose> does. Moose provides a
62 helper module called L<Moose::Exporter> that makes this much
63 simpler. We will be use L<Moose::Exporter> in several of the extension
66 =head2 Object Class Extensions
68 Another common Moose extension technique is to change the default
69 object class's behavior. For example, the L<MooseX::Singleton>
70 extension changes the behavior of your objects so that they are
71 singletons. The L<MooseX::StrictConstructor> extension makes the
72 constructor reject arguments which don't match its attributes.
74 Object class extensions often include metaclass extensions as well. In
75 particular, if you want your object extension to work when a class is
76 made immutable, you may need to extend some or all of the
77 L<Moose::Meta::Instance>, L<Moose::Meta::Method::Constructor>, and
78 L<Moose::Meta::Method::Destructor> objects.
80 The L<Moose::Util::MetaRole> module lets you apply roles to the base
81 object class, as well as the meta classes just mentioned.
83 =head2 Providing a Role
85 Some extensions come in the form of a role for you to consume. The
86 L<MooseX::Object::Pluggable> extension is a great example of this. In
87 fact, despite the C<MooseX> name, it does not actually change anything
88 about Moose's behavior. Instead, it is just a role that an object
89 which wants to be pluggable can consume.
91 If you are implementing this sort of extension, you don't need to do
92 anything special. You simply create a role and document that it should
93 be used via the normal C<with> sugar:
99 with 'MooseX::My::Role';
103 Another common Moose extension is a new type for the Moose type
104 system. In this case, you simply create a type in your module. When
105 people load your module, the type is created, and they can refer to it
106 by name after that. The L<MooseX::Types::URI> and
107 L<MooseX::Types::DateTime> distributions are two good examples of how
108 this works. These both build on top of the L<MooseX::Types> extension.
110 =head1 ROLES VS TRAITS VS SUBCLASSES
112 It is important to understand that B<roles and traits are the same
113 thing>. A role can be used as a trait, and a trait is a role. The only
114 thing that distinguishes the two is that a trait is packaged in a way
115 that lets Moose resolve a short name to a class name. In other words,
116 with a trait, the caller can refer to it by a short name like "Big",
117 and Moose will resolve it to a class like
118 C<MooseX::Embiggen::Meta::Attribute::Role::Big>.
120 See L<Moose::Cookbook::Meta::Recipe3> and
121 L<Moose::Cookbook::Meta::Recipe5> for examples of traits in action. In
122 particular, both of these recipes demonstrate the trait resolution
125 Implementing an extension as a (set of) metaclass or base object
126 role(s) will make your extension more cooperative. It is hard for an
127 end-user to effectively combine together multiple metaclass
128 subclasses, but it is very easy to combine roles.
130 =head1 USING YOUR EXTENSION
132 There are a number of ways in which an extension can be applied. In
133 some cases you can provide multiple ways of consuming your extension.
135 =head2 Extensions as Metaclass Traits
137 If your extension is available as a trait, you can ask end users to
138 simply specify it in a list of traits. Currently, this only works for
139 (class) metaclass and attribute metaclass traits:
141 use Moose -traits => [ 'Big', 'Blue' ];
144 traits => [ 'Big', 'Blue' ],
148 If your extension applies to any other metaclass, or the object base
149 class, you cannot use the trait mechanism.
151 The benefit of the trait mechanism is that is very easy to see where a
152 trait is applied in the code, and consumers have fine-grained control
153 over what the trait applies to. This is especially true for attribute
154 traits, where you can apply the trait to just one attribute in a
157 =head2 Extensions as Metaclass (and Base Object) Subclasses
159 Moose does not provide any simple APIs for consumers to use a subclass
160 extension, except for attribute metaclasses. The attribute declaration
161 options include a C<metaclass> option a consumer of your extension can
162 use to specify your subclass.
164 This is one reason why implementing an extension as a subclass can be
165 a poor choice. However, you can force the use of certain subclasses at
166 import time by calling C<< Moose->init_meta >> for the caller, and
167 providing an alternate metaclass or base object class.
169 If you do want to do this, you should look at using L<Moose::Exporter>
170 to re-export the L<Moose.pm|Moose> sugar function. With
171 L<Moose::Exporter>, if your exporting class has an C<init_meta>
172 method, L<Moose::Exporter> makes sure that this C<init_meta> method
173 gets called when your class is imported.
175 Then in your C<init_meta> you can arrange for the caller to use your
178 package MooseX::Embiggen;
183 use MooseX::Embiggen::Meta::Class;
184 use MooseX::Embiggen::Object;
186 Moose::Exporter->setup_import_methods( also => 'Moose' );
189 shift; # just your package name
192 return Moose->init_meta(
193 for_class => $options{for_class},
194 metaclass => 'MooseX::Embiggen::Meta::Class',
195 base_class => 'MooseX::Embiggen::Object',
199 NOTE: Make sure that your C<init_meta> returns the metaclass object, just as
200 C<< Moose->init_meta >> does.
202 =head2 Extensions as Metaclass (and Base Object) Roles
204 Implementing your extensions as metaclass roles makes your extensions
205 easy to apply, and cooperative with other role-based extensions for
208 Just as with a subclass, you will probably want to package your
209 extensions for consumption with a single module that uses
210 L<Moose::Exporter>. However, in this case, you will use
211 L<Moose::Util::MetaRole> to apply all of your roles. The advantage of
212 using this module is that I<it preserves any subclassing or roles
213 already applied to the user's metaclasses>. This means that your
214 extension is cooperative I<by default>, and consumers of your
215 extension can easily use it with other role-based extensions.
217 package MooseX::Embiggen;
221 use Moose::Util::MetaRole;
223 use MooseX::Embiggen::Role::Meta::Class;
224 use MooseX::Embiggen::Role::Meta::Attribute;
225 use MooseX::Embiggen::Role::Meta::Method::Constructor;
226 use MooseX::Embiggen::Role::Object;
228 Moose::Exporter->setup_import_methods( also => 'Moose' );
231 shift; # just your package name
234 Moose->init_meta(%options);
236 my $meta = Moose::Util::MetaRole::apply_metaclass_roles(
237 for_class => $options{for_class},
238 metaclass_roles => ['MooseX::Embiggen::Role::Meta::Class'],
239 attribute_metaclass_roles =>
240 ['MooseX::Embiggen::Role::Meta::Attribute'],
241 constructor_class_roles =>
242 ['MooseX::Embiggen::Role::Meta::Method::Constructor'],
245 Moose::Util::MetaRole::apply_base_class_roles(
246 for_class => $options{for_class},
247 roles => ['MooseX::Embiggen::Role::Object'],
253 As you can see from this example, you can use L<Moose::Util::MetaRole>
254 to apply roles to any metaclass, as well as the base object class. If
255 some other extension has already applied its own roles, they will be
256 preserved when your extension applies its roles, and vice versa.
258 =head2 Providing Sugar
260 With L<Moose::Exporter>, you can also export your own sugar functions,
261 as well as those from other modules:
263 package MooseX::Embiggen;
268 Moose::Exporter->setup_import_methods(
269 with_caller => ['embiggen'],
273 sub init_meta { ... }
277 $caller->meta()->embiggen(@_);
280 And then the consumer of your extension can use your C<embiggen> sub:
284 use MooseX::Embiggen;
290 This can be combined with metaclass and base class roles quite easily.
292 =head1 LEGACY EXTENSION MECHANISMS
294 Before the existence of L<Moose::Exporter> and
295 L<Moose::Util::MetaRole>, there were a number of other ways to extend
296 Moose. In general, these methods were less cooperative, and only
297 worked well with a single extension.
299 These methods include L<metaclass.pm|metaclass>, L<Moose::Policy>
300 (which uses L<metaclass.pm|metaclass> under the hood), and various
301 hacks to do what L<Moose::Exporter> does. Please do not use these for
304 Note that if you write a cooperative extension, it should cooperate
305 with older extensions, though older extensions generally do not
306 cooperate with each other.
310 If you can write your extension as one or more metaclass and base
311 object roles, please consider doing so. Make sure to read the docs for
312 L<Moose::Exporter> and L<Moose::Util::MetaRole> as well.
316 Dave Rolsky E<lt>autarch@urth.orgE<gt>
318 =head1 COPYRIGHT AND LICENSE
320 Copyright 2009 by Infinity Interactive, Inc.
322 L<http://www.iinteractive.com>
324 This library is free software; you can redistribute it and/or modify
325 it under the same terms as Perl itself.