local-lib5/man/man3/Moose::Cookbook::Basics::Recipe10.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::Recipe10 3"
 132 .TH Moose::Cookbook::Basics::Recipe10 3 "2009-08-11" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Moose::Cookbook::Basics::Recipe10 \- Using BUILDARGS and BUILD to hook into object construction
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&  package Person;
 139 .Ve
 140 .PP
 141 .Vb 5
 142 \&  has 'ssn' => (
 143 \&      is        => 'ro',
 144 \&      isa       => 'Str',
 145 \&      predicate => 'has_ssn',
 146 \&  );
 147 .Ve
 148 .PP
 149 .Vb 5
 150 \&  has 'country_of_residence' => (
 151 \&      is      => 'ro',
 152 \&      isa     => 'Str',
 153 \&      default => 'usa'
 154 \&  );
 155 .Ve
 156 .PP
 157 .Vb 4
 158 \&  has 'first_name' => (
 159 \&      is  => 'ro',
 160 \&      isa => 'Str',
 161 \&  );
 162 .Ve
 163 .PP
 164 .Vb 4
 165 \&  has 'last_name' => (
 166 \&      is  => 'ro',
 167 \&      isa => 'Str',
 168 \&  );
 169 .Ve
 170 .PP
 171 .Vb 3
 172 \&  around BUILDARGS => sub {
 173 \&      my $orig = shift;
 174 \&      my $class = shift;
 175 .Ve
 176 .PP
 177 .Vb 7
 178 \&      if ( @_ == 1 && ! ref $_[0] ) {
 179 \&          return $class\->$orig(ssn => $_[0]);
 180 \&      }
 181 \&      else {
 182 \&          return $class\->$orig(@_);
 183 \&      }
 184 \&  };
 185 .Ve
 186 .PP
 187 .Vb 2
 188 \&  sub BUILD {
 189 \&      my $self = shift;
 190 .Ve
 191 .PP
 192 .Vb 5
 193 \&      if ( $self\->country_of_residence eq 'usa' ) {
 194 \&          die 'Cannot create a Person who lives in the USA without an ssn.'
 195 \&              unless $self\->has_ssn;
 196 \&      }
 197 \&  }
 198 .Ve
 199 .SH "DESCRIPTION"
 200 .IX Header "DESCRIPTION"
 201 This recipe demonstrates the use of \f(CW\*(C`BUILDARGS\*(C'\fR and \f(CW\*(C`BUILD\*(C'\fR. By
 202 defining these methods, we can hook into the object construction
 203 process without overriding \f(CW\*(C`new\*(C'\fR.
 204 .PP
 205 The \f(CW\*(C`BUILDARGS\*(C'\fR method is called \fIbefore\fR an object has been
 206 created. It is called as a class method, and receives all of the
 207 parameters passed to the \f(CW\*(C`new\*(C'\fR method. It is expected to do something
 208 with these arguments and return a hash reference. The keys of the hash
 209 must be attribute \f(CW\*(C`init_arg\*(C'\fRs.
 210 .PP
 211 The primary purpose of \f(CW\*(C`BUILDARGS\*(C'\fR is to allow a class to accept
 212 something other than named arguments. In the case of our \f(CW\*(C`Person\*(C'\fR
 213 class, we are allowing it to be called with a single argument, a
 214 social security number:
 215 .PP
 216 .Vb 1
 217 \&  my $person = Person\->new('123\-45\-6789');
 218 .Ve
 219 .PP
 220 The key part of our \f(CW\*(C`BUILDARGS\*(C'\fR is this conditional:
 221 .PP
 222 .Vb 3
 223 \&      if ( @_ == 1 && ! ref $_[0] ) {
 224 \&          return $class\->$orig(ssn => $_[0]);
 225 \&      }
 226 .Ve
 227 .PP
 228 By default, Moose constructors accept a list of key-value pairs, or a
 229 hash reference. We need to make sure that \f(CW$_[0]\fR is not a reference
 230 before assuming it is a social security number.
 231 .PP
 232 We call the original \f(CW\*(C`BUILDARGS\*(C'\fR method to handle all the other
 233 cases. You should always do this in your own \f(CW\*(C`BUILDARGS\*(C'\fR methods,
 234 since Moose::Object provides its own \f(CW\*(C`BUILDARGS\*(C'\fR method that
 235 handles hash references and a list of key-value pairs.
 236 .PP
 237 The \f(CW\*(C`BUILD\*(C'\fR method is called \fIafter\fR the object is constructed, but
 238 before it is returned to the caller. The \f(CW\*(C`BUILD\*(C'\fR method provides an
 239 opportunity to check the object state as a whole. This is a good place
 240 to put logic that cannot be expressed as a type constraint on a single
 241 attribute.
 242 .PP
 243 In the \f(CW\*(C`Person\*(C'\fR class, we need to check the relationship between two
 244 attributes, \f(CW\*(C`ssn\*(C'\fR and \f(CW\*(C`country_of_residence\*(C'\fR. We throw an exception
 245 if the object is not logically consistent.
 246 .SH "MORE CONSIDERATIONS"
 247 .IX Header "MORE CONSIDERATIONS"
 248 This recipe is made significantly simpler because all of the
 249 attributes are read\-only. If the \f(CW\*(C`country_of_residence\*(C'\fR attribute
 250 were settable, we would need to check that a Person had an \f(CW\*(C`ssn\*(C'\fR if
 251 the new country was \f(CW\*(C`usa\*(C'\fR. This could be done with a \f(CW\*(C`before\*(C'\fR
 252 modifier.
 253 .SH "CONCLUSION"
 254 .IX Header "CONCLUSION"
 255 We have repeatedly discouraged overriding \f(CW\*(C`new\*(C'\fR in Moose
 256 classes. This recipe shows how you can use \f(CW\*(C`BUILDARGS\*(C'\fR and \f(CW\*(C`BUILD\*(C'\fR
 257 to hook into object construction without overriding \f(CW\*(C`new\*(C'\fR
 258 .PP
 259 The \f(CW\*(C`BUILDARGS\*(C'\fR method lets us expand on Moose's built-in parameter
 260 handling for constructors. The \f(CW\*(C`BUILD\*(C'\fR method lets us implement
 261 logical constraints across the whole object after it is created.
 262 .SH "AUTHOR"
 263 .IX Header "AUTHOR"
 264 Dave Rolsky <autarch@urth.org>
 265 .SH "COPYRIGHT AND LICENSE"
 266 .IX Header "COPYRIGHT AND LICENSE"
 267 Copyright 2006\-2009 by Infinity Interactive, Inc.
 268 .PP
 269 <http://www.iinteractive.com>
 270 .PP
 271 This library is free software; you can redistribute it and/or modify
 272 it under the same terms as Perl itself.