local-lib5/man/man3/Moose::Cookbook::Basics::Recipe8.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::Recipe8 3"
 132 .TH Moose::Cookbook::Basics::Recipe8 3 "2009-06-25" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Moose::Cookbook::Basics::Recipe8 \- Builder methods and lazy_build
 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 7
 156 \&  has 'left' => (
 157 \&      is        => 'rw',
 158 \&      isa       => 'BinaryTree',
 159 \&      predicate => 'has_left',
 160 \&      lazy      => 1,
 161 \&      builder   => '_build_child_tree',
 162 \&  );
 163 .Ve
 164 .PP
 165 .Vb 7
 166 \&  has 'right' => (
 167 \&      is        => 'rw',
 168 \&      isa       => 'BinaryTree',
 169 \&      predicate => 'has_right',
 170 \&      lazy      => 1,
 171 \&      builder   => '_build_child_tree',
 172 \&  );
 173 .Ve
 174 .PP
 175 .Vb 4
 176 \&  before 'right', 'left' => sub {
 177 \&      my ($self, $tree) = @_;
 178 \&      $tree\->parent($self) if defined $tree;
 179 \&  };
 180 .Ve
 181 .PP
 182 .Vb 2
 183 \&  sub _build_child_tree {
 184 \&      my $self = shift;
 185 .Ve
 186 .PP
 187 .Vb 2
 188 \&      return BinaryTree\->new( parent => $self );
 189 \&  }
 190 .Ve
 191 .SH "DESCRIPTION"
 192 .IX Header "DESCRIPTION"
 193 If you've already read Moose::Cookbook::Basics::Recipe3, then this
 194 example should look very familiar. In fact, all we've done here is
 195 replace the attribute's \f(CW\*(C`default\*(C'\fR parameter with a \f(CW\*(C`builder\*(C'\fR.
 196 .PP
 197 In this particular case, the \f(CW\*(C`default\*(C'\fR and \f(CW\*(C`builder\*(C'\fR options act in
 198 exactly the same way. When the \f(CW\*(C`left\*(C'\fR or \f(CW\*(C`right\*(C'\fR attribute is read,
 199 Moose calls the builder method to initialize the attribute.
 200 .PP
 201 Note that Moose calls the builder method \fIon the object which has the
 202 attribute\fR. Here's an example:
 203 .PP
 204 .Vb 1
 205 \&  my $tree = BinaryTree\->new();
 206 .Ve
 207 .PP
 208 .Vb 1
 209 \&  my $left = $tree\->left();
 210 .Ve
 211 .PP
 212 When \f(CW\*(C`$tree\->left()\*(C'\fR is called, Moose calls \f(CW\*(C`$tree\->_build_child_tree()\*(C'\fR in order to populate the \f(CW\*(C`left\*(C'\fR
 213 attribute. If we had passed \f(CW\*(C`left\*(C'\fR to the original constructor, the
 214 builder would not be called.
 215 .PP
 216 There are some differences between \f(CW\*(C`default\*(C'\fR and \f(CW\*(C`builder\*(C'\fR. Notably,
 217 a builder is subclassable, and can be composed from a role. See
 218 Moose::Manual::Attributes for more details.
 219 .Sh "The lazy_build shortcut"
 220 .IX Subsection "The lazy_build shortcut"
 221 The \f(CW\*(C`lazy_build\*(C'\fR attribute option can be used as sugar to specify
 222 a whole set of attribute options at once:
 223 .PP
 224 .Vb 5
 225 \&  has 'animal' => (
 226 \&      is         => 'ro',
 227 \&      isa        => 'Animal',
 228 \&      lazy_build => 1,
 229 \&  );
 230 .Ve
 231 .PP
 232 This is a shorthand for:
 233 .PP
 234 .Vb 9
 235 \&  has 'animal' => (
 236 \&      is        => 'ro',
 237 \&      isa       => 'Animal',
 238 \&      required  => 1,
 239 \&      lazy      => 1,
 240 \&      builder   => '_build_animal',
 241 \&      predicate => 'has_animal',
 242 \&      clearer   => 'clear_animal',
 243 \&  );
 244 .Ve
 245 .PP
 246 If your attribute starts with an underscore, Moose is smart and will
 247 do the right thing with the \f(CW\*(C`predicate\*(C'\fR and \f(CW\*(C`clearer\*(C'\fR, making them
 248 both start with an underscore. The \f(CW\*(C`builder\*(C'\fR method \fIalways\fR starts
 249 with an underscore.
 250 .PP
 251 You can read more about \f(CW\*(C`lazy_build\*(C'\fR in Moose::Manual::Attributes
 252 .SH "CONCLUSION"
 253 .IX Header "CONCLUSION"
 254 The \f(CW\*(C`builder\*(C'\fR option is a more OO-friendly version of the \f(CW\*(C`default\*(C'\fR
 255 functionality. It also separates the default-generating code into a
 256 well-defined method. Sprinkling your attribute definitions with
 257 anonymous subroutines can be quite ugly and hard to follow.
 258 .SH "AUTHOR"
 259 .IX Header "AUTHOR"
 260 Dave Rolsky <autarch@urth.org>
 261 .SH "COPYRIGHT AND LICENSE"
 262 .IX Header "COPYRIGHT AND LICENSE"
 263 Copyright 2006\-2009 by Infinity Interactive, Inc.
 264 .PP
 265 <http://www.iinteractive.com>
 266 .PP
 267 This library is free software; you can redistribute it and/or modify
 268 it under the same terms as Perl itself.