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

VERSION
   version 1.09

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

   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.

 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:

   *   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

 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.

 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:

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

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

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

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 <[email protected]>

CONTRIBUTORS
   *   David Golden <[email protected]>

   *   David Precious <[email protected]>

   *   James E Keenan <[email protected]>

   *   Kevin McGrath <[email protected]>

   *   Nova Patch <[email protected]>

   *   Robert Bohne <[email protected]>

   *   thilp <[email protected]>

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

   This is free software, licensed under:

     The Apache License, Version 2.0, January 2004

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.