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.

perl v5.36.0                                       2022-10-14                            Class::AutoloadCAN(3pm)