# NAME

CLI::Popt - Parse CLI parameters via [popt(3)](http://man.he.net/man3/popt)

# 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](https://metacpan.org/pod/Getopt%3A%3ALong) 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)](http://man.he.net/man3/popt) 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)](http://man.he.net/man3/popt) for more information.

- `descrip`, and `arg_descrip` - optional, as described in
[popt(3)](http://man.he.net/man3/popt).

%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)](http://man.he.net/man3/popt) fails the parse), an appropriate exception of type
[CLI::Popt::X::Base](https://metacpan.org/pod/CLI%3A%3APopt%3A%3AX%3A%3ABase) 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](https://metacpan.org/pod/perlartistic).