local-lib5/man/man3/Moose::Cookbook::Roles::Recipe2.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::Roles::Recipe2 3"
 132 .TH Moose::Cookbook::Roles::Recipe2 3 "2009-09-12" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Moose::Cookbook::Roles::Recipe2 \- Advanced Role Composition \- method exclusion and aliasing
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 2
 138 \&  package Restartable;
 139 \&  use Moose::Role;
 140 .Ve
 141 .PP
 142 .Vb 5
 143 \&  has 'is_paused' => (
 144 \&      is      => 'rw',
 145 \&      isa     => 'Bool',
 146 \&      default => 0,
 147 \&  );
 148 .Ve
 149 .PP
 150 .Vb 1
 151 \&  requires 'save_state', 'load_state';
 152 .Ve
 153 .PP
 154 .Vb 1
 155 \&  sub stop { 1 }
 156 .Ve
 157 .PP
 158 .Vb 1
 159 \&  sub start { 1 }
 160 .Ve
 161 .PP
 162 .Vb 2
 163 \&  package Restartable::ButUnreliable;
 164 \&  use Moose::Role;
 165 .Ve
 166 .PP
 167 .Vb 7
 168 \&  with 'Restartable' => {
 169 \&      \-alias => {
 170 \&          stop  => '_stop',
 171 \&          start => '_start'
 172 \&      },
 173 \&      \-excludes => [ 'stop', 'start' ],
 174 \&  };
 175 .Ve
 176 .PP
 177 .Vb 2
 178 \&  sub stop {
 179 \&      my $self = shift;
 180 .Ve
 181 .PP
 182 .Vb 1
 183 \&      $self\->explode() if rand(1) > .5;
 184 .Ve
 185 .PP
 186 .Vb 2
 187 \&      $self\->_stop();
 188 \&  }
 189 .Ve
 190 .PP
 191 .Vb 2
 192 \&  sub start {
 193 \&      my $self = shift;
 194 .Ve
 195 .PP
 196 .Vb 1
 197 \&      $self\->explode() if rand(1) > .5;
 198 .Ve
 199 .PP
 200 .Vb 2
 201 \&      $self\->_start();
 202 \&  }
 203 .Ve
 204 .PP
 205 .Vb 2
 206 \&  package Restartable::ButBroken;
 207 \&  use Moose::Role;
 208 .Ve
 209 .PP
 210 .Vb 1
 211 \&  with 'Restartable' => { \-excludes => [ 'stop', 'start' ] };
 212 .Ve
 213 .PP
 214 .Vb 2
 215 \&  sub stop {
 216 \&      my $self = shift;
 217 .Ve
 218 .PP
 219 .Vb 2
 220 \&      $self\->explode();
 221 \&  }
 222 .Ve
 223 .PP
 224 .Vb 2
 225 \&  sub start {
 226 \&      my $self = shift;
 227 .Ve
 228 .PP
 229 .Vb 2
 230 \&      $self\->explode();
 231 \&  }
 232 .Ve
 233 .SH "DESCRIPTION"
 234 .IX Header "DESCRIPTION"
 235 In this example, we demonstrate how to exercise fine-grained control
 236 over what methods we consume from a role. We have a \f(CW\*(C`Restartable\*(C'\fR
 237 role which provides an \f(CW\*(C`is_paused\*(C'\fR attribute, and two methods,
 238 \&\f(CW\*(C`stop\*(C'\fR and \f(CW\*(C`start\*(C'\fR.
 239 .PP
 240 Then we have two more roles which implement the same interface, each
 241 putting their own spin on the \f(CW\*(C`stop\*(C'\fR and \f(CW\*(C`start\*(C'\fR methods.
 242 .PP
 243 In the \f(CW\*(C`Restartable::ButUnreliable\*(C'\fR role, we want to provide a new
 244 implementation of \f(CW\*(C`stop\*(C'\fR and \f(CW\*(C`start\*(C'\fR, but still have access to the
 245 original implementation. To do this, we alias the methods from
 246 \&\f(CW\*(C`Restartable\*(C'\fR to private methods, and provide wrappers around the
 247 originals (1).
 248 .PP
 249 Note that aliasing simply \fIadds\fR a name, so we also need to exclude the
 250 methods with their original names.
 251 .PP
 252 .Vb 7
 253 \&  with 'Restartable' => {
 254 \&      \-alias => {
 255 \&          stop  => '_stop',
 256 \&          start => '_start'
 257 \&      },
 258 \&      \-excludes => [ 'stop', 'start' ],
 259 \&  };
 260 .Ve
 261 .PP
 262 In the \f(CW\*(C`Restartable::ButBroken\*(C'\fR role, we want to provide an entirely
 263 new behavior for \f(CW\*(C`stop\*(C'\fR and \f(CW\*(C`start\*(C'\fR. We exclude them entirely when
 264 composing the \f(CW\*(C`Restartable\*(C'\fR role into \f(CW\*(C`Restartable::ButBroken\*(C'\fR.
 265 .PP
 266 It's worth noting that the \f(CW\*(C`\-excludes\*(C'\fR parameter also accepts a single
 267 string as an argument if you just want to exclude one method.
 268 .PP
 269 .Vb 1
 270 \&  with 'Restartable' => { \-excludes => [ 'stop', 'start' ] };
 271 .Ve
 272 .SH "CONCLUSION"
 273 .IX Header "CONCLUSION"
 274 Exclusion and renaming are a power tool that can be handy, especially
 275 when building roles out of other roles. In this example, all of our
 276 roles implement the \f(CW\*(C`Restartable\*(C'\fR role. Each role provides same \s-1API\s0,
 277 but each has a different implementation under the hood.
 278 .PP
 279 You can also use the method aliasing and excluding features when
 280 composing a role into a class.
 281 .SH "FOOTNOTES"
 282 .IX Header "FOOTNOTES"
 283 .IP "(1)" 4
 284 .IX Item "(1)"
 285 The mention of wrapper should tell you that we could do the same thing
 286 using method modifiers, but for the sake of this example, we don't.
 287 .SH "AUTHOR"
 288 .IX Header "AUTHOR"
 289 Dave Rolsky <autarch@urth.org>
 290 .SH "COPYRIGHT AND LICENSE"
 291 .IX Header "COPYRIGHT AND LICENSE"
 292 Copyright 2006\-2009 by Infinity Interactive, Inc.
 293 .PP
 294 <http://www.iinteractive.com>
 295 .PP
 296 This library is free software; you can redistribute it and/or modify
 297 it under the same terms as Perl itself.