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