lib/Moose/Cookbook/Extending/Recipe1.pod

   1
   2 =pod
   3
   4 =head1 NAME
   5
   6 Moose::Cookbook::Extending::Recipe1 - Moose extension overview
   7
   8 =head1 DESCRIPTION
   9
  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.
  14
  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.
  19
  20 =head2 Playing Nice With Others
  21
  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.
  25
  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.
  31
  32 =head1 PARTS OF Moose YOU CAN EXTEND
  33
  34 The types of things you might want to do in Moose extensions fall into
  35 a few broad categories.
  36
  37 =head2 Metaclass Extensions
  38
  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
  43 extension.
  44
  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).
  49
  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.
  54
  55 When your extensions are implemented as roles, you can apply them with
  56 the L<Moose::Util::MetaRole> module.
  57
  58 =head2 Providing Sugar Functions
  59
  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
  64 recipes.
  65
  66 =head2 Object Class Extensions
  67
  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.
  73
  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.
  79
  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.
  82
  83 =head2 Providing a Role
  84
  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.
  90
  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:
  94
  95    package MyApp::User;
  96
  97    use Moose;
  98
  99    with 'MooseX::My::Role';
 100
 101 =head2 New Types
 102
 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.
 109
 110 =head1 ROLES VS TRAITS VS SUBCLASSES
 111
 112 It is important to understand that B<roles and traits are the same thing>. A
 113 trait is simply a role applied to a instance. The only thing that may
 114 distinguish the two is that a trait can be packaged in a way that lets Moose
 115 resolve a short name to a class name. In other words, with a trait, the caller
 116 can refer to it by a short name like "Big", and Moose will resolve it to a
 117 class like C<MooseX::Embiggen::Meta::Attribute::Role::Big>.
 118
 119 See L<Moose::Cookbook::Meta::Recipe3> and
 120 L<Moose::Cookbook::Meta::Recipe5> for examples of traits in action. In
 121 particular, both of these recipes demonstrate the trait resolution
 122 mechanism.
 123
 124 Implementing an extension as a (set of) metaclass or base object
 125 role(s) will make your extension more cooperative. It is hard for an
 126 end-user to effectively combine together multiple metaclass
 127 subclasses, but it is very easy to combine roles.
 128
 129 =head1 USING YOUR EXTENSION
 130
 131 There are a number of ways in which an extension can be applied. In
 132 some cases you can provide multiple ways of consuming your extension.
 133
 134 =head2 Extensions as Metaclass Traits
 135
 136 If your extension is available as a trait, you can ask end users to
 137 simply specify it in a list of traits. Currently, this only works for
 138 (class) metaclass and attribute metaclass traits:
 139
 140   use Moose -traits => [ 'Big', 'Blue' ];
 141
 142   has 'animal' => (
 143       traits => [ 'Big', 'Blue' ],
 144       ...
 145   );
 146
 147 If your extension applies to any other metaclass, or the object base
 148 class, you cannot use the trait mechanism.
 149
 150 The benefit of the trait mechanism is that is very easy to see where a
 151 trait is applied in the code, and consumers have fine-grained control
 152 over what the trait applies to. This is especially true for attribute
 153 traits, where you can apply the trait to just one attribute in a
 154 class.
 155
 156 =head2 Extensions as Metaclass (and Base Object) Subclasses
 157
 158 Moose does not provide any simple APIs for consumers to use a subclass
 159 extension, except for attribute metaclasses. The attribute declaration
 160 options include a C<metaclass> option a consumer of your extension can
 161 use to specify your subclass.
 162
 163 This is one reason why implementing an extension as a subclass can be
 164 a poor choice. However, you can force the use of certain subclasses at
 165 import time by calling C<< Moose->init_meta >> for the caller, and
 166 providing an alternate metaclass or base object class.
 167
 168 If you do want to do this, you should look at using L<Moose::Exporter>
 169 to re-export the L<Moose.pm|Moose> sugar function. With
 170 L<Moose::Exporter>, if your exporting class has an C<init_meta>
 171 method, L<Moose::Exporter> makes sure that this C<init_meta> method
 172 gets called when your class is imported.
 173
 174 Then in your C<init_meta> you can arrange for the caller to use your
 175 subclasses:
 176
 177   package MooseX::Embiggen;
 178
 179   use Moose ();
 180   use Moose::Exporter;
 181
 182   use MooseX::Embiggen::Meta::Class;
 183   use MooseX::Embiggen::Object;
 184
 185   Moose::Exporter->setup_import_methods( also => 'Moose' );
 186
 187   sub init_meta {
 188       shift;    # just your package name
 189       my %options = @_;
 190
 191       return Moose->init_meta(
 192           for_class  => $options{for_class},
 193           metaclass  => 'MooseX::Embiggen::Meta::Class',
 194           base_class => 'MooseX::Embiggen::Object',
 195       );
 196   }
 197
 198 NOTE: Make sure that your C<init_meta> returns the metaclass object, just as
 199 C<< Moose->init_meta >> does.
 200
 201 =head2 Extensions as Metaclass (and Base Object) Roles
 202
 203 Implementing your extensions as metaclass roles makes your extensions
 204 easy to apply, and cooperative with other role-based extensions for
 205 metaclasses.
 206
 207 Just as with a subclass, you will probably want to package your
 208 extensions for consumption with a single module that uses
 209 L<Moose::Exporter>. However, in this case, you will use
 210 L<Moose::Util::MetaRole> to apply all of your roles. The advantage of
 211 using this module is that I<it preserves any subclassing or roles
 212 already applied to the user's metaclasses>. This means that your
 213 extension is cooperative I<by default>, and consumers of your
 214 extension can easily use it with other role-based extensions. Most
 215 uses of L<Moose::Util::MetaRole> can be handled by L<Moose::Exporter>
 216 directly; see the L<Moose::Exporter> docs.
 217
 218   package MooseX::Embiggen;
 219
 220   use Moose ();
 221   use Moose::Exporter;
 222
 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;
 227
 228   my ( $import, $unimport, $init_meta ) = Moose::Exporter->build_import_methods(
 229       also => ['Moose'] metaclass_roles =>
 230           ['MooseX::Embiggen::Role::Meta::Class'],
 231       attribute_metaclass_roles => ['MooseX::Embiggen::Role::Meta::Attribute'],
 232       constructor_class_roles =>
 233           ['MooseX::Embiggen::Role::Meta::Method::Constructor'],
 234       base_class_roles => ['MooseX::Embiggen::Role::Object'],
 235       install          => [qw(import unimport)],
 236   );
 237
 238   sub init_meta {
 239       my $package = shift;
 240       my %options = @_;
 241       Moose->init_meta(%options);
 242       return $package->$init_meta(%options);
 243   }
 244
 245 As you can see from this example, you can use L<Moose::Util::MetaRole>
 246 to apply roles to any metaclass, as well as the base object class. If
 247 some other extension has already applied its own roles, they will be
 248 preserved when your extension applies its roles, and vice versa.
 249
 250 =head2 Providing Sugar
 251
 252 With L<Moose::Exporter>, you can also export your own sugar functions,
 253 as well as those from other modules:
 254
 255   package MooseX::Embiggen;
 256
 257   use Moose ();
 258   use Moose::Exporter;
 259
 260   Moose::Exporter->setup_import_methods(
 261       with_caller => ['embiggen'],
 262       also        => 'Moose',
 263   );
 264
 265   sub embiggen {
 266       my $caller = shift;
 267       $caller->meta()->embiggen(@_);
 268   }
 269
 270 And then the consumer of your extension can use your C<embiggen> sub:
 271
 272   package Consumer;
 273
 274   use MooseX::Embiggen;
 275
 276   extends 'Thing';
 277
 278   embiggen ...;
 279
 280 This can be combined with metaclass and base class roles quite easily.
 281
 282 =head1 LEGACY EXTENSION MECHANISMS
 283
 284 Before the existence of L<Moose::Exporter> and
 285 L<Moose::Util::MetaRole>, there were a number of other ways to extend
 286 Moose. In general, these methods were less cooperative, and only
 287 worked well with a single extension.
 288
 289 These methods include L<metaclass.pm|metaclass>, L<Moose::Policy>
 290 (which uses L<metaclass.pm|metaclass> under the hood), and various
 291 hacks to do what L<Moose::Exporter> does. Please do not use these for
 292 your own extensions.
 293
 294 Note that if you write a cooperative extension, it should cooperate
 295 with older extensions, though older extensions generally do not
 296 cooperate with each other.
 297
 298 =head1 CONCLUSION
 299
 300 If you can write your extension as one or more metaclass and base
 301 object roles, please consider doing so. Make sure to read the docs for
 302 L<Moose::Exporter> and L<Moose::Util::MetaRole> as well.
 303
 304 =head1 AUTHOR
 305
 306 Dave Rolsky E<lt>autarch@urth.orgE<gt>
 307
 308 =head1 COPYRIGHT AND LICENSE
 309
 310 Copyright 2009 by Infinity Interactive, Inc.
 311
 312 L<http://www.iinteractive.com>
 313
 314 This library is free software; you can redistribute it and/or modify
 315 it under the same terms as Perl itself.
 316
 317 =cut