NAME

PTools::Loader - Demand load Perl modules at run-time w/error checking.

VERSION

This document describes version 0.11, released October, 2004.

SYNOPSIS

By default PTools::Loader will not abort on errors. Add string generror in use statement to cause PTools::Loader to abort when errors are detected.

     use PTools::Loader qw(generror);        ## Loader will abort on errors

     $loader = new PTools::Loader;
     $loader = "PTools::Loader";

     $loader->req("Date::Format");               # require module
     $loader->use("CGI");                        # use module
     $loader->use("CGI", "qw(:standard)");       # use module w/params 
     $loader->eval("filename");                  # eval contents of "filename"
     $loader->ver("5.004");                      # check Perl level

     @result = $loader->eval("filename");        # eval contents of "filename"
     $codeRef= $loader->codeRef( @result );      # extract code ref from 'eval'

     $loader->inc("req", "LWP");                 # require module
     $loader->inc("use", "Date::Format");        # use module
     $loader->inc("use", "CGI ':standard'");     # use module w/params 

By default PTools::Loader will not abort on errors, and the abort method must be called. This will simply return when no errors occurred.

 or  use PTools::Loader;                      ## Loader won't abort on errors

     $loader = new PTools::Loader;
     $loader = "PTools::Loader";

     $error = $loader->req("Forms::MainMenu");   # these first three exmamples
     $error = $loader->use("CGI","2.56");        #   will attempt to load the
     $error = $loader->eval("filename");         #   file and return any error

     @result = $loader->eval("filename");        # eval contents of "filename"
     $codeRef= $loader->codeRef( @result );      # extract code ref from 'eval'

     (@err) = $loader->use("Roman");             # collect all info on error
     @err and $self->cleanup;  # for example,   # delay abort to run cleanup
     $loader->abort( @err );                     # cause abort IFF any error

     ($perlError, $loadMode, $moduleName,       # collect all info on error
      $callingPackage, $callingFileName,
      $callingFileLineNumber)            = $loader->use("Mail::Mailer");

     ($perlError, $loadMode, $moduleName,
      $callingPackage, $callingFileName,
      $callingFileLineNumber, $codeRef)  = $loader->eval("Mail::Mailer");

DESCRIPTION

Include a Perl module via "use", "require" or "eval" and detect errs.

Constructor

None. All functions in this module are implemented as class methods.

Methods

use ( Module [, @args ] )

Include the specified Perl Module via the use function. Any additional arguments are appended directly to the use function.

Examples:

 $loader->use("CGI");

 $loader->use("CGI", "qw(:standard)");

 $error = $loader->use("CGI","2.56");

 (@err) = $loader->use("Roman");
  @err and $self->cleanup;
  $loader->abort( @err );            # only aborts if error occurred

req ( Module )

Include the specified Perl Module via the require function.

Examples:

 $loader->inc("req", "LWP");

 $error = $loader->req("Forms::MainMenu");

eval ( File )

Include the specified Perl File via the eval function.

Examples:

 $loader->eval( $filename );

 $error = $loader->eval( $filename );

codeRef ( @params )

As this module only contains class methods, the codeRef method is available to extract the code reference from the results of any prior call to the eval method.

 use $loader;

 @results = $loader->eval( $fileName );

 $loader->abort( @results );

 $codeRef = $loader->codeRef( @results );

The above complete example shows one way to ensure the eval call was successful. The call to abort will only terminate the script when errors were detected during the eval.

If the fileName contains a fully defined package, it is not necessary to obtain the codeRef as the resulting code will be available using its package name space as soon as the eval method completes successfully.

Also see notes on the generror option to the use statement, above, and discussion of the abort method, below.

inc ( Mode, Module [, Args ] )

Include the specified Perl Module based on the Mode.

Mode

The Mode parameter must be one of use or req.

Module

The Module parameter is the name of the Perl module, as above.

Args

The Args parameter are optional parms passed to the Perl module, as above.

Examples:

 $loader->inc("req", "LWP");                 # require module

 $loader->inc("use", "Date::Format");        # use module

 $loader->inc("use", "CGI ':standard'");     # use module w/params 

ver

Ensure the required version of the Perl intepreter is currently running.

Example:

 $loader->ver("5.004");

abort ( @params )

abort ( Err, Mode, Module, Pack, File, Line )

The abort method is available to defer aborting the script when errors are detected. This is useful when a "cleanup" step is necessary, for example.

Example:

 (@err) = $loader->use("Roman");             # collect all info on error
 @err and $self->cleanup;                   # delay abort to run cleanup
 $loader->abort( @err );                     # cause abort IFF any error

The parameter list passed to the abort method is designed to be the same as returned from any of the use, req, eval or inc methods.

During the abort, this method emits HTML when run via a Web CGI script. Otherwise it emits plain text.

INHERITANCE

No classes currently inherit from this class.

AUTHOR

Chris Cobb [no dot spam at ccobb dot net]

COPYRIGHT

Copyright (c) 2002-2007 by Chris Cobb. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.