NAME
    Getopt::Again - Yet another attempt at a universal Getopt tool.

DESCRIPTION
    Getopt tool that takes short form "-abc" and/or long form "--alpha"
    options. Options may be boolen, or accept values. Values can be
    specified via "--foo val" or "--foo=val" forms. Can also use a regex to
    slurp up matching options. Ability to auto-generate usage and help
    strings for you when desired.

ANOTHER GETOPT TOOL!!!!
    Yeah... Sorry about that. Here is a relevant XKCD:
    <http://xkcd.com/927/>.

    I have not yet found a Getopt module that works the way I would like. It
    may exist, but the author is doing a poor job of reaching me and my
    searches have failed.

    I went a long time refusing to add yet more clutter to the Getopt
    namespace, but I am tired of writing custom parsing for options every
    time I write a script. So here it is, my way, and I don't care if nobody
    ever uses it, I won't force you.

SYNOPSYS
  SCRIPT
        use Getopt::Again enable_help => 1; # Default is 0

        opt_bools  qw/alpha beta/;  # Quickly define some boolean options
        opt_lists  qw/gamma zeta/;  # Quickly define some options that accept multiple args
        opt_params qw/foo bar/;     # Quickly define some options that accept a single arg
        opt_paths  qw/origin dest/; # Quickly define some options that take directory paths
        opt_files  qw/config/;      # Quickly define some options that take file paths

        # All arguments to opt_add are optional except the name.
        opt_add my_opt => (
            type        => 'string',           # Or 'bool', 'regex', 'path', 'file'
            list        => 1,                  # True to take multiple values
            default     => 'stuff',            # Default value
            example     => " 'a string'",      # Example value, for help/usage
            alias       => [ 'the_opt', 'm' ], # Alternate names
            process     => sub { ... },        # Can also be a validation regex
            description => "My option ..."     # For help/usage
            split_on    => ",",                # Split values (list only)
            regex       => qr/^foo-(.+)$/,     # Match options like this, use the capture for value
        );

        my $usage = opt_usage();
        my $help  = opt_help();

        # Get the options and args from @ARGV. @ARGV is not altered
        my (%opts, @args) = opt_parse(@ARGV);

  OOP
        use Getopt::Again();

        my $ga = Getopt::Again->new(enable_help => 1);

        $ga->add('my_opt' => (
            type        => 'string',           # Or 'bool', 'regex', 'path', 'file'
            list        => 1,                  # True to take multiple values
            default     => 'stuff',            # Default value
            example     => " 'a string'",      # Example value, for help/usage
            alias       => [ 'the_opt', 'm' ], # Alternate names
            process     => sub { ... },        # Can also be a validation regex
            description => "My option ..."     # For help/usage
            split_on    => ",",                # Split values (list only)
            regex       => qr/^foo-(.+)$/,     # Match options like this, use the capture for value
        ));

        my $usage = $ga->usage_string();
        my $help  = $ga->help_string();

        # Get the options and args from @ARGV, @ARGV is not altered
        my (%opts, @args) = $ga->parse(@ARGV);

PARSING RULES
    A single dash denotes 1-character options, so "-xyz" is seen as the x,
    y, and z options.
            command -xyz

            command -x -y -z

            command --xerxes --yolk --zebra

    The final option in a set of single dash options may have an argument.
            command -xf thing

            command -xyzf thing

    Double dash denotes long form "--foo" is seen as the 'foo' option.
            command --thing

    Options that accept arguments may take the "--opt=val" or "--opt val"
    forms.
            command --thing=val

            command --thing val

    Options that can have a list of values may specify a delimiter, and/or
    can be listed multiple times.
            command --thing x --thing y --thing z

            command --thing x,y,z

            command --thing x.y.z

    When it is not ambiguous, you may use the first character of the long
    form in a short form.
        These work:

            command --xerxes
            command -x

        This would not:

            command --xerxes
            command --xandu
            command -x # Nope! ambiguous (unless -x is defined directly)

    End of params is "--" as expected, nothing after this will be parsed,
    instead they are added to the list of arguments.
            command -xyz -- --this_is_not_an_opt --this_is_an_arg

EXPORTS
    $ga = opt_meta()
        Get the underlying Getopt::Again object.

    opt_bools(qw/awake alive/)
        Quickly define some boolean options.

    opt_lists(qw/friends family/)
        Quickly define some list options.

    opt_params(qw/name age/)
        Quickly define some options that take strings.

    opt_paths(qw/origin dest/)
        Quickly define some options that take paths (they must exist).

    opt_files(qw/input config/)
        Quickly define some options that take files (they must exist).

    opt_add(NAME, %OPTIONS)
        Add an option.

    $usage = opt_usage()
    opt_usage($set)
        Get or set the usage string (returns "$0 $string", do not include $0
        when setting).

    $help = opt_help()
        Get the help string.

    ($opts, $args) = opt_parse(...)
        Parse a parameters (@ARGV is the usual argument).

        An exception will be thrown if an unknown option is specified.

        $opts is a hashref, $args is an arrayref.

    opt_use_help()
        Enable the --help and -h options.

OPTION PROPERTIES
    type
        Values may be one of: 'string', 'bool', 'regex', 'file', 'path'.

        If none is specified it is guessed. Names with more than 1 character
        default to string, named with 1 character only default to bool.

    list
        True or false. When true the option will always be an arrayref
        containing 0 or more values.

    default
        Specify the default value when none was specified. For bools this
        gets normalized to true or false. For lists the default is a new
        empty array.

    example
        Example for documentation, usually an example value prefixed with
        either a space or equal sign:

            example => ' foo',

        or

            example => '=foo',

    process
        Post-processing on the value. If this is a regex than an exception
        will be thrown for any value that does not match.

        The value may also be a coderef. For the coderef $_ will be set to
        the value being processed. The value will also be passed in as the
        only argument. Whatever the coderef returns will replace the value,
        so this is a hook to allow you to modify the value.

    description
        Provide a long description of the option for the help string.

    split_on
        Specify a delimiter for list options.

    regex
        Specify a regex to be used to identify parameters. Use this if you
        want something like "enable-*" to be captured.

            list  => 1,
            regex => qr/^enable-(.*)$/,

        This will match all the following:

            --enable-food
            --enable-protection

        In these cases the value will be set to the first capture group, so
        in this case:

            [
                'food',
                'protection'
            ]

        If there is no capture $1, then the remaining string after the match
        $' will be used.

OBJECT METHODS
    $ga->opt_spec($name)
        Get the specification for an option.

    $ga->add($name => %properties)
        Add an option

    ($opts, $args) = $ga->parse(@ARGV)
        Parse a parameters (@ARGV is the usual argument).

        An exception will be thrown if an unknown option is specified.

        $opts is a hashref, $args is an arrayref.

    $ga->usage_string
        Get or set the usage string (returns "$0 $string", do not include $0
        when setting).

    $ga->help_string
        Get the help string

    $ga->enable_help
        Enable the help ("--help" and "-h") tools.

SEE ALSO
    Everything in the massive Getopt namespace.

    On second thought, don't, you do not have that much time.

AUTHORS
    Chad Granum exodist7@gmail.com

COPYRIGHT
    Copyright (C) 2014 Chad Granum

    Getopt-Again is free software; Standard perl license (GPL and Artistic).

    Getopt-Again is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the license for
    more details.