view release on metacpan or  search on metacpan

lib/App/Framework.pm  view on Meta::CPAN

    use App::Framework '+<feature>'

For example:

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

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


=head2 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 ;

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

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



=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<app()> 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<app_start> and B<app_end> are optional, but it is expected that B<app> 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. The most common sections are described below.

=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 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 L<App::Framework::Feature::Options>.

=head4 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 L<App::Framework::Feature::Args>.

=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