local-lib5/man/man3/Moose::Manual::MethodModifiers.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::Manual::MethodModifiers 3"
 132 .TH Moose::Manual::MethodModifiers 3 "2009-04-07" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Moose::Manual::MethodModifiers \- Moose's method modifiers
 135 .SH "WHAT IS A METHOD MODIFIER?"
 136 .IX Header "WHAT IS A METHOD MODIFIER?"
 137 Moose provides a feature called \*(L"method modifiers\*(R". You can also think
 138 of these as \*(L"hooks\*(R" or \*(L"advice\*(R".
 139 .PP
 140 It's probably easiest to understand this feature with a few examples:
 141 .PP
 142 .Vb 1
 143 \&  package Example;
 144 .Ve
 145 .PP
 146 .Vb 1
 147 \&  use Moose;
 148 .Ve
 149 .PP
 150 .Vb 3
 151 \&  sub foo {
 152 \&      print "foo\en";
 153 \&  }
 154 .Ve
 155 .PP
 156 .Vb 2
 157 \&  before 'foo' => sub { print "about to call foo\en"; };
 158 \&  after 'foo'  => sub { print "just called foo\en"; };
 159 .Ve
 160 .PP
 161 .Vb 3
 162 \&  around 'foo' => sub {
 163 \&      my $orig = shift;
 164 \&      my $self = shift;
 165 .Ve
 166 .PP
 167 .Vb 1
 168 \&      print "I'm around foo\en";
 169 .Ve
 170 .PP
 171 .Vb 1
 172 \&      $self\->$orig(@_);
 173 .Ve
 174 .PP
 175 .Vb 2
 176 \&      print "I'm still around foo\en";
 177 \&  };
 178 .Ve
 179 .PP
 180 Now if I call \f(CW\*(C`Example\->new\->foo\*(C'\fR I'll get the following output:
 181 .PP
 182 .Vb 5
 183 \&  about to call foo
 184 \&  I'm around foo
 185 \&  foo
 186 \&  I'm still around foo
 187 \&  just called foo
 188 .Ve
 189 .PP
 190 You probably could have figured that out from the names \*(L"before\*(R",
 191 \&\*(L"after\*(R", and \*(L"around\*(R".
 192 .PP
 193 Also, as you can see, the before modifiers come before around
 194 modifiers, and after modifiers come last.
 195 .PP
 196 When there are multiple modifiers of the same type, the before and
 197 around modifiers run from the last added to the first, and after
 198 modifiers run from first added to last:
 199 .PP
 200 .Vb 9
 201 \&   before 2
 202 \&    before 1
 203 \&     around 2
 204 \&      around 1
 205 \&       primary
 206 \&      around 1
 207 \&     around 2
 208 \&    after 1
 209 \&   after 2
 210 .Ve
 211 .SH "WHY USE THEM?"
 212 .IX Header "WHY USE THEM?"
 213 Method modifiers have many uses. One very common use is in roles. This
 214 lets roles alter the behavior of methods in the classes that use
 215 them. See Moose::Manual::Roles for more information about roles.
 216 .PP
 217 Since modifiers are mostly useful in roles, some of the examples below
 218 are a bit artificial. They're intended to give you an idea of how
 219 modifiers work, but may not be the most natural usage.
 220 .SH "BEFORE, AFTER, AND AROUND"
 221 .IX Header "BEFORE, AFTER, AND AROUND"
 222 Method modifiers can be used to add behavior to a method that Moose
 223 generates for you, such as an attribute accessor:
 224 .PP
 225 .Vb 1
 226 \&  has 'size' => ( is => 'rw' );
 227 .Ve
 228 .PP
 229 .Vb 2
 230 \&  before 'size' => sub {
 231 \&      my $self = shift;
 232 .Ve
 233 .PP
 234 .Vb 4
 235 \&      if (@_) {
 236 \&          Carp::cluck('Someone is setting size');
 237 \&      }
 238 \&  };
 239 .Ve
 240 .PP
 241 Another use for the before modifier would be to do some sort of
 242 prechecking on a method call. For example:
 243 .PP
 244 .Vb 2
 245 \&  before 'size' => sub {
 246 \&      my $self = shift;
 247 .Ve
 248 .PP
 249 .Vb 3
 250 \&      die 'Cannot set size while the person is growing'
 251 \&          if @_ && $self\->is_growing;
 252 \&  };
 253 .Ve
 254 .PP
 255 This lets us implement logical checks that don't make sense as type
 256 constraints. In particular, they're useful for defining logical rules
 257 about an object's state changes.
 258 .PP
 259 Similarly, an after modifier could be used for logging an action that
 260 was taken.
 261 .PP
 262 Note that the return values of both before and after modifiers are
 263 ignored.
 264 .PP
 265 An around modifier is a bit more powerful than either a before or
 266 after modifier. It can modify the arguments being passed to the
 267 original method, and you can even decide to simply not call the
 268 original method at all. You can also modify the return value with an
 269 around modifier.
 270 .PP
 271 An around modifier receives the original method as its first argument,
 272 \&\fIthen\fR the object, and finally any arguments passed to the method.
 273 .PP
 274 .Vb 3
 275 \&  around 'size' => sub {
 276 \&      my $orig = shift;
 277 \&      my $self = shift;
 278 .Ve
 279 .PP
 280 .Vb 2
 281 \&      return $self\->$orig()
 282 \&          unless @_;
 283 .Ve
 284 .PP
 285 .Vb 3
 286 \&      my $size = shift;
 287 \&      $size = $size / 2
 288 \&          if $self\->likes_small_things();
 289 .Ve
 290 .PP
 291 .Vb 2
 292 \&      return $self\->$orig($size);
 293 \&  };
 294 .Ve
 295 .SH "INNER AND AUGMENT"
 296 .IX Header "INNER AND AUGMENT"
 297 Augment and inner are two halves of the same feature. The augment
 298 modifier provides a sort of inverted subclassing. You provide part of
 299 the implementation in a superclass, and then document that subclasses
 300 are expected to provide the rest.
 301 .PP
 302 The superclass calls \f(CW\*(C`inner()\*(C'\fR, which then calls the \f(CW\*(C`augment\*(C'\fR
 303 modifier in the subclass:
 304 .PP
 305 .Vb 1
 306 \&  package Document;
 307 .Ve
 308 .PP
 309 .Vb 1
 310 \&  use Moose;
 311 .Ve
 312 .PP
 313 .Vb 2
 314 \&  sub as_xml {
 315 \&      my $self = shift;
 316 .Ve
 317 .PP
 318 .Vb 3
 319 \&      my $xml = "<document>\en";
 320 \&      $xml .= inner();
 321 \&      $xml .= "</document>\en";
 322 .Ve
 323 .PP
 324 .Vb 2
 325 \&      return $xml;
 326 \&  }
 327 .Ve
 328 .PP
 329 Using \f(CW\*(C`inner()\*(C'\fR in this method makes it possible for one or more
 330 subclasses to then augment this method with their own specific
 331 implementation:
 332 .PP
 333 .Vb 1
 334 \&  package Report;
 335 .Ve
 336 .PP
 337 .Vb 1
 338 \&  use Moose;
 339 .Ve
 340 .PP
 341 .Vb 1
 342 \&  extends 'Document';
 343 .Ve
 344 .PP
 345 .Vb 2
 346 \&  augment 'as_xml' => sub {
 347 \&      my $self = shift;
 348 .Ve
 349 .PP
 350 .Vb 3
 351 \&      my $xml = "<report>\en";
 352 \&      $xml .= inner();
 353 \&      $xml .= "</report>\en";
 354 .Ve
 355 .PP
 356 .Vb 2
 357 \&      return $xml;
 358 \&  };
 359 .Ve
 360 .PP
 361 When we call \f(CW\*(C`as_xml\*(C'\fR on a Report object, we get something like this:
 362 .PP
 363 .Vb 4
 364 \&  <document>
 365 \&  <report>
 366 \&  </report>
 367 \&  </document>
 368 .Ve
 369 .PP
 370 But we also called \f(CW\*(C`inner()\*(C'\fR in \f(CW\*(C`Report\*(C'\fR, so we can continue
 371 subclassing and adding more content inside the document:
 372 .PP
 373 .Vb 1
 374 \&  package Report::IncomeAndExpenses;
 375 .Ve
 376 .PP
 377 .Vb 1
 378 \&  use Moose;
 379 .Ve
 380 .PP
 381 .Vb 1
 382 \&  extends 'Report';
 383 .Ve
 384 .PP
 385 .Vb 2
 386 \&  augment 'as_xml' => sub {
 387 \&      my $self = shift;
 388 .Ve
 389 .PP
 390 .Vb 4
 391 \&      my $xml = '<income>' . $self\->income . '</income>';
 392 \&      $xml .= "\en";
 393 \&      $xml .= '<expenses>' . $self\->expenses . '</expenses>';
 394 \&      $xml .= "\en";
 395 .Ve
 396 .PP
 397 .Vb 1
 398 \&      $xml .= inner() || q{};
 399 .Ve
 400 .PP
 401 .Vb 2
 402 \&      return $xml;
 403 \&  };
 404 .Ve
 405 .PP
 406 Now our report has some content:
 407 .PP
 408 .Vb 6
 409 \&  <document>
 410 \&  <report>
 411 \&  <income>$10</income>
 412 \&  <expenses>$8</expenses>
 413 \&  </report>
 414 \&  </document>
 415 .Ve
 416 .PP
 417 What makes this combination of \f(CW\*(C`augment\*(C'\fR and \f(CW\*(C`inner()\*(C'\fR special is
 418 that it allows us to have methods which are called from parent (least
 419 specific) to child (most specific). This inverts the normal
 420 inheritance pattern.
 421 .PP
 422 Note that in \f(CW\*(C`Report::IncomeAndExpenses\*(C'\fR we call \f(CW\*(C`inner()\*(C'\fR again. If
 423 the object is an instance of \f(CW\*(C`Report::IncomeAndExpenses\*(C'\fR then this
 424 call is a no\-op, and just returns false.
 425 .SH "OVERRIDE AND SUPER"
 426 .IX Header "OVERRIDE AND SUPER"
 427 Finally, Moose provides some simple sugar for Perl's built-in method
 428 overriding scheme. If you want to override a method from a parent
 429 class, you can do this with \f(CW\*(C`override\*(C'\fR:
 430 .PP
 431 .Vb 1
 432 \&  package Employee;
 433 .Ve
 434 .PP
 435 .Vb 1
 436 \&  use Moose;
 437 .Ve
 438 .PP
 439 .Vb 1
 440 \&  extends 'Person';
 441 .Ve
 442 .PP
 443 .Vb 1
 444 \&  has 'job_title' => ( is => 'rw' );
 445 .Ve
 446 .PP
 447 .Vb 2
 448 \&  override 'display_name' => sub {
 449 \&      my $self = shift;
 450 .Ve
 451 .PP
 452 .Vb 2
 453 \&      return super() . q{, } . $self\->title();
 454 \&  };
 455 .Ve
 456 .PP
 457 The call to \f(CW\*(C`super()\*(C'\fR is almost the same as calling \f(CW\*(C`$self\->SUPER::display_name\*(C'\fR. The difference is that the arguments
 458 passed to the superclass's method will always be the same as the ones
 459 passed to the method modifier, and cannot be changed.
 460 .PP
 461 All arguments passed to \f(CW\*(C`super()\*(C'\fR are ignored, as are any changes
 462 made to \f(CW@_\fR before \f(CW\*(C`super()\*(C'\fR is called.
 463 .SH "SEMI-COLONS"
 464 .IX Header "SEMI-COLONS"
 465 Because all of these method modifiers are implemented as Perl
 466 functions, you must always end the modifier declaration with a
 467 semi\-colon:
 468 .PP
 469 .Vb 1
 470 \&  after 'foo' => sub { };
 471 .Ve
 472 .SH "AUTHOR"
 473 .IX Header "AUTHOR"
 474 Dave Rolsky <autarch@urth.org>
 475 .SH "COPYRIGHT AND LICENSE"
 476 .IX Header "COPYRIGHT AND LICENSE"
 477 Copyright 2008\-2009 by Infinity Interactive, Inc.
 478 .PP
 479 <http://www.iinteractive.com>
 480 .PP
 481 This library is free software; you can redistribute it and/or modify
 482 it under the same terms as Perl itself.