NAME
      Class::Accessor - Automated accessor generation

SYNOPSIS
      package Foo;

      use base qw(Class::Accessor);
      Foo->mk_accessors(qw(this that whatever));

      sub new { return bless {} }

      # Meanwhile, in a nearby piece of code!
      my $foo = Foo->new;

      my $whatever = $foo->whatever;    # gets $foo->{whatever}
      $foo->this('likmi');              # sets $foo->{this} = 'likmi'
  
      # Similar to @values = @{$foo}{qw(that whatever)}
      @values = $foo->get(qw(that whatever));
  
      # sets $foo->{that} = 'crazy thing'
      $foo->set('that', 'crazy thing');

DESCRIPTION
    This module automagically generates accessor/mutators for your class.

    Most of the time, writing accessors is an exercise in cutting and
    pasting. You usually wind up with a series of methods like this:

      # accessor for $obj->{foo}
      sub foo {
          my($self) = shift;

          if(@_ == 1) {
              $self->{foo} = shift;
          }
          elsif(@_ > 1) {
              $self->{foo} = [@_];
          }

          return $self->{foo};
      }
          
      # accessor for $obj->{bar}
      sub bar {
          my($self) = shift;

          if(@_ == 1) {
              $self->{bar} = shift;
          }
          elsif(@_ > 1) {
              $self->{bar} = [@_];
          }

          return $self->{bar};
      }

      # etc...

    One for each piece of data in your object. While some will be unique,
    doing value checks and special storage tricks, most will simply be
    exercises in repetition. Not only is it Bad Style to have a bunch of
    repetitious code, but its also simply not Lazy, which is the real
    tragedy.

    If you make your module a subclass of Class::Accessor and declare your
    accessor fields with mk_accessors() then you'll find yourself with a set
    of automatically generated accessors which can even be customized!

    The basic set up is very simple:

        package My::Class;
        use base qw(Class::Accessor);
        My::Class->mk_accessors( qw(foo bar car) );

    Done. My::Class now has simple foo(), bar() and car() accessors defined.

    mk_accessors
            Class->mk_accessors(@fields);

        This creates accessor/mutator methods for each named field given in
        @fields. Foreach field in @fields it will generate two accessors.
        One called "field()" and the other called "_field_accessor()". For
        example:

            # Generates foo(), _foo_accessor(), bar() and _bar_accessor().
            Class->mk_accessors(qw(foo bar));

    The rest is details.

DETAILS
    An accessor generated by Class::Accessor looks something like this:

        # Your foo may vary.
        sub foo {
            my($self) = shift;
            if(@_) {    # set
                return $self->set('foo', @_);
            }
            else {
                return $self->get('foo');
            }
        }

    Very simple. All it does is determine if you're wanting to set a value
    or get a value and calls the appropriate method. Class::Accessor
    provides default get() and set() methods which your class can override.
    They're detailed later.

  Modifying the behavior of the accessor

    Rather than actually modifying the accessor itself, it is much more
    sensible to simply override the two key methods which the accessor
    calls. Namely set() and get().

    If you -really- want to, you can override make_accessor().

    set
            $obj->set($key, $value);
            $obj->set($key, @values);

        set() defines how generally one stores data in the object.

    get
            $value  = $obj->get($key);
            @values = $obj->get(@keys);

    make_accessor
            $accessor = Class->make_accessor($field);

        Generates a subroutine reference which acts as an accessor for the
        given $field.

CAVEATS AND TRICKS
    Class::Accessor has to do some internal wackiness to get its job done
    quickly and efficiently. Because of this, there's a few tricks and traps
    one must know about.

    Hey, nothing's perfect.

  Don't make a field called DESTROY

    This is bad. Since DESTROY is a magical method it would be bad for us to
    define an accessor using that name. Class::Accessor will carp if you try
    to use it with a field named "DESTROY".

  Overriding autogenerated accessors

    You may want to override the autogenerated accessor with your own, yet
    have your custom accessor call the default one. Normally, one would
    expect this to work:

        package My::Class;
        use base qw(Class::Accessor);
        use public qw(foo);

        sub foo {
            my($self) = shift;
        
            ## Do some special work ##

            # XXX THIS WILL NOT WORK.  There is no SUPER::foo().
            return $self->SUPER::foo(@_);
        }

    Unforunately, it doesn't. Class::Accessor employs an autoloader to
    inject methods directly into its subclass. This means there -is- no
    SUPER::foo(). As a simple hack around this, in addition to defining
    foo(), Class::Accessor will also define an alias as _foo_accessor().

    So the correct way to override an autogenerated accessor is to use
    _foo_accessor().

        package My::Class;
        use base qw(Class::Accessor);
        use public qw(foo);

        sub foo {
            my($self) = shift;
        
            ## Do some special work ##

            # The correct way.
            return $self->_foo_accessor(@_);
        }

AUTHOR
    Michael G Schwern <schwern@pobox.com>


WHAT IS THIS?

This is Class::Accessor, a perl module.  Please see the README that comes with
this distribution.

HOW DO I INSTALL IT?

To install this module, cd to the directory that contains this README
file and type the following:

   perl Makefile.PL
   make
   make test
   make install

To install this module into a specific directory, do:
   perl Makefile.PL PREFIX=/name/of/the/directory
   ...the rest is the same...

Please also read the perlmodinstall man page, if available.

