NAME

    Getopt::Yath - Option processing yath style.

DESCRIPTION

    This is the getopt processor yath uses. It should work perfectly fine
    outside of yath as well.

SYNOPSIS

 DEFINING OPTIONS

        package My::Package;
        use Getopt::Yath;
    
        # Include options from other modules that use Getopt::Yath
        include_options(
            'Some::Options::Package',
            ...,
        );
    
        # an option group is basically a way to specify common parameters for all
        # options defined in the codeblock.
        option_group {category => 'Human readable category', group => 'settings_group'} => sub {
    
            # In addition to the fields specified here, all the fields from the
            # 'option_group' above are included:
            option verbose => (
                type => 'Bool',                 # This is a boolean type, it does not take an argument
    
                # Optional fields
                short => 'v',                   # Allow -v in addition to --verbose
                default => 0,                   # What value to use if none is specified (booleans default to 0 anyway)
                from_env_vars => ['VERBOSE'],   # If the $VERBOSE environment variable is set, this will be set to true.
                set_env_vars  => ['VERBOSE'],   # If this is set to true it will also set the $VERBOSE environment variable
    
                description => "This turns on verbose output",
            );
    
            option username => (
                type => 'Scalar',           # Scalar type, requires an argument
    
                # Optional
                short => 'U',               # Allow: -U Bob
                alt => ['user', 'uname'],   # Allow: --user Bob, --uname Bob
                from_env_vars => ['USER'],  # Get the value from the $USER env var if it is not provided.
                default => sub { "bob" . rand(100) }, # If none is specified, and the env var is empty, generate a default.
    
                description => "This sets your username",
            );
    
            # Other options
            ...
        };

 PARSING OPTIONS

        my $parsed = parse_options(
            ['-v', '--user', 'fred', 'not_an_opt', '--', '--will-not-process'],    # Normally you might pass in \@ARGV
            skip_non_opts => 1,                                                    # Skip non-opts, that is any argument that does not start with a '-' it will just skip.
            stops         => ['--'],                                               # Stop processing
            no_set_env    => 1,                                                    # Do not actually change %ENV
            groups        => { ':{' => '}:' },                                     # Arguemnts between the :{ and }: will be captured into an arrayref, they can be used as option values, or stand-alone
        );

    The $parsed structure:

        $parsed = {
            'cleared' => {},                       # Options that were cleared with --no-opt
            'skipped' => ['not_an_opt'],           # Skipped non options
            'settings' => {                        # Blessed as Getopt::Yath::Settings
                'settings_group' => {              # Blessed as Getopt::Yath::Settings::Group
                    'verbose'  => 1,               # The option and its value
                    'username' => 'fred',          # Another option and value
                },
            },
            'stop'    => '--',                     # We stopped at '--', if there was no '--' this would be undef
            'remains' => ['--will-not-process'],   # Stuff after the '--' that we did not process
            'modules' => {'My::Package' => 2},     # Any module that provided options that were seen will be listed
            'env'     => {'VERBOSE' => 1}          # Environment variabvles that would have been set if not for 'no_set_env'
        };

 GENERATING COMMAND LINE HELP OUTPUT:

        sub help {
            print options()->docs('cli');
        }
    
        help();

    Produces:

        Human readable category
         --username ARG,  --username=ARG,  --user ARG,  --user=ARG,  --uname ARG
         --uname=ARG,  -U ARG,  -U=ARG,  --no-username
           This sets your username
    
           Can also be set with the following environment variables: USER
    
         --verbose,  -v,  --no-verbose
           This turns on verbose output
    
           Can also be set with the following environment variables: VERBOSE
    
           The following environment variables will be set after arguments are processed: VERBOSE

 GENERATING POD:

        sub pod {
            print options()->docs('pod', head => 2); # The '2' specifies what heading level to use
        }
    
        pod();

    Produces:

       =head2 Human readable category
    
       =over 4
    
       =item --username ARG
    
       =item --username=ARG
    
       =item --user ARG
    
       =item --user=ARG
    
       =item --uname ARG
    
       =item --uname=ARG
    
       =item -U ARG
    
       =item -U=ARG
    
       =item --no-username
    
       This sets your username
    
       Can also be set with the following environment variables: C<USER>
    
    
       =item --verbose
    
       =item -v
    
       =item --no-verbose
    
       This turns on verbose output
    
       Can also be set with the following environment variables: C<VERBOSE>
    
       The following environment variables will be set after arguments are processed: C<VERBOSE>
    
    
       =back

EXPORTS

    $opts = options()

      This will return an Getopt::Yath::Instance object. This object holds
      all the defined options, and does all the real work under the hood.

    $parsed = parse_options(\@ARGV)

    $parsed = parse_options(\@ARGV, %PARAMS)

      This processes an arrayref of command line arguments into a structure
      that can be easily referenced. If there is a problem parsing, such as
      invalid options in the array, exceptions will be thrown.

      The $parsed structure will look like this:

          $parsed = {
              'cleared' => {},                       # Options that were cleared with --no-opt
              'skipped' => ['not_an_opt'],           # Skipped non options
              'settings' => {                        # Blessed as Getopt::Yath::Settings
                  'settings_group' => {              # Blessed as Getopt::Yath::Settings::Group
                      'verbose'  => 1,               # The option and its value
                      'username' => 'fred',          # Another option and value
                  },
              },
              'stop'    => '--',                     # We stopped at '--', if there was no '--' this would be undef
              'remains' => ['--will-not-process'],   # Stuff after the '--' that we did not process
              'modules' => {'My::Package' => 2},     # Any module that provided options that were seen will be listed
              'env'     => {'VERBOSE' => 1}          # Environment variabvles that would have been set if not for 'no_set_env'
          };

      Available parameters that effect parsing are:

      stops => \@STOP_LIST

      stops => ['--']

	This is a list of string that if encountered should stop the
	parsing process. The string encountered will be put into the stop
	field of the $parsed structure. Any unparsed arguments after the
	stop will be put into the remains key of the $parsed structure.

	This is mostly useful for supporting the -- option.

      groups => \%GROUP_BORDERS

      groups => { ':{' => '}:' }

	Arguments between the specified start and end tokens will be
	grouped together into an arrayref.

      stop_at_non_opts => BOOL

	This will cause parsing to stop at any non-option. A non-option in
	this case is any argument that does not start with a -.

	The item stopped at will be placed in the stop field of the $parsed
	structure with the remaining arguments placed in the remains field.

      skip_non_opts => BOOL

	This will skip any non-option encountered. A non-option is any
	argument that does not start with -. All skipped items will be
	placed into the skipped field of the <$parsed> structure.

      skip_invalid_opts => BOOL

	This will skip any invalid option encountered. This includes any
	argument that starts with - but is not a valid option. All skipped
	items will be placed into the skipped field of the <$parsed>
	structure.

      stop_at_invalid_opts => BOOL

	This will cause parsing to stop at any invalid option. This
	includes any argument that starts with - but is not a valid option.

	The item stopped at will be placed in the stop field of the $parsed
	structure with the remaining arguments placed in the remains field.

      no_set_env => BOOL

	Set this to true to prevent any modifications to %ENV.

	The env key of the $parsed structure will contain the environment
	variable changes that would have been made.

	Note: The env key is always included even if %ENV is modified
	directly.

    include_options('Options::Module::A', 'Options::Module::B', ...)

      This allows you to build libraries of Getopt::Yath options and
      include them as needed. Options from the specified libraries will be
      merged into the current packages options.

    option_group \%fields => sub { ... }

    option_group {group => 'my_group'} => sub { option ...; ... }

      Create a group of options with common parameters.

    option TITLE => \%SPECIFICATION

    option TITLE => (type => '+My::Type', ...)

    option TITLE => (type => 'Getopt::Yath::Option::Type', ...)

    option TITLE => (type => 'Type', ...)

      This is used to define a single option. You must specify an option
      NAME and 'type', which must be a valid Getopt::Yath::Option subclass.

      The TILE is used to produce default values for the 'field' and 'name'
      fields, both of which can be specidied directly if the automatic
      values ar enot sufficient. 'field' gets the value of title with
      dashes replaced by underscrores. 'name' gets the value of title with
      underscores replaced with dashes.

      Most of the time you can just list the type as the part after the
      last :: in Getopt::Yath::Option::TYPE. You can also specify
      Getopt::Yath::Option::TYPE or Getopt::Yath::Option::TYPE::SubType
      directly. However if you need to use a module that is not in the
      Getopt::Yath::Option:: namespace you will need to prefix the module
      with a + to indicate that.

          $export{option_post_process} = sub {
              my $cb           = pop;
              my $weight       = shift // 0;
              my ($applicable) = @_;
      
              $applicable //= $common[-1]->{applicable} if @common;
      
              croak "You must provide a callback coderef" unless $cb && ref($cb) eq 'CODE';
      
              $instance->_post([caller()], $weight, $applicable, $cb);
          };

OPTION TYPES AND SPECIFICATIONS

 REQUIRED WITH NO DEFAULTS

    title

      This is the first argument to option(). It is used to build the
      default values for both field and name.

    group => "group_name"

      Name of the field to use in the options hash under which the option
      will be listed:

      $parsed->{options}->{$group}->{$field_name} = $val

    type => 'TypeName'

    type => 'Getopt::Yath::Option::TypeName'

    type => '+My::Custom::Type'

      This must be a valid Getopt::Yath::Option subclass:

      Scalar

	Takes a scalar value. A value is required. Can be used as --opt VAL
	or --opt=val. --no-opt can be used to clear the value.

      Bool

	Is either on or off. --opt will turn it onn. --no-opt will turn it
	off. Default is off unless the default is parameter is provided.

      Count

	Is an integer value, default is to start at 0. --opt increments the
	counter. --no-opt resets the counter. --opt=VAL can be used to
	specify a desired count.

      List

	Can take multiple values. --opt VAL appends a value to the list.
	--no-opt will empty the list. If a split_on parameter is provided
	then a single use can set multiple values. For example if split_on
	is set to , then --opt foo,bar is provided, then foo and bar will
	both be added to the list.

      Map

	Expects all values to be key=value pairs and produces a hashref.
	--opt foo=bar will set $h{foo} = 'bar'. If a split_on parameter is
	provided then a single use can set multiple values. For example if
	split_on is set to , then --opt foo=bar,baz=bat is provided, then
	the result will have $h{foo} = 'bar'; $h{baz} = 'bat'.

      Auto

	This type has an 'autofill' value that is used if no argument is
	provided to the parameter, IE --opt. But can also be given a
	specific value using --opt=val. It DOES NOT support --opt VAL which
	will most likely result in an exception.

      AutoList

	This is a combination of 'Auto' and 'List' types. The no-arg form
	--opt will add the default values(s) to the list. The --opt=VAL
	form will add additional values.

      AutoMap

	This is a combination of 'Auto' and 'Map' types. The no-arg form
	--opt will add the default key+value pairs to the hash. The
	--opt=KEY=VAL form will add additional values.

 REQUIRED WITH SANE DEFAULTS

    field => "field_name"

      Name of the field to use in the group hash for the result of parsing
      arguments.

      $parsed->{options}->{$group}->{$field_name} = $val

      Default is to take the title value and replace any dashes with
      underscores.

    name => "option-name"

      Primary name for the option --option-name.

      Default is to take the title value and replace any underscores with
      dashes.

    trace => [$caller, $file, $line]

      This normally resolves to the place option() was called. You can
      manually override it with a custom value, but you should rarely ever
      need to.

    category => "Human Readable documentation category"

      When producing POD or command line documentation, options are put
      into "categories" which should be the human readabvle version of the
      group field.

      Default is "NO CATEGORY - FIX ME".

    description => "Explanation of what the option controls"

      Document what the option controls or does.

      Default is 'NO DESCRIPTION - FIX ME'.

 OPTIONAL

    short => 's'

      Specify a short flag to use. This is how you provide single-dash
      single-letter options.

      -s

	If no argument is required this form is available.

      -s=VAL

	If an argument is allowed this form is available

      -sVAL

	If an argument is allowed, and this form is not directly disabled
	by the type (Types can override allows_shortval() to return false
	to forbid this form. Currently Getopt::Yath::Option::Bool and
	Getopt::Yath::Option::Count disable this form.

      -sss

	So far only the Getopt::Yath::Option::Count type makes use of this.
	It allows you to add the flag multiple times after a single dash to
	increment the count.

    alt => \@LIST

    alt => ['alt1', 'alt2']

      Specify alternate or alias names that can be used to set or toggle a
      field.

      --alt1 --alt2 foo

    prefix => "a-prefix"

      Specify a prefix to attach to the name, and to any alternate names.
      This is mainly useful when specifying an option group:

          option_group {prefix => 'foo'} => sub {
              option bar => (
                  type => "Bool",
              );
          };

      This would then be used as --foo-bar

    module => 'My::Module'

      Specify the module the argument should be associated with. This
      defaults to the caller, so usually you do not need to specify it.

      This is mainly used in the case of plugins we only want to load if
      the option is used.

    no_module => BOOL

      Default is 0. When this is set to true the module name is not used.

    applicable => sub { my $options = shift; ... ? 1 : 0 }

      This can be used to dynamically show/hide options. When this returns
      false the option will not be available.

    initialize => $scalar

    initialize => sub { ... }

      Initialize the value to this before any arguments are parsed. This is
      mainly used so that Getopt::Yath::Option::Map can start with an empty
      hash, and Getopt::Yath::Option::List can be initialized to an empty
      arrayref.

      This can be a simple scalar (string or number, not a reference), or
      it may be a codeblock that returns anything you want. Only 1 item
      should be returned, extra values will result in undefined behavior.
      For a map this should return an empty hashref, for a list it should
      return an empty arrayref.

    clear => $scalar

    clear => sub { ... }

      Similar to initialize, but this is used when clearing the value. For
      things like 'Map' this should return a hashref, etc.

    default => $scalar

    default => sub { ... }

      Set a default to use if no value is provided at the command line.

      This can be a simple scalar (string or number, not a reference), or
      it may be a codeblock that returns anything you want.

      Most options will only accept a single default value.
      Getopt::Yath::Option::Map and Getopt::Yath::Option::List support a
      list of defaults for setting key/value pairs, or adding items to an
      array.

      These are valid for anything:

          default => 'foo',
          default => 123,
          default => sub { "hi" }

      This is valid for an Getopt::Yath::Option::Map:

          default => sub { return ('foo' => 'bar') }

      This is valid for a Getopt::Yath::Option::List:

          default => sub { return (1, 2, 3, 4) }

    autofill => $scalar

    autofill => sub { ... }

      This is used for Getopt::Yath::Option::Auto and similar. This is the
      value used if the command line option is provided, but no value is
      provided with it.

      This can be a simple scalar (string or number, not a reference), or
      it may be a codeblock that returns anything you want.

      Most options will only accept a single autofill value.
      Getopt::Yath::Option::Map and Getopt::Yath::Option::List support a
      list of autofill data for setting key/value pairs, or adding items to
      an array.

      These are valid for anything:

          autofill => 'foo',
          autofill => 123,
          autofill => sub { "hi" }

      This is valid for an Getopt::Yath::Option::Map:

          autofill => sub { return ('foo' => 'bar') }

      This is valid for a Getopt::Yath::Option::List:

          autofill => sub { return (1, 2, 3, 4) }

    normalize => sub { my ($input) = @_; ...; return $output }

      If you wish to normalize or transform a value then you use this hook.
      The sub will get the option and the input value as its arguments. You
      should return the new value to set, or the input value if it does not
      need to change.

    trigger => sub { my ($opt, %params) = @_; ... }

      This will be called any time the option is parsed from the command
      line, or whenever the command line clears the option.

      NOTE: It will not run when initial, autofill, or default values are
      set.

      The %params passed into the sub look like this:

          (
              # If this trigger is called because the value is cleared via --no-OPT:
              action => 'clear',
              val    => undef,
      
              # If a value is set because of --opt being parsed:
              action   => 'set',
              val      => [...],
              ref      => $ref,
              state    => $state,
              options  => $self,
              settings => $settings,
              group    => $group,
          );

      Note that val is always passed in as an arrayref. For simple scalar
      type options this will only ever have 1 value. For list or map types
      it may have multiple values, also note that for such types the
      trigger will only see the newly added values in the 'val' arrayref,
      not the values already included, which is important as list and map
      types can be built over several assignments.

    from_env_vars => \@LIST

      A list of environment variables that will be used to populate the
      option's initial value. These will be checked in order, the first one
      that is set is the one that will be used, others will not be checked
      once a value is found. This will prevent the default value from being
      used, but using the option on the command line will override it.

      Note: that an environment variable can be prefixed with a ! to
      indicate the value should be boolean-inverted. This means that an
      option like quiet can have from_env_vars => ['!VERBOSE'] to be set to
      true when the VERBOSE env var is false. This also works when setting
      a variable, so you could have set_env_vars => ['!VERBOSE'].

    clear_env_vars => \@LIST

      A list of enviornment variables to clear after the options are all
      populated. This is useful if you want to use an env var to set an
      option, but want to make sure no child proceses see the environemnt
      variable.

    set_env_vars => \@LIST

      A list of environment variables that will be set to the value of this
      option (if it is set) when argument processing is complete.

      Note: This is only supported in types that have a single value, maps
      and lists are not supported.

      Note: that an environment variable can be prefixed with a ! to
      indicate the value should be boolean-inverted. This means that an
      option like quiet can have from_env_vars => ['!VERBOSE'] to be set to
      true when the VERBOSE env var is false. This also works when setting
      a variable, so you could have set_env_vars => ['!VERBOSE'].

    short_examples => \@LIST

    short_examples => ['', 'ARG', '=ARG']

    short_examples => [' ARG', '=ARG']

      Override the default list of arguments when generating docs. This is
      used for the short form (single dash followed by a single letter and
      then a value -Ilib, -I lib, -I=lib, -v, -vv, -vvv...) documentation.

    long_examples => \@LIST

    long_examples => ['', '=ARG']

    long_examples => [' ARG', '=ARG']

      Override the default list of arguments when generating docs. This is
      used for the long form (double-dash and option name and then a value
      --include, --include=lib, --include lib) documentation.

SOURCE

    The source code repository for Getopt-Yath can be found at
    http://github.com/Test-More/Getopt-Yath/.

MAINTAINERS

    Chad Granum <exodist@cpan.org>

AUTHORS

    Chad Granum <exodist@cpan.org>

COPYRIGHT

    Copyright Chad Granum <exodist7@gmail.com>.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    See http://dev.perl.org/licenses/

