local-lib5/man/man3/Moose::Cookbook::Basics::Recipe3.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::Basics::Recipe3 3"
 132 .TH Moose::Cookbook::Basics::Recipe3 3 "2009-08-11" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Moose::Cookbook::Basics::Recipe3 \- A lazy \fBBinaryTree\fR example
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 2
 138 \&  package BinaryTree;
 139 \&  use Moose;
 140 .Ve
 141 .PP
 142 .Vb 1
 143 \&  has 'node' => ( is => 'rw', isa => 'Any' );
 144 .Ve
 145 .PP
 146 .Vb 6
 147 \&  has 'parent' => (
 148 \&      is        => 'rw',
 149 \&      isa       => 'BinaryTree',
 150 \&      predicate => 'has_parent',
 151 \&      weak_ref  => 1,
 152 \&  );
 153 .Ve
 154 .PP
 155 .Vb 8
 156 \&  has 'left' => (
 157 \&      is        => 'rw',
 158 \&      isa       => 'BinaryTree',
 159 \&      predicate => 'has_left',
 160 \&      lazy      => 1,
 161 \&      default   => sub { BinaryTree\->new( parent => $_[0] ) },
 162 \&      trigger   => \e&_set_parent_for_child
 163 \&  );
 164 .Ve
 165 .PP
 166 .Vb 8
 167 \&  has 'right' => (
 168 \&      is        => 'rw',
 169 \&      isa       => 'BinaryTree',
 170 \&      predicate => 'has_right',
 171 \&      lazy      => 1,
 172 \&      default   => sub { BinaryTree\->new( parent => $_[0] ) },
 173 \&      trigger   => \e&_set_parent_for_child
 174 \&  );
 175 .Ve
 176 .PP
 177 .Vb 2
 178 \&  sub _set_parent_for_child {
 179 \&      my ( $self, $child ) = @_;
 180 .Ve
 181 .PP
 182 .Vb 2
 183 \&      confess "You cannot insert a tree which already has a parent"
 184 \&          if $child\->has_parent;
 185 .Ve
 186 .PP
 187 .Vb 2
 188 \&      $child\->parent($self);
 189 \&  }
 190 .Ve
 191 .SH "DESCRIPTION"
 192 .IX Header "DESCRIPTION"
 193 This recipe shows how various advanced attribute features can be used
 194 to create complex and powerful behaviors. In particular, we introduce
 195 a number of new attribute options, including \f(CW\*(C`predicate\*(C'\fR, \f(CW\*(C`lazy\*(C'\fR,
 196 and \f(CW\*(C`trigger\*(C'\fR.
 197 .PP
 198 The example class is a classic binary tree. Each node in the tree is
 199 itself an instance of \f(CW\*(C`BinaryTree\*(C'\fR. It has a \f(CW\*(C`node\*(C'\fR, which holds
 200 some arbitrary value. It has \f(CW\*(C`right\*(C'\fR and \f(CW\*(C`left\*(C'\fR attributes, which
 201 refer to its child trees, and a \f(CW\*(C`parent\*(C'\fR.
 202 .PP
 203 Let's take a look at the \f(CW\*(C`node\*(C'\fR attribute:
 204 .PP
 205 .Vb 1
 206 \&  has 'node' => ( is => 'rw', isa => 'Any' );
 207 .Ve
 208 .PP
 209 Moose generates a read-write accessor for this attribute. The type
 210 constraint is \f(CW\*(C`Any\*(C'\fR, which literally means it can contain anything.
 211 .PP
 212 We could have left out the \f(CW\*(C`isa\*(C'\fR option, but in this case, we are
 213 including it for the benefit of other programmers, not the computer.
 214 .PP
 215 Next, let's move on to the \f(CW\*(C`parent\*(C'\fR attribute:
 216 .PP
 217 .Vb 6
 218 \&  has 'parent' => (
 219 \&      is        => 'rw',
 220 \&      isa       => 'BinaryTree',
 221 \&      predicate => 'has_parent',
 222 \&      weak_ref  => 1,
 223 \&  );
 224 .Ve
 225 .PP
 226 Again, we have a read-write accessor. This time, the \f(CW\*(C`isa\*(C'\fR option
 227 says that this attribute must always be an instance of
 228 \&\f(CW\*(C`BinaryTree\*(C'\fR. In the second recipe, we saw that every time we create
 229 a Moose-based class, we also get a corresponding class type
 230 constraint.
 231 .PP
 232 The \f(CW\*(C`predicate\*(C'\fR option is new. It creates a method which can be used
 233 to check whether or not a given attribute has been initialized. In
 234 this case, the method is named \f(CW\*(C`has_parent\*(C'\fR.
 235 .PP
 236 This brings us to our last attribute option, \f(CW\*(C`weak_ref\*(C'\fR. Since
 237 \&\f(CW\*(C`parent\*(C'\fR is a circular reference (the tree in \f(CW\*(C`parent\*(C'\fR should
 238 already have a reference to this one, in its \f(CW\*(C`left\*(C'\fR or \f(CW\*(C`right\*(C'\fR
 239 attribute), we want to make sure that we weaken the reference to avoid
 240 memory leaks. If \f(CW\*(C`weak_ref\*(C'\fR is true, it alters the accessor function
 241 so that the reference is weakened when it is set.
 242 .PP
 243 Finally, we have the the \f(CW\*(C`left\*(C'\fR and \f(CW\*(C`right\*(C'\fR attributes. They are
 244 essentially identical except for their names, so we'll just look at
 245 \&\f(CW\*(C`left\*(C'\fR:
 246 .PP
 247 .Vb 8
 248 \&  has 'left' => (
 249 \&      is        => 'rw',
 250 \&      isa       => 'BinaryTree',
 251 \&      predicate => 'has_left',
 252 \&      lazy      => 1,
 253 \&      default   => sub { BinaryTree\->new( parent => $_[0] ) },
 254 \&      trigger   => \e&_set_parent_for_child
 255 \&  );
 256 .Ve
 257 .PP
 258 There are three new options here, \f(CW\*(C`lazy\*(C'\fR, \f(CW\*(C`default\*(C'\fR, and
 259 \&\f(CW\*(C`trigger\*(C'\fR. The \f(CW\*(C`lazy\*(C'\fR and \f(CW\*(C`default\*(C'\fR options options are linked.  In
 260 fact, you cannot have a \f(CW\*(C`lazy\*(C'\fR attribute unless it has a \f(CW\*(C`default\*(C'\fR
 261 (or a \f(CW\*(C`builder\*(C'\fR, but we'll cover that later). If you try to make an
 262 attribute lazy without a default, class creation will fail with an
 263 exception. (2)
 264 .PP
 265 In the second recipe the \fBBankAccount\fR's \f(CW\*(C`balance\*(C'\fR attribute had a
 266 default value of \f(CW0\fR. Given a non\-reference, Perl copies the
 267 \&\fIvalue\fR. However, given a reference, it does not do a deep clone,
 268 instead simply copying the reference. If you just specified a simply
 269 reference for a default, Perl would create it once and it would be
 270 shared by all objects with that attribute.
 271 .PP
 272 As a workaround, we use an anonymous subroutine to generate a new
 273 reference every time the default is called.
 274 .PP
 275 .Vb 1
 276 \&  has 'foo' => ( is => 'rw', default => sub { [] } );
 277 .Ve
 278 .PP
 279 In fact, using a non-subroutine reference as a default is illegal in Moose.
 280 .PP
 281 .Vb 2
 282 \&  # will fail
 283 \&  has 'foo' => ( is => 'rw', default => [] );
 284 .Ve
 285 .PP
 286 This will blow up, so don't do it.
 287 .PP
 288 You'll notice that we use \f(CW$_[0]\fR in our default sub. When the
 289 default subroutine is executed, it is called as a method on the
 290 object.
 291 .PP
 292 In our case, we're making a new \f(CW\*(C`BinaryTree\*(C'\fR object in our default,
 293 with the current tree as the parent.
 294 .PP
 295 Normally, when an object is instantiated, any defaults are evaluated
 296 immediately. With our \f(CW\*(C`BinaryTree\*(C'\fR class, this would be a big
 297 problem! We'd create the first object, which would immediately try to
 298 populate its \f(CW\*(C`left\*(C'\fR and \f(CW\*(C`right\*(C'\fR attributes, which would create a new
 299 \&\f(CW\*(C`BinaryTree\*(C'\fR, which would populate \fIits\fR \f(CW\*(C`left\*(C'\fR and \f(CW\*(C`right\*(C'\fR
 300 slots. Kaboom!
 301 .PP
 302 By making our \f(CW\*(C`left\*(C'\fR and \f(CW\*(C`right\*(C'\fR attributes \f(CW\*(C`lazy\*(C'\fR, we avoid this
 303 problem. If the attribute has a value when it is read, the default is
 304 never executed at all.
 305 .PP
 306 We still have one last bit of behavior to add. The autogenerated
 307 \&\f(CW\*(C`right\*(C'\fR and \f(CW\*(C`left\*(C'\fR accessors are not quite correct. When one of
 308 these is set, we want to make sure that we update the parent of the
 309 \&\f(CW\*(C`left\*(C'\fR or \f(CW\*(C`right\*(C'\fR attribute's tree.
 310 .PP
 311 We could write our own accessors, but then why use Moose at all?
 312 Instead, we use a \f(CW\*(C`trigger\*(C'\fR. A \f(CW\*(C`trigger\*(C'\fR accepts a subroutine
 313 reference, which will be called as a method whenever the attribute is
 314 set. This can happen both during object construction or later by
 315 passing a new object to the attribute's accessor method. However, it
 316 is not called when a value is provided by a \f(CW\*(C`default\*(C'\fR or \f(CW\*(C`builder\*(C'\fR.
 317 .PP
 318 .Vb 2
 319 \&  sub _set_parent_for_child {
 320 \&      my ( $self, $child ) = @_;
 321 .Ve
 322 .PP
 323 .Vb 2
 324 \&      confess "You cannot insert a tree which already has a parent"
 325 \&          if $child\->has_parent;
 326 .Ve
 327 .PP
 328 .Vb 2
 329 \&      $child\->parent($self);
 330 \&  }
 331 .Ve
 332 .PP
 333 This trigger does two things. First, it ensures that the new child
 334 node does not already have a parent. This is done for the sake of
 335 simplifying the example. If we wanted to be more clever, we would
 336 remove the child from its old parent tree and add it to the new one.
 337 .PP
 338 If the child has no parent, we will add it to the current tree, and we
 339 ensure that is has the correct value for its \f(CW\*(C`parent\*(C'\fR attribute.
 340 .PP
 341 As with all the other recipes, \fBBinaryTree\fR can be used just like any
 342 other Perl 5 class. A more detailed example of its usage can be found
 343 in \fIt/000_recipes/moose_cookbook_basics_recipe3.t\fR.
 344 .SH "CONCLUSION"
 345 .IX Header "CONCLUSION"
 346 This recipe introduced several of Moose's advanced features. We hope
 347 that this inspires you to think of other ways these features can be
 348 used to simplify your code.
 349 .SH "FOOTNOTES"
 350 .IX Header "FOOTNOTES"
 351 .IP "(1)" 4
 352 .IX Item "(1)"
 353 Weak references are tricky things, and should be used sparingly and
 354 appropriately (such as in the case of circular refs). If you are not
 355 careful, attribute values could disappear \*(L"mysteriously\*(R" because
 356 Perl's reference counting garbage collector has gone and removed the
 357 item you are weak\-referencing.
 358 .Sp
 359 In short, don't use them unless you know what you are doing :)
 360 .IP "(2)" 4
 361 .IX Item "(2)"
 362 You \fIcan\fR use the \f(CW\*(C`default\*(C'\fR option without the \f(CW\*(C`lazy\*(C'\fR option if you
 363 like, as we showed in the second recipe.
 364 .Sp
 365 Also, you can use \f(CW\*(C`builder\*(C'\fR instead of \f(CW\*(C`default\*(C'\fR. See
 366 Moose::Cookbook::Basics::Recipe8 for details.
 367 .SH "AUTHORS"
 368 .IX Header "AUTHORS"
 369 Stevan Little <stevan@iinteractive.com>
 370 .PP
 371 Dave Rolsky <autarch@urth.org>
 372 .SH "COPYRIGHT AND LICENSE"
 373 .IX Header "COPYRIGHT AND LICENSE"
 374 Copyright 2006\-2009 by Infinity Interactive, Inc.
 375 .PP
 376 <http://www.iinteractive.com>
 377 .PP
 378 This library is free software; you can redistribute it and/or modify
 379 it under the same terms as Perl itself.