Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Getopt::Lucid(3)      User Contributed Perl Documentation     Getopt::Lucid(3)

NAME
       Getopt::Lucid - Clear, readable syntax for command line processing

VERSION
       version 1.10

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:

       o   Five	option types: switches,	counters, parameters, lists, and key
	   pairs

       o   Three option	styles:	long, short (including bundled), and bare
	   (without dashes)

       o   Specification of defaults, required options and option dependencies

       o   Validation of options with regexes or subroutines

       o   Negation of options on the command line

       o   Support for parsing any array, not just the default @ARGV

       o   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" ).

       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.:

       o   Both	"foo" and "--foo" as names in the specification	may be read
	   from	the command line as either "--foo" or "foo"

       o   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.

   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.

       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

   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"),
	  );

       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+/)

       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.

       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']});

   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.

       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.

       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.

   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.

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

       o   Initial default values may be specified as part of the option
	   specification (using	the "default()"	modifier)

       o   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)

       o   When	the command-line array is processed, options and their
	   arguments are stored	in the order they appeared in the command-line
	   array

       o   The stored options are applied in-order to modify or	replace	the
	   set of "current" default option values

       o   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:

       o   "merge_defaults()" -- new defaults overwrite	any matching, existing
	   defaults.  KeyPairs hashes and List arrays are replaced entirely
	   with	new defaults

       o   "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

       o   "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

       o   "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:

       o   "Getopt::Lucid::Exception::Usage" --	thrown when Getopt::Lucid
	   methods are called incorrectly

       o   "Getopt::Lucid::Exception::Spec" -- thrown when the specification
	   array contains incorrect or invalid data

       o   "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.

   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".

       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.

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

       Creates a new Getopt::Lucid object.  An array reference to an option
       spec is required	as an argument.	 (See "USAGE" for a description	of the
       object spec).  By default, objects will be set to read @ARGV for
       command line options. An	optional second	argument with a	reference to
       an array	will use that array for	option processing instead.  The	final
       argument	may be a hashref of parameters.	 The only valid	parameter
       currently is:

       o   strict -- enables strict mode when true

       For typical cases, users	will likely prefer to call "getopt" instead,
       which creates a new object and parses the command line with a single
       function	call.

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

       Takes an	optional argument hashref, validates that all requirements and
       prerequisites are met or	throws an error.  Valid	argument keys are:

       o   "requires" -- an arrayref of	options	that must exist	in the options
	   object.

       This method returns the object for convenient chaining:

	  $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, modifies the
       stored defaults,	recalculates the result	of processing the command line
       with the	revised	defaults, and returns a	hash with the resulting
       options.	 Each key/value	pair in	the passed hash	is added to the	stored
       defaults.  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) will	be pushed onto the end
       of the list of existing values.	For Keypair options, the key/value
       pairs will be added to the existing hash, overwriting existing
       key/value pairs (just like merging two hashes).	Keys which are not
       valid names from	the options specification will be ignored.

   defaults()
	 %defaults = $opt->defaults();

       Returns a hash containing current default values.  Keys are names from
       the option specification	(without any leading dashes).  These defaults
       represent the baseline values that are modified by the parsed command
       line options.

   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 called as a
       class function, "getopt"	takes the same arguments as "new", calls "new"
       to create an object before parsing the command line, and	returns	the
       new object.  When called	as an object method, it	takes no arguments and
       returns itself.

       For convenience,	C<getopts()> is	a alias	for C<getopt()>.

   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.	 Each key/value	pair in	the passed hash	is added to the	stored
       defaults, overwriting any preexisting value.  Keys which	are not	valid
       names from the options specification will be ignored.

   names()
	 @names	= $opt->names();

       Returns the list	of names in the	options	specification.	Each name
       represents a key	in the hash of options provided	by "options".

   options()
	 %options = $opt->options();

       Returns a deep copy of the options hash.	 Before	"getopt" is called,
       its behavior is undefined.  After "getopt" is called, this will return
       the result of modifying the defaults with the results of	command	line
       processing.

   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.	 Each key/value	pair in	the passed hash	replaces existing
       defaults, including those given in the option specifications.  Keys
       which are not valid names from the option specification will be
       ignored.

   reset_defaults()
	 %options = reset_defaults();

       Resets the stored defaults 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 undoes the effect	of a "merge_defaults" or
       "add_defaults" call.

   usage()
       Returns a string	of usage information derived from the options spec,
       including any "doc" modifiers.  Because invalid options throw
       exceptions, if you want to provide usage, you should separately invoke
       "new" and "getopt"

	  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:

       o   "new()" now takes an	optional hashref of parameters as the last
	   argument

       o   The global $STRICT variable has been	replaced with a	per-object
	   parameter "strict"

       o   The "required" modifier has been removed and	a new "validate"
	   method has been added to facilitate late/custom checks of required
	   options

SEE ALSO
       o   Config::Tiny

       o   Config::Simple

       o   Config::Std

       o   Getopt::Long

       o   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.

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.

   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
       o   Chris White <cxwembedded@gmail.com>

       o   David Golden	<xdg@xdg.me>

       o   David Precious <davidp@preshweb.co.uk>

       o   James E Keenan <jkeenan@cpan.org>

       o   Kevin McGrath <kmcgrath@cpan.org>

       o   Nova	Patch <patch@cpan.org>

       o   Robert Bohne	<rbo@cpan.org>

       o   thilp <thilp@thilp.net>

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

       This is free software, licensed under:

	 The Apache License, Version 2.0, January 2004

perl v5.32.0			  2019-10-25		      Getopt::Lucid(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | USAGE | METHODS | API CHANGES | SEE ALSO | BUGS | SUPPORT | AUTHOR | CONTRIBUTORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Getopt::Lucid&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help