File Coverage

blib/lib/App/Framework/Lite.pm

Criterion	Covered	Total	%
statement	1161	1562	74.3
branch	394	718	54.8
condition	89	161	55.2
subroutine	100	117	85.4
pod	50	50	100.0
total	1794	2608	68.7

package App::Framework::Lite ;

=head1 NAME

App::Framework::Lite - A lightweight framework for creating applications

=head1 SYNOPSIS

  use App::Framework::Lite ;

  go() ;

  sub app
  {
	my ($app, $opts_href, $args_href) = @_ ;

	# options
	my %opts = $app->options() ;

	# aplication code here....
  }


=head1 DESCRIPTION

App::Framework::Lite is a framework for quickly developing application scripts, where the majority of the mundane script setup,
documentation jobs are performed by the framework (under direction from simple text definitions stored in the script). This leaves
the developer to concentrate on the main job of implementing the application.

The module also provides the facility of embedding itself into a copy of the original script, creating a self-contained stand-alone
script (for further details see L).

Note that this module provides a subset of the the facilities provided by L, In particular, it provides the L,
L, and L features.

To jump straight in to developing applications, please see L.

=head2 Capabilities

The application framework provides the following capabilities:

=over 2

=item 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.

=item 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.

=item 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.


=item 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.

=back


=head2 Using This Module

The minimum you need is:

    use App::Framework::Lite ;

Optionally, you can specify arguments to the underlying features by appending a string to the 'use' pragma. For exanmple:

    use App::Framework::Lite '+Args(open=none)' ;


=head3 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::Lite->new()->go() ;

As an alternative, the framework creates a subroutine in the calling namespace called B 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



=head3 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:

=over 2

=item * 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)

=item * app()

Called once all of the arguments and options have been processed

=item * app_end()

Called when B terminates or returns (usually of more use to extension developers)

=back

The framework looks for these 3 functions to be defined in the script file. The functions B and B are optional, but it is expected that B will be defined
(otherwise nothing happens!).

=head3 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.

For more details see L and L.

=head4 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.

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


=head4 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.


=head2 Args

Args feature that provides command line arguments handling.

Command line arguments are defined once in a text format and this text format generates both the command line arguments data, but also the man pages,
help text etc. Defining the expected arguments and their types allows the module to check for the existence of the program arguments and their correctness.

=head3 Argument Definition

Arguments are specified in the application __DATA__ section in the format:

    * =



The parts of the specification are defined below.

=head4 name

The name defines the name of the key to use to access the argument value in the arguments hash. The application framework
passes a reference to the argument hash as the third parameter to the application subroutine B (see L)

=head4 specification

The specification is in the format:

   [  ] [  ]  [  ]

The optional I is only valid for file or directory types. For a file or directory types, if no direction is specified then
it is assumed to be input. Direction can be one of:

=over 4

=item <

An input file or directory

=item >

An output file or directory

=item >>

An output appended file

=back

An optional 'b' after the direction specifies that the file is binary mode (only used when the type is file).

The B must be specified and may be one of:

=over 4

=item f

A file

=item d

A directory

=item s

Any string

=back

Additionally, an optional multiple can be specified. If used, this can only be specified on the last argument. When it is used, this tells the
application framework to use the last argument as an ARRAY, pushing all subsequent specified arguments onto this. Accessing the argument
in the script returns the ARRAY ref containing all of the command line argument values.

Multiple can be:

=over 4

=item '@'

One or more items

=item '*'

Zero or more items. There is also a special case (the real reason for *) where the argument specification is of the form '
specify any arguments on the command line for this argument then the framework opens STDIN and provides it as a file handle.

=back


=head4 summary

The summary is a simple line of text used to summarise the argument. It is used in the man pages in 'usage' mode.

=head4 default

Defaults values are optional. If they are defined, they are in the format:

    [default=]

When a default is defined, if the user does not specify a value for an argument then that argument takes on the defualt value.

Also, all subsequent arguments must also be defined as optional.

=head4 description

The summary is multiple lines of text used to fully describe the option. It is used in the man pages in 'man' mode.

=head3 Feature Options

The Args feature allows control over how it opens files. By default, any input or output file definitions also create equivalent file handles
(the files being opened for read/write automatically). These file handles are made available only in the arguments HASH. The key name for the handle
being the name of the argument with the suffix '_fh'.

For example, the following definition:

    [ARGS]

    * file=f		Input file

    A simple input directory name (directory must exist)

    * out=>f		Output file (file will be created)

    An output filename

And the command line arguments:

    infile.txt outfile.txt

Results in the arguments HASH:

    'file'    => 'infile.txt'
    'out'     => 'outfile.txt'
    'file_fh' =>
    'out_fh'  =>

If this behaviour is not required, then you can get the framework to open just input files, output files, or none by using the 'open' option.

Specify this in the App::Framework 'use' line as an argument to the Args feature:

    # Open no file handles
    use App::Framework '+Args(open=none)' ;

    # Open only input file handles
    use App::Framework '+Args(open=in)' ;

    # Open only output file handles
    use App::Framework '+Args(open=out)' ;

    # Open all file handles (the default)
    use App::Framework '+Args(open=all)' ;

=head3 Variable Expansion

Argument values can contain variables, defined using the standard Perl format:

	$
	${}

When the argument is used, the variable is expanded and replaced with a suitable value. The value will be looked up from a variety of possible sources:
object fields (where the variable name matches the field name) or environment variables.

The variable name is looked up in the following order, the first value found with a matching name is used:

=over 4

=item *

Argument names - the values of any other arguments may be used as variables in arguments

=item *

Option names - the values of any command line options may be used as variables in arguments

=item *

Application fields - any fields of the $app object may be used as variables

=item *

Environment variables - if no application fields match the variable name, then the environment variables are used

=back



=head2 Script Usage

The application framework passes a reference to the argument HASH as the third parameter to the application subroutine B. Alternatively,
the script can call the app object's alias to the args accessor, i.e. the B method which returns the arguments value list. Yet another
alternative is to call the args accessor method directly. These alternatives are shown below:


    sub app
    {
        my ($app, $opts_href, $args_href) = @_ ;

        # use parameter
        my $infile = $args_href->{infile}

        # access alias
        my @args = $app->args() ;
        $infile = $args[0] ;

        # access alias
        @args = $app->Args() ;
        $infile = $args[0] ;

        ($infile) = $app->args('infile') ;

        # feature object
        @args = $app->feature('Args')->args() ;
        $infile = $args[0] ;
    }



=head3 Examples

With the following script definition:

    [ARGS]

    * file=f		Input file

    A simple input file name (file must exist)

    * dir=d			Input directory

    A simple input directory name (directory must exist)

    * out=>f		Output file (file will be created)

    An output filename

    * outdir=>d		Output directory

    An output directory name (path will be created)

    * append=>>f	Output file append

    An output filename (an existing file will be appended; otherwise file will be created)

    * array=

    Any other command line arguments will be pushced on to this array.

The following command line arguments:

    infile.txt indir outfile.txt odir append.txt file1.txt file2.txt file3.txt

Give the arguments HASH values:

    'file'     => 'infile.txt'
    'file_fh'  =>
    'dir'      => 'indir'
    'out'      => 'outfile.txt'
    'out_fh'   =>
    'outdir'   => 'odir'
    'append'   => 'append.txt'
    'append_fh'=>
    'array'    => [
    	'file1.txt'
    	'file2.txt'
    	'file3.txt'
    ]
    'array_fh' => [



    ]


An example script that uses the I arguments, along with the default 'open' behaviour is:

    sub app
    {
        my ($app, $opts_href, $args_href) = @_ ;

        foreach my $fh (@{$args_href->{array_fh}})
        {
            while (my $data = <$fh>)
            {
                # do something ...
            }
        }
    }

    __DATA__
    [ARGS]
    * array=f@    Input file


This script can then be called with one or more filenames and each file will be processed. Or it can be called with no
filenames and STDIN will then be used.


=head2 Options

Options feature that provides command line options handling.

Options are defined once in a text format and this text format generates
both the command line options data, but also the man pages, help text etc.

=head3 Option Definition

Options are specified in the application __DATA__ section in the format:

    -



These user-specified options are added to the application framework options (defined dependent on whatever core/features/extensions are installed).
Also, the user may over ride default settings and descriptions on any application framework options by re-defining them in the script.

The parts of the specification are defined below.

=head4 name

The name defines the option name to be used at the command line, along with any command line option aliases (e.g. -log or -l, -logfile etc). Using the
option in the script is via a HASH where the key is the 'main' option name.

Where an option has one or more aliases, this list of names is separated by '|'. By default, the first name defined is the 'main' option name used
as the option HASH key. This may be overridden by quoting the name that is required to be the main name.

For example, the following name definitions:

    -log|logfile|l
    -l|'log'|logfile
    -log

Are all access by the key 'log'

=head4 specification

(Note: This is a subset of the specification supported by L).

The specification is optional. If not defined, then the option is a boolean value - is the user specifies the option on the command line
then the option value is set to 1; otherwise the option value is set to 0.

When the specification is defined, it is in the format:

   [  ]  [  ]

The option requires an argument of the given type. Supported types
are:

=over 4

=item s

String. An arbitrary sequence of characters. It is valid for the
argument to start with C<-> or C<-->.

=item i

Integer. An optional leading plus or minus sign, followed by a
sequence of digits.

=item o

Extended integer, Perl style. This can be either an optional leading
plus or minus sign, followed by a sequence of digits, or an octal
string (a zero, optionally followed by '0', '1', .. '7'), or a
hexadecimal string (C<0x> followed by '0' .. '9', 'a' .. 'f', case
insensitive), or a binary string (C<0b> followed by a series of '0'
and '1').

=item f

Real number. For example C<3.14>, C<-6.23E24> and so on.

=back

The I can be C<@> or C<%> to specify that the option is
list or a hash valued. This is only needed when the destination for
the option value is not otherwise specified. It should be omitted when
not needed.

The I, if used, can be C to specify that the option is meant for application developer
use only. In this case, the option will not be shown in the normal help and man pages, but will
only be shown when the -man-dev option is used.

=head4 summary

The summary is a simple line of text used to summarise the option. It is used in the man pages in 'usage' mode.

=head3 default

Defaults values are optional. If they are defined, they are in the format:

    [default=]

When a default is defined, if the user does not specify a value for an option then that option takes on the defualt value.

=head4 description

The summary is multiple lines of text used to fully describe the option. It is used in the man pages in 'man' mode.

=head3 Variable Expansion

Option values and default values can contain variables, defined using the standard Perl format:

	$
	${}

When the option is used, the variable is expanded and replaced with a suitable value. The value will be looked up from a variety of possible sources:
object fields (where the variable name matches the field name) or environment variables.

The variable name is looked up in the following order, the first value found with a matching name is used:

=over 4

=item *

Option names - the values of any other options may be used as variables in options

=item *

Application fields - any fields of the $app object may be used as variables

=item *

Environment variables - if no application fields match the variable name, then the environment variables are used

=back

=head3 Script Usage

The application framework passes a reference to the options HASH as the second parameter to the application subroutine B. Alternatively,
the script can call the app object's alias to the options accessor, i.e. the B method which returns the options hash. Yet another
alternative is to call the options accessor method directly. These alternatives are shown below:


    sub app
    {
        my ($app, $opts_href, $args_href) = @_ ;

        # use parameter
        my $log = $opts_href->{log}

        # access alias
        my %options = $app->options() ;
        $log = $options{log} ;

        # access alias
        %options = $app->Options() ;
        $log = $options{log} ;

        # feature object
        %options = $app->feature('Options')->options() ;
        $log = $options{log} ;
    }



=head3 Examples

With the following script definition:

    [OPTIONS]

    -n|'name'=s        Test name [default=a name]

    String option, accessed as $opts_href->{name}.

    -nomacro    Do not create test macro calls

    Boolean option, accessed as $opts_href->{nomacro}

    -log=s        Override default [default=another default]

    Over rides the default log option (specified by the framework)

    -int=i        An integer

    Example of integer option

    -float=f    An float

    Example of float option

    -array=s@    An array

    Example of an array option

    -hash=s%    A hash

    Example of a hash option

The following command line options are valid:

    -int 1234 -float 1.23 -array a -array b -array c -hash key1=val1 -hash key2=val2 -nomacro

Giving the options HASH values:

    'name' => 'a name'
    'nomacro' => 1
    'log' => 'another default'
    'int' => 1234
    'float' => 1.23
    'array' => [ 'a', 'b', 'c' ]
    'hash' => {
    	'key1' => 'val1',
    	'key2' => 'val2',
    }


=head2 Data

After the settings (described above), one or more extra data areas can be created by starting that area with a new __DATA__ line.

The __DATA__ section at the end of the script is used by the application framework to allow the script developer to define
various settings for his/her script. This setup is split into "headed" sections of the form:

  [  ]



In general, the  is the name of a field value in the application, and  is some text that the field will be set to. Sections
of this type are:

=over 4

=item B<[SUMMARY]> - Application summary text

A single line summary of the application. Used for man pages and usage summary.

(Stored in the application's I field).

=item B<[DESCRIPTION]> - Application description text

Multiple line description of the application. Used for man pages.

(Stored in the application's I field).

=item B<[SYNOPSIS]> - Application synopsis [I]

Multiple line synopsis of the application usage. By default the application framework creates this if it is not specified.

(Stored in the application's I field).

=item B<[NAME]> - Application name [I]

Name of the application usage. By default the application framework creates this if it is not specified.

(Stored in the application's I field).

=back

__DATA__ sections that have special meaning are: