The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
PTools-0.02
/ PTools::Local

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 strict;           # strict and/or warnings can always go first
use PTools::Local;    # do this before 'use'ing other applic. modules
use lib "legacy/lib"; # modules here will be included before others
use Whatever;         # then use whatever else your application uses

If you have other, legacy Perl library path(s) to include, you can add them either just above or just below the use PTools::Local line. Above, and it/they will appear between app lib paths and system paths. Below, and it/they will appear at the very top of your @INC paths. (If it's confusing at first, try print PTools::Local-dump('incpaths')> and it will soon become obvious what's happening.)

For completely 'relocatable' scripts, just add the first seven lines, below, to the very top of a Perl script. The PTools::Local class will figure out the rest. Then, 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 {  # Script is relocatable. See http://ccobb.net/ptools/
  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 PTools::Local;          # PTools local/global vars/methods

use MyMain::Module;          # then your script starts here #  
exit( run MyMain::Module() );

If you have moved to a pure OO environment, the above nine lines of code is 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 find 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 find any problems, contact the author. Thanks.  ]

Using this PTools::Local class sets the current working directory to the parent of where a given script is located. This is a necessary part of a 'self-locating' Perl script.

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.

SEE ALSO

See PTools::Global.

In addition, general documention about the Perl Tools Framework is available.

See http://www.ccobb.net/ptools/.

AUTHOR

Chris Cobb [no dot spam at ccobb dot net]

COPYRIGHT

Copyright (c) 1997-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.