.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.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.  \*(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-
.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\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" 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::Classes 3pm"
.TH Moose::Manual::Classes 3pm "2012-06-28" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Moose::Manual::Classes \- Making your classes use Moose (and subclassing)
.SH "VERSION"
.IX Header "VERSION"
version 2.0603
.SH "USING MOOSE"
.IX Header "USING MOOSE"
Using Moose is very simple, you just \f(CW\*(C`use Moose\*(C'\fR:
.PP
.Vb 1
\&  package Person;
\&
\&  use Moose;
.Ve
.PP
That's it, you've made a class with Moose!
.PP
There's actually a lot going on here under the hood, so let's step
through it.
.PP
When you load Moose, a bunch of sugar functions are exported into your
class, such as \f(CW\*(C`extends\*(C'\fR, \f(CW\*(C`has\*(C'\fR, \f(CW\*(C`with\*(C'\fR, and more. These functions are what
you use to define your class. For example, you might define an attribute ...
.PP
.Vb 1
\&  package Person;
\&
\&  use Moose;
\&
\&  has \*(Aqssn\*(Aq => ( is => \*(Aqrw\*(Aq );
.Ve
.PP
Attributes are described in the Moose::Manual::Attributes
documentation.
.PP
Loading Moose also enables the \f(CW\*(C`strict\*(C'\fR and \f(CW\*(C`warnings\*(C'\fR pragmas in your
class.
.PP
When you load Moose, your class will become a subclass of
Moose::Object. The Moose::Object class provides a default
constructor and destructor, as well as object construction helper
methods. You can read more about this in the
Moose::Manual::Construction document.
.PP
As a convenience, Moose creates a new class type for your class. See
the Moose::Manual::Types document to learn more about types.
.PP
It also creates a Moose::Meta::Class object for your class. This
metaclass object is now available by calling a \f(CW\*(C`meta\*(C'\fR method on your
class, for example \f(CW\*(C`Person\->meta\*(C'\fR.
.PP
The metaclass object provides an introspection \s-1API\s0 for your class. It
is also used by Moose itself under the hood to add attributes, define
parent classes, and so on. In fact, all of Moose's sugar does the real
work by calling methods on this metaclass object (and other meta \s-1API\s0
objects).
.SH "SUBCLASSING"
.IX Header "SUBCLASSING"
Moose provides a simple sugar function for declaring your parent
classes, \f(CW\*(C`extends\*(C'\fR:
.PP
.Vb 1
\&  package User;
\&
\&  use Moose;
\&
\&  extends \*(AqPerson\*(Aq;
\&
\&  has \*(Aqusername\*(Aq => ( is => \*(Aqrw\*(Aq );
.Ve
.PP
Note that each call to \f(CW\*(C`extends\*(C'\fR will \fIreset\fR your parents. For
multiple inheritance you must provide all the parents at once,
\&\f(CW\*(C`extends \*(AqFoo\*(Aq, \*(AqBar\*(Aq\*(C'\fR.
.PP
You can use Moose to extend a non-Moose parent. However, when you do
this, you will inherit the parent class's constructor (assuming it is
also called \f(CW\*(C`new\*(C'\fR). In that case, you will have to take care of
initializing attributes manually, either in the parent's constructor,
or in your subclass, and you will lose a lot of Moose magic.
.PP
See the MooseX::NonMoose module on \s-1CPAN\s0 if you're interested in extending
non-Moose parent classes with Moose child classes.
.SH "CLEANING UP MOOSE DROPPINGS"
.IX Header "CLEANING UP MOOSE DROPPINGS"
Moose exports a number of functions into your class. It's a good idea to
remove these sugar functions from your class's namespace, so that \f(CW\*(C`Person\->can(\*(Aqhas\*(Aq)\*(C'\fR will no longer return true.
.PP
There are several ways to do this. We recommend using namespace::autoclean,
a \s-1CPAN\s0 module. Not only will it remove Moose exports, it will also remove
any other exports.
.PP
.Vb 1
\&  package Person;
\&
\&  use namespace::autoclean;
\&
\&  use Moose;
.Ve
.PP
If you absolutely can't use a \s-1CPAN\s0 module (but can use Moose?), you can write
\&\f(CW\*(C`no Moose\*(C'\fR at the end of your class. This will remove any Moose exports in
your class.
.PP
.Vb 1
\&  package Person;
\&
\&  use Moose;
\&
\&  has \*(Aqssn\*(Aq => ( is => \*(Aqrw\*(Aq );
\&
\&  no Moose;
.Ve
.SH "MAKING IT FASTER"
.IX Header "MAKING IT FASTER"
Moose has a feature called \*(L"immutabilization\*(R" that you can use to
greatly speed up your classes at runtime. However, using it incurs
a cost when your class is first being loaded. When you make your class
immutable you tell Moose that you will not be changing it in the
future. You will not be adding any more attributes, methods, roles, etc.
.PP
This allows Moose to generate code specific to your class. In
particular, it creates an \*(L"inline\*(R" constructor, making object
construction much faster.
.PP
To make your class immutable you simply call \f(CW\*(C`make_immutable\*(C'\fR on your
class's metaclass object.
.PP
.Vb 1
\&  _\|_PACKAGE_\|_\->meta\->make_immutable;
.Ve
.ie n .SS "Immutabilization and ""new()"""
.el .SS "Immutabilization and \f(CWnew()\fP"
.IX Subsection "Immutabilization and new()"
If you override \f(CW\*(C`new()\*(C'\fR in your class, then the immutabilization code
will not be able to provide an optimized constructor for your
class. Instead, you should use a \f(CW\*(C`BUILD()\*(C'\fR method, which will be
called from the inlined constructor.
.PP
Alternately, if you really need to provide a different \f(CW\*(C`new()\*(C'\fR, you
can also provide your own immutabilization method. Doing so requires
extending the Moose metaclasses, and is well beyond the scope of this
manual.
.SH "AUTHOR"
.IX Header "AUTHOR"
Moose is maintained by the Moose Cabal, along with the help of many contributors. See \*(L"\s-1CABAL\s0\*(R" in Moose and \*(L"\s-1CONTRIBUTORS\s0\*(R" in Moose for details.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2012 by Infinity Interactive, Inc..
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.