1 package Moose::Cookbook::Extending::ExtensionOverview;
3 # ABSTRACT: Moose extension overview
12 Moose provides several ways in which extensions can hook into Moose
13 and change its behavior. Moose also has a lot of behavior that can be
14 changed. This recipe will provide an overview of each extension method
15 and give you some recommendations on what tools to use.
17 If you haven't yet read the recipes on metaclasses, go read those
18 first. You can't write Moose extensions without understanding the
19 metaclasses, and those recipes also demonstrate some basic extension
20 mechanisms, such as metaclass subclasses and traits.
22 =head2 Playing Nice With Others
24 One of the goals of this overview is to help you build extensions that
25 cooperate well with other extensions. This is especially important if
26 you plan to release your extension to CPAN.
28 Moose comes with several modules that exist to help your write
29 cooperative extensions. These are L<Moose::Exporter> and
30 L<Moose::Util::MetaRole>. By using these two modules, you will ensure
31 that your extension works with both the Moose core features and any
32 other CPAN extension using those modules.
34 =head1 PARTS OF Moose YOU CAN EXTEND
36 The types of things you might want to do in Moose extensions fall into
37 a few broad categories.
39 =head2 Metaclass Extensions
41 One way of extending Moose is by extending one or more Moose
42 metaclasses. For example, in L<Moose::Cookbook::Meta::Table_MetaclassTrait> we saw
43 a metaclass role that added a C<table> attribute to the
44 metaclass. If you were writing an ORM, this would be a logical
47 Many of the Moose extensions on CPAN work by providing an attribute
48 metaclass role. For example, the L<MooseX::Aliases> module
49 provides an attribute metaclass trait that lets you specify aliases
50 to install for methods and attribute accessors.
52 A metaclass extension can be packaged as a role/trait or a subclass. If you
53 can, we recommend using traits instead of subclasses, since it's much easier
54 to combine disparate traits than it is to combine a bunch of subclasses.
56 When your extensions are implemented as roles, you can apply them with
57 the L<Moose::Util::MetaRole> module.
59 =head2 Providing Sugar Functions
61 As part of a metaclass extension, you may also want to provide some
62 sugar functions, just like L<Moose.pm|Moose> does. Moose provides a
63 helper module called L<Moose::Exporter> that makes this much
64 simpler. We will be use L<Moose::Exporter> in several of the extension
67 =head2 Object Class Extensions
69 Another common Moose extension technique is to change the default object
70 class's behavior. As with metaclass extensions, this can be done with a
71 role/trait or with a subclass. For example, L<MooseX::StrictConstructor>
72 extension applies a trait that makes the constructor reject arguments which
73 don't match its attributes.
75 Object class extensions often include metaclass extensions as well. In
76 particular, if you want your object extension to work when a class is
77 made immutable, you may need to modify the behavior of some or all of the
78 L<Moose::Meta::Instance>, L<Moose::Meta::Method::Constructor>, and
79 L<Moose::Meta::Method::Destructor> objects.
81 The L<Moose::Util::MetaRole> module lets you apply roles to the base
82 object class, as well as the meta classes just mentioned.
84 =head2 Providing a Role
86 Some extensions come in the form of a role for you to consume. The
87 L<MooseX::Object::Pluggable> extension is a great example of this. In
88 fact, despite the C<MooseX> name, it does not actually change anything
89 about Moose's behavior. Instead, it is just a role that an object
90 which wants to be pluggable can consume.
92 If you are implementing this sort of extension, you don't need to do
93 anything special. You simply create a role and document that it should
94 be used via the normal C<with> sugar:
102 Don't use "MooseX" in the name for such packages.
106 Another common Moose extension is a new type for the Moose type
107 system. In this case, you simply create a type in your module. When
108 people load your module, the type is created, and they can refer to it
109 by name after that. The L<MooseX::Types::URI> and
110 L<MooseX::Types::DateTime> distributions are two good examples of how
111 this works. These both build on top of the L<MooseX::Types> extension.
113 =head1 ROLES VS TRAITS VS SUBCLASSES
115 It is important to understand that B<roles and traits are the same thing>. A
116 trait is simply a role applied to a instance. The only thing that may
117 distinguish the two is that a trait can be packaged in a way that lets Moose
118 resolve a short name to a class name. In other words, with a trait, the caller
119 can refer to it by a short name like "Big", and Moose will resolve it to a
120 class like C<MooseX::Embiggen::Meta::Attribute::Role::Big>.
122 See L<Moose::Cookbook::Meta::Labeled_AttributeTrait> and
123 L<Moose::Cookbook::Meta::Table_MetaclassTrait> for examples of traits in
124 action. In particular, both of these recipes demonstrate the trait resolution
127 Implementing an extension as a (set of) metaclass or base object
128 role(s) will make your extension more cooperative. It is hard for an
129 end-user to effectively combine together multiple metaclass
130 subclasses, but it is very easy to combine roles.
132 =head1 USING YOUR EXTENSION
134 There are a number of ways in which an extension can be applied. In
135 some cases you can provide multiple ways of consuming your extension.
137 =head2 Extensions as Metaclass Traits
139 If your extension is available as a trait, you can ask end users to
140 simply specify it in a list of traits. Currently, this only works for
141 (class) metaclass and attribute metaclass traits:
143 use Moose -traits => [ 'Big', 'Blue' ];
146 traits => [ 'Big', 'Blue' ],
150 If your extension applies to any other metaclass, or the object base
151 class, you cannot use the trait mechanism.
153 The benefit of the trait mechanism is that is very easy to see where a
154 trait is applied in the code, and consumers have fine-grained control
155 over what the trait applies to. This is especially true for attribute
156 traits, where you can apply the trait to just one attribute in a
159 =head2 Extensions as Metaclass (and Base Object) Roles
161 Implementing your extensions as metaclass roles makes your extensions
162 easy to apply, and cooperative with other role-based extensions for
165 Just as with a subclass, you will probably want to package your
166 extensions for consumption with a single module that uses
167 L<Moose::Exporter>. However, in this case, you will use
168 L<Moose::Util::MetaRole> to apply all of your roles. The advantage of
169 using this module is that I<it preserves any subclassing or roles
170 already applied to the user's metaclasses>. This means that your
171 extension is cooperative I<by default>, and consumers of your
172 extension can easily use it with other role-based extensions. Most
173 uses of L<Moose::Util::MetaRole> can be handled by L<Moose::Exporter>
174 directly; see the L<Moose::Exporter> docs.
176 package MooseX::Embiggen;
180 use MooseX::Embiggen::Role::Meta::Class;
181 use MooseX::Embiggen::Role::Meta::Attribute;
182 use MooseX::Embiggen::Role::Meta::Method::Constructor;
183 use MooseX::Embiggen::Role::Object;
185 Moose::Exporter->setup_import_methods(
187 class => ['MooseX::Embiggen::Role::Meta::Class'],
188 attribute => ['MooseX::Embiggen::Role::Meta::Attribute'],
190 ['MooseX::Embiggen::Role::Meta::Method::Constructor'],
192 base_class_roles => ['MooseX::Embiggen::Role::Object'],
195 As you can see from this example, you can use L<Moose::Util::MetaRole>
196 to apply roles to any metaclass, as well as the base object class. If
197 some other extension has already applied its own roles, they will be
198 preserved when your extension applies its roles, and vice versa.
200 =head2 Providing Sugar
202 With L<Moose::Exporter>, you can also export your own sugar functions:
204 package MooseX::Embiggen;
208 Moose::Exporter->setup_import_methods(
209 with_meta => ['embiggen'],
211 class => ['MooseX::Embiggen::Role::Meta::Class'],
220 And then the consumer of your extension can use your C<embiggen> sub:
225 use MooseX::Embiggen;
231 This can be combined with metaclass and base class roles quite easily.
233 =head2 Extensions as Metaclass (and Base Object) Subclasses
235 B<Note: We strongly recommend that you provide your extension as a set of
236 roles whenever possible>.
238 Moose does not provide any simple APIs for consumers to use a subclass
239 extension, except for class and attribute metaclasses. The attribute
240 declaration options include a C<metaclass> option a consumer of your extension
241 can use to specify your subclass, and class metaclasses can be passed via the
242 C<-metaclass> import option when you C<use Moose>.
244 This is one reason why implementing an extension as a subclass can be
245 a poor choice. However, you can force the use of certain subclasses at
246 import time by calling C<< Moose->init_meta >> for the caller, and
247 providing an alternate metaclass or base object class.
249 If you do want to do this, you should look at using L<Moose::Exporter>
250 to re-export the L<Moose.pm|Moose> sugar function. With
251 L<Moose::Exporter>, if your exporting class has an C<init_meta>
252 method, L<Moose::Exporter> makes sure that this C<init_meta> method
253 gets called when your class is imported.
255 Then in your C<init_meta> you can arrange for the caller to use your
258 package MooseX::Embiggen;
263 use MooseX::Embiggen::Meta::Class;
264 use MooseX::Embiggen::Object;
266 Moose::Exporter->setup_import_methods( also => 'Moose' );
269 shift; # just your package name
272 return Moose->init_meta(
273 for_class => $options{for_class},
274 metaclass => 'MooseX::Embiggen::Meta::Class',
275 base_class => 'MooseX::Embiggen::Object',
279 Note that there are several issues with this sort of extension mechanism, most
280 notably that Moose only ever initializes the metaclass for a class once. This
281 means that this extension must be loaded B<first>, before anything
282 Moose-related touches the class. If you say C<use Moose; use
283 MooseX::Embiggen;>, for instance, the extension will not be applied properly.
284 There are very few reasons to implement an extension in this way; using
285 metaclass traits is the right answer in nearly every case.
287 =head1 LEGACY EXTENSION MECHANISMS
289 Before the existence of L<Moose::Exporter> and
290 L<Moose::Util::MetaRole>, there were a number of other ways to extend
291 Moose. In general, these methods were less cooperative, and only
292 worked well with a single extension.
294 These methods include L<metaclass.pm|metaclass>, L<Moose::Policy>
295 (which uses L<metaclass.pm|metaclass> under the hood), and various
296 hacks to do what L<Moose::Exporter> does. Please do not use these for
299 Note that if you write a cooperative extension, it should cooperate
300 with older extensions, though older extensions generally do not
301 cooperate with each other.
305 If you can write your extension as one or more metaclass and base
306 object roles, please consider doing so. Make sure to read the docs for
307 L<Moose::Exporter> and L<Moose::Util::MetaRole> as well.