The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
App-Framework-1.07
River stage one • 1 direct dependent • 1 total dependent
++
/ App::Framework::Feature::Args

NAME

App::Framework::Feature::Args - Handle application command line arguments

SYNOPSIS

  # Args are loaded by default as if the script contained:
  use App::Framework '+Args' ;
  
  # Alternatives...
  
  # 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)' ;

DESCRIPTION

Args feature that provides command line arguments handling.

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.

Argument Definition

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

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

The parts of the specification are defined below.

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 app (see "Script Usage")

specification

The specification is in the format:

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

The optional direction 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:

<

An input file or directory

>

An output file or directory

>>

An output appended file

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

The type must be specified and may be one of:

f

A file

d

A directory

s

Any string

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:

'@'

One or more items

'*'

Zero or more items. 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.

summary

The summary is a simple line of text used to summarise the argument. 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 argument then that argument takes on the defualt value.

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

description

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

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' => <file handle of 'infile.txt'>
    'out_fh'  => <file handle of 'outfile.txt'>

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)' ;

Variable Expansion

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

        $<name>
        ${<name>}

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:

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

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

  • 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 argument HASH as the third parameter to the application subroutine app. Alternatively, the script can call the app object's alias to the args accessor, i.e. the args 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] ;
    }

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=<f*         All other args are input files
    
    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'  => <infile.txt file handle>
    'dir'      => 'indir'
    'out'      => 'outfile.txt'
    'out_fh'   => <outfile.txt file handle>
    'outdir'   => 'odir'
    'append'   => 'append.txt'
    'append_fh'=> <append.txt file handle>
    'array'    => [
        'file1.txt'
        'file2.txt'
        'file3.txt'
    ]
    'array_fh' => [
        <file1.txt file handle>
        <file2.txt file handle>
        <file3.txt file handle>
    ]

An example script that uses the multiple 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.

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_args - list of argument definitions

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

arg_names - list of argument names

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

argv - list of command line arguments

Reference to @ARGV array.

CONSTRUCTOR

new([%args])

Create a new Args.

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

CLASS METHODS

init_class([%args])

Initialises the Args object class variables.

OBJECT METHODS

args([$name])

When called with no arguments, returns the full arguments list (same as call to method "arg_list").

When a name (or list of names) is specified: if the named arguments hash is available, returns the argument values as a list; otherwise just returns the complete args list.

Args([$name])

Alias to "args"

arg_list()

Returns the full arguments list. This is the list of arguments, as specified at the command line by the user.

arg_hash()

Returns the full arguments hash.

append_args($args_aref)

Append the options listed in the ARRAY ref $args_aref to the current args list

update()

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

Each entry in the ARRAY is an ARRAY ref containing:

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

Returns the hash of args/values

check_args()

At start of application, check the arguments for valid files etc.

close_args()

If any arguements cause files/devices to be opened, this shuts them down

get_args()

Finish any args processing and return the arguments list

arg_entry($arg_name)

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

args_values_hash()

Returns the args values HASH reference.

args_values_set($values_href)

Sets the args values based on the values in the HASH reference $values_href.

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!