local-lib5/man/man3/MooseX::Declare.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "MooseX::Declare 3"
 127 .TH MooseX::Declare 3 "2010-02-04" "perl v5.8.8" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 MooseX::Declare \- Declarative syntax for Moose
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 1
 137 \&    use MooseX::Declare;
 138 \&
 139 \&    class BankAccount {
 140 \&        has \*(Aqbalance\*(Aq => ( isa => \*(AqNum\*(Aq, is => \*(Aqrw\*(Aq, default => 0 );
 141 \&
 142 \&        method deposit (Num $amount) {
 143 \&            $self\->balance( $self\->balance + $amount );
 144 \&        }
 145 \&
 146 \&        method withdraw (Num $amount) {
 147 \&            my $current_balance = $self\->balance();
 148 \&            ( $current_balance >= $amount )
 149 \&                || confess "Account overdrawn";
 150 \&            $self\->balance( $current_balance \- $amount );
 151 \&        }
 152 \&    }
 153 \&
 154 \&    class CheckingAccount extends BankAccount {
 155 \&        has \*(Aqoverdraft_account\*(Aq => ( isa => \*(AqBankAccount\*(Aq, is => \*(Aqrw\*(Aq );
 156 \&
 157 \&        before withdraw (Num $amount) {
 158 \&            my $overdraft_amount = $amount \- $self\->balance();
 159 \&            if ( $self\->overdraft_account && $overdraft_amount > 0 ) {
 160 \&                $self\->overdraft_account\->withdraw($overdraft_amount);
 161 \&                $self\->deposit($overdraft_amount);
 162 \&            }
 163 \&        }
 164 \&    }
 165 .Ve
 166 .SH "DESCRIPTION"
 167 .IX Header "DESCRIPTION"
 168 This module provides syntactic sugar for Moose, the postmodern object system
 169 for Perl 5. When used, it sets up the \f(CW\*(C`class\*(C'\fR and \f(CW\*(C`role\*(C'\fR keywords.
 170 .SH "KEYWORDS"
 171 .IX Header "KEYWORDS"
 172 .SS "class"
 173 .IX Subsection "class"
 174 .Vb 1
 175 \&    class Foo { ... }
 176 \&
 177 \&    my $anon_class = class { ... };
 178 .Ve
 179 .PP
 180 Declares a new class. The class can be either named or anonymous, depending on
 181 whether or not a classname is given. Within the class definition Moose and
 182 MooseX::Method::Signatures are set up automatically in addition to the other
 183 keywords described in this document. At the end of the definition the class
 184 will be made immutable. namespace::autoclean is injected to clean up Moose and
 185 other imports for you.
 186 .PP
 187 Because of the way the options are parsed, you cannot have a class named \*(L"is\*(R",
 188 \&\*(L"with\*(R" or \*(L"extends\*(R".
 189 .PP
 190 It's possible to specify options for classes:
 191 .IP "extends" 4
 192 .IX Item "extends"
 193 .Vb 1
 194 \&    class Foo extends Bar { ... }
 195 .Ve
 196 .Sp
 197 Sets a superclass for the class being declared.
 198 .IP "with" 4
 199 .IX Item "with"
 200 .Vb 3
 201 \&    class Foo with Role             { ... }
 202 \&    class Foo with Role1 with Role2 { ... }
 203 \&    class Foo with (Role1, Role2)   { ... }
 204 .Ve
 205 .Sp
 206 Applies a role or roles to the class being declared.
 207 .IP "is mutable" 4
 208 .IX Item "is mutable"
 209 .Vb 1
 210 \&    class Foo is mutable { ... }
 211 .Ve
 212 .Sp
 213 Causes the class not to be made immutable after its definition.
 214 .Sp
 215 Options can also be provided for anonymous classes using the same syntax:
 216 .Sp
 217 .Vb 1
 218 \&    my $meta_class = class with Role;
 219 .Ve
 220 .SS "role"
 221 .IX Subsection "role"
 222 .Vb 1
 223 \&    role Foo { ... }
 224 \&
 225 \&    my $anon_role = role { ... };
 226 .Ve
 227 .PP
 228 Declares a new role. The role can be either named or anonymous, depending on
 229 whether or not a name is given. Within the role definition Moose::Role and
 230 MooseX::Method::Signatures are set up automatically in addition to the other
 231 keywords described in this document. Again, namespace::autoclean is injected to
 232 clean up Moose::Role and other imports for you.
 233 .PP
 234 It's possible to specify options for roles:
 235 .IP "with" 4
 236 .IX Item "with"
 237 .Vb 1
 238 \&    role Foo with Bar { ... }
 239 .Ve
 240 .Sp
 241 Applies a role to the role being declared.
 242 .SS "before / after / around / override / augment"
 243 .IX Subsection "before / after / around / override / augment"
 244 .Vb 5
 245 \&    before   foo ($x, $y, $z) { ... }
 246 \&    after    bar ($x, $y, $z) { ... }
 247 \&    around   baz ($x, $y, $z) { ... }
 248 \&    override moo ($x, $y, $z) { ... }
 249 \&    augment  kuh ($x, $y, $z) { ... }
 250 .Ve
 251 .PP
 252 Add a method modifier. Those work like documented in Moose, except for
 253 the slightly nicer syntax and the method signatures, which work like documented
 254 in MooseX::Method::Signatures.
 255 .PP
 256 For the \f(CW\*(C`around\*(C'\fR modifier an additional argument called \f(CW$orig\fR is
 257 automatically set up as the invocant for the method.
 258 .SS "clean"
 259 .IX Subsection "clean"
 260 Sometimes you don't want the automatic cleaning the \f(CW\*(C`class\*(C'\fR and \f(CW\*(C`role\*(C'\fR
 261 keywords provide using namespace::autoclean. In those cases you can specify the
 262 \&\f(CW\*(C`dirty\*(C'\fR trait for your class or role:
 263 .PP
 264 .Vb 2
 265 \&    use MooseX::Declare;
 266 \&    class Foo is dirty { ... }
 267 .Ve
 268 .PP
 269 This will prevent cleaning of your namespace, except for the keywords imported
 270 from \f(CW\*(C`Moose\*(C'\fR or \f(CW\*(C`Moose::Role\*(C'\fR. Additionally, a \f(CW\*(C`clean\*(C'\fR keyword is provided,
 271 which allows you to explicitly clean all functions that were defined prior to
 272 calling \f(CW\*(C`clean\*(C'\fR. Here's an example:
 273 .PP
 274 .Vb 6
 275 \&    use MooseX::Declare;
 276 \&    class Foo is dirty {
 277 \&        sub helper_function { ... }
 278 \&        clean;
 279 \&        method foo ($stuff) { ...; return helper_function($stuff); }
 280 \&    }
 281 .Ve
 282 .PP
 283 With that, the helper function won't be available as a method to a user of your
 284 class, but you're still able to use it inside your class.
 285 .SH "NOTE ON IMPORTS"
 286 .IX Header "NOTE ON IMPORTS"
 287 When creating a class with MooseX::Declare like:
 288 .PP
 289 .Vb 2
 290 \&    use MooseX::Declare;
 291 \&    class Foo { ... }
 292 .Ve
 293 .PP
 294 What actually happens is something like this:
 295 .PP
 296 .Vb 7
 297 \&    {
 298 \&        package Foo;
 299 \&        use Moose;
 300 \&        use namespace::autoclean;
 301 \&        ...
 302 \&        _\|_PACKAGE_\|_\->meta\->make_immutable;
 303 \&    }
 304 .Ve
 305 .PP
 306 So if you declare imports outside the class, the symbols get imported into the
 307 \&\f(CW\*(C`main::\*(C'\fR namespace, not the class' namespace. The symbols then cannot be called
 308 from within the class:
 309 .PP
 310 .Vb 6
 311 \&    use MooseX::Declare;
 312 \&    use Data::Dump qw/dump/;
 313 \&    class Foo {
 314 \&        method dump($value) { return dump($value) } # Data::Dump::dump IS NOT in Foo::
 315 \&        method pp($value)   { $self\->dump($value) } # an alias for our dump method
 316 \&    }
 317 .Ve
 318 .PP
 319 To solve this, only import MooseX::Declare outside the class definition
 320 (because you have to). Make all other imports inside the class definition.
 321 .PP
 322 .Vb 6
 323 \&    use MooseX::Declare;
 324 \&    class Foo {
 325 \&        use Data::Dump qw/dump/;
 326 \&        method dump($value) { return dump($value) } # Data::Dump::dump IS in Foo::
 327 \&        method pp($value)   { $self\->dump($value) } # an alias for our dump method
 328 \&    }
 329 \&
 330 \&    Foo\->new\->dump($some_value);
 331 \&    Foo\->new\->pp($some_value);
 332 .Ve
 333 .PP
 334 \&\fB\s-1NOTE\s0\fR that the import \f(CW\*(C`Data::Dump::dump()\*(C'\fR and the method \f(CW\*(C`Foo::dump()\*(C'\fR,
 335 although having the same name, do not conflict with each other, because the
 336 imported \f(CW\*(C`dump\*(C'\fR function will be cleaned during compile time, so only the
 337 method remains there at run time. If you want to do more esoteric things with
 338 imports, have a look at the \f(CW\*(C`clean\*(C'\fR keyword and the \f(CW\*(C`dirty\*(C'\fR trait.
 339 .SH "SEE ALSO"
 340 .IX Header "SEE ALSO"
 341 Moose
 342 .PP
 343 Moose::Role
 344 .PP
 345 MooseX::Method::Signatures
 346 .PP
 347 namespace::autoclean
 348 .PP
 349 vim syntax: <http://www.vim.org/scripts/script.php?script_id=2526>
 350 .PP
 351 emacs syntax: <http://github.com/jrockway/cperl\-mode>
 352 .PP
 353 Geany syntax + notes: <http://www.cattlegrid.info/blog/2009/09/moosex\-declare\-geany\-syntax.html>
 354 .SH "AUTHOR"
 355 .IX Header "AUTHOR"
 356 Florian Ragwitz <rafl@debian.org>
 357 .PP
 358 With contributions from:
 359 .IP "Ash Berlin <ash@cpan.org>" 4
 360 .IX Item "Ash Berlin <ash@cpan.org>"
 361 .PD 0
 362 .IP "Chas. J. Owens \s-1IV\s0 <chas.owens@gmail.com>" 4
 363 .IX Item "Chas. J. Owens IV <chas.owens@gmail.com>"
 364 .IP "Chris Prather <chris@prather.org>" 4
 365 .IX Item "Chris Prather <chris@prather.org>"
 366 .IP "Dave Rolsky <autarch@urth.org>" 4
 367 .IX Item "Dave Rolsky <autarch@urth.org>"
 368 .IP "Devin Austin <dhoss@cpan.org>" 4
 369 .IX Item "Devin Austin <dhoss@cpan.org>"
 370 .IP "Hans Dieter Pearcey <hdp@cpan.org>" 4
 371 .IX Item "Hans Dieter Pearcey <hdp@cpan.org>"
 372 .IP "Justin Hunter <justin.d.hunter@gmail.com>" 4
 373 .IX Item "Justin Hunter <justin.d.hunter@gmail.com>"
 374 .IP "Matt Kraai <kraai@ftbfs.org>" 4
 375 .IX Item "Matt Kraai <kraai@ftbfs.org>"
 376 .IP "Michele Beltrame <arthas@cpan.org>" 4
 377 .IX Item "Michele Beltrame <arthas@cpan.org>"
 378 .IP "Nelo Onyiah <nelo.onyiah@gmail.com>" 4
 379 .IX Item "Nelo Onyiah <nelo.onyiah@gmail.com>"
 380 .IP "nperez <nperez@cpan.org>" 4
 381 .IX Item "nperez <nperez@cpan.org>"
 382 .IP "Piers Cawley <pdcawley@bofh.org.uk>" 4
 383 .IX Item "Piers Cawley <pdcawley@bofh.org.uk>"
 384 .IP "Rafael Kitover <rkitover@io.com>" 4
 385 .IX Item "Rafael Kitover <rkitover@io.com>"
 386 .IP "Robert a\*^XXphaylona\*^XX Sedlacek <rs@474.at>" 4
 387 .IX Item "Robert a^XXphaylona^XX Sedlacek <rs@474.at>"
 388 .IP "Stevan Little <stevan.little@iinteractive.com>" 4
 389 .IX Item "Stevan Little <stevan.little@iinteractive.com>"
 390 .IP "Tomas Doran <bobtfish@bobtfish.net>" 4
 391 .IX Item "Tomas Doran <bobtfish@bobtfish.net>"
 392 .IP "Yanick Champoux <yanick@babyl.dyndns.org>" 4
 393 .IX Item "Yanick Champoux <yanick@babyl.dyndns.org>"
 394 .PD
 395 .SH "COPYRIGHT AND LICENSE"
 396 .IX Header "COPYRIGHT AND LICENSE"
 397 Copyright (c) 2008, 2009  Florian Ragwitz
 398 .PP
 399 Licensed under the same terms as perl itself.