NAME

Autoload::AUTOCAN - Easily set up autoloading

SYNOPSIS

  package My::Class;
  use Moo; # or object system of choice
  use Autoload::AUTOCAN;
  
  has count => (is => 'rw', default => 0);
  
  sub increment { $_[0]->count($_[0]->count + 1) }
  
  sub AUTOCAN {
    my ($self, $method) = @_;
    return sub { $_[0]->increment } if $method =~ m/inc/;
    return undef;
  }
  
  1;
  
  # elsewhere
  my $obj = My::Class->new;
  $obj->inc;
  say $obj->count; # 1
  $obj->increment; # existing method, not autoloaded
  say $obj->count; # 2
  $obj->do_increment;
  say $obj->count; # 3
  $obj->explode; # method not found error

DESCRIPTION

Autoloading is a very powerful mechanism for dynamically handling function calls that are not defined. However, its implementation is very complicated. For the simple case where you wish to allow method calls to methods that don't yet exist, this module allows you to define an AUTOCAN method which will return either a code reference or undef.

Autoload::AUTOCAN installs an AUTOLOAD subroutine in the current package, which is invoked when an unknown method is called. The installed AUTOLOAD will call AUTOCAN with the invocant (class or object the method was called on) and the method name. If AUTOCAN returns a code reference, it will be called with the same arguments as passed to the unknown method (including the invocant). If AUTOCAN returns undef, an error will be thrown as expected when calling an undefined method.

Along with AUTOLOAD, the module installs a can method which returns code references as normal for defined methods (see UNIVERSAL), and delegates to AUTOCAN for unknown methods.

CONFIGURING

Autoload::AUTOCAN accepts import arguments to configure its behavior.

functions

AUTOLOAD affects standard function calls in addition to method calls. By default, the AUTOLOAD provided by this module will die (as Perl normally does without a defined AUTOLOAD) if a nonexistent function is called without a class or object invocant. If you wish to autoload functions instead of methods, you can pass functions as an import argument, and the installed AUTOLOAD will autoload functions using AUTOCAN from the current package, rather than using the first argument as an invocant.

  package My::Functions;
  use Autoload::AUTOCAN 'functions';
  
  sub AUTOCAN {
    my ($package, $function) = @_;
    return sub { $_[0]x5 } if $function =~ m/dup/;
    return undef;
  }
  
  # elsewhere
  say My::Functions::duplicate('foo'); # foofoofoofoofoo
  say My::Functions::foo('bar'); # undefined subroutine error

install_subs

By passing install_subs as an import argument, any autoloaded function or method returned by AUTOCAN will be installed into the package, so that future invocations do not need to go through AUTOLOAD. This should not be used if the autoloaded code is expected to change in subsequent calls to AUTOCAN, as the installed version will be called or returned by can directly.

  package My::Class;
  use Moo;
  use Autoload::AUTOCAN 'install_subs';
  
  sub AUTOCAN {
    my ($self, $method) = @_;
    my $hash = expensive_calculation($method);
    return sub { $hash };
  }
  
  # elsewhere
  my $obj = My::Class->new;
  $obj->foo; # sub foo installed in My::Class
  $obj->foo; # not autoloaded anymore

CAVEATS

If you use namespace::clean, it will clean up the installed AUTOLOAD function. To avoid this, either use this module after namespace::clean, or add an exception for AUTOLOAD as below.

  use Autoload::AUTOCAN;
  use namespace::clean -except => 'AUTOLOAD';

This issue does not seem to occur with namespace::autoclean.

BUGS

Report any issues on the public bugtracker.

AUTHOR

Dan Book <dbook@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2017 by Dan Book.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)

SEE ALSO

AutoLoader, SelfLoader