NAME

PTools::Local - PTools Framework for Local and Global variables

VERSION

This document describes version 0.09, released Nov 12, 2002.

SYNOPSIS

    use '/opt/tools/<AppSubDir>/lib';
    use PTools::Local;

    $attrValue = PTools::Local->param( 'AttributeName' );
or  $attrValue = PTools::Local->get( 'AttributeName' );

    PTools::Local->set( 'AttributeName', $attrValue );

    PTools::Local->reset( 'AttributeName' );

    $fullPath = PTools::Local->path( 'PathAttribute' );
or  $fullPath = PTools::Local->path( 'PathAttribute', 'filename.ext' );
or  $fullPath = PTools::Local->path( 'PathAttribute', 'extra/path/filename.ext' );

    PTools::Local->resetAppVariables();
    PTools::Local->resetVariables();

DESCRIPTION

This PTools::Local module is a component of the Perl Tools Framework that provides a mechanism for maintaining and resetting some or all of the necessary 'script local' and 'application global' variables.

Using this class avoids the problem of having to pass long argument lists to methods in modules or scripts. Neither this class, nor instances thereof, need be passed. Simlpy 'using' this class provides access to the local/global variable storage space.

This provides a deceptively simple mechanism that allows for mostly 'relocatable' Perl scripts. I.e., scripts that rely on the methods in an application's PTools::Local module to generate file system paths will almost never need to change if/when they are moved to an entirely different directory subtree (assuming, of course, that all the related subdirectories remain in the relative position).

use lib "/my/lib";   # if/when PTools::Local not under "site_perl"
use PTools::Local;   # do this before 'use'ing other modules
use Whatever;        # whatever else your application uses

In addition, for a completely 'relocatable' script, add the following eight lines to the very top of a Perl script. Place a copy of PTools::Local in the directory generated in the 'use lib' line and this module will figure out the rest. After this, as long as a relative directory structure is maintained, your Perl scripts and modules can move to other locations without changing a thing.

use Cwd;
BEGIN {  # With the following addition, script is relocatable.
  my $cwd = $1 if ( $0 =~ m#^(.*/)?.*# );  chdir( "$cwd/.." );
  my($top,$app)=($1,$2) if ( getcwd() =~ m#^(.*)(?=/)/?(.*)#);
  $ENV{'PTOOLS_TOPDIR'} = $top;  $ENV{'PTOOLS_APPDIR'} = $app;
} #-----------------------------------------------------------
use lib "$ENV{'PTOOLS_TOPDIR'}/$ENV{'PTOOLS_APPDIR'}/lib";
use PTools::Local;

use MyMain::Module;
$result = run MyMain::Module();
exit( $result ||0 );

For those who have moved to a pure OO environment, the above dozen lines represents a full and complete example of a script. It just acts as an outer block to initiate the main module for some application.

[ While this class has been stable for many years, it needed some ]
[ fairly significant changes to make it acceptable for submittal  ]
[ to CPAN. If you have any problems, contact the author. Thanks.  ]

Constructor

A constructor is provided for convenience; however, all methods are designed for use as class methods.

$local = new PTools::Local;     # constructor provided for convenience

$local = "PTools::Local";       # (no constructor necessary)

Methods

param ( AttributeName )

get ( AttributeName )

Retrieve the value for a currently set attribute.

    $attrValue = PTools::Local->param( 'AttributeName' );
or  $attrValue = PTools::Local->get( 'AttributeName' );

set ( AttributeName, NewValue )

Set the value for either a new or currently set attribute.

PTools::Local->set( 'AttributeName', $attrValue );

reset ( AttributeName )

Reset (unset) the value for currently set attribute.

PTools::Local->reset( 'AttributeName' );

path ( PathAttribute [, AdditionalPath ] )

Return a 'rooted' file system path, optionally with a filename and/or additional path segments.

    $dirPath  = PTools::Local->path( 'PathAttribute' );

or  $fileName = PTools::Local->path( 'PathAttribute', 'filename.ext' );

or  $fileName = PTools::Local->path( 'PathAttribute', 'extra/path/filename.ext' );

dump ( [ State ] )

The dump method is used to display the currently defined attributes and values. This will also show other useful State information.

The State value can be any or all of the following strings. The default for this method is to show only the vars (currently defined local and global attributes and their values).

incpath   - show current library include path(s)
origpath  - show the original lib include path(s)
inclib    - show full path of currently included library modules
vars      - show all local/global attributes and their values
env       - show all Environment Variables
all       - show all of the above

Examples:

print PTools::Local->dump();
print PTools::Local->dump( "incpath" );
print PTools::Local->dump( "incpath,inclib" );
print PTools::Local->dump( "vars,env" );
print PTools::Local->dump( "all" );

writeLog ( VerboseLevel, LogMsg [, LogFile ] )

Append an entry to the logfile defined by the 'app_logFile' attribute, but only if the VerboseLevel is greater than the value defined by the 'app_verbose' attribute. Optionally, pass the name of another log file. A VerboseLevel of -1 disables logging.

PTools::Local->writeLogFile( 0, 'Almost always log at this verbose level' );

PTools::Local->writeLogFile( 10, 'Maybe log at this verbose level' );

cgiRequired

This method is used with Web CGI-BIN scripts to determine whether the script is currently running under a Web server.

PTools::Local->cgiRequired();          # die unless running in CGI contect

Other attributes are available to determine correct actions to take.

PTools::Local->get('nph') and print "HTTP/1.0 200 OK\n";
PTools::Local->get('cgi') and print "Content-type: text/html\n\n";

resetVariables

resetAppVariables

These methods are invoked in mod_perl or FastCGI scripts to reset all 'script local' and 'application global' variables between iterations of a persistent Perl script.

This first form is the most generally useful to reset variables.

PTools::Local->resetVariables;

The second form is used with variations of the PTools::Local module discussed elsewhere. See the See Also section for further pointers.

PTools::Local->resetAppVariables;

Update: This class does not work in a persistent mod_cgi environment. See the Warnings section, below.

Application Attributes

The following attributes (or Variables) are provided by the PTools::Local module. Note that the attribute names are not case sensitive.

Layout of Application specific directories.

 Directory path        Variable      Description
 --------------------  --------      ----------------------------------
 tools/                APP_TOPDIR    Common subdir, could be "apps," whatever
    example1/          APP_PATH      Root for app; for dir name use APP_DIR
    *  bin/            APP_BINDIR    Scripts and binary files
       bin/util/       APP_BINUTL    Utility scripts and binary files
       conf/           APP_CFGDIR    Configuration files
       data/           APP_DATDIR    Data subdirectories
       data/logs       APP_LOGDIR    Log subdirectory
       data/queue      APP_QUEDIR    Data queues (ad hoc)
       data/tmp        APP_TMPDIR    Temporary files
       data/xml        APP_XMLDIR    XML data files
       doc/            APP_DOCDIR    Private documents
    *  lib/            APP_LIBDIR    Library files
       lib/util/       APP_LIBUTL    Library utilities
       man/            APP_MANDIR    man(n) files
       src/            APP_SRCDIR    Source for Binary files
       src/util/       APP_SRCUTL    Source for Binary utilities
       webcgi/         APP_CGIDIR    CGI subdirectories; for URL use APP_CGIURL
       webcgi/util/    APP_CGIUTL    CGI utilities
       webdoc/         APP_WEBDOC    Public documents; for URL use APP_WEBURL
       webdoc/images   APP_IMGDIR    Web images; for URL use APP_IMGURL
       webdoc/DTD      APP_DTDDIR    DTD specs; for URL use APP_DTDURL
       webdoc/index.html             Default welcome page

    * = required subdirectories ... all others are optional
	(the only required module in "lib" is "PTools::Local.pm")

INHERITANCE

This PTools::Local class inherits from the PTools::Global abstract base class.

WARNINGS

[ While this class has been stable for many years, it needed some ]
[ fairly significant changes to make it acceptable for submittal  ]
[ to CPAN. If you have any problems, contact the author. Thanks.  ]

Unfortunately, the PTools::Local class does not work well when running in a persistent mod_perl environment. The original intent was for a copy of this class to be used within multiple different components of a larger application.

Running within a persistent mod_perl envorionment makes this usage impossible, as only the first script in a component that happens to load a copy of this class will 'win.' If/when other components attempt to load their own version of this class, the attempt will silently fail causing a lot of subtle and not-so-subtle problems.

AUTHOR

Chris Cobb, <nospamplease@ccobb.net>

COPYRIGHT

To install PTools, copy and paste the appropriate command in to your terminal.

cpanm

cpanm PTools

CPAN shell

perl -MCPAN -e shell
install PTools

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)