local-lib5/man/man3/Moose::Manual.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 3"
 132 .TH Moose::Manual 3 "2009-07-13" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Moose::Manual \- What is Moose, and how do I use it?
 135 .SH "WHAT IS MOOSE?"
 136 .IX Header "WHAT IS MOOSE?"
 137 Moose is a \fIcomplete\fR object system for Perl 5. Consider any modern
 138 object-oriented language (which Perl 5 definitely isn't). It provides
 139 keywords for attribute declaration, object construction, inheritance,
 140 and maybe more. These keywords are part of the language, and you don't
 141 care how they are implemented.
 142 .PP
 143 Moose aims to do the same thing for Perl 5 \s-1OO\s0. We can't actually
 144 create new keywords, but we do offer \*(L"sugar\*(R" that looks a lot like
 145 them. More importantly, with Moose, you \fIdefine your class
 146 declaratively\fR, without needing to know about blessed hashrefs,
 147 accessor methods, and so on.
 148 .PP
 149 With Moose, you can concentrate on the \fIlogical\fR structure of your
 150 classes, focusing on \*(L"what\*(R" rather than \*(L"how\*(R". A class definition with
 151 Moose reads like a list of very concise English sentences.
 152 .PP
 153 Moose is built on top of \f(CW\*(C`Class::MOP\*(C'\fR, a meta-object protocol (aka
 154 \&\s-1MOP\s0). Using the \s-1MOP\s0, Moose provides complete introspection for all
 155 Moose-using classes. This means you can ask classes about their
 156 attributes, parents, children, methods, etc., all using a well-defined
 157 \&\s-1API\s0. The \s-1MOP\s0 abstracts away the symbol table, looking at \f(CW@ISA\fR vars,
 158 and all the other crufty Perl tricks we know and love(?).
 159 .PP
 160 Moose is based in large part on the Perl 6 object system, as well as
 161 drawing on the best ideas from \s-1CLOS\s0, Smalltalk, and many other
 162 languages.
 163 .SH "WHY MOOSE?"
 164 .IX Header "WHY MOOSE?"
 165 Moose makes Perl 5 \s-1OO\s0 both simpler and more powerful. It encapsulates
 166 Perl 5 power tools in high-level declarative APIs which are easy to
 167 use. Best of all, you don't need to be a wizard to use it.
 168 .PP
 169 But if you want to dig about in the guts, Moose lets you do that too,
 170 by using and extending its powerful introspection \s-1API\s0.
 171 .SH "AN EXAMPLE"
 172 .IX Header "AN EXAMPLE"
 173 .Vb 1
 174 \&  package Person;
 175 .Ve
 176 .PP
 177 .Vb 1
 178 \&  use Moose;
 179 .Ve
 180 .PP
 181 .Vb 4
 182 \&  has 'first_name' => (
 183 \&      is  => 'rw',
 184 \&      isa => 'Str',
 185 \&  );
 186 .Ve
 187 .PP
 188 .Vb 4
 189 \&  has 'last_name' => (
 190 \&      is  => 'rw',
 191 \&      isa => 'Str',
 192 \&  );
 193 .Ve
 194 .PP
 195 .Vb 2
 196 \&  no Moose;
 197 \&  __PACKAGE__\->meta\->make_immutable;
 198 .Ve
 199 .PP
 200 This is a \fIcomplete and usable\fR class definition!
 201 .PP
 202 .Vb 1
 203 \&  package User;
 204 .Ve
 205 .PP
 206 .Vb 2
 207 \&  use DateTime;
 208 \&  use Moose;
 209 .Ve
 210 .PP
 211 .Vb 1
 212 \&  extends 'Person';
 213 .Ve
 214 .PP
 215 .Vb 4
 216 \&  has 'password' => (
 217 \&      is  => 'rw',
 218 \&      isa => 'Str',
 219 \&  );
 220 .Ve
 221 .PP
 222 .Vb 5
 223 \&  has 'last_login' => (
 224 \&      is      => 'rw',
 225 \&      isa     => 'DateTime',
 226 \&      handles => { 'date_of_last_login' => 'date' },
 227 \&  );
 228 .Ve
 229 .PP
 230 .Vb 3
 231 \&  sub login {
 232 \&      my $self = shift;
 233 \&      my $pw   = shift;
 234 .Ve
 235 .PP
 236 .Vb 1
 237 \&      return 0 if $pw ne $self\->password;
 238 .Ve
 239 .PP
 240 .Vb 1
 241 \&      $self\->last_login( DateTime\->now() );
 242 .Ve
 243 .PP
 244 .Vb 2
 245 \&      return 1;
 246 \&  }
 247 .Ve
 248 .PP
 249 .Vb 2
 250 \&  no Moose;
 251 \&  __PACKAGE__\->meta\->make_immutable;
 252 .Ve
 253 .PP
 254 We'll leave the line-by-line explanation of this code to other
 255 documentation, but you can see how Moose reduces common \s-1OO\s0 idioms to
 256 simple declarative constructs.
 257 .SH "TABLE OF CONTENTS"
 258 .IX Header "TABLE OF CONTENTS"
 259 This manual consists of a number of documents.
 260 .IP "Moose::Manual::Concepts" 4
 261 .IX Item "Moose::Manual::Concepts"
 262 Introduces Moose concepts, and contrasts them against \*(L"old school\*(R"
 263 Perl 5 \s-1OO\s0.
 264 .IP "Moose::Manual::Unsweetened" 4
 265 .IX Item "Moose::Manual::Unsweetened"
 266 Shows two example classes, each written first with Moose and then with
 267 \&\*(L"plain old Perl 5\*(R".
 268 .IP "Moose::Manual::Classes" 4
 269 .IX Item "Moose::Manual::Classes"
 270 How do you make use of Moose in your classes? Now that I'm a Moose,
 271 how do I subclass something?
 272 .IP "Moose::Manual::Attributes" 4
 273 .IX Item "Moose::Manual::Attributes"
 274 Attributes are a core part of the Moose \s-1OO\s0 system. An attribute is a
 275 piece of data that an object has. Moose has a lot of attribute-related
 276 features!
 277 .IP "Moose::Manual::Delegation" 4
 278 .IX Item "Moose::Manual::Delegation"
 279 Delegation is a powerful way to make use of attributes which are
 280 themselves objects.
 281 .IP "Moose::Manual::Construction" 4
 282 .IX Item "Moose::Manual::Construction"
 283 Learn how objects are built in Moose, and in particular about the
 284 \&\f(CW\*(C`BUILD\*(C'\fR and \f(CW\*(C`BUILDARGS\*(C'\fR methods. Also covers object destruction
 285 with \f(CW\*(C`DEMOLISH\*(C'\fR.
 286 .IP "Moose::Manual::MethodModifiers" 4
 287 .IX Item "Moose::Manual::MethodModifiers"
 288 A method modifier lets you say \*(L"before calling method X, do this
 289 first\*(R", or \*(L"wrap method X in this code\*(R". Method modifiers are
 290 particularly handy in roles and with attribute accessors.
 291 .IP "Moose::Manual::Roles" 4
 292 .IX Item "Moose::Manual::Roles"
 293 A role is something a class does (like \*(L"Debuggable\*(R" or
 294 \&\*(L"Printable\*(R"). Roles provide a way of adding behavior to classes that
 295 is orthogonal to inheritance.
 296 .IP "Moose::Manual::Types" 4
 297 .IX Item "Moose::Manual::Types"
 298 Moose's type system lets you strictly define what values an attribute
 299 can contain.
 300 .IP "Moose::Manual::MOP" 4
 301 .IX Item "Moose::Manual::MOP"
 302 Moose's meta \s-1API\s0 system lets you ask classes about their parents,
 303 children, methods, attributes, etc.
 304 .IP "Moose::Manual::MooseX" 4
 305 .IX Item "Moose::Manual::MooseX"
 306 This document describes a few of the most useful Moose extensions on
 307 \&\s-1CPAN\s0.
 308 .IP "Moose::Manual::BestPractices" 4
 309 .IX Item "Moose::Manual::BestPractices"
 310 Moose has a lot of features, and there's definitely more than one way
 311 to do it. However, we think that picking a subset of these features
 312 and using them consistently makes everyone's life easier.
 313 .IP "Moose::Manual::FAQ" 4
 314 .IX Item "Moose::Manual::FAQ"
 315 Frequently asked questions about Moose.
 316 .IP "Moose::Manual::Contributing" 4
 317 .IX Item "Moose::Manual::Contributing"
 318 Interested in hacking on Moose? Read this.
 319 .IP "Moose::Manual::Delta" 4
 320 .IX Item "Moose::Manual::Delta"
 321 This document details backwards-incompatibilities and other major
 322 changes to Moose.
 323 .SH "JUSTIFICATION"
 324 .IX Header "JUSTIFICATION"
 325 If you're still asking yourself \*(L"Why do I need this?\*(R", then this
 326 section is for you.
 327 .IP "Another object system!?!?" 4
 328 .IX Item "Another object system!?!?"
 329 Yes, we know there are many, many ways to build objects in Perl 5,
 330 many of them based on inside-out objects and other such things. Moose
 331 is different because it is not a new object system for Perl 5, but
 332 instead an extension of the existing object system.
 333 .Sp
 334 Moose is built on top of Class::MOP, which is a metaclass system
 335 for Perl 5. This means that Moose not only makes building normal
 336 Perl 5 objects better, but it also provides the power of metaclass
 337 programming.
 338 .IP "Is this for real? Or is this just an experiment?" 4
 339 .IX Item "Is this for real? Or is this just an experiment?"
 340 Moose is \fIbased\fR on the prototypes and experiments Stevan did for the
 341 Perl 6 meta\-model. However, Moose is \fB\s-1NOT\s0\fR an experiment or
 342 prototype; it is for \fBreal\fR.
 343 .IP "Is this ready for use in production?" 4
 344 .IX Item "Is this ready for use in production?"
 345 Yes.
 346 .Sp
 347 Moose has been used successfully in production environments by many
 348 people and companies. There are Moose applications which have been in
 349 production with little or no issue now for years. We consider it
 350 highly stable and we are committed to keeping it stable.
 351 .Sp
 352 Of course, in the end, you need to make this call yourself. If you
 353 have any questions or concerns, please feel free to email Stevan or
 354 the moose@perl.org list, or just stop by irc.perl.org#moose and ask
 355 away.
 356 .IP "Is Moose just Perl 6 in Perl 5?" 4
 357 .IX Item "Is Moose just Perl 6 in Perl 5?"
 358 No. While Moose is very much inspired by Perl 6, it is not itself Perl
 359 6. Instead, it is an \s-1OO\s0 system for Perl 5. Stevan built Moose because
 360 he was tired of writing the same old boring Perl 5 \s-1OO\s0 code, and
 361 drooling over Perl 6 \s-1OO\s0. So instead of switching to Ruby, he wrote
 362 Moose :)
 363 .IP "Wait, \fIpost\fR modern, I thought it was just \fImodern\fR?" 4
 364 .IX Item "Wait, post modern, I thought it was just modern?"
 365 Stevan read Larry Wall's talk from the 1999 Linux World entitled
 366 \&\*(L"Perl, the first postmodern computer language\*(R" in which he talks about
 367 how he picked the features for Perl because he thought they were cool
 368 and he threw out the ones that he thought sucked. This got him
 369 thinking about how we have done the same thing in Moose. For Moose, we
 370 have \*(L"borrowed\*(R" features from Perl 6, \s-1CLOS\s0 (\s-1LISP\s0), Smalltalk, Java,
 371 \&\s-1BETA\s0, OCaml, Ruby and more, and the bits we didn't like (cause they
 372 sucked) we tossed aside. So for this reason (and a few others) Stevan
 373 has re-dubbed Moose a \fIpostmodern\fR object system.
 374 .Sp
 375 Nuff Said.
 376 .SH "AUTHORS"
 377 .IX Header "AUTHORS"
 378 Dave Rolsky <autarch@urth.org>
 379 .PP
 380 Stevan Little <stevan@iinteractive.com>
 381 .SH "COPYRIGHT AND LICENSE"
 382 .IX Header "COPYRIGHT AND LICENSE"
 383 Copyright 2008\-2009 by Infinity Interactive, Inc.
 384 .PP
 385 <http://www.iinteractive.com>
 386 .PP
 387 This library is free software; you can redistribute it and/or modify
 388 it under the same terms as Perl itself.