NAME
    OptArgs - integrated argument and option processing

VERSION
    0.0.1 Development release.

SYNOPSIS
        #!/usr/bin/env perl
        use OptArgs;

        opt quiet => (
            isa     => 'Bool',
            alias   => 'q',
            comment => 'output nothing while working',
        );

        arg item => (
            isa      => 'Str',
            required => 1,
            comment  => 'the item to paint',
        );

        my $ref = optargs;

        print "Painting $ref->{item}\n" unless $ref->{quiet};

DESCRIPTION
    OptArgs processes command-line *options* and *arguments* for Perl
    scripts. This is in contrast to anything anything in the Getopt::*
    namespace that deals with command options only.

    The following model is assumed by OptArgs for command-line applications:

    Command
        The program name - i.e. the filename be executed by the shell.

    Options
        Options are parameters that affect the way a command runs. They are
        generally not required to be present, but that is configurable. All
        options have a long form prefixed by '--', and may have a single
        letter alias prefixed by '-'.

    Arguments
        Arguments are positional parameters that that a command needs know
        in order to do its work. Confusingly, arguments can be optional. The
        last argument defined may be *greedy*: it can consume everything
        else left on the command line.

    Sub-commands
        From a users point of view sub-command arguments and options are
        indistinguishable from arguments and options to the Command.
        Subcommand options and arguments are defined in the same place as
        Command arguments and options. However from a code perspective they
        are implemented as separate, stand-alone programs to be called by a
        dispatcher.

  Simple Scripts
    To demonstrate lets put the code from the synopsis in a file called
    "paint" and observe the following interactions from the shell:

        $ ./paint
        usage: paint ITEM

          arguments:
            ITEM          the item to paint

          options:
            --quiet, -q   output nothing while working

    As you can see a usage message is generated automatically. The
    "optargs()" function parses the command line according to the
    declarations and returns a single HASH reference, easily interpolated
    inside strings.

        $ ./paint house
        Painting house

    Because OptArgs knows about arguments it can detect more errors than an
    option-only processing module:

        $ ./paint house car
        error: unexpected option or argument: car

    The usage message is constructed based on option and argument
    attributes. If we add another argument:

        arg colour => (
            isa     => 'Str',
            default => 'blue',
            comment => 'the colour to use',
        );

    And then check the usage again:

        $ ./paint
        usage: paint ITEM [COLOUR]

          arguments:
            ITEM          the item to paint
            COLOUR        the colour to use

          options:
            --quiet, -q   output nothing while working

    It can be seen that the non-required argument "colour" appears inside
    square brackets indicating its optional nature. Three dots (...) are
    postfixed to greedy arguments. The order in which options and arguments
    (and also sub-commands: see below) are defined is the order in which
    they appear in usage messsages.

  Sub-Command Scripts
FUNCTIONS
    The following functions are exported (by default except for "dispatch")
    using Exporter::Tidy.

    opt( $name, %parameters )
        Define a Command Option. If $name contains underscores then aliases
        with the underscores replaced by dashes (-) will be created. The
        following parameters are accepted:

        isa Required. Is mapped to a Getopt::Long type according to the
            following table:

                 optargs         Getopt::Long
                ------------------------------
                 'Bool'          '!'
                 'Counter'       '+'
                 'Str'           '=s'
                 'Int'           '=i'
                 'Num'           '=f'
                 'ArrayRef'      's@'
                 'HashRef'       's%'

        comment
            Required. Used to generate the usage/help message.

        default
            The value set when the option is not used.

            If this is a subroutine reference it will be called with a
            hashref containg all option/argument values after parsing the
            source has finished. The value to be set must be returned, and
            any changes to the hashref are ignored.

        alias
            A single character alias.

        ishelp
            When true flags this option as a help option, which when given
            on the command line results in a usage message exception. This
            flag is basically a cleaner way of doing the following in each
            (sub) command:

                my $opts = optargs;
                if ( $opts->{help} ) {
                    die usage('help requested');
                }

    arg( $name, %parameters )
        Define a Command Argument with the following parameters:

        isa Required. Is mapped to a Getopt::Long type according to the
            following table:

                 optargs         Getopt::Long
                ------------------------------
                 'Str'           '=s'
                 'Int'           '=i'
                 'Num'           '=f'
                 'ArrayRef'      's@'
                 'HashRef'       's%'
                 'SubCmd'        '=s'

        comment
            Required. Used to generate the usage/help message.

        required
            Set to a true value when the caller must specify this argument.
            Can not be used if a 'default' is given.

        default
            The value set when the argument is not given. Can not be used if
            'required' is set.

            If this is a subroutine reference it will be called with a
            hashref containg all option/argument values after parsing the
            source has finished. The value to be set must be returned, and
            any changes to the hashref are ignored.

        greedy
            If true the argument swallows the rest of the command line. It
            doesn't make sense to define any more arguments once you have
            used this as they will never be seen.

        fallback
            If "isa" is a "SubCmd" this option (when set) will stop the
            generation of the usage message when the argument is not found
            as a sub-command. The current command will be called instead.
            This option when set must be a HASH reference containing "name"
            and "comment" key/value pairs, which are only used in usage
            messages.

    optargs( [ @argv ] ) -> HashRef
        Parse @ARGV by default (or @argv when given) and returns a hashref
        containing key/value pairs for options and arguments *combined*. An
        error / usage exception is thrown if an invalid combination of
        options and arguments is given.

        Note that @ARGV will be decoded into UTF-8 (if necessary) from
        whatever I18N::Langinfo says your environment encoding is.

    usage( [$message] ) -> Str
        Returns a usage string prefixed with $message if given.

    subcmd( @cmd, $description )
        Create a sub-command. After this function is called further calls to
        "opt" and "arg" define options and arguments respectively for the
        sub-command.

    dispatch( $method, $rootclass, [ @argv ] )
        Parse @ARGV (or @argv if given) and dispatch to the method $method
        in the appropriate package name constructed from $rootclass.

SEE ALSO
    Getopt::Long, Exporter::Tidy

SUPPORT & DEVELOPMENT
    This distribution is managed via github:

        https://github.com/mlawren/p5-OptArgs/tree/devel

    This distribution follows the semantic versioning model:

        http://semver.org/

    Code is tidied up on Git commit using githook-perltidy:

        http://github.com/mlawren/githook-perltidy

AUTHOR
    Mark Lawrence <nomad@null.net>

LICENSE
    Copyright 2012 Mark Lawrence <nomad@null.net>

    This program is free software; you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by the
    Free Software Foundation; either version 3 of the License, or (at your
    option) any later version.

