Getopt::Lucid(3pm)

📦
version 1.10 · 4 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

okay bestie, Getopt::Lucid(3pm) is giving clear, readable syntax for command line processing, and version 1.10 is the one we're stanning. no cap. 💅

✨ NAME ✨

Getopt::Lucid — clear, readable syntax for command line processing. 💖

🎀 VERSION 🎀

version 1.10 — that's the whole vibe, fr fr. ✨

🌸 SYNOPSIS 🌸

use Getopt::Lucid qw( :all );

# basic option specifications with aliases

@specs = (
  Switch("version|V"),
  Counter("verbose|v"),
  Param("config|C"),
  List("lib|l|I"),
  Keypair("define"),
  Switch("help|h")
);

$opt = Getopt::Lucid->getopt( \@specs )->validate;

$verbosity = $opt->get_verbose;
@libs = $opt->get_lib;
%defs = $opt->get_define;

%all_options = $opt->options;

# advanced option specifications

@adv_spec = (
  Param("input"),
  Param("mode")->default("tcp"),     # defaults
  Param("host")->needs("port"),      # dependencies
  Param("port")->valid(qr/\d+/),     # regex validation
  Param("config")->valid(sub { -r }),# custom validation
  Param("help")->anycase,            # case insensitivity
);
$opt = Getopt::Lucid->getopt( \@adv_spec );
$opt->validate({ 'requires' => ['input'] });

# example with a config file

$opt = Getopt::Lucid->getopt( \@adv_spec );
use Config::Std;
if ( -r $opt->get_config ) {
  read_config( $opt->get_config() => my %config_hash );
  $opt->merge_defaults( $config_hash{''} );
}

🦋 DESCRIPTION 🦋

The goal of this module is providing good code readability and clarity of intent for command-line option processing. While readability is a subjective standard, Getopt::Lucid relies on a more verbose, plain-English option specification as compared against the more symbolic approach of Getopt::Long. Key features include:

  • Five option types: switches, counters, parameters, lists, and key pairs
  • Three option styles: long, short (including bundled), and bare (without dashes)
  • Specification of defaults, required options and option dependencies
  • Validation of options with regexes or subroutines
  • Negation of options on the command line
  • Support for parsing any array, not just the default @ARGV
  • Incorporation of external defaults (e.g. from a config file) with user control of precedence

💅 USAGE 💅

🎀 Option Styles, Naming and "Strictness" 🎀

Getopt::Lucid support three kinds of option styles: long-style ("--foo"), short-style ("-f") and bareword style ("foo"). Short-style options are automatically unbundled during command line processing if a single dash is followed by more than one letter (e.g. "-xzf" becomes "-x -z -f" ). so convenient, honestly. 🫶

Each option is identified in the specification with a string consisting of the option "name" followed by zero or more "aliases", with any alias (and each subsequent alias) separated by a vertical bar character. E.g.:

"lib|l|I" means name "lib", alias "l" and alias "I"

Names and aliases must begin with an alphanumeric character, but subsequently may also include both underscore and dash. (E.g. both "input-file" and "input_file" are valid.) While names and aliases are interchangeable when provided on the command line, the "name" portion is used with the accessors for each option (see "Accessors and Mutators").

Any of the names and aliases in the specification may be given in any of the three styles. By default, Getopt::Lucid works in "magic" mode, in which option names or aliases may be specified with or without leading dashes, and will be parsed from the command line whether or not they have corresponding dashes. Single-character names or aliases may be read with no dash, one dash or two dashes. Multi-character names or aliases must have either no dashes or two dashes. E.g.:

  • Both "foo" and "--foo" as names in the specification may be read from the command line as either "--foo" or "foo"
  • The specification name "f" may be read from the command line as "--f", "-f", or just "f"

In practice, this means that the specification need not use dashes, but if used on the command line, they will be treated appropriately.

Alternatively, Getopt::Lucid can operate in "strict" mode by setting the strict parameter to a true value. In strict mode, option names and aliases may still be specified in any of the three styles, but they will only be parsed from the command line if they are used in exactly the same style. E.g., given the name and alias "--help|-h", only "--help" and "-h" are valid for use on the command line. strict mode is giving boundaries, and we respect it. 💙

🛠️ Option Specification Constructors 🛠️

Options specifications are provided to Getopt::Lucid in an array. Entries in the array must be created with one of several special constructor functions that return a specification object. These constructor functions may be imported either individually or as a group using the import tag ":all" (e.g. use Getopt::Lucid qw(:all);).

The form of the constructor is:

TYPE( NAME_ARGUMENT );

The constructor function name indicates the type of option. The name argument is a string with the names and aliases separated by vertical bar characters.

The five option specification constructors are:

Switch()

A true/false value. Defaults to false. The appearance of an option of this type on the command line sets it to true. flip it on, bestie. ✅

Counter()

A numerical counter. Defaults to 0. The appearance of an option of this type on the command line increments the counter by one. stack those little wins. 🔢

Param()

A variable taking an argument. Defaults to "" (the empty string). When an option of this type appears on the command line, the value of the option is set in one of two ways -- appended with an equals sign or from the next argument on the command line:

--name=value
--name value

In the case where white space is used to separate the option name and the value, if the value looks like an option, an exception will be thrown:

--name --value        # throws an exception
⚠️ watch out: that exception is not a vibe. Give it a real value, not something that looks like another option.

List()

This is like Param() but arguments are pushed onto a list. The default list is empty. collect them all, periodt. 📝

Keypair()

A variable taking an argument pair, which are added to a hash. Arguments are handled as with Param(), but the argument itself must have a key and value joined by an equals sign.

--name=key=value
--name key=value

🎨 Option modifiers 🎨

An option specification can be further modified with the following methods, each of which return the object modified so that modifier chaining is possible. E.g.:

@spec = (
  Param("input")->default("/dev/random")->needs("output"),
  Param("output")->default("/dev/null"),
);

valid()

Sets the validation parameter(s) for an option.

@spec = (
  Param("port")->valid(qr/\d+/),          # regex validation
  Param("config")->valid(sub { -r }),     # custom validation
  Keypair("define")
    ->valid(\&_valid_key, \&valid_value), # keypairs take two
);

See the "Validation" section, below, for more.

default()

Changes the default for the option to the argument(s) of default(). List and hashes can take either a list or a reference to an array or hash, respectively.

@spec = (
  Switch("debug")->default(1),
  Counter("verbose")->default(3),
  Param("config")->default("/etc/profile"),
  List("dirs")->default(qw( /var /home )),
  Keypair("define")->default( arch => "i386" ),
);

needs()

Takes as an argument a list of option names or aliases of dependencies. If the option this modifies appears on the command line, each of the options given as an argument must appear on the command line as well or an exception is thrown.

@spec = (
  Param("input")->needs("output"),
  Param("output"),
);
bestie, dependency check: if input shows up, output has to show up too, or it's an exception. No ghosting. 👻

anycase()

Indicates that the associated option names/aliases may appear on the command line in lowercase, uppercase, or any mixture of the two. No argument is needed.

@spec = (
  Switch("help|h")->anycase(),    # "Help", "HELP", etc.
);

doc()

Sets the documentation string for an option.

@spec = (
  Param("output")->doc("write output to the specified file"),
);

This string shows up in the "usage" method.

🔍 Validation 🔍

Validation happens in two stages. First, individual parameters may have validation criteria added to them. Second, the parsed options object may be validated by checking that all requirements collectively are met.

Parameter validation

The Param, List, and Keypair option types may be provided an optional validation specification. Values provided on the command line will be validated according to the specification or an exception will be thrown.

A validation specification can be either a regular expression, or a reference to a subroutine. Keypairs take up to two validation specifiers. The first is applied to keys and the second is applied to values; either can be left undef to ignore validation. (More complex validation of specific values for specific keys must be done manually.)

Validation is also applied to default values provided via the default() modifier or later modified with append_defaults, merge_defaults, or replace_defaults. This ensures internal consistency.

If no default is explicitly provided, validation is only applied if the option appears on the command line. (In other words, the built-in defaults are always considered valid if the option does not appear.) If this is not desired, the required option to the validate method should be used to force users to provide an explicit value.

# Must be provided and is thus always validated
@spec = ( Param("width")->valid(qr/\d+/) );
$opt = Getopt::Lucid->getopt(\@spec);
$opt->validate( {requires => ['width']} );

For validation subroutines, the value found on the command line is passed as the first element of @_, and $_ is also set equal to the first element. (N.B. Changing $_ will not change the value that is captured.) The value validates if the subroutine returns a true value.

For validation with regular expressions, consider using Regexp::Common for a ready library of validation options.

Older versions of Getopt::Lucid used validation arguments provided in the Spec constructor. This is still supported, but is deprecated and discouraged. It may be removed in a future version of Getopt::Lucid.

# deprecated
Param("height", qr/\d+/)
🚨 deprecated alert: still supported, but discouraged. It may be removed in a future version of Getopt::Lucid. Don't build your whole personality on it.

Options object validation

The validate method should be called on the result of getopt. This will check that all parameter prerequisites defined by needs have been met. It also takes a hashref of arguments. The optional requires argument gives an arrayref of parameters that must exist. gatekeeping, but make it correct. 💜

okay so the reason object validation is done separate from getopt is literally so you get better control over which different options might be required — and so some dependencies (i.e. from needs) can be met via a configuration file. like, that's the whole point bestie 💅

@spec = (
  Param("action")->needs(qw/user password/),
  Param("user"),
  Param("password"),
);
$opt = Getopt::Lucid->getopt(\@spec);
$opt->merge_defaults( read_config() ); # provides 'user' & 'password'
$opt->validate({requires => ['action']});

✨ Parsing the Command Line ✨

Technically, Getopt::Lucid scans an array for command line options, not a command-line string. By default, this array is @ARGV (though other arrays can be used — see new()), which is typically provided by the operating system according to system-specific rules. no cap. 🫶

When Getopt::Lucid processes the array, it scans the array in order, removing any specified command line options and any associated arguments, and leaving behind any unrecognized elements in the array. If an element consisting solely of two-dashes (--) is found, array scanning is terminated at that point. Any options found during scanning are applied in order. E.g.:

@ARGV = qw( --lib /tmp --lib /var );
my $opt = Getopt::Lucid->getopt( [ List("lib") ] );
print join ", " $opt->lib;
# prints "/tmp, /var"

If an element encountered in processing begins with a dash, but is not recognized as a short-form or long-form option name or alias, an exception will be thrown. 💀

🚫 Negation 🚫

Getopt::Lucid also supports negating options. Options are negated if the option is specified with no- or --no- prefixed to a name or alias. By default, negation clears the option: Switch and Counter options are set to zero; Param options are set to ""; List and Keypair options are set to an empty list and empty hash, respectively. For List and Keypair options, it is also possible to negate a specific list element or hash key by placing an equals sign and the list element or key immediately after the option name:

--no-lib=/tmp --no-define=arch
# removes "/tmp" from lib and the "arch" key from define

As with all options, negation is processed in order, allowing a "reset" in the middle of command line processing. This may be useful for those using command aliases who wish to "switch off" options in the alias. E.g, in Unix:

$ alias wibble = wibble.pl --verbose
$ wibble --no-verbose

# @ARGV would contain ( "--verbose", "--no-verbose" )

This also may have applications in post-processing configuration files (see "Managing Defaults and Config Files"). 🎀

💖 Accessors and Mutators 💖

After processing the command-line array, the values of the options may be read or modified using accessors/mutators of the form get_NAME and set_NAME, where NAME represents the option name in the specification without any leading dashes. E.g.

@spec = (
  Switch("--test|-t"),
  List("--lib|-L"),
  Keypair("--define|-D"),
);

$opt = Getopt::Lucid->getopt( \@spec );
print $opt->get_test ? "True" : "False";
$opt->set_test(1);

For option names with dashes, underscores should be substituted in the accessor calls. E.g.

@spec = (
  Param("--input-file|-i")
);

$opt = Getopt::Lucid->getopt( \@spec );
print $opt->get_input_file;

This can create an ambiguous case if a similar option exists with underscores in place of dashes. (E.g. input_file and input-file.) Users can safely avoid these problems by choosing to use either dashes or underscores exclusively and not mixing the two styles. bestie pls just pick one, i'm begging 😭

List and Keypair options are returned as flattened lists:

my @lib = $opt->get_lib;
my %define = $opt->get_define;

Using the set_NAME mutator is not recommended and should be used with caution. No validation is performed and changes will be lost if the results of processing the command line array are recomputed (e.g, such as occurs if new defaults are applied). List and Keypair options mutators take a list, not references. lowkey a trap, so watch urself 👀

🌸 Managing Defaults and Config Files 🌸

A typical problem for command-line option processing is the precedence relationship between default option values specified within the program, default option values stored in a configuration file or in environment variables, and option values specified on the command-line, particularly when the command-line specifies an alternate configuration file. it's giving chaos fr fr

Getopt::Lucid takes the following approach to this problem:

  • Initial default values may be specified as part of the option specification (using the default() modifier)
  • Default values from the option specification may be modified or replaced entirely with default values provided in an external hash (such as from a standard config file or environment variables)
  • When the command-line array is processed, options and their arguments are stored in the order they appeared in the command-line array
  • The stored options are applied in-order to modify or replace the set of "current" default option values
  • If default values are subsequently changed (such as from an alternative configuration file), the stored options are re-applied in-order to the new set of default option values

With this approach, the resulting option set is always the result of applying options (or negations) from the command-line array to a set of default-values. Users have complete freedom to apply whatever precedence rules they wish to the default values and may even change default values after the command-line array is processed without losing the options given on the command line. iconic behaviour honestly 👑

Getopt::Lucid provides several functions to assist in manipulating default values:

  • merge_defaults() — new defaults overwrite any matching, existing defaults. KeyPairs hashes and List arrays are replaced entirely with new defaults
  • append_defaults() — new defaults overwrite any matching, existing defaults, except for Counter and List options, which have the new defaults added and appended, respectively, and KeyPair options, which are flattened into any existing default hash
  • replace_defaults() — new defaults replace existing defaults; any options not provided in the new defaults are reset to zero/empty, ignoring any default given in the option specification
  • reset_defaults() — returns defaults to values given in the options specification

😭 Exceptions and Error Handling 😭

Getopt::Lucid uses Exception::Class for exceptions. When a major error occurs, Getopt::Lucid will die and throw one of three Exception::Class subclasses:

  • Getopt::Lucid::Exception::Usage — thrown when Getopt::Lucid methods are called incorrectly
  • Getopt::Lucid::Exception::Spec — thrown when the specification array contains incorrect or invalid data
  • Getopt::Lucid::Exception::ARGV — thrown when the command-line is processed and fails to pass specified validation, requirements, or is otherwise determined to be invalid

These exceptions may be caught using an eval block and allow the calling program to respond differently to each class of exception. so you can catch each one and vibe accordingly ✨

🦋 Ambiguous Cases and Gotchas 🦋

One-character aliases and anycase

@spec = (
  Counter("verbose|v")->anycase,
  Switch("version|V")->anycase,
);

Consider the spec above. By specifying anycase on these, verbose, Verbose, VERBOSE are all acceptable, as are version, Version and so on. (Including long-form versions of these, too, if magic mode is used.) However, what if the command line has -v or even -v -V? In this case, the rule is that exact case matches are used before case-insensitive matches are searched. Thus, -v can only match verbose, despite the anycase modification, and likewise -V can only match version. the way exact case wins first is so real 💅

Identical names except for dashes and underscores

@spec = (
  Param("input-file"),
  Switch("input_file"),
);

Consider the spec above. These are two, separate, valid options, but a call to the accessor get_input_file is ambiguous and may return either option, depending on which first satisfies a "fuzzy-matching" algorithm inside the accessor code. Avoid identical names with mixed dash and underscore styles. genuinely not worth the drama bestie 🙈

💖 METHODS 💖

✨ new() ✨

$opt = Getopt::Lucid->new( \@option_spec );
$opt = Getopt::Lucid->new( \@option_spec, \%parameters );
$opt = Getopt::Lucid->new( \@option_spec, \@option_array );
$opt = Getopt::Lucid->new( \@option_spec, \@option_array, \%parameters );

Okay bestie, this one births a brand new Getopt::Lucid object 🎀. You have to pass it an array reference to an option spec — that's non-negotiable, it's required, no spec no object, periodt. (Go peek at "USAGE" if you need the tea on what the spec looks like.) By default, objects are set to read @ARGV for command line options, because that's just where the vibes live. Want to feed it something else? Pass an optional second argument with a reference to an array and it'll process that array instead. And the final argument can be a hashref of parameters — the only valid parameter right now is:

  • strict — turns on strict mode when it's true

Lowkey for typical cases you're gonna want to call getopt instead, which builds a new object and parses the command line in a single function call. One and done, no extra steps, we love efficiency 💅.

✨ validate() ✨

$opt->validate();
$opt->validate( \%arguments );

Takes an optional argument hashref and validates that all the requirements and prerequisites are met — or it throws an error, dramatic but fair 😭. Valid argument keys are:

  • "requires" — an arrayref of options that must exist in the options object

And the best part? This method returns the object so you can chain it like the main character you are:

$opt = Getopt::Lucid->getopt(\@spec)->validate;

✨ append_defaults() ✨

%options = append_defaults( %config_hash );
%options = append_defaults( \%config_hash );

Takes a hash or hash reference of new default values, tweaks the stored defaults, recalculates the result of processing the command line with those revised defaults, and hands you back a hash with the resulting options 🫶. Every key/value pair you pass gets added to the stored defaults. Here's the breakdown by type, iykyk:

  • For Switch and Param options, the value in the passed hash will overwrite any preexisting value.
  • For Counter options, the value is added to any preexisting value.
  • For List options, the value (or values, if the value is an array reference) gets pushed onto the end of the list of existing values.
  • For Keypair options, the key/value pairs get added to the existing hash, overwriting existing key/value pairs (just like merging two hashes).

Keys that aren't valid names from the options specification? Ignored. We simply do not see them 💅.

✨ defaults() ✨

%defaults = $opt->defaults();

Returns a hash containing the current default values. Keys are names from the option specification (without any leading dashes, obviously). These defaults are the baseline values that get modified by the parsed command line options. The before pic, if you will 📸.

✨ getopt() ✨

$opt = Getopt::Lucid->getopt( \@option_spec );
$opt = Getopt::Lucid->getopt( \@option_spec, \@option_array );
$opt->getopt();

Parses the command line array (@ARGV by default). When you call it as a class function, getopt takes the same arguments as new, calls new to create an object before parsing the command line, and returns that new object. When you call it as an object method, it takes no arguments and returns itself. Self-love, honestly ✨.

For convenience, getopts() is an alias for getopt(). Same energy, different spelling 💜.

✨ merge_defaults() ✨

%options = merge_defaults( %config_hash );
%options = merge_defaults( \%config_hash );

Takes a hash or hash reference of new default values, modifies the stored defaults, recalculates the result of processing the command line with the revised defaults, and returns a hash with the resulting options. Every key/value pair in the passed hash is added to the stored defaults, overwriting any preexisting value. Keys that aren't valid names from the options specification will be ignored. Respectfully, they were never invited 🚫.

✨ names() ✨

@names = $opt->names();

Returns the list of names in the options specification. Each name represents a key in the hash of options that options gives you. It's the roll call 📋✨.

✨ options() ✨

%options = $opt->options();

Returns a deep copy of the options hash. Heads up though: before getopt is called, its behavior is undefined — so don't come for it, it simply hasn't been born yet 💀. After getopt is called, this returns the result of modifying the defaults with the results of command line processing. The glow-up, captured 🦋.

✨ replace_defaults() ✨

%options = replace_defaults( %config_hash );
%options = replace_defaults( \%config_hash );

Takes a hash or hash reference of new default values, replaces the stored defaults, recalculates the result of processing the command line with the revised defaults, and returns a hash with the resulting options. Every key/value pair in the passed hash replaces existing defaults, including the ones given in the option specifications — yeah, it's bold like that 👑. Keys that aren't valid names from the option specification will be ignored.

✨ reset_defaults() ✨

%options = reset_defaults();

Resets the stored defaults back to the original values from the options specification, recalculates the result of processing the command line with the restored defaults, and returns a hash with the resulting options. This is the undo button for a merge_defaults or add_defaults call. Ctrl+Z but make it iconic ✨.

✨ usage() ✨

Returns a string of usage information derived from the options spec, including any doc modifiers. Here's the catch though: because invalid options throw exceptions, if you want to provide usage info you should separately invoke new and getopt — like this:

my $opt = Getopt::Lucid->new( \@spec );
eval { $opt->getopt() };
if ($@) {
  print "$@\n" && print $opt->usage and exit 1
    if ref $@ eq 'Getopt::Lucid::Exception::ARGV';
  ref $@ ? $@->rethrow : die $@;
}

💫 API CHANGES 💫

In 1.00, the following API changes have been made:

  • new() now takes an optional hashref of parameters as the last argument
  • The global $STRICT variable has been replaced with a per-object parameter strict
  • The required modifier has been removed and a new validate method has been added to facilitate late/custom checks of required options

👀 SEE ALSO 👀

  • Config::Tiny
  • Config::Simple
  • Config::Std
  • Getopt::Long
  • Regexp::Common

💀 BUGS 💀

Please report any bugs or feature using the CPAN Request Tracker. Bugs can be submitted through the web interface at <http://rt.cpan.org/Dist/Display.html?Queue=Getopt-Lucid>

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature. Receipts, bestie — give us the receipts 🧾.

🫶 SUPPORT 🫶

🌸 Bugs / Feature Requests 🌸

Please report any bugs or feature requests through the issue tracker at <https://github.com/dagolden/Getopt-Lucid/issues>. You will be notified automatically of any progress on your issue. We'll keep you in the loop, no ghosting 💖.

🌈 Source Code 🌈

This is open source software. The code repository is available for public review and contribution under the terms of the license.

<https://github.com/dagolden/Getopt-Lucid>

git clone https://github.com/dagolden/Getopt-Lucid.git

👑 AUTHOR 👑

David Golden <dagolden@cpan.org>

⭐ CONTRIBUTORS ⭐

  • Chris White <cxwembedded@gmail.com>
  • David Golden <xdg@xdg.me>
  • David Precious <davidp@preshweb.co.uk>
  • James E Keenan <jkeenan@cpan.org>
  • Kevin McGrath <kmcgrath@cpan.org>
  • Nova Patch <patch@cpan.org>
  • Robert Bohne <rbo@cpan.org>
  • thilp <thilp@thilp.net>

This software is Copyright (c) 2019 by David Golden.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004

and that's the whole page, bestie!! 🌈✨ shoutout to perl v5.36.0 and the date 2022-12-06 for stamping this masterpiece, and to the original manpage for Getopt::Lucid(3pm) — go parse some command lines, you absolute icon 💅💖🎀

📦 where this page comes from