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

NAME

OptArgs - integrated argument and option processing for Perl

VERSION

0.0.1 Development release.

SYNOPSIS

use OptArgs;

opt quiet => (
    isa     => 'Bool',
    alias   => 'q',
    comment => 'be quiet please',
);

arg item => (
    isa     => 'Str',
    default => 1,
    comment => 'try this many times',
);

my $ref = optargs;
print "Working on: $ref->{item}\n" unless $ref->{quiet};

DESCRIPTION

OptArgs provides command-line option and argument processing for Perl scripts. It is designed to be a very simple way to write programs using a declarative style. Getopt::Long is used for the underlying parsing.

How exactly does one define a command line application? OptArgs assumes a fairly common (but by no means universal) approach:

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. Options are prefixed with '-' for single letter option names or '--' for long option names.

Arguments

Arguments are positional parameters that that a command needs know in order to do its work. Some arguments may be optional.

Sub-commands

A command may also have sub-commands with their own options and arguments. From the users point of view sub-commands and their options are indisinguishable from options and arguments to the main command, but from an implementation perspective they could (perhaps should) be separate, stand-alone programs, with possibly their own set of sub-commands.

Declaring Options and Arguments

OptArgs exports the following functions for defining Options and Arguments. The order in which they are defined also determines the order they appear in usage messages, and the order in which they are processed.

opt name => ( %parameters )

Define a Command Option with the following parameters:

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

Can be single characters or words separated by '|' if more than one alias is desired. If the option name contains underscores ('_') then an alias with '-' substitutions will be automatically added.

ishelp

When true flags this option as a help option, which when given will then result in an internal "die usage()" call. This is basically a shortcut saving you from doing the following in each (sub)command:

my $opts = optargs;
die usage('help requested') if $opts->{help};
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.

Parsing and Retrieving Values

OptArgs exports the following functions for parsing and retriving option and argument values:

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.

Utility Functions

usage([$message]) -> Str

Returns a usage string based on the defined opts and args, prefixed with $message if given.

Writing Sub-Commands

OptArgs exports the following functions for defining and running subcommands.

subcmd(@cmd, $description)

TBD.

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

TBD.

SEE ALSO

Getopt::Long, Exporter::Tidy

SUPPORT & DEVELOPMENT

This distribution is managed via github:

http://github.com/mlawren/p5-OptArgs

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

Test coverage according to Devel::Cover is as follows:

--------------------------------------------------------------
File                  stmt  bran  cond   sub   pod  time total
--------------------------------------------------------------
blib/lib/optargs.pm   98.8  89.7 100.0 100.0 100.0  91.1  97.0
lib/optargs.pod      100.0   n/a   n/a 100.0   n/a   8.9 100.0
Total                 98.9  89.7 100.0 100.0 100.0 100.0  97.0
--------------------------------------------------------------

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.