OptionStyles,Namingand"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" ).
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 C<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.
OptionSpecificationConstructors
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.
Counter()
A numerical counter. Defaults to 0. The appearance of an option of this type on the command line
increments the counter by one.
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
List()
This is like "Param()" but arguments are pushed onto a list. The default list is empty.
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
Optionmodifiers
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"),
);
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.
Parametervalidation
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+/)
Optionsobjectvalidation
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.
The reason that object validation is done separate from "getopt" is to allow for better control over
different options that might be required or to allow some dependencies (i.e. from "needs") to be met via
a configuration file.
@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']});
ParsingtheCommandLine
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.
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").
AccessorsandMutators
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.
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.
ManagingDefaultsandConfigFiles
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.
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.
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
ExceptionsandErrorHandling
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.
AmbiguousCasesandGotchasOne-characteraliasesand"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".
Identicalnamesexceptfordashesandunderscores
@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.
Install Now
PNG Icons
