local-lib5/man/man3/Moose::Manual::Construction.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::Construction 3"
 132 .TH Moose::Manual::Construction 3 "2009-09-12" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Moose::Manual::Construction \- Object construction (and destruction) with Moose
 135 .SH "WHERE'S THE CONSTRUCTOR?"
 136 .IX Header "WHERE'S THE CONSTRUCTOR?"
 137 \&\fBDo not define a \f(CB\*(C`new()\*(C'\fB method for your classes!\fR
 138 .PP
 139 When you \f(CW\*(C`use Moose\*(C'\fR in your class, you will become a subclass of
 140 Moose::Object, which provides a \f(CW\*(C`new\*(C'\fR method for you. If you
 141 follow our recommendations in Moose::Manual::BestPractices and make
 142 your class immutable, then you actually get a class-specific \f(CW\*(C`new\*(C'\fR
 143 method \*(L"inlined\*(R" in your class.
 144 .SH "OBJECT CONSTRUCTION AND ATTRIBUTES"
 145 .IX Header "OBJECT CONSTRUCTION AND ATTRIBUTES"
 146 The Moose-provided constructor accepts a hash or hash reference of
 147 named parameters matching your attributes (actually, matching their
 148 \&\f(CW\*(C`init_arg\*(C'\fRs). This is just another way in which Moose keeps you from
 149 worrying \fIhow\fR classes are implemented. Simply define a class and
 150 you're ready to start creating objects!
 151 .SH "OBJECT CONSTRUCTION HOOKS"
 152 .IX Header "OBJECT CONSTRUCTION HOOKS"
 153 Moose lets you hook into object construction. You can validate an
 154 object's state, do logging, or maybe allow non\-hash(ref) constructor
 155 arguments. You can do this by creating \f(CW\*(C`BUILD\*(C'\fR and/or \f(CW\*(C`BUILDARGS\*(C'\fR
 156 methods.
 157 .PP
 158 If these methods exist in your class, Moose will arrange for them to
 159 be called as part of the object construction process.
 160 .Sh "\s-1BUILDARGS\s0"
 161 .IX Subsection "BUILDARGS"
 162 The \f(CW\*(C`BUILDARGS\*(C'\fR method is called as a class method \fIbefore\fR an
 163 object is created. It will receive all of the arguments that were
 164 passed to \f(CW\*(C`new\*(C'\fR \fIas-is\fR, and is expected to return a hash
 165 reference. This hash reference will be used to construct the object,
 166 so it should contain keys matching your attributes' names (well,
 167 \&\f(CW\*(C`init_arg\*(C'\fRs).
 168 .PP
 169 One common use for \f(CW\*(C`BUILDARGS\*(C'\fR is to accommodate a non\-hash(ref)
 170 calling style. For example, we might want to allow our Person class to
 171 be called with a single argument of a social security number, \f(CW\*(C`Person\->new($ssn)\*(C'\fR.
 172 .PP
 173 Without a \f(CW\*(C`BUILDARGS\*(C'\fR method, Moose will complain, because it expects
 174 a hash or hash reference. We can use the \f(CW\*(C`BUILDARGS\*(C'\fR method to
 175 accommodate this calling style:
 176 .PP
 177 .Vb 3
 178 \&  around BUILDARGS => sub {
 179 \&      my $orig = shift;
 180 \&      my $class = shift;
 181 .Ve
 182 .PP
 183 .Vb 7
 184 \&      if ( @_ == 1 && ! ref $_[0] ) {
 185 \&          return $class\->$orig(ssn => $_[0]);
 186 \&      }
 187 \&      else {
 188 \&          return $class\->$orig(@_);
 189 \&      }
 190 \&  };
 191 .Ve
 192 .PP
 193 Note the call to \f(CW\*(C`$class\->$orig\*(C'\fR. This will call the default
 194 \&\f(CW\*(C`BUILDARGS\*(C'\fR in Moose::Object. This method handles distinguishing
 195 between a hash reference and a plain hash for you.
 196 .Sh "\s-1BUILD\s0"
 197 .IX Subsection "BUILD"
 198 The \f(CW\*(C`BUILD\*(C'\fR method is called \fIafter\fR an object is created. There are
 199 several ways to use a \f(CW\*(C`BUILD\*(C'\fR method. One of the most common is to
 200 check that the object state is valid. While we can validate individual
 201 attributes through the use of types, we can't validate the state of a
 202 whole object that way.
 203 .PP
 204 .Vb 2
 205 \&  sub BUILD {
 206 \&      my $self = shift;
 207 .Ve
 208 .PP
 209 .Vb 5
 210 \&      if ( $self\->country_of_residence eq 'USA' ) {
 211 \&          die 'All US residents must have an SSN'
 212 \&              unless $self\->has_ssn;
 213 \&      }
 214 \&  }
 215 .Ve
 216 .PP
 217 Another use of a \f(CW\*(C`BUILD\*(C'\fR method could be for logging or tracking
 218 object creation.
 219 .PP
 220 .Vb 2
 221 \&  sub BUILD {
 222 \&      my $self = shift;
 223 .Ve
 224 .PP
 225 .Vb 2
 226 \&      debug( 'Made a new person \- SSN = ', $self\->ssn, );
 227 \&  }
 228 .Ve
 229 .PP
 230 Note that while it is not shown here, the \f(CW\*(C`BUILD\*(C'\fR method receives
 231 not only the created object, but also a hashref of the original
 232 arguments passed to new (or the results of your \f(CW\*(C`BUILDARGS\*(C'\fR,
 233 if you have overridden the default \f(CW\*(C`BUILDARGS\*(C'\fR.)  This can be
 234 useful if you need to venture beyond what the default
 235 initialization behavior and coercions can accomplish.
 236 .PP
 237 \fI\s-1BUILD\s0 and parent classes\fR
 238 .IX Subsection "BUILD and parent classes"
 239 .PP
 240 The interaction between multiple \f(CW\*(C`BUILD\*(C'\fR methods in an inheritance
 241 hierarchy is different from normal Perl methods. \fBYou should never
 242 call \f(CB\*(C`$self\->SUPER::BUILD\*(C'\fB.\fR
 243 .PP
 244 Moose arranges to have all of the \f(CW\*(C`BUILD\*(C'\fR methods in a hierarchy
 245 called when an object is constructed, \fIfrom parents to
 246 children\fR. This might be surprising at first, because it reverses the
 247 normal order of method inheritance.
 248 .PP
 249 The theory behind this is that \f(CW\*(C`BUILD\*(C'\fR methods can only be used for
 250 increasing specialization of a class's constraints, so it makes sense
 251 to call the least specific \f(CW\*(C`BUILD\*(C'\fR method first. Also, this is how
 252 Perl 6 does it.
 253 .SH "OBJECT DESTRUCTION"
 254 .IX Header "OBJECT DESTRUCTION"
 255 Moose provides a hook for object destruction with the \f(CW\*(C`DEMOLISH\*(C'\fR
 256 method. As with \f(CW\*(C`BUILD\*(C'\fR, you should never explicitly call \f(CW\*(C`$self\->SUPER::DEMOLISH\*(C'\fR. Moose will arrange for all of the
 257 \&\f(CW\*(C`DEMOLISH\*(C'\fR methods in your hierarchy to be called, from most to least
 258 specific.
 259 .PP
 260 Each \f(CW\*(C`DEMOLISH\*(C'\fR method is called with a single argument.
 261 .PP
 262 In most cases, Perl's built-in garbage collection is sufficient, and
 263 you won't need to provide a \f(CW\*(C`DEMOLISH\*(C'\fR method.
 264 .Sh "Error Handling During Destruction"
 265 .IX Subsection "Error Handling During Destruction"
 266 The interaction of object destruction and Perl's global \f(CW$@\fR and \f(CW$?\fR
 267 variables can be very confusing.
 268 .PP
 269 Moose always localizes \f(CW$?\fR when an object is being destroyed. This means
 270 that if you explicitly call \f(CW\*(C`exit\*(C'\fR, that exit code will be preserved even if
 271 an object's destructor makes a system call.
 272 .PP
 273 Moose also preserves \f(CW$@\fR against any \f(CW\*(C`eval\*(C'\fR calls that may happen during
 274 object destruction. However, if an object's \f(CW\*(C`DEMOLISH\*(C'\fR method actually dies,
 275 Moose explicitly rethrows that error.
 276 .PP
 277 If you do not like this behavior, you will have to provide your own \f(CW\*(C`DESTROY\*(C'\fR
 278 method and use that instead of the one provided by Moose::Object. You can
 279 do this to preserve \f(CW$@\fR \fIand\fR capture any errors from object destruction by
 280 creating an error stack.
 281 .SH "AUTHOR"
 282 .IX Header "AUTHOR"
 283 Dave Rolsky <autarch@urth.org>
 284 .SH "COPYRIGHT AND LICENSE"
 285 .IX Header "COPYRIGHT AND LICENSE"
 286 Copyright 2009 by Infinity Interactive, Inc.
 287 .PP
 288 <http://www.iinteractive.com>
 289 .PP
 290 This library is free software; you can redistribute it and/or modify
 291 it under the same terms as Perl itself.