view release on metacpan or  search on metacpan

lib/App/Framework/GetStarted.pod  view on Meta::CPAN

    #
    sub app
    {
        my ($app, $opts_href, $args_href) = @_ ;
    
        print "Hello world\n" ;
    
        # do something more useful...
    }
    
    #=================================================================================
    # SETUP
    #=================================================================================
    __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 Object Creation

The first few lines of the script import the App::Framework and then create an App::Framework object (using App::Framework->new()) followed by
immediately using it (the ->go() part). Alternatively, you can do this in 2 stages:

    # Create application ...
    my $app = App::Framework->new() ;
    
    # ... and run it
    $app->go() ;

Or, if like me you are *really* lazy, then you can just call:

    # Create application and run it
    go() ;

It's usually a "good thing" to define a version number (and better still, keep it updated as the script changes!). If you do define a $VERSION
at the start of the script, App::Framework will use it when displaying script manual pages.    

=head2 Set-up

The command-line arguments and options are defined in a text section at the end of the program. In fact it's actually part of a 
__DATA__ definition. 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 since the framework sets most of them to useful defaults, then the most common 
settings are:

=over 4

=item * 

SUMMARY

=item * 

ARGS

=item * 

OPTIONS

=item * 

DESCRIPTION

=back

The following sections describe these items in more detail.



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

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

=head3 Options

Command line options are defined in general as:

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

The specification is in the format:

   <type> [ <desttype> ]

Allowed specifications are:

   (s|i|o|f) [ @|% ]  

where the I<type> may be s (string), i (integer), o (extended integer), f (float); the optional I<desttype> can be @ (array), % (hash).