local-lib5/man/man3/Class::Accessor.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 "Class::Accessor 3"
 132 .TH Class::Accessor 3 "2009-09-15" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 .Vb 1
 135 \&  Class::Accessor \- Automated accessor generation
 136 .Ve
 137 .SH "SYNOPSIS"
 138 .IX Header "SYNOPSIS"
 139 .Vb 4
 140 \&  package Foo;
 141 \&  use base qw(Class::Accessor);
 142 \&  Foo\->follow_best_practice;
 143 \&  Foo\->mk_accessors(qw(name role salary));
 144 .Ve
 145 .PP
 146 .Vb 1
 147 \&  # or if you prefer a Moose\-like interface...
 148 .Ve
 149 .PP
 150 .Vb 5
 151 \&  package Foo;
 152 \&  use Class::Accessor "antlers";
 153 \&  has name => ( is => "rw", isa => "Str" );
 154 \&  has role => ( is => "rw", isa => "Str" );
 155 \&  has salary => ( is => "rw", isa => "Num" );
 156 .Ve
 157 .PP
 158 .Vb 3
 159 \&  # Meanwhile, in a nearby piece of code!
 160 \&  # Class::Accessor provides new().
 161 \&  my $mp = Foo\->new({ name => "Marty", role => "JAPH" });
 162 .Ve
 163 .PP
 164 .Vb 2
 165 \&  my $job = $mp\->role;  # gets $mp\->{role}
 166 \&  $mp\->salary(400000);  # sets $mp\->{salary} = 400000 # I wish
 167 .Ve
 168 .PP
 169 .Vb 2
 170 \&  # like my @info = @{$mp}{qw(name role)}
 171 \&  my @info = $mp\->get(qw(name role));
 172 .Ve
 173 .PP
 174 .Vb 2
 175 \&  # $mp\->{salary} = 400000
 176 \&  $mp\->set('salary', 400000);
 177 .Ve
 178 .SH "DESCRIPTION"
 179 .IX Header "DESCRIPTION"
 180 This module automagically generates accessors/mutators for your class.
 181 .PP
 182 Most of the time, writing accessors is an exercise in cutting and
 183 pasting.  You usually wind up with a series of methods like this:
 184 .PP
 185 .Vb 7
 186 \&    sub name {
 187 \&        my $self = shift;
 188 \&        if(@_) {
 189 \&            $self\->{name} = $_[0];
 190 \&        }
 191 \&        return $self\->{name};
 192 \&    }
 193 .Ve
 194 .PP
 195 .Vb 7
 196 \&    sub salary {
 197 \&        my $self = shift;
 198 \&        if(@_) {
 199 \&            $self\->{salary} = $_[0];
 200 \&        }
 201 \&        return $self\->{salary};
 202 \&    }
 203 .Ve
 204 .PP
 205 .Vb 1
 206 \&  # etc...
 207 .Ve
 208 .PP
 209 One for each piece of data in your object.  While some will be unique,
 210 doing value checks and special storage tricks, most will simply be
 211 exercises in repetition.  Not only is it Bad Style to have a bunch of
 212 repetitious code, but it's also simply not lazy, which is the real
 213 tragedy.
 214 .PP
 215 If you make your module a subclass of Class::Accessor and declare your
 216 accessor fields with \fImk_accessors()\fR then you'll find yourself with a
 217 set of automatically generated accessors which can even be
 218 customized!
 219 .PP
 220 The basic set up is very simple:
 221 .PP
 222 .Vb 3
 223 \&    package Foo;
 224 \&    use base qw(Class::Accessor);
 225 \&    Foo\->mk_accessors( qw(far bar car) );
 226 .Ve
 227 .PP
 228 Done.  Foo now has simple \fIfar()\fR, \fIbar()\fR and \fIcar()\fR accessors
 229 defined.
 230 .PP
 231 Alternatively, if you want to follow Damian's \fIbest practice\fR guidelines
 232 you can use:
 233 .PP
 234 .Vb 4
 235 \&    package Foo;
 236 \&    use base qw(Class::Accessor);
 237 \&    Foo\->follow_best_practice;
 238 \&    Foo\->mk_accessors( qw(far bar car) );
 239 .Ve
 240 .PP
 241 \&\fBNote:\fR you must call \f(CW\*(C`follow_best_practice\*(C'\fR before calling \f(CW\*(C`mk_accessors\*(C'\fR.
 242 .Sh "Moose-like"
 243 .IX Subsection "Moose-like"
 244 By popular demand we now have a simple Moose-like interface.  You can now do:
 245 .PP
 246 .Vb 5
 247 \&    package Foo;
 248 \&    use Class::Accessor "antlers";
 249 \&    has far => ( is => "rw" );
 250 \&    has bar => ( is => "rw" );
 251 \&    has car => ( is => "rw" );
 252 .Ve
 253 .PP
 254 Currently only the \f(CW\*(C`is\*(C'\fR attribute is supported.
 255 .SH "CONSTRUCTOR"
 256 .IX Header "CONSTRUCTOR"
 257 Class::Accessor provides a basic constructor, \f(CW\*(C`new\*(C'\fR.  It generates a
 258 hash-based object and can be called as either a class method or an
 259 object method.
 260 .Sh "new"
 261 .IX Subsection "new"
 262 .Vb 2
 263 \&    my $obj = Foo\->new;
 264 \&    my $obj = $other_obj\->new;
 265 .Ve
 266 .PP
 267 .Vb 2
 268 \&    my $obj = Foo\->new(\e%fields);
 269 \&    my $obj = $other_obj\->new(\e%fields);
 270 .Ve
 271 .PP
 272 It takes an optional \f(CW%fields\fR hash which is used to initialize the
 273 object (handy if you use read-only accessors).  The fields of the hash
 274 correspond to the names of your accessors, so...
 275 .PP
 276 .Vb 3
 277 \&    package Foo;
 278 \&    use base qw(Class::Accessor);
 279 \&    Foo\->mk_accessors('foo');
 280 .Ve
 281 .PP
 282 .Vb 2
 283 \&    my $obj = Foo\->new({ foo => 42 });
 284 \&    print $obj\->foo;    # 42
 285 .Ve
 286 .PP
 287 however \f(CW%fields\fR can contain anything, \fInew()\fR will shove them all into
 288 your object.
 289 .SH "MAKING ACCESSORS"
 290 .IX Header "MAKING ACCESSORS"
 291 .Sh "follow_best_practice"
 292 .IX Subsection "follow_best_practice"
 293 In Damian's Perl Best Practices book he recommends separate get and set methods
 294 with the prefix set_ and get_ to make it explicit what you intend to do.  If you
 295 want to create those accessor methods instead of the default ones, call:
 296 .PP
 297 .Vb 1
 298 \&    __PACKAGE__\->follow_best_practice
 299 .Ve
 300 .PP
 301 \&\fBbefore\fR you call any of the accessor-making methods.
 302 .Sh "accessor_name_for / mutator_name_for"
 303 .IX Subsection "accessor_name_for / mutator_name_for"
 304 You may have your own crazy ideas for the names of the accessors, so you can
 305 make those happen by overriding \f(CW\*(C`accessor_name_for\*(C'\fR and \f(CW\*(C`mutator_name_for\*(C'\fR in
 306 your subclass.  (I copied that idea from Class::DBI.)
 307 .Sh "mk_accessors"
 308 .IX Subsection "mk_accessors"
 309 .Vb 1
 310 \&    __PACKAGE__\->mk_accessors(@fields);
 311 .Ve
 312 .PP
 313 This creates accessor/mutator methods for each named field given in
 314 \&\f(CW@fields\fR.  Foreach field in \f(CW@fields\fR it will generate two accessors.
 315 One called \*(L"\fIfield()\fR\*(R" and the other called \*(L"\fI_field_accessor()\fR\*(R".  For
 316 example:
 317 .PP
 318 .Vb 2
 319 \&    # Generates foo(), _foo_accessor(), bar() and _bar_accessor().
 320 \&    __PACKAGE__\->mk_accessors(qw(foo bar));
 321 .Ve
 322 .PP
 323 See \*(L"Overriding autogenerated accessors\*(R" in \s-1CAVEATS\s0 \s-1AND\s0 \s-1TRICKS\s0
 324 for details.
 325 .Sh "mk_ro_accessors"
 326 .IX Subsection "mk_ro_accessors"
 327 .Vb 1
 328 \&  __PACKAGE__\->mk_ro_accessors(@read_only_fields);
 329 .Ve
 330 .PP
 331 Same as \fImk_accessors()\fR except it will generate read-only accessors
 332 (ie. true accessors).  If you attempt to set a value with these
 333 accessors it will throw an exception.  It only uses \fIget()\fR and not
 334 \&\fIset()\fR.
 335 .PP
 336 .Vb 3
 337 \&    package Foo;
 338 \&    use base qw(Class::Accessor);
 339 \&    Foo\->mk_ro_accessors(qw(foo bar));
 340 .Ve
 341 .PP
 342 .Vb 3
 343 \&    # Let's assume we have an object $foo of class Foo...
 344 \&    print $foo\->foo;  # ok, prints whatever the value of $foo\->{foo} is
 345 \&    $foo\->foo(42);    # BOOM!  Naughty you.
 346 .Ve
 347 .Sh "mk_wo_accessors"
 348 .IX Subsection "mk_wo_accessors"
 349 .Vb 1
 350 \&  __PACKAGE__\->mk_wo_accessors(@write_only_fields);
 351 .Ve
 352 .PP
 353 Same as \fImk_accessors()\fR except it will generate write-only accessors
 354 (ie. mutators).  If you attempt to read a value with these accessors
 355 it will throw an exception.  It only uses \fIset()\fR and not \fIget()\fR.
 356 .PP
 357 \&\fB\s-1NOTE\s0\fR I'm not entirely sure why this is useful, but I'm sure someone
 358 will need it.  If you've found a use, let me know.  Right now it's here
 359 for orthoginality and because it's easy to implement.
 360 .PP
 361 .Vb 3
 362 \&    package Foo;
 363 \&    use base qw(Class::Accessor);
 364 \&    Foo\->mk_wo_accessors(qw(foo bar));
 365 .Ve
 366 .PP
 367 .Vb 3
 368 \&    # Let's assume we have an object $foo of class Foo...
 369 \&    $foo\->foo(42);      # OK.  Sets $self\->{foo} = 42
 370 \&    print $foo\->foo;    # BOOM!  Can't read from this accessor.
 371 .Ve
 372 .SH "Moose!"
 373 .IX Header "Moose!"
 374 If you prefer a Moose-like interface to create accessors, you can use \f(CW\*(C`has\*(C'\fR by
 375 importing this module like this:
 376 .PP
 377 .Vb 1
 378 \&  use Class::Accessor "antlers";
 379 .Ve
 380 .PP
 381 or
 382 .PP
 383 .Vb 1
 384 \&  use Class::Accessor "moose\-like";
 385 .Ve
 386 .PP
 387 Then you can declare accessors like this:
 388 .PP
 389 .Vb 3
 390 \&  has alpha => ( is => "rw", isa => "Str" );
 391 \&  has beta  => ( is => "ro", isa => "Str" );
 392 \&  has gamma => ( is => "wo", isa => "Str" );
 393 .Ve
 394 .PP
 395 Currently only the \f(CW\*(C`is\*(C'\fR attribute is supported.  And our \f(CW\*(C`is\*(C'\fR also supports
 396 the \*(L"wo\*(R" value to make a write-only accessor.
 397 .PP
 398 If you are using the Moose-like interface then you should use the \f(CW\*(C`extends\*(C'\fR
 399 rather than tweaking your \f(CW@ISA\fR directly.  Basically, replace
 400 .PP
 401 .Vb 1
 402 \&  @ISA = qw/Foo Bar/;
 403 .Ve
 404 .PP
 405 with
 406 .PP
 407 .Vb 1
 408 \&  extends(qw/Foo Bar/);
 409 .Ve
 410 .SH "DETAILS"
 411 .IX Header "DETAILS"
 412 An accessor generated by Class::Accessor looks something like
 413 this:
 414 .PP
 415 .Vb 10
 416 \&    # Your foo may vary.
 417 \&    sub foo {
 418 \&        my($self) = shift;
 419 \&        if(@_) {    # set
 420 \&            return $self\->set('foo', @_);
 421 \&        }
 422 \&        else {
 423 \&            return $self\->get('foo');
 424 \&        }
 425 \&    }
 426 .Ve
 427 .PP
 428 Very simple.  All it does is determine if you're wanting to set a
 429 value or get a value and calls the appropriate method.
 430 Class::Accessor provides default \fIget()\fR and \fIset()\fR methods which
 431 your class can override.  They're detailed later.
 432 .Sh "Modifying the behavior of the accessor"
 433 .IX Subsection "Modifying the behavior of the accessor"
 434 Rather than actually modifying the accessor itself, it is much more
 435 sensible to simply override the two key methods which the accessor
 436 calls.  Namely \fIset()\fR and \fIget()\fR.
 437 .PP
 438 If you \-really\- want to, you can override \fImake_accessor()\fR.
 439 .Sh "set"
 440 .IX Subsection "set"
 441 .Vb 2
 442 \&    $obj\->set($key, $value);
 443 \&    $obj\->set($key, @values);
 444 .Ve
 445 .PP
 446 \&\fIset()\fR defines how generally one stores data in the object.
 447 .PP
 448 override this method to change how data is stored by your accessors.
 449 .Sh "get"
 450 .IX Subsection "get"
 451 .Vb 2
 452 \&    $value  = $obj\->get($key);
 453 \&    @values = $obj\->get(@keys);
 454 .Ve
 455 .PP
 456 \&\fIget()\fR defines how data is retreived from your objects.
 457 .PP
 458 override this method to change how it is retreived.
 459 .Sh "make_accessor"
 460 .IX Subsection "make_accessor"
 461 .Vb 1
 462 \&    $accessor = __PACKAGE__\->make_accessor($field);
 463 .Ve
 464 .PP
 465 Generates a subroutine reference which acts as an accessor for the given
 466 \&\f(CW$field\fR.  It calls \fIget()\fR and \fIset()\fR.
 467 .PP
 468 If you wish to change the behavior of your accessors, try overriding
 469 \&\fIget()\fR and \fIset()\fR before you start mucking with \fImake_accessor()\fR.
 470 .Sh "make_ro_accessor"
 471 .IX Subsection "make_ro_accessor"
 472 .Vb 1
 473 \&    $read_only_accessor = __PACKAGE__\->make_ro_accessor($field);
 474 .Ve
 475 .PP
 476 Generates a subroutine refrence which acts as a read-only accessor for
 477 the given \f(CW$field\fR.  It only calls \fIget()\fR.
 478 .PP
 479 Override \fIget()\fR to change the behavior of your accessors.
 480 .Sh "make_wo_accessor"
 481 .IX Subsection "make_wo_accessor"
 482 .Vb 1
 483 \&    $read_only_accessor = __PACKAGE__\->make_wo_accessor($field);
 484 .Ve
 485 .PP
 486 Generates a subroutine refrence which acts as a write-only accessor
 487 (mutator) for the given \f(CW$field\fR.  It only calls \fIset()\fR.
 488 .PP
 489 Override \fIset()\fR to change the behavior of your accessors.
 490 .SH "EXCEPTIONS"
 491 .IX Header "EXCEPTIONS"
 492 If something goes wrong Class::Accessor will warn or die by calling Carp::carp
 493 or Carp::croak.  If you don't like this you can override \fI_carp()\fR and \fI_croak()\fR in
 494 your subclass and do whatever else you want.
 495 .SH "EFFICIENCY"
 496 .IX Header "EFFICIENCY"
 497 Class::Accessor does not employ an autoloader, thus it is much faster
 498 than you'd think.  Its generated methods incur no special penalty over
 499 ones you'd write yourself.
 500 .PP
 501 .Vb 6
 502 \&  accessors:
 503 \&              Rate  Basic   Fast Faster Direct
 504 \&  Basic   367589/s     \-\-   \-51%   \-55%   \-89%
 505 \&  Fast    747964/s   103%     \-\-    \-9%   \-77%
 506 \&  Faster  819199/s   123%    10%     \-\-   \-75%
 507 \&  Direct 3245887/s   783%   334%   296%     \-\-
 508 .Ve
 509 .PP
 510 .Vb 6
 511 \&  mutators:
 512 \&              Rate    Acc   Fast Faster Direct
 513 \&  Acc     265564/s     \-\-   \-54%   \-63%   \-91%
 514 \&  Fast    573439/s   116%     \-\-   \-21%   \-80%
 515 \&  Faster  724710/s   173%    26%     \-\-   \-75%
 516 \&  Direct 2860979/s   977%   399%   295%     \-\-
 517 .Ve
 518 .PP
 519 Class::Accessor::Fast is faster than methods written by an average programmer
 520 (where \*(L"average\*(R" is based on Schwern's example code).
 521 .PP
 522 Class::Accessor is slower than average, but more flexible.
 523 .PP
 524 Class::Accessor::Faster is even faster than Class::Accessor::Fast.  It uses an
 525 array internally, not a hash.  This could be a good or bad feature depending on
 526 your point of view.
 527 .PP
 528 Direct hash access is, of course, much faster than all of these, but it
 529 provides no encapsulation.
 530 .PP
 531 Of course, it's not as simple as saying \*(L"Class::Accessor is slower than
 532 average\*(R".  These are benchmarks for a simple accessor.  If your accessors do
 533 any sort of complicated work (such as talking to a database or writing to a
 534 file) the time spent doing that work will quickly swamp the time spend just
 535 calling the accessor.  In that case, Class::Accessor and the ones you write
 536 will be roughly the same speed.
 537 .SH "EXAMPLES"
 538 .IX Header "EXAMPLES"
 539 Here's an example of generating an accessor for every public field of
 540 your class.
 541 .PP
 542 .Vb 1
 543 \&    package Altoids;
 544 .Ve
 545 .PP
 546 .Vb 3
 547 \&    use base qw(Class::Accessor Class::Fields);
 548 \&    use fields qw(curiously strong mints);
 549 \&    Altoids\->mk_accessors( Altoids\->show_fields('Public') );
 550 .Ve
 551 .PP
 552 .Vb 5
 553 \&    sub new {
 554 \&        my $proto = shift;
 555 \&        my $class = ref $proto || $proto;
 556 \&        return fields::new($class);
 557 \&    }
 558 .Ve
 559 .PP
 560 .Vb 1
 561 \&    my Altoids $tin = Altoids\->new;
 562 .Ve
 563 .PP
 564 .Vb 2
 565 \&    $tin\->curiously('Curiouser and curiouser');
 566 \&    print $tin\->{curiously};    # prints 'Curiouser and curiouser'
 567 .Ve
 568 .PP
 569 .Vb 3
 570 \&    # Subclassing works, too.
 571 \&    package Mint::Snuff;
 572 \&    use base qw(Altoids);
 573 .Ve
 574 .PP
 575 .Vb 3
 576 \&    my Mint::Snuff $pouch = Mint::Snuff\->new;
 577 \&    $pouch\->strong('Blow your head off!');
 578 \&    print $pouch\->{strong};     # prints 'Blow your head off!'
 579 .Ve
 580 .PP
 581 Here's a simple example of altering the behavior of your accessors.
 582 .PP
 583 .Vb 3
 584 \&    package Foo;
 585 \&    use base qw(Class::Accessor);
 586 \&    Foo\->mk_accessors(qw(this that up down));
 587 .Ve
 588 .PP
 589 .Vb 2
 590 \&    sub get {
 591 \&        my $self = shift;
 592 .Ve
 593 .PP
 594 .Vb 2
 595 \&        # Note every time someone gets some data.
 596 \&        print STDERR "Getting @_\en";
 597 .Ve
 598 .PP
 599 .Vb 2
 600 \&        $self\->SUPER::get(@_);
 601 \&    }
 602 .Ve
 603 .PP
 604 .Vb 2
 605 \&    sub set {
 606 \&        my ($self, $key) = splice(@_, 0, 2);
 607 .Ve
 608 .PP
 609 .Vb 2
 610 \&        # Note every time someone sets some data.
 611 \&        print STDERR "Setting $key to @_\en";
 612 .Ve
 613 .PP
 614 .Vb 2
 615 \&        $self\->SUPER::set($key, @_);
 616 \&    }
 617 .Ve
 618 .SH "CAVEATS AND TRICKS"
 619 .IX Header "CAVEATS AND TRICKS"
 620 Class::Accessor has to do some internal wackiness to get its
 621 job done quickly and efficiently.  Because of this, there's a few
 622 tricks and traps one must know about.
 623 .PP
 624 Hey, nothing's perfect.
 625 .Sh "Don't make a field called \s-1DESTROY\s0"
 626 .IX Subsection "Don't make a field called DESTROY"
 627 This is bad.  Since \s-1DESTROY\s0 is a magical method it would be bad for us
 628 to define an accessor using that name.  Class::Accessor will
 629 carp if you try to use it with a field named \*(L"\s-1DESTROY\s0\*(R".
 630 .Sh "Overriding autogenerated accessors"
 631 .IX Subsection "Overriding autogenerated accessors"
 632 You may want to override the autogenerated accessor with your own, yet
 633 have your custom accessor call the default one.  For instance, maybe
 634 you want to have an accessor which checks its input.  Normally, one
 635 would expect this to work:
 636 .PP
 637 .Vb 3
 638 \&    package Foo;
 639 \&    use base qw(Class::Accessor);
 640 \&    Foo\->mk_accessors(qw(email this that whatever));
 641 .Ve
 642 .PP
 643 .Vb 4
 644 \&    # Only accept addresses which look valid.
 645 \&    sub email {
 646 \&        my($self) = shift;
 647 \&        my($email) = @_;
 648 .Ve
 649 .PP
 650 .Vb 7
 651 \&        if( @_ ) {  # Setting
 652 \&            require Email::Valid;
 653 \&            unless( Email::Valid\->address($email) ) {
 654 \&                carp("$email doesn't look like a valid address.");
 655 \&                return;
 656 \&            }
 657 \&        }
 658 .Ve
 659 .PP
 660 .Vb 2
 661 \&        return $self\->SUPER::email(@_);
 662 \&    }
 663 .Ve
 664 .PP
 665 There's a subtle problem in the last example, and it's in this line:
 666 .PP
 667 .Vb 1
 668 \&    return $self\->SUPER::email(@_);
 669 .Ve
 670 .PP
 671 If we look at how Foo was defined, it called \fImk_accessors()\fR which
 672 stuck \fIemail()\fR right into Foo's namespace.  There *is* no
 673 \&\fISUPER::email()\fR to delegate to!  Two ways around this... first is to
 674 make a \*(L"pure\*(R" base class for Foo.  This pure class will generate the
 675 accessors and provide the necessary super class for Foo to use:
 676 .PP
 677 .Vb 3
 678 \&    package Pure::Organic::Foo;
 679 \&    use base qw(Class::Accessor);
 680 \&    Pure::Organic::Foo\->mk_accessors(qw(email this that whatever));
 681 .Ve
 682 .PP
 683 .Vb 2
 684 \&    package Foo;
 685 \&    use base qw(Pure::Organic::Foo);
 686 .Ve
 687 .PP
 688 And now \fIFoo::email()\fR can override the generated
 689 \&\fIPure::Organic::Foo::email()\fR and use it as \fISUPER::email()\fR.
 690 .PP
 691 This is probably the most obvious solution to everyone but me.
 692 Instead, what first made sense to me was for \fImk_accessors()\fR to define
 693 an alias of \fIemail()\fR, \fI_email_accessor()\fR.  Using this solution,
 694 \&\fIFoo::email()\fR would be written with:
 695 .PP
 696 .Vb 1
 697 \&    return $self\->_email_accessor(@_);
 698 .Ve
 699 .PP
 700 instead of the expected \fISUPER::email()\fR.
 701 .SH "AUTHORS"
 702 .IX Header "AUTHORS"
 703 Copyright 2009 Marty Pauley <marty+perl@kasei.com>
 704 .PP
 705 This program is free software; you can redistribute it and/or modify it under
 706 the same terms as Perl itself.  That means either (a) the \s-1GNU\s0 General Public
 707 License or (b) the Artistic License.
 708 .Sh "\s-1ORIGINAL\s0 \s-1AUTHOR\s0"
 709 .IX Subsection "ORIGINAL AUTHOR"
 710 Michael G Schwern <schwern@pobox.com>
 711 .Sh "\s-1THANKS\s0"
 712 .IX Subsection "THANKS"
 713 Liz and \s-1RUZ\s0 for performance tweaks.
 714 .PP
 715 Tels, for his big feature request/bug report.
 716 .PP
 717 Various presenters at YAPC::Asia 2009 for criticising the non-Moose interface.
 718 .SH "SEE ALSO"
 719 .IX Header "SEE ALSO"
 720 See Class::Accessor::Fast and Class::Accessor::Faster if speed is more
 721 important than flexibility.
 722 .PP
 723 These are some modules which do similar things in different ways
 724 Class::Struct, Class::Methodmaker, Class::Generate,
 725 Class::Class, Class::Contract, Moose, Mouse
 726 .PP
 727 See Class::DBI for an example of this module in use.