/ 
Getopt-Again-0.000002
/ Getopt::Again

NAME

Getopt::Again - Yet another attempt at a universal Getopt tool.

DESCRIPTION

Getopt tool that takes short form -abc and/or long form --alpha options. Options may be boolen, or accept values. Values can be specified via --foo val or --foo=val forms. Can also use a regex to slurp up matching options. Ability to auto-generate usage and help strings for you when desired.

ANOTHER GETOPT TOOL!!!!

Yeah... Sorry about that. Here is a relevant XKCD: http://xkcd.com/927/.

I have not yet found a Getopt module that works the way I would like. It may exist, but the author is doing a poor job of reaching me and my searches have failed.

I went a long time refusing to add yet more clutter to the Getopt namespace, but I am tired of writing custom parsing for options every time I write a script. So here it is, my way, and I don't care if nobody ever uses it, I won't force you.

SYNOPSYS

SCRIPT

use Getopt::Again enable_help => 1; # Default is 0

opt_bools  qw/alpha beta/;  # Quickly define some boolean options
opt_lists  qw/gamma zeta/;  # Quickly define some options that accept multiple args
opt_params qw/foo bar/;     # Quickly define some options that accept a single arg
opt_paths  qw/origin dest/; # Quickly define some options that take directory paths
opt_files  qw/config/;      # Quickly define some options that take file paths

# All arguments to opt_add are optional except the name.
opt_add my_opt => (
    type        => 'string',           # Or 'bool', 'regex', 'path', 'file'
    list        => 1,                  # True to take multiple values
    default     => 'stuff',            # Default value
    example     => " 'a string'",      # Example value, for help/usage
    alias       => [ 'the_opt', 'm' ], # Alternate names
    process     => sub { ... },        # Can also be a validation regex
    description => "My option ..."     # For help/usage
    split_on    => ",",                # Split values (list only)
    regex       => qr/^foo-(.+)$/,     # Match options like this, use the capture for value
);

my $usage = opt_usage();
my $help  = opt_help();

# Get the options and args from @ARGV. @ARGV is not altered
my (%opts, @args) = opt_parse(@ARGV);

OOP

use Getopt::Again();

my $ga = Getopt::Again->new(enable_help => 1);

$ga->add('my_opt' => (
    type        => 'string',           # Or 'bool', 'regex', 'path', 'file'
    list        => 1,                  # True to take multiple values
    default     => 'stuff',            # Default value
    example     => " 'a string'",      # Example value, for help/usage
    alias       => [ 'the_opt', 'm' ], # Alternate names
    process     => sub { ... },        # Can also be a validation regex
    description => "My option ..."     # For help/usage
    split_on    => ",",                # Split values (list only)
    regex       => qr/^foo-(.+)$/,     # Match options like this, use the capture for value
));

my $usage = $ga->usage_string();
my $help  = $ga->help_string();

# Get the options and args from @ARGV, @ARGV is not altered
my (%opts, @args) = $ga->parse(@ARGV);

PARSING RULES

A single dash denotes 1-character options, so -xyz is seen as the x, y, and z options.
command -xyz

command -x -y -z

command --xerxes --yolk --zebra
The final option in a set of single dash options may have an argument.
command -xf thing

command -xyzf thing
Double dash denotes long form --foo is seen as the 'foo' option.
command --thing
Options that accept arguments may take the --opt=val or --opt val forms.
command --thing=val

command --thing val
Options that can have a list of values may specify a delimiter, and/or can be listed multiple times.
command --thing x --thing y --thing z

command --thing x,y,z

command --thing x.y.z
When it is not ambiguous, you may use the first character of the long form in a short form.

These work:

command --xerxes
command -x

This would not:

command --xerxes
command --xandu
command -x # Nope! ambiguous (unless -x is defined directly)
End of params is -- as expected, nothing after this will be parsed, instead they are added to the list of arguments.
command -xyz -- --this_is_not_an_opt --this_is_an_arg

EXPORTS

$ga = opt_meta()

Get the underlying Getopt::Again object.

opt_bools(qw/awake alive/)

Quickly define some boolean options.

opt_lists(qw/friends family/)

Quickly define some list options.

opt_params(qw/name age/)

Quickly define some options that take strings.

opt_paths(qw/origin dest/)

Quickly define some options that take paths (they must exist).

opt_files(qw/input config/)

Quickly define some options that take files (they must exist).

opt_add(NAME, %OPTIONS)

Add an option.

$usage = opt_usage()
opt_usage($set)

Get or set the usage string (returns "$0 $string", do not include $0 when setting).

$help = opt_help()

Get the help string.

($opts, $args) = opt_parse(...)

Parse a parameters (@ARGV is the usual argument).

An exception will be thrown if an unknown option is specified.

$opts is a hashref, $args is an arrayref.

opt_use_help()

Enable the --help and -h options.

OPTION PROPERTIES

type

Values may be one of: 'string', 'bool', 'regex', 'file', 'path'.

If none is specified it is guessed. Names with more than 1 character default to string, named with 1 character only default to bool.

list

True or false. When true the option will always be an arrayref containing 0 or more values.

default

Specify the default value when none was specified. For bools this gets normalized to true or false. For lists the default is a new empty array.

example

Example for documentation, usually an example value prefixed with either a space or equal sign:

example => ' foo',

or

example => '=foo',
process

Post-processing on the value. If this is a regex than an exception will be thrown for any value that does not match.

The value may also be a coderef. For the coderef $_ will be set to the value being processed. The value will also be passed in as the only argument. Whatever the coderef returns will replace the value, so this is a hook to allow you to modify the value.

description

Provide a long description of the option for the help string.

split_on

Specify a delimiter for list options.

regex

Specify a regex to be used to identify parameters. Use this if you want something like enable-* to be captured.

list  => 1,
regex => qr/^enable-(.*)$/,

This will match all the following:

--enable-food
--enable-protection

In these cases the value will be set to the first capture group, so in this case:

[
    'food',
    'protection'
]

If there is no capture $1, then the remaining string after the match $' will be used.

OBJECT METHODS

$ga->opt_spec($name)

Get the specification for an option.

$ga->add($name => %properties)

Add an option

($opts, $args) = $ga->parse(@ARGV)

Parse a parameters (@ARGV is the usual argument).

An exception will be thrown if an unknown option is specified.

$opts is a hashref, $args is an arrayref.

$ga->usage_string

Get or set the usage string (returns "$0 $string", do not include $0 when setting).

$ga->help_string

Get the help string

$ga->enable_help

Enable the help (--help and -h) tools.

SEE ALSO

Everything in the massive Getopt namespace.

On second thought, don't, you do not have that much time.

AUTHORS

Chad Granum exodist7@gmail.com

COPYRIGHT

Copyright (C) 2014 Chad Granum

Getopt-Again is free software; Standard perl license (GPL and Artistic).

Getopt-Again is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the license for more details.