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

NAME

App::Framework - A framework for creating applications

SYNOPSIS

  use App::Framework ;
  
  App::Framework->new()->go() ;
  
  sub app
  {
	my ($app, $opts_href, $args_href) = @_ ;
	
	# options
	my %opts = $app->options() ;
    
	# aplication code here....  	
  }

DESCRIPTION

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.

Capabilities

The application framework provides the following capabilities:

Options definition

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.

Arguments definition

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.

Named data sections

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.

Personalities

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.

Extensions

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

Daemon

Selecting this extension converts the command line script into a daemon (see App::Framework::Extension::Daemon)

Filter

Sets up the application for file filtering, the framework doing most of the work in the background (see App::Framework::Extension::Filter).

Find

Sets up the application for file finding, the framework doing most of the work in the background

Features

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

Config

Provides the application with configuration file support. Automatically uses the configuration file for all command line option settings (see App::Framework::Feature::Config).

Sql

Provides a simplified interface to MySQL. Provides easy set up for Sql operations delete, update, select etc (see App::Framework::Feature::Sql).

Mail

Provides mail send support (including file attachment) (see App::Framework::Feature::Mail).

Application directories

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.

Framework Components

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

Core and personalities

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)

Extensions

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

For example:

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

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

For example:

use App::Framework '+Args +Data +Mail +Config'

(See App::Framework::FeatureModules for your currently installed extensions)

Using This Module

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 ;

Creating Application Object

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

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!).

Setup

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.

Summary

This should be a single line, concise summary of what the script does. It's used in the terse man page created by pod2man.

Description

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

Options

Command line options are defined in this section in the format:

-<name>=<specification>    <Summary>    <optional default setting>

<Description>

For example:

-table|tbl|sql_table=s        Table [default=listings2]

For full details, see App::Framework::Feature::Options.

Arguments

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.

Example

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.

Data

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.

Directories

The framework sets up various directory paths automatically, as described below.

@INC path

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.

Feature modules

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.

Settings

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

Loaded modules

App::Framework pre-loads the user namespace with some common modules. See App::Framework::Settings for the complete list.

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

* 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

METHODS

new([%args])

Create a new object.

The %args passed down to the parent objects.

The parameters are specific to App::Framework:

specification - Application definition

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.

modpod()

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.

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:

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.