Add built local::lib

[catagits/Gitalist.git] / local-lib5 / man / man3 / Moose::Manual::Construction.3pm

.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Moose::Manual::Construction 3"
.TH Moose::Manual::Construction 3 "2009-09-12" "perl v5.8.7" "User Contributed Perl Documentation"
.SH "NAME"
Moose::Manual::Construction \- Object construction (and destruction) with Moose
.SH "WHERE'S THE CONSTRUCTOR?"
.IX Header "WHERE'S THE CONSTRUCTOR?"
\&\fBDo not define a \f(CB\*(C`new()\*(C'\fB method for your classes!\fR
.PP
When you \f(CW\*(C`use Moose\*(C'\fR in your class, you will become a subclass of
Moose::Object, which provides a \f(CW\*(C`new\*(C'\fR method for you. If you
follow our recommendations in Moose::Manual::BestPractices and make
your class immutable, then you actually get a class-specific \f(CW\*(C`new\*(C'\fR
method \*(L"inlined\*(R" in your class.
.SH "OBJECT CONSTRUCTION AND ATTRIBUTES"
.IX Header "OBJECT CONSTRUCTION AND ATTRIBUTES"
The Moose-provided constructor accepts a hash or hash reference of
named parameters matching your attributes (actually, matching their
\&\f(CW\*(C`init_arg\*(C'\fRs). This is just another way in which Moose keeps you from
worrying \fIhow\fR classes are implemented. Simply define a class and
you're ready to start creating objects!
.SH "OBJECT CONSTRUCTION HOOKS"
.IX Header "OBJECT CONSTRUCTION HOOKS"
Moose lets you hook into object construction. You can validate an
object's state, do logging, or maybe allow non\-hash(ref) constructor
arguments. You can do this by creating \f(CW\*(C`BUILD\*(C'\fR and/or \f(CW\*(C`BUILDARGS\*(C'\fR
methods.
.PP
If these methods exist in your class, Moose will arrange for them to
be called as part of the object construction process.
.Sh "\s-1BUILDARGS\s0"
.IX Subsection "BUILDARGS"
The \f(CW\*(C`BUILDARGS\*(C'\fR method is called as a class method \fIbefore\fR an
object is created. It will receive all of the arguments that were
passed to \f(CW\*(C`new\*(C'\fR \fIas-is\fR, and is expected to return a hash
reference. This hash reference will be used to construct the object,
so it should contain keys matching your attributes' names (well,
\&\f(CW\*(C`init_arg\*(C'\fRs).
.PP
One common use for \f(CW\*(C`BUILDARGS\*(C'\fR is to accommodate a non\-hash(ref)
calling style. For example, we might want to allow our Person class to
be called with a single argument of a social security number, \f(CW\*(C`Person\->new($ssn)\*(C'\fR.
.PP
Without a \f(CW\*(C`BUILDARGS\*(C'\fR method, Moose will complain, because it expects
a hash or hash reference. We can use the \f(CW\*(C`BUILDARGS\*(C'\fR method to
accommodate this calling style:
.PP
.Vb 3
\&  around BUILDARGS => sub {
\&      my $orig = shift;
\&      my $class = shift;
.Ve
.PP
.Vb 7
\&      if ( @_ == 1 && ! ref $_[0] ) {
\&          return $class\->$orig(ssn => $_[0]);
\&      }
\&      else {
\&          return $class\->$orig(@_);
\&      }
\&  };
.Ve
.PP
Note the call to \f(CW\*(C`$class\->$orig\*(C'\fR. This will call the default
\&\f(CW\*(C`BUILDARGS\*(C'\fR in Moose::Object. This method handles distinguishing
between a hash reference and a plain hash for you.
.Sh "\s-1BUILD\s0"
.IX Subsection "BUILD"
The \f(CW\*(C`BUILD\*(C'\fR method is called \fIafter\fR an object is created. There are
several ways to use a \f(CW\*(C`BUILD\*(C'\fR method. One of the most common is to
check that the object state is valid. While we can validate individual
attributes through the use of types, we can't validate the state of a
whole object that way.
.PP
.Vb 2
\&  sub BUILD {
\&      my $self = shift;
.Ve
.PP
.Vb 5
\&      if ( $self\->country_of_residence eq 'USA' ) {
\&          die 'All US residents must have an SSN'
\&              unless $self\->has_ssn;
\&      }
\&  }
.Ve
.PP
Another use of a \f(CW\*(C`BUILD\*(C'\fR method could be for logging or tracking
object creation.
.PP
.Vb 2
\&  sub BUILD {
\&      my $self = shift;
.Ve
.PP
.Vb 2
\&      debug( 'Made a new person \- SSN = ', $self\->ssn, );
\&  }
.Ve
.PP
Note that while it is not shown here, the \f(CW\*(C`BUILD\*(C'\fR method receives  
not only the created object, but also a hashref of the original 
arguments passed to new (or the results of your \f(CW\*(C`BUILDARGS\*(C'\fR, 
if you have overridden the default \f(CW\*(C`BUILDARGS\*(C'\fR.)  This can be 
useful if you need to venture beyond what the default 
initialization behavior and coercions can accomplish.
.PP
\fI\s-1BUILD\s0 and parent classes\fR
.IX Subsection "BUILD and parent classes"
.PP
The interaction between multiple \f(CW\*(C`BUILD\*(C'\fR methods in an inheritance
hierarchy is different from normal Perl methods. \fBYou should never
call \f(CB\*(C`$self\->SUPER::BUILD\*(C'\fB.\fR
.PP
Moose arranges to have all of the \f(CW\*(C`BUILD\*(C'\fR methods in a hierarchy
called when an object is constructed, \fIfrom parents to
children\fR. This might be surprising at first, because it reverses the
normal order of method inheritance.
.PP
The theory behind this is that \f(CW\*(C`BUILD\*(C'\fR methods can only be used for
increasing specialization of a class's constraints, so it makes sense
to call the least specific \f(CW\*(C`BUILD\*(C'\fR method first. Also, this is how
Perl 6 does it.
.SH "OBJECT DESTRUCTION"
.IX Header "OBJECT DESTRUCTION"
Moose provides a hook for object destruction with the \f(CW\*(C`DEMOLISH\*(C'\fR
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
\&\f(CW\*(C`DEMOLISH\*(C'\fR methods in your hierarchy to be called, from most to least
specific.
.PP
Each \f(CW\*(C`DEMOLISH\*(C'\fR method is called with a single argument.
.PP
In most cases, Perl's built-in garbage collection is sufficient, and
you won't need to provide a \f(CW\*(C`DEMOLISH\*(C'\fR method.
.Sh "Error Handling During Destruction"
.IX Subsection "Error Handling During Destruction"
The interaction of object destruction and Perl's global \f(CW$@\fR and \f(CW$?\fR
variables can be very confusing.
.PP
Moose always localizes \f(CW$?\fR when an object is being destroyed. This means
that if you explicitly call \f(CW\*(C`exit\*(C'\fR, that exit code will be preserved even if
an object's destructor makes a system call.
.PP
Moose also preserves \f(CW$@\fR against any \f(CW\*(C`eval\*(C'\fR calls that may happen during
object destruction. However, if an object's \f(CW\*(C`DEMOLISH\*(C'\fR method actually dies,
Moose explicitly rethrows that error.
.PP
If you do not like this behavior, you will have to provide your own \f(CW\*(C`DESTROY\*(C'\fR
method and use that instead of the one provided by Moose::Object. You can
do this to preserve \f(CW$@\fR \fIand\fR capture any errors from object destruction by
creating an error stack.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dave Rolsky <autarch@urth.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2009 by Infinity Interactive, Inc.
.PP
<http://www.iinteractive.com>
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.