1Moose::Cookbook::ExtendUisnegr::CEoxnttMeroniosbsiueot:ne:OdCvoePorekvrbiloeowDk(o:3c:)uEmxetnetnadtiinogn::ExtensionOverview(3)
2
6 Moose::Cookbook::Extending::ExtensionOverview - Moose extension
7 overview
8
10 version 2.2012
11
13 Moose provides several ways in which extensions can hook into Moose and
14 change its behavior. Moose also has a lot of behavior that can be
15 changed. This recipe will provide an overview of each extension method
16 and give you some recommendations on what tools to use.
17 If you haven't yet read the recipes on metaclasses, go read those
19 first. You can't write Moose extensions without understanding the
20 metaclasses, and those recipes also demonstrate some basic extension
21 mechanisms, such as metaclass subclasses and traits.
22 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.
27 Moose comes with several modules that exist to help your write
29 cooperative extensions. These are Moose::Exporter and
30 Moose::Util::MetaRole. By using these two modules, you will ensure that
31 your extension works with both the Moose core features and any other
32 CPAN extension using those modules.
33
35 The types of things you might want to do in Moose extensions fall into
36 a few broad categories.
37 Metaclass Extensions
39 One way of extending Moose is by extending one or more Moose
40 metaclasses. For example, in
41 Moose::Cookbook::Meta::Table_MetaclassTrait we saw a metaclass role
42 that added a "table" attribute to the metaclass. If you were writing an
43 ORM, this would be a logical extension.
44 Many of the Moose extensions on CPAN work by providing an attribute
46 metaclass role. For example, the MooseX::Aliases module provides an
47 attribute metaclass trait that lets you specify aliases to install for
48 methods and attribute accessors.
49 A metaclass extension can be packaged as a role/trait or a subclass. If
51 you can, we recommend using traits instead of subclasses, since it's
52 much easier to combine disparate traits than it is to combine a bunch
53 of subclasses.
54 When your extensions are implemented as roles, you can apply them with
56 the Moose::Util::MetaRole module.
57 Providing Sugar Functions
59 As part of a metaclass extension, you may also want to provide some
60 sugar functions, just like Moose.pm does. Moose provides a helper
61 module called Moose::Exporter that makes this much simpler. We will be
62 use Moose::Exporter in several of the extension recipes.
63 Object Class Extensions
65 Another common Moose extension technique is to change the default
66 object class's behavior. As with metaclass extensions, this can be done
67 with a role/trait or with a subclass. For example,
68 MooseX::StrictConstructor extension applies a trait that makes the
69 constructor reject arguments which don't match its attributes.
70 Object class extensions often include metaclass extensions as well. In
72 particular, if you want your object extension to work when a class is
73 made immutable, you may need to modify the behavior of some or all of
74 the Moose::Meta::Instance, Moose::Meta::Method::Constructor, and
75 Moose::Meta::Method::Destructor objects.
76 The Moose::Util::MetaRole module lets you apply roles to the base
78 object class, as well as the meta classes just mentioned.
79 Providing a Role
81 Some extensions come in the form of a role for you to consume. The
82 MooseX::Object::Pluggable extension is a great example of this. In
83 fact, despite the "MooseX" name, it does not actually change anything
84 about Moose's behavior. Instead, it is just a role that an object which
85 wants to be pluggable can consume.
86 If you are implementing this sort of extension, you don't need to do
88 anything special. You simply create a role and document that it should
89 be used via the normal "with" sugar:
90 package MyApp::User;
92 use Moose;
94 with 'My::Role';
96 Don't use "MooseX" in the name for such packages.
98 New Types
100 Another common Moose extension is a new type for the Moose type system.
101 In this case, you simply create a type in your module. When people load
102 your module, the type is created, and they can refer to it by name
103 after that. The MooseX::Types::URI and MooseX::Types::DateTime
104 distributions are two good examples of how this works. These both build
105 on top of the MooseX::Types extension.
106
108 It is important to understand that roles and traits are the same thing.
109 A trait is simply a role applied to a instance. The only thing that may
110 distinguish the two is that a trait can be packaged in a way that lets
111 Moose resolve a short name to a class name. In other words, with a
112 trait, the caller can refer to it by a short name like "Big", and Moose
113 will resolve it to a class like
114 "MooseX::Embiggen::Meta::Attribute::Role::Big".
115 See Moose::Cookbook::Meta::Labeled_AttributeTrait and
117 Moose::Cookbook::Meta::Table_MetaclassTrait for examples of traits in
118 action. In particular, both of these recipes demonstrate the trait
119 resolution mechanism.
120 Implementing an extension as a (set of) metaclass or base object
122 role(s) will make your extension more cooperative. It is hard for an
123 end-user to effectively combine together multiple metaclass subclasses,
124 but it is very easy to combine roles.
125
127 There are a number of ways in which an extension can be applied. In
128 some cases you can provide multiple ways of consuming your extension.
129 Extensions as Metaclass Traits
131 If your extension is available as a trait, you can ask end users to
132 simply specify it in a list of traits. Currently, this only works for
133 (class) metaclass and attribute metaclass traits:
134 use Moose -traits => [ 'Big', 'Blue' ];
136 has 'animal' => (
138 traits => [ 'Big', 'Blue' ],
139 ...
140 );
141 If your extension applies to any other metaclass, or the object base
143 class, you cannot use the trait mechanism.
144 The benefit of the trait mechanism is that is very easy to see where a
146 trait is applied in the code, and consumers have fine-grained control
147 over what the trait applies to. This is especially true for attribute
148 traits, where you can apply the trait to just one attribute in a class.
149 Extensions as Metaclass (and Base Object) Roles
151 Implementing your extensions as metaclass roles makes your extensions
152 easy to apply, and cooperative with other role-based extensions for
153 metaclasses.
154 Just as with a subclass, you will probably want to package your
156 extensions for consumption with a single module that uses
157 Moose::Exporter. However, in this case, you will use
158 Moose::Util::MetaRole to apply all of your roles. The advantage of
159 using this module is that it preserves any subclassing or roles already
160 applied to the user's metaclasses. This means that your extension is
161 cooperative by default, and consumers of your extension can easily use
162 it with other role-based extensions. Most uses of Moose::Util::MetaRole
163 can be handled by Moose::Exporter directly; see the Moose::Exporter
164 docs.
165 package MooseX::Embiggen;
167 use Moose::Exporter;
169 use MooseX::Embiggen::Role::Meta::Class;
171 use MooseX::Embiggen::Role::Meta::Attribute;
172 use MooseX::Embiggen::Role::Meta::Method::Constructor;
173 use MooseX::Embiggen::Role::Object;
174 Moose::Exporter->setup_import_methods(
176 class_metaroles => {
177 class => ['MooseX::Embiggen::Role::Meta::Class'],
178 attribute => ['MooseX::Embiggen::Role::Meta::Attribute'],
179 constructor =>
180 ['MooseX::Embiggen::Role::Meta::Method::Constructor'],
181 },
182 base_class_roles => ['MooseX::Embiggen::Role::Object'],
183 );
184 As you can see from this example, you can use Moose::Util::MetaRole to
186 apply roles to any metaclass, as well as the base object class. If some
187 other extension has already applied its own roles, they will be
188 preserved when your extension applies its roles, and vice versa.
189 Providing Sugar
191 With Moose::Exporter, you can also export your own sugar functions:
192 package MooseX::Embiggen;
194 use Moose::Exporter;
196 Moose::Exporter->setup_import_methods(
198 with_meta => ['embiggen'],
199 class_metaroles => {
200 class => ['MooseX::Embiggen::Role::Meta::Class'],
201 },
202 );
203 sub embiggen {
205 my $meta = shift;
206 $meta->embiggen(@_);
207 }
208 And then the consumer of your extension can use your "embiggen" sub:
210 package Consumer;
212 use Moose;
214 use MooseX::Embiggen;
215 extends 'Thing';
217 embiggen ...;
219 This can be combined with metaclass and base class roles quite easily.
221 More advanced extensions
223 Providing your extension simply as a set of traits that gets applied to
224 the appropriate metaobjects is easy, but sometimes not sufficient. For
225 instance, sometimes you need to supply not just a base object role, but
226 an actual base object class (due to needing to interact with existing
227 systems that only provide a base class). To write extensions like this,
228 you will need to provide a custom "init_meta" method in your exporter.
229 For instance:
230 package MooseX::Embiggen;
232 use Moose::Exporter;
234 my ($import, $unimport, $init_meta) = Moose::Exporter->build_import_methods(
236 install => ['import', 'unimport'],
237 with_meta => ['embiggen'],
238 class_metaroles => {
239 class => ['MooseX::Embiggen::Role::Meta::Class'],
240 },
241 );
242 sub embiggen {
244 my $meta = shift;
245 $meta->embiggen(@_);
246 }
247 sub init_meta {
249 my $package = shift;
250 my %options = @_;
251 if (my $meta = Class::MOP::class_of($options{for_class})) {
252 if ($meta->isa('Class::MOP::Class')) {
253 my @supers = $meta->superclasses;
254 $meta->superclasses('MooseX::Embiggen::Base::Class')
255 if @supers == 1 && $supers[0] eq 'Moose::Object';
256 }
257 }
258 $package->$init_meta(%options);
259 }
260 In the previous examples, "init_meta" was generated for you, but here
262 you must override it in order to add additional functionality. Some
263 differences to note:
264 "build_import_methods" instead of "setup_import_methods"
266 "build_import_methods" simply returns the "import", "unimport", and
267 "init_meta" methods, rather than installing them under the
268 appropriate names. This way, you can write your own methods which
269 wrap the functionality provided by Moose::Exporter. The
270 "build_import_methods" sub also takes an additional "install"
271 parameter, which tells it to just go ahead and install these
272 methods (since we don't need to modify them).
273 "sub init_meta"
275 Next, we must write our "init_meta" wrapper. The important things
276 to remember are that it is called as a method, and that %options
277 needs to be passed through to the existing implementation. We call
278 the base implementation by using the $init_meta subroutine
279 reference that was returned by "build_import_methods" earlier.
280 Additional implementation
282 This extension sets a different default base object class. To do
283 so, it first checks to see if it's being applied to a class, and
284 then checks to see if Moose::Object is that class's only
285 superclass, and if so, replaces that with the superclass that this
286 extension requires.
287 Note that two extensions that do this same thing will not work
289 together properly (the second extension to be loaded won't see
290 Moose::Object as the base object, since it has already been
291 overridden). This is why using a base object role is recommended
292 for the general case.
293 This "init_meta" also works defensively, by only applying its
295 functionality if a metaclass already exists. This makes sure it
296 doesn't break with legacy extensions which override the metaclass
297 directly (and so must be the first extension to initialize the
298 metaclass). This is likely not necessary, since almost no
299 extensions work this way anymore, but just provides an additional
300 level of protection. The common case of "use Moose; use
301 MooseX::Embiggen;" is not affected regardless.
302 This is just one example of what can be done with a custom "init_meta"
304 method. It can also be used for preventing an extension from being
305 applied to a role, doing other kinds of validation on the class being
306 applied to, or pretty much anything that would otherwise be done in an
307 "import" method.
308
310 Before the existence of Moose::Exporter and Moose::Util::MetaRole,
311 there were a number of other ways to extend Moose. In general, these
312 methods were less cooperative, and only worked well with a single
313 extension.
314 These methods include metaclass.pm, Moose::Policy (which uses
316 metaclass.pm under the hood), and various hacks to do what
317 Moose::Exporter does. Please do not use these for your own extensions.
318 Note that if you write a cooperative extension, it should cooperate
320 with older extensions, though older extensions generally do not
321 cooperate with each other.
322
324 If you can write your extension as one or more metaclass and base
325 object roles, please consider doing so. Make sure to read the docs for
326 Moose::Exporter and Moose::Util::MetaRole as well.
327
329 · Stevan Little <stevan.little@iinteractive.com>
330 · Dave Rolsky <autarch@urth.org>
332 · Jesse Luehrs <doy@tozt.net>
334 · Shawn M Moore <code@sartak.org>
336 · יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
338 · Karen Etheridge <ether@cpan.org>
340 · Florian Ragwitz <rafl@debian.org>
342 · Hans Dieter Pearcey <hdp@weftsoar.net>
344 · Chris Prather <chris@prather.org>
346 · Matt S Trout <mst@shadowcat.co.uk>
348
350 This software is copyright (c) 2006 by Infinity Interactive, Inc.
351 This is free software; you can redistribute it and/or modify it under
353 the same terms as the Perl 5 programming language system itself.
354perl v5.30.1 Moos2e0:2:0C-o0o1k-b3o0ok::Extending::ExtensionOverview(3)