App::Framework - A framework for creating applications
use App::Framework ; App::Framework->new()->go() ; sub app { my ($app, $opts_href, $args_href) = @_ ; # options my %opts = $app->options() ; # aplication code here.... }
App::Framework is a framework for quickly developing application scripts, where the majority of the mundane script setup, documentation etc. jobs are performed by the framework (usually under direction from simple text definitions stored in the script).
This leaves the developer to concentrate on the main job of implementing the application.
To jump straight in to developing applications, please see App::Framework::GetStarted.
The application framework provides the following capabilities:
Text definition of options in application, providing command line options, help pages, options checking.
Also supports variables in options definition, the variables being replaced by other option values, application field values, or environment variables.
Text definition of arguments in application, providing command line arguments, help pages, arguments checking, file/directory creation, file/directory existence, file opening
Also supports variables in arguments definition, the variables being replaced by other argument values, option values, application field values, or environment variables.
Multiple named __DATA__ sections, the data being readily accessible by name from the application.
Variables can be used in the data definitions, the variables being replaced by command line option values, application field values, or environment variables.
Single line selection of the base application type (i.e. command line script, Tk application, POE application etc).
Modular application framework allows for separate installation of new personalities in the installed Perl library space, or locally under an application-specific directory.
Single line selection of one or more application extension plugins which modify the selected personality behaviour.
Modular application framework allows for separate installation of new extensions in the installed Perl library space, or locally under an application-specific directory.
Example extensions (may not be installed on your system):
Selecting this extension converts the command line script into a daemon (see App::Framework::Extension::Daemon)
Sets up the application for file filtering, the framework doing most of the work in the background (see App::Framework::Extension::Filter).
Sets up the application for file finding, the framework doing most of the work in the background
Single line selection of one or more application feature plugins which provide application targetted functionality (for example Sql support, mail handling etc).
Modular application framework allows for separate installation of new features in the installed Perl library space, or locally under an application-specific directory.
Example features (may not be installed on your system):
Provides the application with configuration file support. Automatically uses the configuration file for all command line option settings (see App::Framework::Feature::Config).
Provides a simplified interface to MySQL. Provides easy set up for Sql operations delete, update, select etc (see App::Framework::Feature::Sql).
Provides mail send support (including file attachment) (see App::Framework::Feature::Mail).
The framework automatically adds the location of the script (following any links) to the Perl search path. This means that perl modules can be created in subdirectories under the application's script making the application self-contained.
The directories used for loading personalities/extensions/features also include the script install directory, meaning that new personalities/extensions/features can also be provided with a script.
The diagram below shows the relationship between the application framework object (Framework) and the other components:
+--------------+ | Core | +--------------+ ^ | | +--------------+ | Personality | Script, POE etc +--------------+ ^ | | ................ : Extension(s) :.. Filter, Daemon etc ................ : :............... ^ | | +--------------+ +--------------+ | Framework |--------------->| Features |-+ Args, Options, Pod etc +--------------+ +--------------+ | +--------------+
An application is built by creating an App::Framework object that is derived from the application core, and also contains 0 or more feature objects. The application core (App::Framework::Core) is not directly deriveable, you actually derive from a "personality" module that provides the base essentials for this selected type of application (for example 'Script' for a command line script).
The personality is selected in the App::Framework 'use' command as:
use App::Framework ':<personality>'
For example:
use App::Framework ':Script'
Personalities add specific methods, options, arguments to the core application.
All of the methods defined in the selected personality add to the core methods and are available to the application object ($app).
(See App::Framework::CoreModules for your currently installed personalities)
When creating the App::Framework object, you can optionally select to derive it from one (or more) 'extensions'. An extension can modify how the application routine is called, add extra command line options, and so on. For example, the 'filter' extension sets up the application for file filtering (calling the aplication subroutine with each line of an input file so that the file contents may be filtered).
Extensions are added in the App::Framework 'use' command as:
use App::Framework '::<extension>'
use App::Framework '::Daemon ::Filter'
(See App::Framework::ExtensionModules for your currently installed extensions)
Like the personality, all of the methods defined in the selected extensions add to the core methods and are available to the application object ($app).
Features provide additional application capabilities, optional modifying what the application framework does depedning on the feature. A feature may also simply be an application-specific collection of useful methods.
Unlike core/personality/extension, features are not part of the application object - they are kept in a "feature list" that the application can access to use a feature's methods. For convenience, all features provide an accessor method that is aliased as an application method with the same name as the feature. This access method provides the most commonly used functionality for that feature. For example, the 'data' feature provides access to named data sections as:
my $data = $app->data('named_section') ;
Alternatively, the data feature object can be retrieved and used:
my $data_feature = $app->feature('data') ; my $data = $data_feature->data('named_section') ;
Features are added in the App::Framework 'use' command as:
use App::Framework '+<feature>'
use App::Framework '+Args +Data +Mail +Config'
(See App::Framework::FeatureModules for your currently installed extensions)
To create an application you need to declare: the personality to use, any optional extensions, and which features you wish to use.
You do all this in the 'use' pragma for the module, for example:
use App::Framework ':Script ::Filter +Mail +Config' ;
By default, the 'Script' personality is assumed (and so need not be declared), and the framework ensures that all of the features it requires are always loaded (so you don't need to declare +Args, +Options, +Data, +Pod, +Run). So, the minimum is:
use App::Framework ;
There are two ways of creating an application object and running it. The normal way is:
# Create application and run it App::Framework->new()->go() ;
As an alternative, the framework creates a subroutine in the calling namespace called go() which does the same thing:
# Create application and run it go() ;
You can use whatever takes your fancy. Either way, the application object will end up calling the user-defined application subroutines
Once the application object has been created it can then be run by calling the 'go()' method. go() calls the application's registered functions in turn:
app_start()
Called at the start of the application. You can use this for any additional set up (usually of more use to extension developers)
app()
Called once all of the arguments and options have been processed
app_end()
Called when app() terminates or returns (usually of more use to extension developers)
The framework looks for these 3 functions to be defined in the script file. The functions app_start and app_end are optional, but it is expected that app will be defined (otherwise nothing happens!).
The application settings are entered into the __DATA__ section at the end of the file. All program settings are grouped under sections which are introduced by '[section]' style headings. There are many different settings that can be set using this mechanism, but the framework sets most of them to useful defaults. The most common sections are described below.
This should be a single line, concise summary of what the script does. It's used in the terse man page created by pod2man.
As you'd expect, this should be a full description, user-guide etc. on what the script does and how to do it. Notice that this example has used one (of many) of the variables available: $name (which expands to the script name, without any path or extension).
Command line options are defined in this section in the format:
-<name>=<specification> <Summary> <optional default setting> <Description>
-table|tbl|sql_table=s Table [default=listings2]
For full details, see App::Framework::Feature::Options.
The command line arguments specification are similar to the options specification. In this case we use '*' to signify the start of a new argument definition.
Arguments are defined in the format:
* <name>=<specification> <Summary> <optional default setting> <Description>
For full details, see App::Framework::Feature::Args.
An example script setup is:
__DATA__ [SUMMARY] An example of using the application framework [ARGS] * infile=f Input file Should be set to the input file * indir=d Input dir Should be set to the input dir [OPTIONS] -table=s Table [default=listings2] Sql table name -database=s Database [default=tvguide] Sql database name [DESCRIPTION] B<$name> is an example script.
After the settings (described above), one or more extra data areas can be created by starting that area with a new __DATA__ line.
If the new data area is defined simply with '__DATA__' then the area is automatically named as 'data1', 'data2' etc. Alternatively, the data section can be arbitrarily named by appending a text name after __DATA__. For example, the definition:
__DATA__ [DESCRIPTION] An example __DATA__ test.txt some text __DATA__ a_bit_of_sql.sql DROP TABLE IF EXISTS `listings2`;
Creates 2 extra data areas 'test.txt' and 'a_bit_of_sql.sql'. These data area contents can be accessed using:
my $contents1 = $app->data('text.txt') ; # or $contents1 = $app->data('data1') ; my $contents2 = $app->data('a_bit_of_sql.sql') ; # or $contents2 = $app->data('data2') ;
See App::Framework::Feature::Data for further details.
The framework sets up various directory paths automatically, as described below.
App::Framework automatically pushes some extra directories at the start of the Perl include library path. This allows you to 'use' application-specific modules without having to install them globally on a system. The path of the executing Perl application is found by following any links until an actually Perl file is found. The @INC array has the following added:
* $progpath * $progpath/lib
i.e. The directory that the script resides in, and a sub-directory 'lib' will be searched for application-specific modules.
Note that this is the path also used when the framework loads in the core personality, and any optional extensions.
When the application framework loads in the various required and user-specified features, then it attempts to load the following feature modules until one is sucessfully loaded:
* App::Framework::Feature::${personality}::${feature} * App::Framework::Feature::${feature}
Where ${feature} is the name of the feature being loaded (e.g. Config), and ${personality} is the specified core personality (e.g. Script). Note that it does this using the "@INC path", so an application can bundle it's own feature's in under it's own install directory.
App::Framework loads some settings from App::Framework::Settings. This may be modified on a site basis as required (in a similar fashion to CPAN Config.pm).
App::Framework pre-loads the user namespace with some common modules. See App::Framework::Settings for the complete list.
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') * 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
Create a new object.
The %args passed down to the parent objects.
The parameters are specific to App::Framework:
Instead of specifying the application in the 'use App::Framework' line, you can just specify them in this argument when creating the object. If this is specified it will overwrite any specification in the 'use' pragma.
Create/update module pod files. Creates/updates the pod for the module lists: App::Framework::FeatureModules,App::Framework::ExtensionModules,App::Framework::CoreModules
Used during installation.
Steve Price, <sdprice at cpan.org>
<sdprice at cpan.org>
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.
bug-app-framework at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc App::Framework
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=App-Framework
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/App-Framework
CPAN Ratings
http://cpanratings.perl.org/d/App-Framework
Search CPAN
http://search.cpan.org/dist/App-Framework/
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.
To install App::Framework, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::Framework
CPAN shell
perl -MCPAN -e shell install App::Framework
For more information on module installation, please visit the detailed CPAN module installation guide.