NAME
       Class::Accessor::Ref - Access members by reference

SYNOPSIS
         package Foo;
         use base qw(Class::Accessor::Ref);
         use Some::API;

         my @members = qw(fruit color);
         Foo->mk_accessors(@members);     # as with Class::Accessor
         Foo->mk_refaccessors(@members);

         my $obj = Foo->new({fruit => 'grape', color => 'green'});
         Some::API::redden($obj->_ref_color);
         print $obj->color;               # prints 'red'

DESCRIPTION
       This is an extension of Class::Accessor that allows taking a reference
       of members of an object. This is typically useful when your class
       implementation uses a third-party module that expect an in/out parame-
       ter in its interface.

       Without Class::Accessor::Ref, you might try to do somethin like

         my $reference = \$obj->member;   # WRONG!
         Some::API::call($reference);

       But that takes a reference to a *copy* of $obj->member, and is thus not
       useful if you want to use the reference to later change the member's
       value.

       It is quite possible to do something like

         my $reference = \$obj->{member}; # right, but risky

       But then you will get no errors if you accidentally mistype the mem-
       ber's name.

       Class::Accessor::Ref is used very similarly to Class::Accessor -- just
       subclass it instead of Class::Accessor in your module, and call
       mk_accessors on the fields you want to generate accessors for. Then,
       call mk_refaccessors on the subset of the fields you want reference-
       taking accessors generated for. The accessors will be automatically
       named _ref_FIELD. You can continue to use the normal (non-reference)
       accessors as before whenever appropriate.

       Methods


       mk_refaccessor
               Class->mk_refaccessors(@fields);

           This creates accessor methods for each named field given in
           @fields.  Foreach field in @fields it will generate one accessor
           called "_ref_field()".  Normal accessors for the fields *must* have
           already been created with Class::Accessor::mk_accessors(). For
           example:

               # Generates _ref_foo(), _ref_bar() but not _ref_baz():
               #     Class->mk_accessors(qw(foo bar baz));
               #     Class->mk_refaccessors(qw(foo bar));

           It is up to the user of this reference to know what to do with it.

CAVEATS
       Class::Accessor::Ref generates methods called _ref_SOMETHING in the
       caller's namespace. Having an existing member whose name begins with
       _ref_ would render the normal accessor to that member inaccessible, so
       don't do that.

       One point of Class::Accessor is to allow you to avoid changing members
       directly. Since whoever gets hold of the return value of a _ref_ acces-
       sor can circumvent any validations you may have imposed on the member
       (for example, by overriding the normal setter method), this can be con-
       sidered somewhat unsafe. The main use of Class::Accessor::Ref is inside
       class implementations, where you have control over who you trust with
       giving a reference to your private data and who you don't.

AUTHOR
       Gaal Yahas <gaal@forum2.org>

SEE ALSO
       Class::Accessor


WHAT IS THIS?

This is Class::Accessor::Ref, 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.

