NAME

App::Framework::Feature::Options - Handle application options

SYNOPSIS

  # Options are loaded by default as if the script contained:
  use App::Framework '+Options' ;

DESCRIPTION

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.

Option Definition

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

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

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.

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'

specification

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

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:

   [ <flag> ] <type> [ <desttype> ]

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

s

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

i

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

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 (0x followed by '0' .. '9', 'a' .. 'f', case insensitive), or a binary string (0b followed by a series of '0' and '1').

f

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

The desttype can be @ or % 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 flag, if used, can be dev: 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.

summary

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

default

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

    [default=<value>]

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

description

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

Variable Expansion

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

        $<name>
        ${<name>}

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:

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

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

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

Script Usage

The application framework passes a reference to the options HASH as the second parameter to the application subroutine app. Alternatively, the script can call the app object's alias to the options accessor, i.e. the options 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} ;
    }

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

FIELDS

The following fields should be defined either in the call to 'new()', as part of a 'set()' call, or called by their accessor method (which is the same name as the field):

user_options - list of options

Created by the object. Once all of the options have been created, this field contains an ARRAY ref to the list of all of the specified option specifications (see method "append_options").

option_names - list of options names

Created by the object. Once all of the options have been created, this field contains an ARRAY ref to the list of all of the option field names.

CONSTRUCTOR

new([%args])

Create a new Options.

The %args are specified as they would be in the set method to set field values (see "Fields").

CLASS METHODS

init_class([%args])

Initialises the Options object class variables.

OBJECT METHODS

options()

Feature accessor method (aliases on the app object as options)

Returns the hash of options/values

Options([%args])

Alias to "options"

option($option_name)

Returns the value of the named option

update()

(Called by App::Framework::Core)

Take the list of options (created by calls to "append_options") and process the list into the final options list.

Returns the hash of options/values

append_options($options_aref [, $caller_pkg])

Append the options listed in the ARRAY ref $options_aref to the current options list

Each entry in the ARRAY ref is an ARRAY ref containing:

 [ <option spec>, <option summary>, <option description>, <option default> ]

Where the <option spec> is in the format <name><specification> (see "name" and "specification" above). The summary and description are as describe in "Option Definition". The optional default value is just the value (rather than the string '[default=...]').

Can optionally specify the caller package name (otherwise works out the caller and stores that package name)

clear_options()

Clears the current options list.

get_options()

Use Getopt::Long to process the command line options. Returns 1 on success; 0 otherwise

option_entry($option_name)

Returns the HASH ref of option if name is found; undef otherwise.

The HASH ref contains:

        'field' => option 'main' name 
        'spec' => specification string
        'summary' => summary text 
        'description' => description text
        'default' => default value (if specified)
        'pod_spec' => specification string suitable for pod output
        'type' => option type (e.g. s, f etc)
        'dest_type' => destination type (e.g. @, %)
        'developer' => developer only option (flag set if option is to be used for developer use only)
        'entry' => reference to the ARRAY that defined the option (as per L</append_options>) 

modify_default($option_name, $default)

Changes the default setting of the named option. Returns the option value if sucessful; undef otherwise

defaults_from_obj($obj [, $names_aref])

Scans through the options looking for any matching variable stored in $obj (accessed via $obj->$variable). Where there is an variable, modifies the option default to be equal to the current variable setting.

Optionally, you can specify an ARRAY ref of option names so that only those named are examined

This is a utility routine that can be called by extensions (or features) that want to set the option defaults equal to their object variable settings.

obj_vars($obj [, $names_aref])

Scans through the options looking for any matching variable stored in $obj (accessed via $obj->$variable). Where there is an variable, modifies the object variable value to be equal to the current option setting.

Optionally, you can specify an ARRAY ref of option names so that only those named are examined

This is effectively the reversal of defaults_from_obj

option_values_hash()

Returns the options values and defaults HASH references in an array, values HASH ref as the first element.

option_values_set($values_href, $defaults_href)

Sets the options values and defaults based on the HASH references passed in.

DIAGNOSTICS

Setting the debug flag to level 1 prints out (to STDOUT) some debug messages, setting it to level 2 prints out more verbose messages.

AUTHOR

Steve Price <sdprice at cpan.org>

BUGS

None that I know of!

cpanm App::Framework

perl -MCPAN -e shell
install App::Framework