/ 
Getopt-Yath-2.000011
/ README.md

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        => { ':{' => '}:' },                                     # Arguments between the :{ and }: will be captured into an arrayref, they can be used as option values, or stand-alone
);

$parsed is a Getopt::Yath::State object:

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

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

OPTION TYPES AND SPECIFICATIONS

REQUIRED WITH NO DEFAULTS

REQUIRED WITH SANE DEFAULTS

OPTIONAL

SOURCE

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

MAINTAINERS

AUTHORS

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/