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::Framework::Modules::Script).

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 <sdprice at cpan.org>

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> object

CONSTRUCTOR 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_handler

The 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__ template1

creates 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 option

Any 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 option

Optional [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

cpanm App::Framework

perl -MCPAN -e shell
install App::Framework