view release on metacpan or  search on metacpan

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

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

Note, if a specification is not defined then the option is treated as a boolean flag that is by default unset, but set if the option is 
used at the command line, for example:

    -ok        Flag for validity

Defaults, where specified, are in the format:

    [default=<value>]

The name (or names) of the option are specified as a list separated by '|'. One name is used as the option variable name, and the others
are used as aliases that the script user can specify at the command line. Normally, the first name specified in a list is used as the variable
name, but this may be over-ridden by surrounding the required name in quotes. For example, we could have said:

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

or

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

so that the command line could use -tbl, -table, or -sql_table and the option value be retrieved using 'table' as the option name.

The option spec (which in the example is set to 's') is a subset of the set supported by L<Getpt::Long>. For full details of the supported
set please see L<App::Framework::Feature::Options>

If a default is specified, that the option will be given the default value if it is not specified at the command line. Also, the default
can contains variables which will be expanded once the script starts. These variables can include the values of other options. For example, 
we could have specified the 'database' option as:

    -database=s        Database [default=${table}_db]

Then the database option would be set to 'listings2_db' if no options were specified by the user at the command line.

By default, the application is called with the options HASH as the 2nd parameter. Using the option values is discussed 
in L<Application body>


=head3 Arguments

The command line arguments specification is (not) suprisingly similar to the options specification! In this case we use '*' to signify the
start of a new argument definition (rather than the '-' for options). Note, however, that you can actually use '-' if you want to (for example,
you might want to move something that starts as an option but then you decide it would be better as an argument).

The main differences between options and arguments are the specification and the defaults.

Arguments are defined in general as:

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


For arguments, the specification is in the format:

   [ <direction> ] [ <binary> ] <type> [ <multiple> ]

allowed specifications are:

   [ (<|>|>>) ] [b] (f|d|s) [@|*]  

The optional I<direction> can be one of: <, >, or >> signifying input, output, or appended output.

The I<type> can be: s, f, or d for string, file, or directory. 

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

Additionally, an optional multiple can be specified as: @ or *. 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 (don't worry, an example should make this clear).

The difference between @ and * is that @ specifies that there must be at least one argument specified, whereas * expects 0 or more arguments.

There is also a special case (the real reason for *) where the argument specification is of the form '<f*' (input file multiple). Here, if the script user does not
specify any arguments on the command line for this argument then the framework opens STDIN and provides it as a file handle.  

Defaults, where specified, are in the format:

    [default=<value>]

If a default is specifed, this makes this argument optional. It also makes all subsequent arguments optional. Optional arguments are not checked for by the application (and if
they are not specified will take the default value).

The main reason for specifying arguments is to get the framework to do all the work of checking for you. All (non optional) values are checked to ensure that the user specified
something on the command line. This is all the checking string arguments are given. However, input file and directory arguments are also checked for presence, causing an error
message if they are not present. 

For the lazy, you'll appreciate the fact that the framework does even more for you. By default, any arguments specified as input files will be opened for reading; output files will be opened for writing; output directories will be created. In additio...
specified with >> will be appended to (rather than truncated). All of these opened files are passed in as file handles in the arguments HASH named with the argument name suffixed
by '_fh' (you can turn this off by declaring the Args feature with 'open' settings - see L<App::Framework::Feature::Args>).

For example, with the following specifications

    * infile=<f
    * outfile=>f 

the command line arguments (and opened files) can be accessed with the argument HASH keys:

    infile        = infile filename
    infile_fh    = infile file handle opened for reading
    outfile        = outfile filename
    outfile_fh    = outfile file handle opened for writing

An example of using the * multiple is as follows: