NAME

Getopt::Long::More - Like Getopt::Long, but with more stuffs

VERSION

This document describes version 0.007 of Getopt::Long::More (from Perl distribution Getopt-Long-More), released on 2020-04-08.

SYNOPSIS

use Getopt::Long::More; # imports GetOptions as well as optspec; you can also
                        # explicitly import Configure, GetOptionsFromArray,
                        # GetOptionsFromString

my %opts;
GetOptions(
    # just like in Getopt::Long
    'foo=s' => \$opts{foo},
    'bar'   => sub { ... },

    # but if you want to specify extra stuffs...
    'baz'   => optspec(
        # will be passed to Getopt::Long
        destination => \$opts{baz},

        # specify that this option is required
        required => 1,

        # specify this for default value
        default => 10,

        # specify this if you want nicer usage message
        summary => 'Blah blah blah',

        # specify longer (multiparagraphs) of text for POD, in POD format
        description => <<'_',
Blah blah ...
blah
Blah blah ...
blah blah
_

        # provide completion from a list of strings
        # completion => [qw/apple apricot banana/],

        # provide more advanced completion routine
        completion => sub {
            require Complete::Util;
            my %args = @_;
            Complete::Util::complete_array_elem(
                word => $args{word},
                array => [ ... ],
            );
        },

        # other properties: x or x.* or _* are allowed
        'x.debug' => 'blah',
        _app_code => {foo=>1},
    ),
);

DESCRIPTION

This module is a wrapper and drop-in replacement for Getopt::Long. It provides the same interface as Getopt::Long and, unlike other wrappers like Getopt::Long::Complete or Getopt::Long::Modern it does not change default configuration and all Getopt::Long configuration are supported. In fact, Getopt::Long::More behaves much like Getopt::Long until you start to use optspec object as one or more option destinations.

OPTSPEC OBJECT

In addition to using scalarref, arrayref, hashref, or coderef as the option destination as Getopt::Long allows, Getopt::Long::More also allows using optspec object as the destination. This enables you to specify more stuffs.

Optspec object is created using the optspec function which accepts a list of property name-property value pairs:

'--fruit=s' => optspec(
    destination => \$opts{fruit},
    default => 'apple',
    summary => 'Supply name of fruit to order',
    completion => [qw/apple apricot banana/],
    ...
)

All properties are optional.

destination => ScalarRef / ArrayRef / HashRef / CodeRef

The destination property, if present, will be passed to Getopt::Long when parsing options.

Note that, in previous versions of this module, destination was referred to as handler, which is now deprecated. At this time handler is still being accepted as an alias for destination, but do NOT count on that forever. The name handler will be discontinued at one point. You have been warned.

In addition to destination, these other properties are also recognized:

required => bool

Set this to 1 to specify that the option is required.

default => any

Provide default for the option.

summary => str

Provide a short summary message for the option. This is used when generating usage/help message.

description => str

Provide a longer (multiparagraph) text, in POD format. Will be used to generate POD.

completion => array|code

Provide completion routine. Can also be a simple array of strings.

Completion routine will be passed a hash argument, with at least the following keys: word (str, the word to be completed). It is expected to return a completion answer structure (see Complete for mor edetails) which is usually just an array of strings.

x, x., _ => any

You are allowed to have properties named x or anything that begins with x. or _. These are ignored by Getopt::Long::More. You can use store comments or whatever additional information here.

FUNCTIONS