local-lib5/man/man3/Moose::Cookbook::Extending::Recipe1.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Moose::Cookbook::Extending::Recipe1 3"
 132 .TH Moose::Cookbook::Extending::Recipe1 3 "2009-09-12" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Moose::Cookbook::Extending::Recipe1 \- Moose extension overview
 135 .SH "DESCRIPTION"
 136 .IX Header "DESCRIPTION"
 137 Moose provides several ways in which extensions can hook into Moose
 138 and change its behavior. Moose also has a lot of behavior that can be
 139 changed. This recipe will provide an overview of each extension method
 140 and give you some recommendations on what tools to use.
 141 .PP
 142 If you haven't yet read the recipes on metaclasses, go read those
 143 first. You can't write Moose extensions without understanding the
 144 metaclasses, and those recipes also demonstrate some basic extension
 145 mechanisms, such as metaclass subclasses and traits.
 146 .Sh "Playing Nice With Others"
 147 .IX Subsection "Playing Nice With Others"
 148 One of the goals of this overview is to help you build extensions that
 149 cooperate well with other extensions. This is especially important if
 150 you plan to release your extension to \s-1CPAN\s0.
 151 .PP
 152 Moose comes with several modules that exist to help your write
 153 cooperative extensions. These are Moose::Exporter and
 154 Moose::Util::MetaRole. By using these two modules, you will ensure
 155 that your extension works with both the Moose core features and any
 156 other \s-1CPAN\s0 extension using those modules.
 157 .SH "PARTS OF Moose YOU CAN EXTEND"
 158 .IX Header "PARTS OF Moose YOU CAN EXTEND"
 159 The types of things you might want to do in Moose extensions fall into
 160 a few broad categories.
 161 .Sh "Metaclass Extensions"
 162 .IX Subsection "Metaclass Extensions"
 163 One way of extending Moose is by extending one or more Moose
 164 metaclasses. For example, in Moose::Cookbook::Meta::Recipe4 we saw
 165 a metaclass subclass that added a \f(CW\*(C`table\*(C'\fR attribute to the
 166 metaclass. If you were writing an \s-1ORM\s0, this would be a logical
 167 extension.
 168 .PP
 169 Many of the Moose extensions on \s-1CPAN\s0 work by providing an attribute
 170 metaclass extension. For example, the MooseX::AttributeHelpers
 171 distribution provides a new attribute metaclass that lets you delegate
 172 behavior to a non-object attribute (a hashref or simple number).
 173 .PP
 174 A metaclass extension can be packaged as a subclass or a
 175 role/trait. If you can, we recommend using traits instead of
 176 subclasses, since it's much easier to combine disparate traits than it
 177 is to combine a bunch of subclasses.
 178 .PP
 179 When your extensions are implemented as roles, you can apply them with
 180 the Moose::Util::MetaRole module.
 181 .Sh "Providing Sugar Functions"
 182 .IX Subsection "Providing Sugar Functions"
 183 As part of a metaclass extension, you may also want to provide some
 184 sugar functions, just like Moose.pm does. Moose provides a
 185 helper module called Moose::Exporter that makes this much
 186 simpler. We will be use Moose::Exporter in several of the extension
 187 recipes.
 188 .Sh "Object Class Extensions"
 189 .IX Subsection "Object Class Extensions"
 190 Another common Moose extension technique is to change the default
 191 object class's behavior. For example, the MooseX::Singleton
 192 extension changes the behavior of your objects so that they are
 193 singletons. The MooseX::StrictConstructor extension makes the
 194 constructor reject arguments which don't match its attributes.
 195 .PP
 196 Object class extensions often include metaclass extensions as well. In
 197 particular, if you want your object extension to work when a class is
 198 made immutable, you may need to extend some or all of the
 199 Moose::Meta::Instance, Moose::Meta::Method::Constructor, and
 200 Moose::Meta::Method::Destructor objects.
 201 .PP
 202 The Moose::Util::MetaRole module lets you apply roles to the base
 203 object class, as well as the meta classes just mentioned.
 204 .Sh "Providing a Role"
 205 .IX Subsection "Providing a Role"
 206 Some extensions come in the form of a role for you to consume. The
 207 MooseX::Object::Pluggable extension is a great example of this. In
 208 fact, despite the \f(CW\*(C`MooseX\*(C'\fR name, it does not actually change anything
 209 about Moose's behavior. Instead, it is just a role that an object
 210 which wants to be pluggable can consume.
 211 .PP
 212 If you are implementing this sort of extension, you don't need to do
 213 anything special. You simply create a role and document that it should
 214 be used via the normal \f(CW\*(C`with\*(C'\fR sugar:
 215 .PP
 216 .Vb 1
 217 \&   package MyApp::User;
 218 .Ve
 219 .PP
 220 .Vb 1
 221 \&   use Moose;
 222 .Ve
 223 .PP
 224 .Vb 1
 225 \&   with 'MooseX::My::Role';
 226 .Ve
 227 .Sh "New Types"
 228 .IX Subsection "New Types"
 229 Another common Moose extension is a new type for the Moose type
 230 system. In this case, you simply create a type in your module. When
 231 people load your module, the type is created, and they can refer to it
 232 by name after that. The MooseX::Types::URI and
 233 MooseX::Types::DateTime distributions are two good examples of how
 234 this works. These both build on top of the MooseX::Types extension.
 235 .SH "ROLES VS TRAITS VS SUBCLASSES"
 236 .IX Header "ROLES VS TRAITS VS SUBCLASSES"
 237 It is important to understand that \fBroles and traits are the same thing\fR. A
 238 trait is simply a role applied to a instance. The only thing that may
 239 distinguish the two is that a trait can be packaged in a way that lets Moose
 240 resolve a short name to a class name. In other words, with a trait, the caller
 241 can refer to it by a short name like \*(L"Big\*(R", and Moose will resolve it to a
 242 class like \f(CW\*(C`MooseX::Embiggen::Meta::Attribute::Role::Big\*(C'\fR.
 243 .PP
 244 See Moose::Cookbook::Meta::Recipe3 and
 245 Moose::Cookbook::Meta::Recipe5 for examples of traits in action. In
 246 particular, both of these recipes demonstrate the trait resolution
 247 mechanism.
 248 .PP
 249 Implementing an extension as a (set of) metaclass or base object
 250 role(s) will make your extension more cooperative. It is hard for an
 251 end-user to effectively combine together multiple metaclass
 252 subclasses, but it is very easy to combine roles.
 253 .SH "USING YOUR EXTENSION"
 254 .IX Header "USING YOUR EXTENSION"
 255 There are a number of ways in which an extension can be applied. In
 256 some cases you can provide multiple ways of consuming your extension.
 257 .Sh "Extensions as Metaclass Traits"
 258 .IX Subsection "Extensions as Metaclass Traits"
 259 If your extension is available as a trait, you can ask end users to
 260 simply specify it in a list of traits. Currently, this only works for
 261 (class) metaclass and attribute metaclass traits:
 262 .PP
 263 .Vb 1
 264 \&  use Moose \-traits => [ 'Big', 'Blue' ];
 265 .Ve
 266 .PP
 267 .Vb 4
 268 \&  has 'animal' => (
 269 \&      traits => [ 'Big', 'Blue' ],
 270 \&      ...
 271 \&  );
 272 .Ve
 273 .PP
 274 If your extension applies to any other metaclass, or the object base
 275 class, you cannot use the trait mechanism.
 276 .PP
 277 The benefit of the trait mechanism is that is very easy to see where a
 278 trait is applied in the code, and consumers have fine-grained control
 279 over what the trait applies to. This is especially true for attribute
 280 traits, where you can apply the trait to just one attribute in a
 281 class.
 282 .Sh "Extensions as Metaclass (and Base Object) Subclasses"
 283 .IX Subsection "Extensions as Metaclass (and Base Object) Subclasses"
 284 Moose does not provide any simple APIs for consumers to use a subclass
 285 extension, except for attribute metaclasses. The attribute declaration
 286 options include a \f(CW\*(C`metaclass\*(C'\fR option a consumer of your extension can
 287 use to specify your subclass.
 288 .PP
 289 This is one reason why implementing an extension as a subclass can be
 290 a poor choice. However, you can force the use of certain subclasses at
 291 import time by calling \f(CW\*(C`Moose\->init_meta\*(C'\fR for the caller, and
 292 providing an alternate metaclass or base object class.
 293 .PP
 294 If you do want to do this, you should look at using Moose::Exporter
 295 to re-export the Moose.pm sugar function. With
 296 Moose::Exporter, if your exporting class has an \f(CW\*(C`init_meta\*(C'\fR
 297 method, Moose::Exporter makes sure that this \f(CW\*(C`init_meta\*(C'\fR method
 298 gets called when your class is imported.
 299 .PP
 300 Then in your \f(CW\*(C`init_meta\*(C'\fR you can arrange for the caller to use your
 301 subclasses:
 302 .PP
 303 .Vb 1
 304 \&  package MooseX::Embiggen;
 305 .Ve
 306 .PP
 307 .Vb 2
 308 \&  use Moose ();
 309 \&  use Moose::Exporter;
 310 .Ve
 311 .PP
 312 .Vb 2
 313 \&  use MooseX::Embiggen::Meta::Class;
 314 \&  use MooseX::Embiggen::Object;
 315 .Ve
 316 .PP
 317 .Vb 1
 318 \&  Moose::Exporter\->setup_import_methods( also => 'Moose' );
 319 .Ve
 320 .PP
 321 .Vb 3
 322 \&  sub init_meta {
 323 \&      shift;    # just your package name
 324 \&      my %options = @_;
 325 .Ve
 326 .PP
 327 .Vb 6
 328 \&      return Moose\->init_meta(
 329 \&          for_class  => $options{for_class},
 330 \&          metaclass  => 'MooseX::Embiggen::Meta::Class',
 331 \&          base_class => 'MooseX::Embiggen::Object',
 332 \&      );
 333 \&  }
 334 .Ve
 335 .PP
 336 \&\s-1NOTE:\s0 Make sure that your \f(CW\*(C`init_meta\*(C'\fR returns the metaclass object, just as
 337 \&\f(CW\*(C`Moose\->init_meta\*(C'\fR does.
 338 .Sh "Extensions as Metaclass (and Base Object) Roles"
 339 .IX Subsection "Extensions as Metaclass (and Base Object) Roles"
 340 Implementing your extensions as metaclass roles makes your extensions
 341 easy to apply, and cooperative with other role-based extensions for
 342 metaclasses.
 343 .PP
 344 Just as with a subclass, you will probably want to package your
 345 extensions for consumption with a single module that uses
 346 Moose::Exporter. However, in this case, you will use
 347 Moose::Util::MetaRole to apply all of your roles. The advantage of
 348 using this module is that \fIit preserves any subclassing or roles
 349 already applied to the user's metaclasses\fR. This means that your
 350 extension is cooperative \fIby default\fR, and consumers of your
 351 extension can easily use it with other role-based extensions. Most
 352 uses of Moose::Util::MetaRole can be handled by Moose::Exporter
 353 directly; see the Moose::Exporter docs.
 354 .PP
 355 .Vb 1
 356 \&  package MooseX::Embiggen;
 357 .Ve
 358 .PP
 359 .Vb 2
 360 \&  use Moose ();
 361 \&  use Moose::Exporter;
 362 .Ve
 363 .PP
 364 .Vb 4
 365 \&  use MooseX::Embiggen::Role::Meta::Class;
 366 \&  use MooseX::Embiggen::Role::Meta::Attribute;
 367 \&  use MooseX::Embiggen::Role::Meta::Method::Constructor;
 368 \&  use MooseX::Embiggen::Role::Object;
 369 .Ve
 370 .PP
 371 .Vb 9
 372 \&  my ( $import, $unimport, $init_meta ) = Moose::Exporter\->build_import_methods(
 373 \&      also => ['Moose'] metaclass_roles =>
 374 \&          ['MooseX::Embiggen::Role::Meta::Class'],
 375 \&      attribute_metaclass_roles => ['MooseX::Embiggen::Role::Meta::Attribute'],
 376 \&      constructor_class_roles =>
 377 \&          ['MooseX::Embiggen::Role::Meta::Method::Constructor'],
 378 \&      base_class_roles => ['MooseX::Embiggen::Role::Object'],
 379 \&      install          => [qw(import unimport)],
 380 \&  );
 381 .Ve
 382 .PP
 383 .Vb 6
 384 \&  sub init_meta {
 385 \&      my $package = shift;
 386 \&      my %options = @_;
 387 \&      Moose\->init_meta(%options);
 388 \&      return $package\->$init_meta(%options);
 389 \&  }
 390 .Ve
 391 .PP
 392 As you can see from this example, you can use Moose::Util::MetaRole
 393 to apply roles to any metaclass, as well as the base object class. If
 394 some other extension has already applied its own roles, they will be
 395 preserved when your extension applies its roles, and vice versa.
 396 .Sh "Providing Sugar"
 397 .IX Subsection "Providing Sugar"
 398 With Moose::Exporter, you can also export your own sugar functions,
 399 as well as those from other modules:
 400 .PP
 401 .Vb 1
 402 \&  package MooseX::Embiggen;
 403 .Ve
 404 .PP
 405 .Vb 2
 406 \&  use Moose ();
 407 \&  use Moose::Exporter;
 408 .Ve
 409 .PP
 410 .Vb 4
 411 \&  Moose::Exporter\->setup_import_methods(
 412 \&      with_meta => ['embiggen'],
 413 \&      also      => 'Moose',
 414 \&  );
 415 .Ve
 416 .PP
 417 .Vb 4
 418 \&  sub embiggen {
 419 \&      my $meta = shift;
 420 \&      $meta\->embiggen(@_);
 421 \&  }
 422 .Ve
 423 .PP
 424 And then the consumer of your extension can use your \f(CW\*(C`embiggen\*(C'\fR sub:
 425 .PP
 426 .Vb 1
 427 \&  package Consumer;
 428 .Ve
 429 .PP
 430 .Vb 1
 431 \&  use MooseX::Embiggen;
 432 .Ve
 433 .PP
 434 .Vb 1
 435 \&  extends 'Thing';
 436 .Ve
 437 .PP
 438 .Vb 1
 439 \&  embiggen ...;
 440 .Ve
 441 .PP
 442 This can be combined with metaclass and base class roles quite easily.
 443 .SH "LEGACY EXTENSION MECHANISMS"
 444 .IX Header "LEGACY EXTENSION MECHANISMS"
 445 Before the existence of Moose::Exporter and
 446 Moose::Util::MetaRole, there were a number of other ways to extend
 447 Moose. In general, these methods were less cooperative, and only
 448 worked well with a single extension.
 449 .PP
 450 These methods include metaclass.pm, Moose::Policy
 451 (which uses metaclass.pm under the hood), and various
 452 hacks to do what Moose::Exporter does. Please do not use these for
 453 your own extensions.
 454 .PP
 455 Note that if you write a cooperative extension, it should cooperate
 456 with older extensions, though older extensions generally do not
 457 cooperate with each other.
 458 .SH "CONCLUSION"
 459 .IX Header "CONCLUSION"
 460 If you can write your extension as one or more metaclass and base
 461 object roles, please consider doing so. Make sure to read the docs for
 462 Moose::Exporter and Moose::Util::MetaRole as well.
 463 .SH "AUTHOR"
 464 .IX Header "AUTHOR"
 465 Dave Rolsky <autarch@urth.org>
 466 .SH "COPYRIGHT AND LICENSE"
 467 .IX Header "COPYRIGHT AND LICENSE"
 468 Copyright 2009 by Infinity Interactive, Inc.
 469 .PP
 470 <http://www.iinteractive.com>
 471 .PP
 472 This library is free software; you can redistribute it and/or modify
 473 it under the same terms as Perl itself.