Module::AutoINC - Download and install CPAN/PPM modules upon first use.

Module-AutoINC documentation Contained in the Module-AutoINC distribution.

Index

Code Index:

NAME

Top

Module::AutoINC - Download and install CPAN/PPM modules upon first use.

SYNOPSIS

Top

  perl -MModule::AutoINC <script>

ABSTRACT

Top

When Module::AutoINC is loaded, it will add itself to @INC and catch any requests for missing resources. If a Perl module is requested that has not been installed, then this will attempt to load it. Under Active State Perl (or any Perl where PPM is available), PPM will attempt to install it. Otherwise CPAN will be queried and, assuming that the module exists on CPAN, CPAN::Shell will be invoked to install it. Execution of the script continues after the requisite module has been installed.

DESCRIPTION

Top

Module::AutoINC is a slightly useful tool designed to streamline the process of installing the modules required by a script. By loading the Module::AutoINC module (usually via a "-MModule::AutoINC" command-line option), the user is registering a handler that will catch any attempt to use a module that does not exist on the local machine. In this case, the CPAN::Shell module will be invoked to search for the specified module and, if found, an attempt will be made to install the module. If successful, the module will be loaded and execution will continue as normal.

Imported Symbols

You can modify the behavior of the module slightly using several import symbols. All import symbols are case-insensitive.

If you import the special symbol 'force' then the installation of the module(s) will be forced. The definition of a 'forced' installation varies depending on whether you are installing using PPM or CPAN. See the relevant documentation for each system for more information.

You can override the installation method detection using the import symbols, 'cpan' or 'ppm'. 'cpan' will cause CPAN to be used for module installation no matter whether PPM is available or not. 'ppm' will attempt to install the module using PPM regardless of whether ppm is findable by Module::AutoINC. Of course, you should know what you are doing if you use these import symbols.

Examples

Top

  perl -MModule::AutoINC -MLingua::Num2Word=cardinal -le 'print cardinal("en", 42)'

...will download and install Lingua::Num2Word and Lingua::EN::Num2Word.

  perl -MModule::AutoINC=cpan -MLingua::Num2Word=cardinal -le 'print cardinal("de", 42)'

...will then download and install (using CPAN, even under ActiveState Perl) Lingua::DE::Num2Word (German).

  perl -MModule::AutoINC=force -MLingua::Num2Word=cardinal -le 'print cardinal("es", 42)'

...will then download and install (forcefully) Lingua::ES::Numeros (Spanish).

CPAN CAVEATS

Top

PPM CAVEATS

Top

MOTIVATION

Top

Don's Motivation

The description for the Acme::RemoteINC CPAN module ("Slowest Possible Module Loading") prompted me to write this module. The only thing slower than loading precompiled modules via FTP is loading module source code from FTP and compiling it. Except maybe carrier pigeons.

As you can see from the CAVEATS section, there is a fair amount of set-up work required and it will not work for all modules. This makes it relatively useless, especially in a production environment. But it's a cool hack, and could potentially be useful under very limited circumstances.

Mike's Motivation

Since we use a number of CPAN modules in our scripts at work setting up new systems with the range of modules can be onerous especially for those who are not very experienced with Perl and it's nuances. Don's CPAN::AutoINC was a good start on a solution, but since we use a mix of Linux and Windows systems I wanted something that would handle ActiveState Perl as well as vanilla Perl transparently.

HISTORY

Top

v0.02

  • No code changes. The Makefile.pl was asking for too recent a version of Perl. Now it asks for Perl 5.004 as a minimum which is about the time the CPAN.pm module was introduded, near as I can tell.

v0.01

  • Uses Perl Package Manager to do installations if it is available.
  • Renamed module to reflect broader functionality
  • Added ability to do 'forced' intalls.
  • Added ability to explicitly choose between CPAN and PPM installation methods.

CPAN::AutoINC v0.01

Don Schwarz's original version. Did CPAN installs only.

SEE ALSO

Top

CPAN::AutoINC, CPAN, Perl Package Manager documentation, perlfunc's section on the require function for the features of @INC that this module uses.

AUTHOR

Top

Mike MacKenzie, <mackenzie@cpan.org> Original CPAN::AutoINC: Don Schwarz, <don@schwarz.name>

COPYRIGHT AND LICENSE

Top

Copyright 2006 by Language Weaver, Inc.

Based on CPAN::AutoINC

Copyright 2004 by Don Schwarz

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Module-AutoINC documentation Contained in the Module-AutoINC distribution. 
package Module::AutoINC;

use strict;
our $PPM;
BEGIN {eval 'use PPM::UI'; $PPM = not "$@"}  # Do we have Perl Package Manager?
use CPAN;
use File::Spec;
use File::Basename;
use Config;

our $VERSION = '0.02';
our $FORCE;

sub import {
    my $package = shift;
    $FORCE = grep /^force$/i, @_;
    my $ppm = grep /^ppm$/i, @_;
    my $cpan = grep /^cpan$/i, @_;
    die "You can't specify both PPM and CPAN installation methods." 
        if $ppm && $cpan;
    *Module::AutoINC::INC = *Module::AutoINC::PPMINC if $ppm;
    *Module::AutoINC::INC = *Module::AutoINC::CPANINC if $cpan;
}

sub new { bless {}, ref($_[0]) || $_[0] }

{
my $ppmpath;
sub Module::AutoINC::PPMINC {
    my ($self, $filename) = @_;

    $ppmpath ||= File::Spec->catfile(dirname($Config{perlpath}), 'ppm');

    if ($filename =~ /^(.+)\.pm$/) {
        my $module = $1;
        $module =~ tr|/|-|;
        
        system($ppmpath, 'install', $FORCE ? '-force' : (), $module);
        
        foreach my $prefix (@INC) {
            my $realfilename = File::Spec->catfile($prefix,$filename);
            my $fh;
            return $fh if -f $realfilename && open($fh, $realfilename);
        }
    }  
    
    return undef;
}
}

sub Module::AutoINC::CPANINC {
    my ($self, $filename) = @_;

    if ($filename =~ /^(.+)\.pm$/) {
        my $module = $1;
        $module =~ s|/|::|g;
        
        foreach my $m (expand('Module', $module)) {
            $FORCE ? CPAN::Shell->force('install', $m)
                   : CPAN::Shell->install($m);
        
            foreach my $prefix (@INC) {
                my $realfilename = File::Spec->catfile($prefix,$filename);
                my $fh;
                return $fh if -f $realfilename && open($fh, $realfilename);
            }
        }
    }

    return undef;
}


BEGIN {
    *Module::AutoINC::INC = $PPM ? *Module::AutoINC::PPMINC 
                                 : *Module::AutoINC::CPANINC;
    push (@INC, new Module::AutoINC());
};

1;
__END__