local-lib5/man/man3/Moose::Cookbook::Basics::Recipe1.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::Cookbook::Basics::Recipe1 3"
 132 .TH Moose::Cookbook::Basics::Recipe1 3 "2009-05-01" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Moose::Cookbook::Basics::Recipe1 \- The (always classic) \fBPoint\fR example.
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 2
 138 \&  package Point;
 139 \&  use Moose;
 140 .Ve
 141 .PP
 142 .Vb 2
 143 \&  has 'x' => (isa => 'Int', is => 'rw', required => 1);
 144 \&  has 'y' => (isa => 'Int', is => 'rw', required => 1);
 145 .Ve
 146 .PP
 147 .Vb 5
 148 \&  sub clear {
 149 \&      my $self = shift;
 150 \&      $self\->x(0);
 151 \&      $self\->y(0);
 152 \&  }
 153 .Ve
 154 .PP
 155 .Vb 2
 156 \&  package Point3D;
 157 \&  use Moose;
 158 .Ve
 159 .PP
 160 .Vb 1
 161 \&  extends 'Point';
 162 .Ve
 163 .PP
 164 .Vb 1
 165 \&  has 'z' => (isa => 'Int', is => 'rw', required => 1);
 166 .Ve
 167 .PP
 168 .Vb 4
 169 \&  after 'clear' => sub {
 170 \&      my $self = shift;
 171 \&      $self\->z(0);
 172 \&  };
 173 .Ve
 174 .PP
 175 .Vb 1
 176 \&  package main;
 177 .Ve
 178 .PP
 179 .Vb 3
 180 \&  # hash or hashrefs are ok for the constructor
 181 \&  my $point1 = Point\->new(x => 5, y => 7);
 182 \&  my $point2 = Point\->new({x => 5, y => 7});
 183 .Ve
 184 .PP
 185 .Vb 1
 186 \&  my $point3d = Point3D\->new(x => 5, y => 42, z => \-5);
 187 .Ve
 188 .SH "DESCRIPTION"
 189 .IX Header "DESCRIPTION"
 190 This is the classic Point example. It is taken directly from the Perl
 191 6 Apocalypse 12 document, and is similar to the example found in the
 192 classic K&R C book as well.
 193 .PP
 194 As with all Perl 5 classes, a Moose class is defined in a package.
 195 Moose handles turning on \f(CW\*(C`strict\*(C'\fR and \f(CW\*(C`warnings\*(C'\fR for us, so all we
 196 need to do is say \f(CW\*(C`use Moose\*(C'\fR, and no kittens will die.
 197 .PP
 198 When Moose is loaded, it exports a set of sugar functions into our
 199 package. This means that we import some functions which serve as Moose
 200 \&\*(L"keywords\*(R". These aren't real language keywords, they're just Perl
 201 functions exported into our package.
 202 .PP
 203 Moose automatically makes our package a subclass of Moose::Object.
 204 The Moose::Object class provides us with a constructor that
 205 respects our attributes, as well other features. See Moose::Object
 206 for details.
 207 .PP
 208 Now, onto the keywords. The first one we see here is \f(CW\*(C`has\*(C'\fR, which
 209 defines an instance attribute in our class:
 210 .PP
 211 .Vb 1
 212 \&  has 'x' => (isa => 'Int', is => 'rw', required => 1);
 213 .Ve
 214 .PP
 215 This will create an attribute named \f(CW\*(C`x\*(C'\fR. The \f(CW\*(C`isa\*(C'\fR parameter says
 216 that we expect the value stored in this attribute to pass the type
 217 constraint for \f(CW\*(C`Int\*(C'\fR (1). The accessor generated for this attribute
 218 will be read\-write.
 219 .PP
 220 The \f(CW\*(C`requires => 1\*(C'\fR parameter means that this attribute must be
 221 provided when a new object is created. A point object without
 222 coordinates doesn't make much sense, so we don't allow it.
 223 .PP
 224 We have defined our attributes; next we define our methods. In Moose,
 225 as with regular Perl 5 \s-1OO\s0, a method is just a subroutine defined
 226 within the package:
 227 .PP
 228 .Vb 5
 229 \&  sub clear {
 230 \&      my $self = shift;
 231 \&      $self\->x(0);
 232 \&      $self\->y(0);
 233 \&  }
 234 .Ve
 235 .PP
 236 That concludes the \fBPoint\fR class.
 237 .PP
 238 Next we have a subclass of \fBPoint\fR, \fBPoint3D\fR. To declare our
 239 superclass, we use the Moose keyword \f(CW\*(C`extends\*(C'\fR:
 240 .PP
 241 .Vb 1
 242 \&  extends 'Point';
 243 .Ve
 244 .PP
 245 The \f(CW\*(C`extends\*(C'\fR keyword works much like \f(CW\*(C`use base\*(C'\fR. First, it will
 246 attempt to load your class if needed. However, unlike \f(CW\*(C`base\*(C'\fR, the
 247 \&\f(CW\*(C`extends\*(C'\fR keyword will \fIoverwrite\fR any previous values in your
 248 package's \f(CW@ISA\fR, where \f(CW\*(C`use base\*(C'\fR will \f(CW\*(C`push\*(C'\fR values onto the
 249 package's \f(CW@ISA\fR.
 250 .PP
 251 It is my opinion that the behavior of \f(CW\*(C`extends\*(C'\fR is more intuitive.
 252 (2).
 253 .PP
 254 Next we create a new attribute for \fBPoint3D\fR called \f(CW\*(C`z\*(C'\fR.
 255 .PP
 256 .Vb 1
 257 \&  has 'z' => (isa => 'Int', is => 'rw', required => 1);
 258 .Ve
 259 .PP
 260 This attribute is just like \fBPoint\fR's \f(CW\*(C`x\*(C'\fR and \f(CW\*(C`y\*(C'\fR attributes.
 261 .PP
 262 The \f(CW\*(C`after\*(C'\fR keyword demonstrates a Moose feature called \*(L"method
 263 modifiers\*(R" (or \*(L"advice\*(R" for the \s-1AOP\s0 inclined):
 264 .PP
 265 .Vb 4
 266 \&  after 'clear' => sub {
 267 \&      my $self = shift;
 268 \&      $self\->z(0);
 269 \&  };
 270 .Ve
 271 .PP
 272 When \f(CW\*(C`clear\*(C'\fR is called on a \fBPoint3D\fR object, our modifier method
 273 gets called as well. Unsurprisingly, the modifier is called \fIafter\fR
 274 the real method.
 275 .PP
 276 In this case, the real \f(CW\*(C`clear\*(C'\fR method is inherited from \fBPoint\fR. Our
 277 modifier method receives the same arguments as those passed to the
 278 modified method (just \f(CW$self\fR here).
 279 .PP
 280 Of course, using the \f(CW\*(C`after\*(C'\fR modifier is not the only way to
 281 accomplish this. This \fBis\fR Perl, right? You can get the same results
 282 with this code:
 283 .PP
 284 .Vb 5
 285 \&  sub clear {
 286 \&      my $self = shift;
 287 \&      $self\->SUPER::clear();
 288 \&      $self\->z(0);
 289 \&  }
 290 .Ve
 291 .PP
 292 You could also use another Moose method modifier, \f(CW\*(C`override\*(C'\fR:
 293 .PP
 294 .Vb 5
 295 \&  override 'clear' => sub {
 296 \&      my $self = shift;
 297 \&      super();
 298 \&      $self\->z(0);
 299 \&  };
 300 .Ve
 301 .PP
 302 The \f(CW\*(C`override\*(C'\fR modifier allows you to use the \f(CW\*(C`super\*(C'\fR keyword to
 303 dispatch to the superclass's method in a very Ruby-ish style.
 304 .PP
 305 The choice of whether to use a method modifier, and which one to use,
 306 is often a question of style as much as functionality.
 307 .PP
 308 Since \fBPoint\fR inherits from Moose::Object, it will also inherit
 309 the default Moose::Object constructor:
 310 .PP
 311 .Vb 2
 312 \&  my $point1 = Point\->new(x => 5, y => 7);
 313 \&  my $point2 = Point\->new({x => 5, y => 7});
 314 .Ve
 315 .PP
 316 .Vb 1
 317 \&  my $point3d = Point3D\->new(x => 5, y => 42, z => \-5);
 318 .Ve
 319 .PP
 320 The \f(CW\*(C`new\*(C'\fR constructor accepts a named argument pair for each
 321 attribute defined by the class, which you can provide as a hash or
 322 hash reference. In this particular example, the attributes are
 323 required, and calling \f(CW\*(C`new\*(C'\fR without them will throw an error.
 324 .PP
 325 .Vb 1
 326 \&  my $point = Point\->new( x => 5 ); # no y, kaboom!
 327 .Ve
 328 .PP
 329 From here on, we can use \f(CW$point\fR and \f(CW$point3d\fR just as you would
 330 any other Perl 5 object. For a more detailed example of what can be
 331 done, you can refer to the
 332 \&\fIt/000_recipes/moose_cookbook_basics_recipe1.t\fR test file.
 333 .Sh "Moose Objects are Just Hashrefs"
 334 .IX Subsection "Moose Objects are Just Hashrefs"
 335 While this all may appear rather magical, it's important to realize
 336 that Moose objects are just hash references under the hood (3). For
 337 example, you could pass \f(CW$self\fR to \f(CW\*(C`Data::Dumper\*(C'\fR and you'd get
 338 exactly what you'd expect.
 339 .PP
 340 You could even poke around inside the object's data structure, but
 341 that is strongly discouraged.
 342 .PP
 343 The fact that Moose objects are hashrefs means it is easy to use Moose
 344 to extend non-Moose classes, as long as they too are hash
 345 references. If you want to extend a non-hashref class, check out
 346 \&\f(CW\*(C`MooseX::InsideOut\*(C'\fR.
 347 .SH "CONCLUSION"
 348 .IX Header "CONCLUSION"
 349 This recipe demonstrates some basic Moose concepts, attributes,
 350 subclassing, and a simple method modifier.
 351 .SH "FOOTNOTES"
 352 .IX Header "FOOTNOTES"
 353 .IP "(1)" 4
 354 .IX Item "(1)"
 355 Moose provides a number of builtin type constraints are provided by,
 356 of which \f(CW\*(C`Int\*(C'\fR is one. For more information on the type constraint
 357 system, see Moose::Util::TypeConstraints.
 358 .IP "(2)" 4
 359 .IX Item "(2)"
 360 The \f(CW\*(C`extends\*(C'\fR keyword support multiple inheritance. Simply pass all
 361 of your superclasses to \f(CW\*(C`extends\*(C'\fR as a list:
 362 .Sp
 363 .Vb 1
 364 \&  extends 'Foo', 'Bar', 'Baz';
 365 .Ve
 366 .IP "(3)" 4
 367 .IX Item "(3)"
 368 Moose supports using instance structures other than blessed hash
 369 references (such as in a glob reference \- see
 370 MooseX::GlobRef::Object).
 371 .SH "SEE ALSO"
 372 .IX Header "SEE ALSO"
 373 .IP "Method Modifiers" 4
 374 .IX Item "Method Modifiers"
 375 The concept of method modifiers is directly ripped off from \s-1CLOS\s0. A
 376 great explanation of them can be found by following this link.
 377 .Sp
 378 <http://www.gigamonkeys.com/book/object\-reorientation\-generic\-functions.html>
 379 .SH "AUTHORS"
 380 .IX Header "AUTHORS"
 381 Stevan Little <stevan@iinteractive.com>
 382 .PP
 383 Dave Rolsky <autarch@urth.org>
 384 .SH "COPYRIGHT AND LICENSE"
 385 .IX Header "COPYRIGHT AND LICENSE"
 386 Copyright 2006\-2009 by Infinity Interactive, Inc.
 387 .PP
 388 <http://www.iinteractive.com>
 389 .PP
 390 This library is free software; you can redistribute it and/or modify
 391 it under the same terms as Perl itself.