Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/fgasper/p5-cli-popt

CPAN’s CLI::Popt
https://github.com/fgasper/p5-cli-popt

Last synced: 19 days ago
JSON representation

CPAN’s CLI::Popt

Awesome Lists containing this project

README

        

# NAME

CLI::Popt - Parse CLI parameters via [popt](https://github.com/rpm-software-management/popt)

# SYNOPSIS

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

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

# 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);

if ($opts_hr->{'help'}) {
print $popt->get_help();
exit;
}

… and so on.

# 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](https://github.com/rpm-software-management/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).