local-lib5/man/man3/Moose::Manual::Delegation.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::Delegation 3"
 132 .TH Moose::Manual::Delegation 3 "2009-10-24" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Moose::Manual::Delegation \- Attribute delegation
 135 .SH "WHAT IS DELEGATION?"
 136 .IX Header "WHAT IS DELEGATION?"
 137 Delegation is a feature that lets you create \*(L"proxy\*(R" methods that
 138 do nothing more than call some other method on an attribute. This
 139 is quite handy since it lets you simplify a complex set of \*(L"has\-a\*(R"
 140 relationships and present a single unified \s-1API\s0 from one class.
 141 .PP
 142 With delegation, consumers of a class don't need to know about all the
 143 objects it contains, reducing the amount of \s-1API\s0 they need to learn.
 144 .PP
 145 Delegations are defined as a mapping between one or more methods
 146 provided by the \*(L"real\*(R" class (the delegatee), and a set of
 147 corresponding methods in the delegating class. The delegating class
 148 can re-use the method names provided by the delegatee or provide its
 149 own names.
 150 .PP
 151 Delegation is also a great way to wrap an existing class, especially a
 152 non-Moose class or one that is somehow hard (or impossible) to
 153 subclass.
 154 .SH "DEFINING A MAPPING"
 155 .IX Header "DEFINING A MAPPING"
 156 Moose offers a number of options for defining a delegation's mapping,
 157 ranging from simple to complex.
 158 .PP
 159 The simplest form is to simply specify a list of methods:
 160 .PP
 161 .Vb 1
 162 \&  package Website;
 163 .Ve
 164 .PP
 165 .Vb 1
 166 \&  use Moose;
 167 .Ve
 168 .PP
 169 .Vb 5
 170 \&  has 'uri' => (
 171 \&      is      => 'ro',
 172 \&      isa     => 'URI',
 173 \&      handles => [qw( host path )],
 174 \&  );
 175 .Ve
 176 .PP
 177 With this definition, we can call \f(CW\*(C`$website\->host\*(C'\fR and it \*(L"just
 178 works\*(R". Under the hood, Moose will call \f(CW\*(C`$website\->uri\->host\*(C'\fR for
 179 you. Note that \f(CW$website\fR is not automatically passed to the \f(CW\*(C`host\*(C'\fR
 180 method; the invocant is \f(CW\*(C`$website\->uri\*(C'\fR.
 181 .PP
 182 We can also define a mapping as a hash reference. This allows you to
 183 rename methods as part of the mapping:
 184 .PP
 185 .Vb 1
 186 \&  package Website;
 187 .Ve
 188 .PP
 189 .Vb 1
 190 \&  use Moose;
 191 .Ve
 192 .PP
 193 .Vb 8
 194 \&  has 'uri' => (
 195 \&      is      => 'ro',
 196 \&      isa     => 'URI',
 197 \&      handles => {
 198 \&          hostname => 'host',
 199 \&          path     => 'path',
 200 \&      },
 201 \&  );
 202 .Ve
 203 .PP
 204 In this example, we've created a \f(CW\*(C`$website\->hostname\*(C'\fR method,
 205 rather than using \f(CW\*(C`URI.pm\*(C'\fR's name, \f(CW\*(C`host\*(C'\fR.
 206 .PP
 207 These two mapping forms are the ones you will use most often. The
 208 remainder are a bit more complex, and less common.
 209 .PP
 210 .Vb 5
 211 \&  has 'uri' => (
 212 \&      is      => 'ro',
 213 \&      isa     => 'URI',
 214 \&      handles => qr/^(?:host|path|query.*)/,
 215 \&  );
 216 .Ve
 217 .PP
 218 This is similar to the array version, except it uses the regex to
 219 match against all the methods provided by the delegatee. In order for
 220 this to work, you must provide an \f(CW\*(C`isa\*(C'\fR parameter for the attribute,
 221 and it must be a class. Moose uses this to introspect the delegatee
 222 class and determine what methods it provides.
 223 .PP
 224 You can use a role name as the value of \f(CW\*(C`handles\*(C'\fR:
 225 .PP
 226 .Vb 5
 227 \&  has 'uri' => (
 228 \&      is      => 'ro',
 229 \&      isa     => 'URI',
 230 \&      handles => 'HasURI',
 231 \&  );
 232 .Ve
 233 .PP
 234 Moose will introspect the role to determine what methods it provides
 235 and create a mapping for each of those methods.
 236 .PP
 237 Finally, you can also provide a sub reference to \fIgenerate\fR a
 238 mapping. You probably won't need this version often (if ever). See the
 239 Moose docs for more details on exactly how this works.
 240 .SH "PERL DATA STRUCTURES"
 241 .IX Header "PERL DATA STRUCTURES"
 242 Handles also will allow you to delegate to \*(L"helper\*(R" methods that work on
 243 common Perl data structures. If you remember or have ever used
 244 MooseX::AttributeHelpers the mechanism is very
 245 similar.
 246 .PP
 247 .Vb 9
 248 \&  has 'queue' => (
 249 \&      isa     => 'ArrayRef[Item]',
 250 \&      traits  => ['Array'],
 251 \&      default => sub { [ ] },
 252 \&      handles => {
 253 \&          add_item  => 'push',
 254 \&          next_item => 'shift',
 255 \&      },
 256 \&  )
 257 .Ve
 258 .PP
 259 By providing the \f(CW\*(C`Array\*(C'\fR trait to the \f(CW\*(C`traits\*(C'\fR parameter you signal to
 260 Moose that you would like to use the set of Array helpers. Moose will then
 261 create \f(CW\*(C`add_item\*(C'\fR and \f(CW\*(C`next_item\*(C'\fR method that \*(L"just works\*(R". Behind the
 262 scenes \f(CW\*(C`add_item\*(C'\fR is something like
 263 .PP
 264 .Vb 2
 265 \&  sub add_item {
 266 \&      my ($self, @items) = @_;
 267 .Ve
 268 .PP
 269 .Vb 3
 270 \&      for my $item (@items) {
 271 \&          $Item_TC\->validate($item);
 272 \&      }
 273 .Ve
 274 .PP
 275 .Vb 2
 276 \&      push @{ $self\->queue }, @items;
 277 \&  }
 278 .Ve
 279 .PP
 280 There are traits for not only \f(CW\*(C`Array\*(C'\fR but also \f(CW\*(C`Hash\*(C'\fR, \f(CW\*(C`Bool\*(C'\fR, \f(CW\*(C`String\*(C'\fR,
 281 \&\f(CW\*(C`Number\*(C'\fR, and \f(CW\*(C`Counter\*(C'\fR. For more information see the documentation in
 282 Moose::Meta::Attribute::Native.
 283 .SH "CURRYING"
 284 .IX Header "CURRYING"
 285 Currying is a way of creating a method or function from another method or
 286 function with some of the parameters pre\-defined. Moose provides the ability to
 287 curry methods when creating delegates.
 288 .PP
 289 .Vb 2
 290 \&    package Spider;
 291 \&    use Moose;
 292 .Ve
 293 .PP
 294 .Vb 7
 295 \&    has request => (
 296 \&        is      => 'ro'
 297 \&        isa     => 'HTTP::Request',
 298 \&        handles => {
 299 \&            set_user_agent => [ header => 'UserAgent' ],
 300 \&        },
 301 \&    )
 302 .Ve
 303 .PP
 304 With this definition, calling \f(CW\*(C`$spider\->set_user_agent('MyClient')\*(C'\fR will
 305 behind the scenes call \f(CW\*(C`$spider\->request\->header('UserAgent', 'MyClient')\*(C'\fR.
 306 .SH "MISSING ATTRIBUTES"
 307 .IX Header "MISSING ATTRIBUTES"
 308 It is perfectly valid to delegate methods to an attribute which is not
 309 required or can be undefined. When a delegated method is called, Moose
 310 will throw a runtime error if the attribute does not contain an
 311 object.
 312 .SH "AUTHOR"
 313 .IX Header "AUTHOR"
 314 Dave Rolsky <autarch@urth.org>
 315 .SH "COPYRIGHT AND LICENSE"
 316 .IX Header "COPYRIGHT AND LICENSE"
 317 Copyright 2009 by Infinity Interactive, Inc.
 318 .PP
 319 <http://www.iinteractive.com>
 320 .PP
 321 This library is free software; you can redistribute it and/or modify
 322 it under the same terms as Perl itself.