NAME

App::Framework::Core - Base application object

SYNOPSIS

use App::Framework::Core ;

our @ISA = qw(App::Framework::Core) ; 

DESCRIPTION

The details of this module are only of interest to personality/extension/feature developers.

Base class for applications. Expected to be derived from by an implementable class (like App::Framework::Core::Script).

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')

* feature_config = HASH ref containing setup information for any installed features. Each feature must have it's own
                   HASH of values, keyed by the feature name

* app_start_fn = Function called before app() function (default is application-defined 'app_start' subroutine if available)
* app_fn = Function called to execute program (default is application-defined 'app' subroutine if available)
* app_end_fn = Function called after app() function (default is application-defined 'app_end' 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:

* 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

CONSTRUCTOR METHODS

new([%args])

Create a new App::Framework::Core.

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

init_class([%args])

Initialises the App::Framework::Core object class variables.

allowed_class_instance()

Class instance object is not allowed

dynamic_load($module [, $pkg])

Attempt to load the module into the specified package $pkg (or load it into a temporary space).

Then checks that the load was ok by checking the module's version number.

Returns 1 on success; 0 on failure.

dynamic_isa($module)

Load the module into the caller's namespace then set it's @ISA ready for that module to call it's parent's new() method

inherit($caller_class, [%args])

Initialises the object class variables.

find_lib($module)

Looks for the named module in the @INC path. If found, checks the package name inside the file to ensure that it really matches the capitalisation.

(Mainly for Microsoft Windows use!)

lib_glob($module_path)

Looks for any perl modules contained under the module path. Looks at all possible locations in the @INC path, returning the first found.

Returns a HASH contains the module name as key and the full filename path as the value.

isa_tree(package)

Starting at package, return a HASH ref in the form of a tree of it's parents. They keys are the parent module names, and the values are HASH refs of their parents and so on. Value is undef when last parent is reached.

OBJECT METHODS

set_paths($filename)

Get the full path to this application (follows links where required)

catch_error($error)

Function that gets called on errors. $error is as defined in App::Framework::Base::Object::ErrorHandle

install_features($feature_list [, $feature_args])

Add the listed features to the application. List is an ARRAY ref list of feature names.

Note: names need correct capitalisation (e.g. Sql not sql) - or just use first char capitalised(?)

Method/feature name will be all lowercase

Optionally, can specify $feature_args HASH ref. Each feature name in $feature_list should be a key in the HASH, the value of which is an arguments string (which is a list of feature arguments separated by space and/or commas)

feature_installed($name)

Return named feature object if the feature is installed; otherwise returns undef.

feature($name [, %args])

Return named feature object. Alternative interface to just calling the feature's 'get/set' method.

For example, 'sql' feature can be accessed either as:

my $sql = $app->feature("sql") ;

or:

	my $sql = $app->sql() ;
 

feature_register($feature, $feature_obj, @function_list)

API for feature objects. Used so that they can register their methods to be called at the start and end of the registered functions.

Function list is a list of strings where the string is in the format:

<method name>_entry
<method_name>_exit

To register a call at the start of the method and/or at the end of the method.

This is usually called when the feature is being created (which is usually because this Core object is installing the feature). To ensure the core's lists are up to date, this function sets the feature object and priority.

Application execution methods

go()

Execute the application.

Calls the following methods in turn:

* app_start * application * app_end * exit

getopts()

Convert the (already processed) options list into settings.

Returns result of calling GetOptions

app_start()

Set up before running the application.

Calls the following methods in turn:

* getopts * [internal _expand_vars method] * options * (Application registered 'app_start' function)

application()

Execute the application.

Calls the following methods in turn:

* (Application registered 'app' function)

app_end()

Tidy up after the application.

Calls the following methods in turn:

* (Application registered 'app_end' function)

exit()

Exit the application.

usage()

Show usage

Utility methods

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) ;

debug_prt($items_aref [, $min_debug])

Print out the items in the $items_aref ARRAY ref iff the application's debug level is >0. If $min_debug is specified, will only print out items if the application's debug level is >= $min_debug.

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!