local-lib5/man/man3/Moose::Cookbook::Roles::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::Roles::Recipe1 3"
 132 .TH Moose::Cookbook::Roles::Recipe1 3 "2009-09-05" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Moose::Cookbook::Roles::Recipe1 \- The Moose::Role example
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 2
 138 \&  package Eq;
 139 \&  use Moose::Role;
 140 .Ve
 141 .PP
 142 .Vb 1
 143 \&  requires 'equal_to';
 144 .Ve
 145 .PP
 146 .Vb 4
 147 \&  sub not_equal_to {
 148 \&      my ( $self, $other ) = @_;
 149 \&      not $self\->equal_to($other);
 150 \&  }
 151 .Ve
 152 .PP
 153 .Vb 2
 154 \&  package Comparable;
 155 \&  use Moose::Role;
 156 .Ve
 157 .PP
 158 .Vb 1
 159 \&  with 'Eq';
 160 .Ve
 161 .PP
 162 .Vb 1
 163 \&  requires 'compare';
 164 .Ve
 165 .PP
 166 .Vb 4
 167 \&  sub equal_to {
 168 \&      my ( $self, $other ) = @_;
 169 \&      $self\->compare($other) == 0;
 170 \&  }
 171 .Ve
 172 .PP
 173 .Vb 4
 174 \&  sub greater_than {
 175 \&      my ( $self, $other ) = @_;
 176 \&      $self\->compare($other) == 1;
 177 \&  }
 178 .Ve
 179 .PP
 180 .Vb 4
 181 \&  sub less_than {
 182 \&      my ( $self, $other ) = @_;
 183 \&      $self\->compare($other) == \-1;
 184 \&  }
 185 .Ve
 186 .PP
 187 .Vb 4
 188 \&  sub greater_than_or_equal_to {
 189 \&      my ( $self, $other ) = @_;
 190 \&      $self\->greater_than($other) || $self\->equal_to($other);
 191 \&  }
 192 .Ve
 193 .PP
 194 .Vb 4
 195 \&  sub less_than_or_equal_to {
 196 \&      my ( $self, $other ) = @_;
 197 \&      $self\->less_than($other) || $self\->equal_to($other);
 198 \&  }
 199 .Ve
 200 .PP
 201 .Vb 2
 202 \&  package Printable;
 203 \&  use Moose::Role;
 204 .Ve
 205 .PP
 206 .Vb 1
 207 \&  requires 'to_string';
 208 .Ve
 209 .PP
 210 .Vb 2
 211 \&  package US::Currency;
 212 \&  use Moose;
 213 .Ve
 214 .PP
 215 .Vb 1
 216 \&  with 'Comparable', 'Printable';
 217 .Ve
 218 .PP
 219 .Vb 1
 220 \&  has 'amount' => ( is => 'rw', isa => 'Num', default => 0 );
 221 .Ve
 222 .PP
 223 .Vb 4
 224 \&  sub compare {
 225 \&      my ( $self, $other ) = @_;
 226 \&      $self\->amount <=> $other\->amount;
 227 \&  }
 228 .Ve
 229 .PP
 230 .Vb 4
 231 \&  sub to_string {
 232 \&      my $self = shift;
 233 \&      sprintf '$%0.2f USD' => $self\->amount;
 234 \&  }
 235 .Ve
 236 .SH "DESCRIPTION"
 237 .IX Header "DESCRIPTION"
 238 Roles have two primary purposes: as interfaces, and as a means of code
 239 reuse. This recipe demonstrates the latter, with roles that define
 240 comparison and display code for objects.
 241 .PP
 242 Let's start with \f(CW\*(C`Eq\*(C'\fR. First, note that we've replaced \f(CW\*(C`use Moose\*(C'\fR
 243 with \f(CW\*(C`use Moose::Role\*(C'\fR. We also have a new sugar function, \f(CW\*(C`requires\*(C'\fR:
 244 .PP
 245 .Vb 1
 246 \&  requires 'equal_to';
 247 .Ve
 248 .PP
 249 This says that any class which consumes this role must provide an
 250 \&\f(CW\*(C`equal_to\*(C'\fR method. It can provide this method directly, or by
 251 consuming some other role.
 252 .PP
 253 The \f(CW\*(C`Eq\*(C'\fR role defines its \f(CW\*(C`not_equal_to\*(C'\fR method in terms of the
 254 required \f(CW\*(C`equal_to\*(C'\fR method. This lets us minimize the methods that
 255 consuming classes must provide.
 256 .PP
 257 The next role, \f(CW\*(C`Comparable\*(C'\fR, builds on the \f(CW\*(C`Eq\*(C'\fR role. We include
 258 \&\f(CW\*(C`Eq\*(C'\fR in \f(CW\*(C`Comparable\*(C'\fR using \f(CW\*(C`with\*(C'\fR, another new sugar function:
 259 .PP
 260 .Vb 1
 261 \&  with 'Eq';
 262 .Ve
 263 .PP
 264 The \f(CW\*(C`with\*(C'\fR function takes a list of roles to consume. In our example,
 265 the \f(CW\*(C`Comparable\*(C'\fR role provides the \f(CW\*(C`equal_to\*(C'\fR method required by
 266 \&\f(CW\*(C`Eq\*(C'\fR. However, it could opt not to, in which case a class that
 267 consumed \f(CW\*(C`Comparable\*(C'\fR would have to provide its own \f(CW\*(C`equal_to\*(C'\fR. In
 268 other words, a role can consume another role \fIwithout\fR providing any
 269 required methods.
 270 .PP
 271 The \f(CW\*(C`Comparable\*(C'\fR role requires a method,  \f(CW\*(C`compare\*(C'\fR:
 272 .PP
 273 .Vb 1
 274 \&  requires 'compare';
 275 .Ve
 276 .PP
 277 The \f(CW\*(C`Comparable\*(C'\fR role also provides a number of other methods, all of
 278 which ultimately rely on \f(CW\*(C`compare\*(C'\fR.
 279 .PP
 280 .Vb 4
 281 \&  sub equal_to {
 282 \&      my ( $self, $other ) = @_;
 283 \&      $self\->compare($other) == 0;
 284 \&  }
 285 .Ve
 286 .PP
 287 .Vb 4
 288 \&  sub greater_than {
 289 \&      my ( $self, $other ) = @_;
 290 \&      $self\->compare($other) == 1;
 291 \&  }
 292 .Ve
 293 .PP
 294 .Vb 4
 295 \&  sub less_than {
 296 \&      my ( $self, $other ) = @_;
 297 \&      $self\->compare($other) == \-1;
 298 \&  }
 299 .Ve
 300 .PP
 301 .Vb 4
 302 \&  sub greater_than_or_equal_to {
 303 \&      my ( $self, $other ) = @_;
 304 \&      $self\->greater_than($other) || $self\->equal_to($other);
 305 \&  }
 306 .Ve
 307 .PP
 308 .Vb 4
 309 \&  sub less_than_or_equal_to {
 310 \&      my ( $self, $other ) = @_;
 311 \&      $self\->less_than($other) || $self\->equal_to($other);
 312 \&  }
 313 .Ve
 314 .PP
 315 Finally, we the \f(CW\*(C`Printable\*(C'\fR role. This role exists solely to provide
 316 an interface. It has no methods, just a list of required methods. In
 317 this case, it just requires a \f(CW\*(C`to_string\*(C'\fR method.
 318 .PP
 319 An interface role is useful because it defines both a method and a
 320 \&\fIname\fR. We know that any class which does this role has a
 321 \&\f(CW\*(C`to_string\*(C'\fR method, but we can also assume that this method has the
 322 semantics we want. Presumably, in real code we would define those
 323 semantics in the documentation for the \f(CW\*(C`Printable\*(C'\fR role. (1)
 324 .PP
 325 Finally, we have the \f(CW\*(C`US::Currency\*(C'\fR class which consumes both the
 326 \&\f(CW\*(C`Comparable\*(C'\fR and \f(CW\*(C`Printable\*(C'\fR roles.
 327 .PP
 328 .Vb 1
 329 \&  with 'Comparable', 'Printable';
 330 .Ve
 331 .PP
 332 It also defines a regular Moose attribute, \f(CW\*(C`amount\*(C'\fR:
 333 .PP
 334 .Vb 1
 335 \&  has 'amount' => ( is => 'rw', isa => 'Num', default => 0 );
 336 .Ve
 337 .PP
 338 Finally we see the implementation of the methods required by our
 339 roles. We have a \f(CW\*(C`compare\*(C'\fR method:
 340 .PP
 341 .Vb 4
 342 \&  sub compare {
 343 \&      my ( $self, $other ) = @_;
 344 \&      $self\->amount <=> $other\->amount;
 345 \&  }
 346 .Ve
 347 .PP
 348 By consuming the \f(CW\*(C`Comparable\*(C'\fR role and defining this method, we gain
 349 the following methods for free: \f(CW\*(C`equal_to\*(C'\fR, \f(CW\*(C`greater_than\*(C'\fR,
 350 \&\f(CW\*(C`less_than\*(C'\fR, \f(CW\*(C`greater_than_or_equal_to\*(C'\fR and
 351 \&\f(CW\*(C`less_than_or_equal_to\*(C'\fR.
 352 .PP
 353 Then we have our \f(CW\*(C`to_string\*(C'\fR method:
 354 .PP
 355 .Vb 4
 356 \&  sub to_string {
 357 \&      my $self = shift;
 358 \&      sprintf '$%0.2f USD' => $self\->amount;
 359 \&  }
 360 .Ve
 361 .SH "CONCLUSION"
 362 .IX Header "CONCLUSION"
 363 Roles can be very powerful. They are a great way of encapsulating
 364 reusable behavior, as well as communicating (semantic and interface)
 365 information about the methods our classes provide.
 366 .SH "FOOTNOTES"
 367 .IX Header "FOOTNOTES"
 368 .IP "(1)" 4
 369 .IX Item "(1)"
 370 Consider two classes, \f(CW\*(C`Runner\*(C'\fR and \f(CW\*(C`Process\*(C'\fR, both of which define a
 371 \&\f(CW\*(C`run\*(C'\fR method. If we just require that an object implements a \f(CW\*(C`run\*(C'\fR
 372 method, we still aren't saying anything about what that method
 373 \&\fIactually does\fR. If we require an object that implements the
 374 \&\f(CW\*(C`Executable\*(C'\fR role, we're saying something about semantics.
 375 .SH "AUTHORS"
 376 .IX Header "AUTHORS"
 377 Stevan Little <stevan@iinteractive.com>
 378 .PP
 379 Dave Rolsky <autarch@urth.org>
 380 .SH "COPYRIGHT AND LICENSE"
 381 .IX Header "COPYRIGHT AND LICENSE"
 382 Copyright 2006\-2009 by Infinity Interactive, Inc.
 383 .PP
 384 <http://www.iinteractive.com>
 385 .PP
 386 This library is free software; you can redistribute it and/or modify
 387 it under the same terms as Perl itself.