/ 
OptArgs-0.0.1_20
River stage one • 2 direct dependents • 2 total dependents
/ OptArgs

NAME

OptArgs - integrated argument and option processing

VERSION

0.0.1 Development release.

SYNOPSIS

#!/usr/bin/env perl
use OptArgs;

opt quiet => (
    isa     => 'Bool',
    alias   => 'q',
    comment => 'output nothing while working',
);

arg item => (
    isa      => 'Str',
    required => 1,
    comment  => 'the item to paint',
);

my $ref = optargs;

print "Painting $ref->{item}\n" unless $ref->{quiet};

DESCRIPTION

OptArgs processes command-line options and arguments for Perl scripts. This is in contrast to anything anything in the Getopt::* namespace that deals with command options only.

The following model is assumed by OptArgs for command-line applications:

Command

The program name - i.e. the filename be executed by the shell.

Options

Options are parameters that affect the way a command runs. They are generally not required to be present, but that is configurable. All options have a long form prefixed by '--', and may have a single letter alias prefixed by '-'.

Arguments

Arguments are positional parameters that that a command needs know in order to do its work. Confusingly, arguments can be optional. The last argument defined may be greedy: it can consume everything else left on the command line.

Sub-commands

From a users point of view sub-command arguments and options are indistinguishable from arguments and options to the Command. Subcommand options and arguments are defined in the same place as Command arguments and options. However from a code perspective they are implemented as separate, stand-alone programs to be called by a dispatcher.

Simple Scripts

To demonstrate lets put the code from the synopsis in a file called paint and observe the following interactions from the shell:

$ ./paint
usage: paint ITEM

  arguments:
    ITEM          the item to paint

  options:
    --quiet, -q   output nothing while working

As you can see a usage message is generated automatically. The optargs() function parses the command line according to the declarations and returns a single HASH reference, easily interpolated inside strings.

$ ./paint house
Painting house

Because OptArgs knows about arguments it can detect more errors than an option-only processing module:

$ ./paint house car
error: unexpected option or argument: car

The usage message is constructed based on option and argument attributes. If we add another argument:

arg colour => (
    isa     => 'Str',
    default => 'blue',
    comment => 'the colour to use',
);

And then check the usage again:

$ ./paint
usage: paint ITEM [COLOUR]

  arguments:
    ITEM          the item to paint
    COLOUR        the colour to use

  options:
    --quiet, -q   output nothing while working

It can be seen that the non-required argument colour appears inside square brackets indicating its optional nature. Three dots (...) are postfixed to greedy arguments. The order in which options and arguments (and also sub-commands: see below) are defined is the order in which they appear in usage messsages.

Sub-Command Scripts

FUNCTIONS

The following functions are exported (by default except for dispatch) using Exporter::Tidy.

opt( $name, %parameters )

Define a Command Option. If $name contains underscores then aliases with the underscores replaced by dashes (-) will be created. The following parameters are accepted:

isa

Required. Is mapped to a Getopt::Long type according to the following table:

 optargs         Getopt::Long
------------------------------
 'Bool'          '!'
 'Counter'       '+'
 'Str'           '=s'
 'Int'           '=i'
 'Num'           '=f'
 'ArrayRef'      's@'
 'HashRef'       's%'
comment

Required. Used to generate the usage/help message.

default

The value set when the option is not used.

If this is a subroutine reference it will be called with a hashref containg all option/argument values after parsing the source has finished. The value to be set must be returned, and any changes to the hashref are ignored.

alias

A single character alias.

ishelp

When true flags this option as a help option, which when given on the command line results in a usage message exception. This flag is basically a cleaner way of doing the following in each (sub) command:

my $opts = optargs;
if ( $opts->{help} ) {
    die usage('help requested');
}
arg( $name, %parameters )

Define a Command Argument with the following parameters:

isa

Required. Is mapped to a Getopt::Long type according to the following table:

 optargs         Getopt::Long
------------------------------
 'Str'           '=s'
 'Int'           '=i'
 'Num'           '=f'
 'ArrayRef'      's@'
 'HashRef'       's%'
 'SubCmd'        '=s'
comment

Required. Used to generate the usage/help message.

required

Set to a true value when the caller must specify this argument. Can not be used if a 'default' is given.

default

The value set when the argument is not given. Can not be used if 'required' is set.

If this is a subroutine reference it will be called with a hashref containg all option/argument values after parsing the source has finished. The value to be set must be returned, and any changes to the hashref are ignored.

greedy

If true the argument swallows the rest of the command line. It doesn't make sense to define any more arguments once you have used this as they will never be seen.

fallback

If isa is a SubCmd this option (when set) will stop the generation of the usage message when the argument is not found as a sub-command. The current command will be called instead. This option when set must be a HASH reference containing "name" and "comment" key/value pairs, which are only used in usage messages.

optargs( [ @argv ] ) -> HashRef

Parse @ARGV by default (or @argv when given) and returns a hashref containing key/value pairs for options and arguments combined. An error / usage exception is thrown if an invalid combination of options and arguments is given.

Note that @ARGV will be decoded into UTF-8 (if necessary) from whatever I18N::Langinfo says your environment encoding is.

usage( [$message] ) -> Str

Returns a usage string prefixed with $message if given.

subcmd( @cmd, $description )

Create a sub-command. After this function is called further calls to opt and arg define options and arguments respectively for the sub-command.

dispatch( $method, $rootclass, [ @argv ] )

Parse @ARGV (or @argv if given) and dispatch to the method $method in the appropriate package name constructed from $rootclass.

SEE ALSO

Getopt::Long, Exporter::Tidy

SUPPORT & DEVELOPMENT

This distribution is managed via github:

https://github.com/mlawren/p5-OptArgs/tree/devel

This distribution follows the semantic versioning model:

http://semver.org/

Code is tidied up on Git commit using githook-perltidy:

http://github.com/mlawren/githook-perltidy

AUTHOR

Mark Lawrence <nomad@null.net>

LICENSE

Copyright 2012 Mark Lawrence <nomad@null.net>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.