NAME

CLI::Popt - Parse CLI parameters via popt(3)

SYNOPSIS

my $popt = CLI::Popt->new(
    [

        # A simple boolean:
        {
            long_name => 'verbose',
        },

        # Customize the boolean’s truthy value:
        {
            long_name => 'gotta-be-me',
            type => 'val',
            val => 42,
        },
    ],
    name => $0,     # default; shown just for demonstration
);

my ($opts_hr, @leftovers) = $popt->parse(@ARGV);

DESCRIPTION

Getopt::Long is nice, but its inability to auto-generate help & usage text requires you to duplicate data between your code and your script’s documentation.

popt(3) remedies that problem. This module makes that solution available to Perl.

CHARACTER ENCODING

All strings into & out of this library are byte strings. Please decode/encode according to your application’s needs.

METHODS

$obj = CLASS->new( \@OPTIONS, %EXTRA )

Instantiates CLASS.

Each @OPTIONS member is a reference to a hash that describes an option that the returned $obj will parse() out:

• long_name (required)

• type - optional; one of: none (default), string, argv (i.e., an array of strings), short, int, long, longlong, float, or double

• short_name - optional

• flags - optional arrayref of onedash, doc_hidden, optional, show_default, random, and/or toggle.

  Numeric options may also include or, and, or xor, and optionally not.

  NB: not all flags make sense together; e.g., or conflicts with xor.

  See popt(3) for more information.

• descrip, and arg_descrip - optional, as described in popt(3).

%EXTRA is:

• name - defaults to Perl’s $0. Give empty string to leave this unset.

($opts_hr, @leftovers) = OBJ->parse(@ARGV)

Parses a list of strings understood to be parameters to script invocation. Returns a hash reference of the parsed options (keyed on each option’s long_name) as well as a list of “leftover” @ARGV members that didn’t go into one of the parsed options.

If @ARGV doesn’t match OBJ’s stored options specification (e.g., popt(3) fails the parse), an appropriate exception of type CLI::Popt::X::Base is thrown.

$str = OBJ->get_help()

Returns the help text.

$str = OBJ->get_usage()

Returns the usage text.

LICENSE & COPYRIGHT

Copyright 2022 by Gasper Software Consulting. All rights reserved.

This library is licensed under the same terms as Perl itself. See perlartistic.