NAME

       Class::AutoloadCAN - Make AUTOLOAD, can and inheritance cooperate.

SYNOPSIS

         package Foo;
         use Class::AutoloadCAN;

         sub CAN {
           my ($starting_class, $method, $self, @arguments) = @_;
           return sub {
             my $self = shift;
             print join ", ", $method, @_;
             print "\n";
           };
         }

         # And this prints the famous greeting.
         Foo->hello("world");

DESCRIPTION

       This module solves a fundamental conflict between AUTOLOAD, can and inheritance.  The
       problem is that while you can implement anything in AUTOLOAD, UNIVERSAL::can is not aware
       that it is there.  Attempting to modify UNIVERSAL::can to document those methods is very
       hard.  And if a parent class uses AUTOLOAD then subclasses have to do a lot of work to
       make their AUTOLOADs cooperate with the parent one.  It is harder still if 2 parent
       classes in a multiple inheritance tree wish to cooperate with each other.  Few try to do
       this, which may be good since those who try usually get it wrong.  See
       http://www.perlmonks.org/?node_id=342804 for a fuller discussion.

       With this module instead of writing AUTOLOADs, you write CANs.  Based on what they return,
       Class::AutoloadCAN will decide whether you handle the call or it needs to search higher up
       the inheritance chain.

       Here are the methods and functions that matter for the operation of this module.

       "AUTOLOAD"
           An AUTOLOAD will be installed in every package that uses this module.  You can choose
           to have it installed in other packages.  If you write your own AUTOLOADs, you can
           easily break this module.  So don't do that.  Write CANs instead.

       "can"
           UNIVERSAL::can will be modified to be aware of the functions provided dynamically
           through this module.  You are free to override can in any subclass and this module
           will not interfere.  I have no idea why you would want to, though.

       "CAN"
           If there is a method named CAN in a class that inherits from one that
           Universal::AutoloadCAN was installed to, it may be called in deciding how a method is
           implemented.  It will be passed the class that the method search started in, the
           method name, the object called, and the arguments to the function.  It is expected to
           do nothing but return a subroutine reference if it implements that method on that
           object, or undef otherwise.

           If that subroutine is actually called, it will be passed all of the usual arguments
           that a method call gets, and the AUTOLOAD that found it will erase itself from the
           callstack.

       "Class::AutoloadCAN::import"
           If the import method for Class::AutoloadCAN is called with no arguments it installs an
           AUTOLOAD in the calling class.  If it is called with arguments, it installs an
           AUTOLOAD in those classes as well.  Use with caution: this is a convenience feature
           that is not expected to be used very often.

SUGGESTION

       Many people use AUTOLOAD to implement large numbers of fixed and straightforward methods.
       Such as accessors.  If you are doing this, then I suggest implementing them by
       typeglobbing closures instead of by using AUTOLOAD or this module.  Here is a simple
       example:

         package Parent;
         use strict;

         sub make_accessors {
           my ($class, @attributes) = @_;
           foreach my $attribute (@attributes) {
             no strict 'refs';
             *{"$class\::$attribute"} = sub {
               my $self = shift;
               if (@_) {
                 $self->{$attribute} = shift;
               }
               return $self->{$attribute};
             };
           }
         }

         package Child;
         our @ISA = 'Parent';
         __PACKAGE__->make_accessors(qw(this that the other));

       This approach is simpler, often faster, and avoids some of the problems that AUTOLOAD has,
       like mistaking function calls as method calls.

BUGS AND LIMITATIONS

       There are many other issues with AUTOLOAD that this module does not address.  Primary
       among them is the fact that if you call a function that does not exist in a package that
       inherits from one with an AUTOLOAD, Perl will do a method search for that AUTOLOAD.  This
       is why this module does not install AUTOLOAD in UNIVERSAL by default, and it is strongly
       suggested that you not do so either.

       Also many people like to lazily install AUTOLOADed methods in the local package so that
       they will be found more quickly in the future.  This module won't do that for you, but you
       can easily do that from within CAN.  The reason that this module doesn't do that is that
       some useful CANs may decide whether to support a method on an object by object basis.

ACKNOWLEDGEMENTS

       My thanks to various people on Perlmonks for conversations that clarified what problems
       AUTOLOAD raises, and convinced me that it would be good to have a solution to them.

AUTHOR AND COPYRIGHT

       Ben Tilly (btilly@gmail.com).

       Copyright 2005.  This may be copied, modified and distributed on the same terms as Perl.