local-lib5/man/man3/Moose::Manual::Classes.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::Classes 3"
 132 .TH Moose::Manual::Classes 3 "2009-09-12" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Moose::Manual::Classes \- Making your classes use Moose (and subclassing)
 135 .SH "USING MOOSE"
 136 .IX Header "USING MOOSE"
 137 Using Moose is very simple, you just \f(CW\*(C`use Moose\*(C'\fR:
 138 .PP
 139 .Vb 1
 140 \&  package Person;
 141 .Ve
 142 .PP
 143 .Vb 1
 144 \&  use Moose;
 145 .Ve
 146 .PP
 147 That's it, you've made a class with Moose!
 148 .PP
 149 There's actually a lot going on here under the hood, so let's step
 150 through it.
 151 .PP
 152 When you load Moose, a bunch of sugar functions are exported into
 153 your class. These include things like \f(CW\*(C`extends\*(C'\fR, \f(CW\*(C`has\*(C'\fR, \f(CW\*(C`with\*(C'\fR, and
 154 more. These functions are what you use to define your class. For
 155 example, you might define an attribute ...
 156 .PP
 157 .Vb 1
 158 \&  package Person;
 159 .Ve
 160 .PP
 161 .Vb 1
 162 \&  use Moose;
 163 .Ve
 164 .PP
 165 .Vb 1
 166 \&  has 'ssn' => ( is => 'rw' );
 167 .Ve
 168 .PP
 169 Attributes are described in the Moose::Manual::Attributes
 170 documentation.
 171 .PP
 172 Loading Moose also enables \f(CW\*(C`strict\*(C'\fR and \f(CW\*(C`warnings\*(C'\fR pragmas in your
 173 class.
 174 .PP
 175 When you load Moose, your class will become a subclass of
 176 Moose::Object. The Moose::Object class provides a default
 177 constructor and destructor, as well as object construction helper
 178 methods. You can read more about this in the
 179 Moose::Manual::Construction document.
 180 .PP
 181 As a convenience, Moose creates a new class type for your class. See
 182 the Moose::Manual::Types document to learn more about types.
 183 .PP
 184 It also creates a Moose::Meta::Class object for your class. This
 185 metaclass object is now available by calling a \f(CW\*(C`meta\*(C'\fR method on your
 186 class, for example \f(CW\*(C`Person\->meta\*(C'\fR.
 187 .PP
 188 The metaclass object provides an introspection \s-1API\s0 for your class. It
 189 is also used by Moose itself under the hood to add attributes, define
 190 parent classes, and so on. In fact, all of Moose's sugar does the real
 191 work by calling methods on this metaclass object (and other meta \s-1API\s0
 192 objects).
 193 .SH "SUBCLASSING"
 194 .IX Header "SUBCLASSING"
 195 Moose provides a simple sugar function for declaring your parent
 196 classes, \f(CW\*(C`extends\*(C'\fR:
 197 .PP
 198 .Vb 1
 199 \&  package User;
 200 .Ve
 201 .PP
 202 .Vb 1
 203 \&  use Moose;
 204 .Ve
 205 .PP
 206 .Vb 1
 207 \&  extends 'Person';
 208 .Ve
 209 .PP
 210 .Vb 1
 211 \&  has 'username' => ( is => 'rw' );
 212 .Ve
 213 .PP
 214 Note that each call to \f(CW\*(C`extends\*(C'\fR will \fIreset\fR your parents. For
 215 multiple inheritance you must provide all the parents at once,
 216 \&\f(CW\*(C`extends 'Foo', 'Bar'\*(C'\fR.
 217 .PP
 218 You can use Moose to extend a non-Moose parent. However, when you do
 219 this, you will inherit the parent class's constructor (assuming it is
 220 also called \f(CW\*(C`new\*(C'\fR). In that case, you will have to take care of
 221 initializing attributes manually, either in the parent's constructor,
 222 or in your subclass, and you will lose a lot of Moose magic.
 223 .SH "NO MOOSE"
 224 .IX Header "NO MOOSE"
 225 Moose also allows you to remove its sugar functions from your class's
 226 namespace. We recommend that you take advantage of this feature, since
 227 it just makes your classes \*(L"cleaner\*(R". You can do this by simply adding
 228 \&\f(CW\*(C`no Moose\*(C'\fR at the end of your module file.
 229 .PP
 230 .Vb 1
 231 \&  package Person;
 232 .Ve
 233 .PP
 234 .Vb 1
 235 \&  use Moose;
 236 .Ve
 237 .PP
 238 .Vb 1
 239 \&  has 'ssn' => ( is => 'rw' );
 240 .Ve
 241 .PP
 242 .Vb 1
 243 \&  no Moose;
 244 .Ve
 245 .PP
 246 This deletes Moose's sugar functions from your class's namespace, so
 247 that \f(CW\*(C`Person\->can('has')\*(C'\fR will no longer return true.
 248 .PP
 249 A more generic way to unimport not only Moose's exports but also
 250 those from type libraries and other modules is to use
 251 namespace::clean or namespace::autoclean.
 252 .SH "MAKING IT FASTER"
 253 .IX Header "MAKING IT FASTER"
 254 Moose has a feature called \*(L"immutabilization\*(R" that you can use to
 255 greatly speed up your classes at runtime. However, using it does incur
 256 a cost when your class is first being loaded. When you make your class
 257 immutable you tell Moose that you will not be changing it in the
 258 future. You will not be adding any more attributes, methods, roles, etc.
 259 .PP
 260 This allows Moose to generate code specific to your class. In
 261 particular, it creates an \*(L"inline\*(R" constructor, making object
 262 construction much faster.
 263 .PP
 264 To make your class immutable you simply call \f(CW\*(C`make_immutable\*(C'\fR on your
 265 class's metaclass object.
 266 .PP
 267 .Vb 1
 268 \&  __PACKAGE__\->meta\->make_immutable;
 269 .Ve
 270 .ie n .Sh "Immutabilization and ""new()"""
 271 .el .Sh "Immutabilization and \f(CWnew()\fP"
 272 .IX Subsection "Immutabilization and new()"
 273 If you override \f(CW\*(C`new()\*(C'\fR in your class, then the immutabilization code
 274 will not be able to provide an optimized constructor for your
 275 class. Instead, you should use a \f(CW\*(C`BUILD()\*(C'\fR method, which will be
 276 called from the inlined constructor.
 277 .PP
 278 Alternately, if you really need to provide a different \f(CW\*(C`new()\*(C'\fR, you
 279 can also provide your own immutabilization method. Doing so requires
 280 extending the Moose metaclasses, and is well beyond the scope of this
 281 manual.
 282 .SH "AUTHOR"
 283 .IX Header "AUTHOR"
 284 Dave Rolsky <autarch@urth.org>
 285 .SH "COPYRIGHT AND LICENSE"
 286 .IX Header "COPYRIGHT AND LICENSE"
 287 Copyright 2008\-2009 by Infinity Interactive, Inc.
 288 .PP
 289 <http://www.iinteractive.com>
 290 .PP
 291 This library is free software; you can redistribute it and/or modify
 292 it under the same terms as Perl itself.