local-lib5/man/man3/Moose::Manual::MooseX.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::MooseX 3"
 132 .TH Moose::Manual::MooseX 3 "2009-09-12" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Moose::Manual::MooseX \- Recommended Moose extensions
 135 .SH "MooseX?"
 136 .IX Header "MooseX?"
 137 It's easy to extend and change Moose, and this is part of what makes
 138 Moose so powerful. You can use the \s-1MOP\s0 \s-1API\s0 to do things your own way,
 139 add new features, and generally customize your Moose.
 140 .PP
 141 Writing your own extensions does require a good understanding of the
 142 meta\-model. You can start learning about this with the
 143 Moose::Manual::MOP docs. There are also several extension recipes
 144 in the Moose::Cookbook.
 145 .PP
 146 Explaining how to write extensions is beyond the scope of this
 147 manual. Fortunately, lots of people have already written extensions
 148 and put them on \s-1CPAN\s0 for you.
 149 .PP
 150 This document covers a few of the ones we like best.
 151 .SH "MooseX::AttributeHelpers"
 152 .IX Header "MooseX::AttributeHelpers"
 153 The functionality of this MooseX module has been moved into Moose core.
 154 See Moose::Meta::Attribute::Native.
 155 .SH "Moose::Autobox"
 156 .IX Header "Moose::Autobox"
 157 MooseX::AttributeHelpers, but turned inside out, Moose::Autobox provides
 158 methods on both arrays/hashes/etc. but also references to them, using
 159 Moose roles, allowing you do to things like:
 160 .PP
 161 .Vb 1
 162 \&  use Moose::Autobox;
 163 .Ve
 164 .PP
 165 .Vb 1
 166 \&  $somebody_elses_object\->orders\->push($order);
 167 .Ve
 168 .PP
 169 Lexically scoped and not to everybody's taste, but very handy for sugaring
 170 up other people's APIs and your own code.
 171 .SH "MooseX::StrictConstructor"
 172 .IX Header "MooseX::StrictConstructor"
 173 By default, Moose lets you pass any old junk into a class's
 174 constructor. If you load MooseX::StrictConstructor, your class will
 175 throw an error if it sees something it doesn't recognize;
 176 .PP
 177 .Vb 1
 178 \&  package User;
 179 .Ve
 180 .PP
 181 .Vb 2
 182 \&  use Moose;
 183 \&  use MooseX::StrictConstructor;
 184 .Ve
 185 .PP
 186 .Vb 2
 187 \&  has 'name';
 188 \&  has 'email';
 189 .Ve
 190 .PP
 191 .Vb 1
 192 \&  User\->new( name => 'Bob', emali => 'bob@example.com' );
 193 .Ve
 194 .PP
 195 With MooseX::StrictConstructor, that typo (\*(L"emali\*(R") will cause a
 196 runtime error. With plain old Moose, the \*(L"emali\*(R" attribute would be
 197 silently ignored.
 198 .SH "MooseX::Params::Validate"
 199 .IX Header "MooseX::Params::Validate"
 200 We have high hopes for the future of MooseX::Method::Signatures and
 201 MooseX::Declare. However, these modules, while used regularly in
 202 production by some of the more insane members of the community, are
 203 still marked alpha just in case backwards incompatible changes need to
 204 be made.
 205 .PP
 206 If you don't want to risk that, for now we recommend the decidedly more
 207 clunky (but also faster and simpler) MooseX::Params::Validate. This
 208 module lets you apply Moose types and coercions to any method
 209 arguments.
 210 .PP
 211 .Vb 1
 212 \&  package User;
 213 .Ve
 214 .PP
 215 .Vb 2
 216 \&  use Moose;
 217 \&  use MooseX::Params::Validate;
 218 .Ve
 219 .PP
 220 .Vb 4
 221 \&  sub login {
 222 \&      my $self = shift;
 223 \&      my ($password)
 224 \&          = validated_list( \e@_, password => { isa => 'Str', required => 1 } );
 225 .Ve
 226 .PP
 227 .Vb 2
 228 \&      ...
 229 \&  }
 230 .Ve
 231 .SH "MooseX::Getopt"
 232 .IX Header "MooseX::Getopt"
 233 This is a role which adds a \f(CW\*(C`new_with_options\*(C'\fR method to your
 234 class. This is a constructor that takes the command line options and
 235 uses them to populate attributes.
 236 .PP
 237 This makes writing a command-line application as a module trivially
 238 simple:
 239 .PP
 240 .Vb 1
 241 \&  package App::Foo;
 242 .Ve
 243 .PP
 244 .Vb 2
 245 \&  use Moose;
 246 \&  with 'MooseX::Getopt';
 247 .Ve
 248 .PP
 249 .Vb 5
 250 \&  has 'input' => (
 251 \&      is       => 'ro',
 252 \&      isa      => 'Str',
 253 \&      required => 1
 254 \&  );
 255 .Ve
 256 .PP
 257 .Vb 5
 258 \&  has 'output' => (
 259 \&      is       => 'ro',
 260 \&      isa      => 'Str',
 261 \&      required => 1
 262 \&  );
 263 .Ve
 264 .PP
 265 .Vb 1
 266 \&  sub run { ... }
 267 .Ve
 268 .PP
 269 Then in the script that gets run we have:
 270 .PP
 271 .Vb 1
 272 \&  use App::Foo;
 273 .Ve
 274 .PP
 275 .Vb 1
 276 \&  App::Foo\->new_with_options\->run;
 277 .Ve
 278 .PP
 279 From the command line, someone can execute the script:
 280 .PP
 281 .Vb 1
 282 \&  foo@example> foo \-\-input /path/to/input \-\-output /path/to/output
 283 .Ve
 284 .SH "MooseX::Singleton"
 285 .IX Header "MooseX::Singleton"
 286 To be honest, using a singleton is just a way to have a magic global
 287 variable in languages that don't actually have global variables.
 288 .PP
 289 In perl, you can just as easily use a global. However, if your
 290 colleagues are Java\-infected, they might prefer a singleton. Also, if
 291 you have an existing class that \fIisn't\fR a singleton but should be,
 292 using MooseX::Singleton is the easiest way to convert it.
 293 .PP
 294 .Vb 1
 295 \&  package Config;
 296 .Ve
 297 .PP
 298 .Vb 1
 299 \&  use MooseX::Singleton; # instead of Moose
 300 .Ve
 301 .PP
 302 .Vb 1
 303 \&  has 'cache_dir' => ( ... );
 304 .Ve
 305 .PP
 306 It's that simple.
 307 .SH "EXTENSIONS TO CONSIDER"
 308 .IX Header "EXTENSIONS TO CONSIDER"
 309 There are literally dozens of other extensions on \s-1CPAN\s0. This is a list
 310 of extensions that you might find useful, but we're not quite ready to
 311 endorse just yet.
 312 .Sh "MooseX::Declare"
 313 .IX Subsection "MooseX::Declare"
 314 Extends Perl with Moose-based keywords using \f(CW\*(C`Devel::Declare\*(C'\fR. Very
 315 cool, but still new and experimental.
 316 .PP
 317 .Vb 1
 318 \&  class User {
 319 .Ve
 320 .PP
 321 .Vb 2
 322 \&      has 'name'  => ( ... );
 323 \&      has 'email' => ( ... );
 324 .Ve
 325 .PP
 326 .Vb 2
 327 \&      method login (Str $password) { ... }
 328 \&  }
 329 .Ve
 330 .Sh "MooseX::Types"
 331 .IX Subsection "MooseX::Types"
 332 This extension helps you build a type library for your application. It
 333 also lets you predeclare type names and use them as barewords.
 334 .PP
 335 .Vb 2
 336 \&  use MooseX::Types \-declare => ['PositiveInt'];
 337 \&  use MooseX::Types::Moose 'Int';
 338 .Ve
 339 .PP
 340 .Vb 4
 341 \&  subtype PositiveInt,
 342 \&      as Int,
 343 \&      where { $_ > 0 },
 344 \&      message { "Int is not larger than 0" };
 345 .Ve
 346 .PP
 347 One nice feature is that those bareword names are actually namespaced
 348 in Moose's type registry, so multiple applications can use the same
 349 bareword names, even if the type definitions differ.
 350 .Sh "MooseX::Types::Structured"
 351 .IX Subsection "MooseX::Types::Structured"
 352 This extension builds on top of MooseX::Types to let you declare
 353 complex data structure types.
 354 .PP
 355 .Vb 3
 356 \&  use MooseX::Types \-declare => [ qw( Name Color ) ];
 357 \&  use MooseX::Types::Moose qw(Str Int);
 358 \&  use MooseX::Types::Structured qw(Dict Tuple Optional);
 359 .Ve
 360 .PP
 361 .Vb 2
 362 \&  subtype Name
 363 \&      => as Dict[ first => Str, middle => Optional[Str], last => Str ];
 364 .Ve
 365 .PP
 366 .Vb 2
 367 \&  subtype Color
 368 \&      => as Tuple[ Int, Int, Int, Optional[Int] ];
 369 .Ve
 370 .PP
 371 Of course, you could always use objects to represent these sorts of
 372 things too.
 373 .Sh "MooseX::ClassAttribute"
 374 .IX Subsection "MooseX::ClassAttribute"
 375 This extension provides class attributes for Moose classes. The
 376 declared class attributes are introspectable just like regular Moose
 377 attributes.
 378 .PP
 379 .Vb 1
 380 \&  package User;
 381 .Ve
 382 .PP
 383 .Vb 2
 384 \&  use Moose;
 385 \&  use MooseX::ClassAttribute;
 386 .Ve
 387 .PP
 388 .Vb 1
 389 \&  has 'name' => ( ... );
 390 .Ve
 391 .PP
 392 .Vb 1
 393 \&  class_has 'Cache' => ( ... );
 394 .Ve
 395 .PP
 396 Note however that this class attribute does \fInot\fR inherit like a
 397 Class::Data::Inheritable or similar attribute \- calling
 398 .PP
 399 .Vb 1
 400 \&  $subclass\->Cache($cache);
 401 .Ve
 402 .PP
 403 will set it for the superclass as well. Additionally, class data is usually
 404 The Wrong Thing To Do in a strongly \s-1OO\s0 program since it makes testing a
 405 lot harder \- consider carefully whether you'd be better off with an object
 406 that's passed around instead.
 407 .Sh "MooseX::Daemonize"
 408 .IX Subsection "MooseX::Daemonize"
 409 This is a role that provides a number of methods useful for creating a
 410 daemon, including methods for starting and stopping, managing a \s-1PID\s0
 411 file, and signal handling.
 412 .Sh "MooseX::Role::Parameterized"
 413 .IX Subsection "MooseX::Role::Parameterized"
 414 If you find yourself wanting a role that customizes itself for each
 415 consumer, this is the tool for you. With this module, you can create a
 416 role that accepts parameters and generates attributes, methods, etc. on
 417 a customized basis for each consumer.
 418 .Sh "MooseX::POE"
 419 .IX Subsection "MooseX::POE"
 420 This is a small wrapper that ties together a Moose class with
 421 \&\f(CW\*(C`POE::Session\*(C'\fR, and gives you an \f(CW\*(C`event\*(C'\fR sugar function to declare
 422 event handlers.
 423 .Sh "MooseX::FollowPBP"
 424 .IX Subsection "MooseX::FollowPBP"
 425 Automatically names all accessors \fIPerl Best Practices\fR\-style,
 426 \&\*(L"get_size\*(R" and \*(L"set_size\*(R".
 427 .Sh "MooseX::SemiAffordanceAccessor"
 428 .IX Subsection "MooseX::SemiAffordanceAccessor"
 429 Automatically names all accessors with an explicit set and implicit
 430 get, \*(L"size\*(R" and \*(L"set_size\*(R".
 431 .Sh "MooseX::NonMoose"
 432 .IX Subsection "MooseX::NonMoose"
 433 MooseX::NonMoose allows for easily subclassing non-Moose classes with Moose,
 434 taking care of the annoying details connected with doing this, such as
 435 setting up proper inheritance from Moose::Object and installing
 436 (and inlining, at make_immutable time) a constructor that makes sure things
 437 like \s-1BUILD\s0 methods are called.
 438 .SH "AUTHOR"
 439 .IX Header "AUTHOR"
 440 Dave Rolsky <autarch@urth.org>
 441 .SH "COPYRIGHT AND LICENSE"
 442 .IX Header "COPYRIGHT AND LICENSE"
 443 Copyright 2009 by Infinity Interactive, Inc.
 444 .PP
 445 <http://www.iinteractive.com>
 446 .PP
 447 This library is free software; you can redistribute it and/or modify
 448 it under the same terms as Perl itself.