/ 
Getopt-O2-v1.1.0
River stage zero No dependents
/ README.md

NAME

Getopt::O2 - Command line argument processing and automated help generation, object oriented

SYNOPSIS

package MyPackage;
use parent 'Getopt::O2';

# return a short descriptive string about the program (appears in --help)
sub get_program_description
{
        return 'A sample program';
}

# return rules about parameters
sub get_option_rules
{
        return shift->SUPER::get_option_rules(),
                'length=i' => ['A numeric argument', 'default' => 33],
                'file=s'   => ['A mandatory argument', 'required' => 1],
                'quiet'    => ['A "flag" argument'];
}

# read options
new MyPackage->getopt(\my %options, \my @values);

DESCRIPTION

The Getopt::O2 module implements an extended Getopt class which parses the command line from @ARGV, recognizing and removing specified options and their possible values.

This module adheres to the POSIX syntax for command line options, with GNU extensions. In general, this means that options have long names instead of single letters, and are introduced with a double dash "--". Support for bundling of command line options, as was the case with the more traditional single-letter approach, is provided.

Getopt::O2 stands out for its extensive usage generation feature; anything printed in its "usage" output is generated from the input options and saves the users the time to write usage output by themselves.

Methods

Writing Rules

Command line options are processed using rules returned the getOptionsRules() implementation. Rules are expressed much like with Getopt::Long. A rule expression is followed by the rule's help string and possible options.

The options must be represented as either a string (used as help string) or an ARRAYREF. The first element of the latter is used as the options' help string. Its second element can be a CODEREF which is called when the option was seen. The rest are key-value-pairs that are coerced to a hash.

A single undef can be used to separate option categories by producing an empty line in usage() output.

# Short variant. Define flag and its help string
'q|quiet' => 'Suppresses informational program output'

# Actual implementation of "--help" parameter
'h|help' => ['Display this help message', sub {
    $self->usage()
}]

# Enumeration with allowed values
'o|output=?' => ['Use ARG as output format', 'values' => [qw(xml html json)]]

# One or more occurences of a value (result is ARRAYREF)
'i|input=s@' => 'Create result from input file ARG'

# Use callback return value as option value
'l|limit=i' => ['Limit amount of things', sub {
    my ($arg, $key) = @_;
    $arg = 100 if $arg > 100;
    return $arg; # make sure --limit is not larger than 100
}]

Rule syntax

Contextual rules

Rules can be allowed in a given context and may change the context appropriately.

Consider the following ruleset:

sub get_option_rules
{
    return
        'q|quiet'     => ['Be quiet', 'context' => '-logging'],
        'v|verbose'   => ['Be verbose', 'context' => '+logging'],
        'l|logfile=s' => ['Log to file ARG', 'context' => 'logging']
}

The above example would introduce the logging context; an internal state which makes options appearing outside of that context invalid.

The --verbose flag would activate the context - allowing for the option --logfile, which would otherwise (without the context) be considered illegal.

Contexts can be comma separated. A context of -a,-b,+c,d would:

TODO

DEPENDENCIES

None special. Uses core perl libraries.

AUTHOR

Oliver Schieche schiecheo@cpan.org

http://perfect-co.de/

LICENSE AND COPYRIGHT

Copyright 2013-2019 Oliver Schieche.

This software is a free library. You can modify and/or distribute it under the same terms as Perl itself.