NAME
App::Framework::Base - Base application object
SYNOPSIS
use App::Framework::Base ;
our @ISA = qw(App::Framework::Base) ;
sub new { ... }
sub exit { ... }
sub options { ... }
DESCRIPTION
Base class for applications. Expected to be derived from by an implementable class (like App:Script).
Base provides (and handles) the following options:
debug Set the debug level value
h|"help" Show brief help message then exit
man Show full man page then exit
pod Show full man page as pod then exitOnce the object has been created it can then be run by calling the 'go()' method. go() calls in turn:
* pre_run() Gets & processes the options, then calls the pre_run_fn if set
* run() Handles any special options (-man etc), then calls the run_fn if set
* post_run() Calls post_run_fn if set
* exit() Called with exit value 0 if execution reaches this farThe pre_run_fn, run_fn, and post_run_fn fields of the object can either be set directly as part of the new() call, or the prefered approach is to define pre_run, run, and post_run subroutines in the calling namespace. These subroutines are detected by App::Framework::Base and automatically set on the object.
Similarly, the __DATA__ area of the calling namespace if the prefered area to use for object set up of common fields (rather than as part of the new() call). Example __DATA__ contents:
__DATA__
[HISTORY]
30-May-08 SDP Re-written to use App::Framework::Script
28-May-08 SDP New
[SUMMARY]
List (and repair) any faulty rrd database files
[SYNOPSIS]
$name [options] <rrd file(s)>
[OPTIONS]
-d|'dir'=s temp directory [default=/tmp]
Specify the directory in which to store the xml output files (created by dumping the rrd databases)
-repair Enable rrd repair
When this option is specified, causes the script to repair any faulty rrd files
[DESCRIPTION]
Scans the specified rrd directory and lists any files which are 'faulty'.
Optionally this script can also repair the fault by setting the value to NaN.
An export RRD database in XML file is of the form:
<!-- Round Robin Database Dump --><rrd> <version> 0003 </version>
<step> 300 </step> <!-- Seconds -->
<lastupdate> 1211355308 </lastupdate> <!-- 2008-05-21 08:35:08 BST -->
This example sets the fields: history, summary, synopsis, options, and description. This information is also used to automatically create the application pod, man, and usage pages.
Similarly, the $VERSION variable in the calling namespace is detected and used to set the application version number.
Loaded modules
App::Framework::Base pre-loads the user namespace with the following modules:
'Cwd',
'File::Basename',
'File::Path',
'File::Temp',
'File::Spec',
'File::Find',
'File::Copy',
"File::DosGlob 'glob'",
'Pod::Usage',
'Date::Manip',
'Getopt::Long qw(:config no_ignore_case)',MySql support
The 'sql' field may be specified as either a HASH ref or an ARRAY ref (where each ARRAY entry is a HASH ref). The HASH ref must contain sufficient information to create a App::Framework::Base::Sql object.
Calling to the sql() method with no parameter will return the first created App::Framework::Base::Sql object. Calling the sql() method with a string will return the App::Framework::Base::Sql object created for the named database (i.e. sql objects are named by their database). The sql object can then be used as defined in App::Framework::Base::Sql
DIAGNOSTICS
Setting the debug flag to level 1 prints out (to STDOUT) some debug messages, setting it to level 2 prints out more verbose messages.
AUTHOR
Steve Price <linux@quartz-net.co.uk>
BUGS
None that I know of!
INTERFACE
FIELDS
The following fields should be defined either in the call to 'new()' or as part of the application configuration in the __DATA__ section:
* name = Program name (default is name of program)
* summary = Program summary text
* synopsis = Synopsis text (default is program name and usage)
* description = Program description text
* history = Release history information
* version = Program version (default is value of 'our $VERSION')
* options = Definition of program options (see below)
* nameargs = Definition of the program arguments and their intended usage (see below)
* sql = Definition of sql database connection & queries (see below)
* pre_run_fn = Function called before run() function (default is application-defined 'pre_run' subroutine if available)
* run_fn = Function called to execute program (default is application-defined 'run' subroutine if available)
* post_run_fn = Function called after run() function (default is application-defined 'post_run' subroutine if available)
* usage_fn = Function called to display usage information (default is application-defined 'usage' subroutine if available)During program execution, the following values can be accessed:
* arglist = Array of the program arguments, in the order they were specified
* arghash = Hash of the program arguments, named by the 'nameargs' field
* package = Name of the application package (usually main::)
* filename = Full filename path to the application (after following any links)
* progname = Name of the program (without path or extension)
* progpath = Pathname to program
* progext = Extension of program
* runobj = L<App::Framework::Base::Run> objectCONSTRUCTOR METHODS
App::Framework::Base->new([%args])-
Create a new App::Framework::Base.
The %args are specified as they would be in the set method, for example:
'mmap_handler' => $mmap_handlerThe full list of possible arguments are :
'fields' => Either ARRAY list of valid field names, or HASH of field names with default values
CLASS METHODS
App::Framework::Base->init_class([%args])-
Initialises the App::Framework::Base object class variables.
App::Framework::Base->allowed_class_instance()-
Class instance object is not allowed
OBJECT METHODS
App::Framework::Base->set_paths($filename)-
Get the full path to this application (follows links where required)
App::Framework::Base->catch_error($error)-
Function that gets called on errors. $error is as defined in App::Framework::Base::Object::ErrorHandle
App::Framework::Base->sql([$name | $sql_spec])-
Create or return App::Framework::Base::Sql object(s)
App::Framework::Base->sql_query($query_name [, @args])-
Run an SQL query
App::Base->sql_next($query_name)-
Returns hash ref to next row (as a result of query). Uses prepared STH name $query_name (as created by sth_create method), or default name (as created by query method)
App::Framework::Base->sql_query_all($query_name [, @args])-
Run an SQL query and return all the results in an array
App::Framework::Base->sql_from_data($name)-
Execute the (possible sequence of) command(s) stored in a named __DATA__ area
Run command methods
App::Framework::Base->run_results()-
Return output lines from running a command
NOTE: This interface is DIFFERENT to that employed by the underlying Run object. This form is meant to be easier to use for Applications.
App::Framework::Base->run_cmd($cmd, [$cmd_args])-
Execute a specified command, return either the exit status [0=success] (in scalar context) or the array of lines output by the command (in array context)
NOTE: This interface is DIFFERENT to that employed by the underlying Run object. This form is meant to be easier to use for Applications.
POD methods
App::Framework::Base->pod()-
Return full pod of application
App::Framework::Base->pod_head()-
Return pod heading of application
App::Framework::Base->pod_options()-
Return pod of options of application
App::Framework::Base->pod_description()-
Return pod of description of application
Options methods
App::Framework::Base->getopts()-
Convert the (already processed) options list into settings.
Returns result of calling GetOptions
App::Framework::Base->options([$options_aref])-
Set options based on the ARRAY ref specification.
Each entry in the ARRAY is an ARRAY ref containing:
[ <option spec>, <option summary>, <option description> ]Where the <option spec> is in the format used by Getopt::Long
NOTE: The <option spec> also determines the name of the field used to store the option value/flag. If alternatives are specified, then the first one is used. Alternatively, if any alternative is marked with quotes, then that is the one used.
Examples:
dir|d|directory - Field name is 'dir' dir|d|'directory' - Field name is 'directory'When no arguments are specifed, returns the hash of options/values
Called with an ARRAY ref either when an ARRAY ref is specified in the new() call or when the __DATA__ specification is being processed.
App::Framework::Base->option($option_name)-
Returns the value of the named option
Application execution methods
App::Framework::Base->go()-
Execute the application.
App::Framework::Base->pre_run()-
Set up before running the application.
App::Framework::Base->run()-
Execute the application.
App::Framework::Base->post_run()-
Tidy up after the application.
App::Framework::Base->exit()-
Exit the application.
App::Framework::Base->usage()-
Show usage
__DATA_ access methods
App::Framework::Base->data([$name])-
Returns the lines for the named __DATA__ section. If no name is specified returns the first section. If an ARRAY is required, returns the array; otherwise concatenates the lines with "\n".
Sections are named by adding the name after __DATA__:
__DATA__ template1creates a data section called 'template1'
Returns undef if no data found, or no section with specified name
Utility methods
App::Framework::Base->file_split($fname)-
Utility method
Parses the filename and returns the full path, basename, and extension.
Effectively does:
$fname = File::Spec->rel2abs($fname) ; ($path, $base, $ext) = fileparse($fname, '\.[^\.]+') ; return ($path, $base, $ext) ;
PRIVATE METHODS
App::Framework::Base->_exec_fn($function, @args)-
Execute the registered function (if one is registered). Passes @args to the function.
App::Framework::Base->_import()-
Load modules into caller package namespace.
App::Framework::Base->register_fn()-
Register a function provided as a subroutine in the caller package as a run method in this object.
Will only set the field value if it's not already set.
App::Framework::Base->register_scalar($external_name, $field_name)-
Read the value of a variable in the caller package and copy that value as a data field in this object.
Will only set the field value if it's not already set.
App::Framework::Base->register_var($type, $external_name, $field_name)-
Read the value of a variable in the caller package and copy that value as a data field in this object. $type specifies the variable type: 'SCALAR', 'ARRAY', 'HASH', 'CODE'
NOTE: This method overwrites the field value irrespective of whether it's already set.
App::Framework::Base->_show_data()-
Show the __DATA__ defined in the main script. Run when option --debug-show-data is used
App::Framework::Base->_show_data_array()-
Show data array (after processing the __DATA__ defined in the main script).
Run when option --debug-show-data-arry is used
App::Framework::Base->_process_data()-
If caller package namespace has __DATA__ defined then use that information to set up object parameters.
Recognised entries are:
[SUMMARY] Application summary text [SYNOPSIS] Application description text [DESCRIPTION] Application description text [OPTIONS] Definition of program options. Specified in the form: -<opt>[=s] Summary of option Description of optionAny subsequent text of the form __DATA__ will split the data into a new section...
App::Framework::Base->_handle_field($field_data_aref)-
Set the field based on the accumlated data
App::Framework::Base->_parse_options($data_aref)-
Parses option definition lines(s) of the form:
-<opt>[=s] Summary of option [default=<value>] Description of optionOptional [default] specification that sets the option to the default if not otherwised specified.
And returns an ARRAY in the format useable by the 'options' method.
App::Framework::Base->_expand_vars()-
Run through some of the application variables/fields and expand any instances of variables embedded within the values.
Example:
__DATA_ [SYNOPSIS] $name [options] <rrd file(s)>Here the 'synopsis' field contains the $name field variable. This needs to be expanded to the value of $name.
NOTE: Currently this will NOT cope with cross references (so, if in the above example $name also contains a variable then that variable may or may not be expanded before the synopsis field is processed)
App::Framework::Base->_process_nameargs($nameargs)-
The 'nameargs' options allows specification of args as names and also specification of certain properties of those arguments. Once the args have been named, they can be accessed via the arghash() method to provide a hash of name/value pairs (rather than using the arglist method)
Argument properties: * able to name each arg + return this hash as argshash() (?) * specify if arg is optional * specify if arg is a file/dir * specify if arg is expected to exist (autocheck existence; autocreate dir if output?) * specify if arg is an executable (autosearch PATH so don't need to specify full path?) * ?flag arg as an input or output (for filters, simple in/out scripts)? * ?specify arg expected to be a link?
Specification is the format: name:flags[, ]
i.e. a space and/or comma separated list of names with optional flags (indicated by a leading :)
Valid flags: ? arg is optional f file d dir x executable e exists i input o output - dummy flag (see below)
If names not required, can just specify flags e.g.:
:- :- :- :?Examples: in:if out:of - Arg named 'in' is an input file; arg named 'out' is an output file dir:d temp:?d cmd:?x - Arg named 'dir' is a directory; arg named 'temp' is optional and a directory; arg named 'cmd' is an optional executable
By default, any arg with the f,d,x,e flag is assumed to be an input and doesn't need the 'i' flag.
App::Framework::Base->_check_synopsis()-
Check to ensure synopsis is set. If not, set based on application name and any 'nameargs' settings
App::Framework::Base->_check_args()-
Check arguments based on 'nameargs' settings
App::Framework::Base::dumpvar(package)-
Dump out all of the symbols in package package
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 1315:
=over without closing =back