/ 
App-Framework-0.01
River stage one • 1 direct dependent • 1 total dependent
/ App::Framework

NAME

App::Framework - A framework for creating applications

SYNOPSIS

  use App::Framework ;
  use App::Framework qw/Script/ ;

  App::Framework->new()->go() ;
  
  sub run
  {
	my ($app) = @_ ;
	
	# options
	my %opts = $app->options() ;

	# aplication code here....  	
  }

DESCRIPTION

This class actually uses one of the framework sub-modules to provide it's "personality". By default that will be Script, but others will be available later (or if anyone adds their own).

The framework is intended to do most of the common tasks required to set up an application, being driven predominantly by the applications "documentation" (see section "DATA").

COMMAND LINE OPTIONS

The basic framework provides (and handles) the following pre-defined 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 exit

Application-specific options are specified in the __DATA__ section under the heading [OPTIONS]. An example of which is:

[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

Here two options -d (or -dir) and -repair are defined. In this case -d is used to specify a directory name and a default has been declared so that, if the user does not specify the option, the default value will be used. In the application itself, all options are accessed via the options HASH (accessed using $app->options())

APPLICATION FUNCTIONS

Once 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 far

The 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.

DATA

Similarly, the __DATA__ area of the calling namespace is 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:

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.

In addition to specifying teh application settings, additional named __DATA__ sections can be created. These named sections are then accessed via $app->data($name) to recover the text string (or an array of the text lines). Named data sections are specified as:

__DATA__ name

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

Loaded modules

App::Framework 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',
'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

CONSTRUCTOR

new([%args])

Create a new object.

The %args are specified as they would be in the set method, for example:

'adapter_num' => 0

The full list of possible arguments are as described in the "FIELDS" section

AUTHOR

Steve Price, <sdprice at cpan.org>

BUGS

Please report any bugs or feature requests to bug-app-framework at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-Framework. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc App::Framework

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2009 Steve Price, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.