NAME
    Declare::Opts - Simple and Sane Command Line Argument processing

DESCRIPTION
    Declare-Opts is a sane and declarative way to define and consume command
    line options. Any number of dashes can be used, it is not picky about
    -opt or --opt. You can use '-opt value' or '-opt=value', it will just
    work. Shortest unambiguous substring of any opt name can be used to
    specify the option.

WHY NOT GETOPT?
    The Getopt ecosystem is bloated. Type getopt into search.cpan.org and
    you will be given pages and pages of results. Normally this would be a
    good thing, the issue is that each package provides specialised
    functionality, and most cannot operate together.

    The Getopt ecosystem is also very crufty. Getopt is an old module that
    uses many outdated practices, and an even more outdated interface.
    Unfortunately this has been carried forward into the new getopt modules,
    possibly for compatability/familiarity reasons.

    Declare::Opts is a full on break from the Getopt ecosystem. Designed
    from scratch using modern practices and interface design.

SYNOPSIS
  DECLARATIVE
    Code:

        #!/usr/bin/env perl
        use Declare::Opts;

        # Define a simple opt, any value works:
        opt 'simple';

        # Define a boolean opt
        opt with_x => ( bool => 1 );

        # Define a list
        opt items => ( list => 1 );

        # Other Options
        opt complex => (
            alias       => $name_or_array_of_names,
            default     => $val_or_sub,
            check       => $bultin_regex_or_sub,
            transform   => sub { my $opt = shift; ...; return $opt },
            description => "This is a complex option",
        );

        # Get the (opts => descriptions) hash, useful for a help() function
        my $info = opt_info();

        #########################
        # Now process some opts #
        #########################

        my ( $args, $opts ) = parse_opts( @ARGV );

        # $args contains the items from @ARGV that are not specified opts (or their
        # values)
        # $opts is a hashref containing the opts and their values.

    Command Line:

        ./my_command.pl -simple simple_value -with_x --items "a,b, c"

    The shortest unambiguous string can be used for each parameter. For
    instance we only have one option defined above that starts with 's',
    that is 'simple':

        ./my_command.pl -s simple_value

  OBJECT ORIENTED
        require Declare::Opts;

        # Create
        my $opts = Declare::Opts->new( %opts );

        # Add an opt
        $opts->opt( $name, %config );

        # Get info
        my $info = $opts->info;

        # Parse some opts
        my ( $args_array, $opts_hash ) = $opts->parse( @ARGV );

META OBJECT
    When you import Declare::Opts a meta-object is created in your package.
    The meta object can be accessed via the OPTS_META() method/function.
    This object is an instance of Declare::Opts and can be manipulated just
    like any Declare::Opts object.

EXPORTS
    opt( $name, %config );
    opt name => ( %config );
        Define an option

    my $info = opt_info();
        Get a ( name => description ) hashref for use in help output.

    my ( $args, $opts ) = parse_opts( @OPTS );
        Parse some options. $list contains the options leftovers (those that
        do not start with '-'), $opts is a hashref containing the values of
        all the dashed opts.

METHODS
    $class->new( %opts );
        Create a new instance.

    my $class = $opts->class;
        If the object was created as a meta-object this will contain the
        class to which it applies. When created directly this will always be
        empty.

    $opts->opt( $name, %config );
        Define an option

    my $info = $opts->info();
        Get a ( name => description ) hashref for use in help output.

    my ( $args_array, $opts_hash ) = $opts->parse( @OPTS );
        Parse some options. $list contains the options leftovers (those that
        do not start with '-'), $opts is a hashref containing the values of
        all the dashed opts.

OPTION PROPERTIES
    alias => $name
    alias => [ $name1, $name2 ]
        Set aliases for the option.

    list => $true_or_false
        If true, the option can be provided on the command line any number
        of times, and comma seperated lists will be split for you.

    bool => $true_or_false
        If true, the option does not require a value and turns the option on
        or off. A value can be specified using the '--opt=VAL' format.
        However '--opt val' will not treat 'val' as the option value.

    default => $scalar
    default => sub { ... }
        Set the default value. If the opt is not specified on the command
        line this value will be used. If the value is not a simple scalar it
        must be wrapped in a code block.

    check => 'builtin'
    check => qr/.../
    check => sub { my $val = shift; ...; return $bool }
        Used to validate option values. Can be a coderef, a regexp, or one
        of these bultins:

            'number'    The value(s) must be numeric (only contains digit characters)
            'file'      The value(s) must be a file (uses -f check)
            'dir'       The value(s) must be a directory (-d check)

    transform => sub { my $orig = shift; ...; return $new }
        Function to transform the provided value into something else.
        Applies to eahc item of a list when list is true.

    description => $description_string
        Used to describe an option, useful for help() output.

AUTHORS
    Chad Granum exodist7@gmail.com

COPYRIGHT
    Copyright (C) 2012 Chad Granum

    Declare-Opts is free software; Standard perl licence.

    Declare-Opts 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.