NAME
    Getopt::Awesome - Let your modules define/export their own arguments

DESCRIPTION
    First of, this module was very inspired in the Getopt::Modular CPAN
    package however at the moment of using it I found it was giving me
    "more" of what I was looking so I thought I could borrow some ideas of
    it, make it lighter and add some of the features/functionalities I was
    looking for and so this is the result: a module I've been using every
    day for all my perl scripts and modules, though would be nice to give it
    to the Perl community.

    Now, this module is handy if you want to give your modules the freedom
    of definining their own "getopt options" so next time they get called
    (or *used*) the options will be available in the form of arguments
    (--foo, --bar).

    Another feature of this module is that when user asks for help (-h or
    --help) a usage will be printed by showing all the options available by
    the current perl script and by all the modules in use.

    All options are prefixed by the package name in lowercase where
    namespace separator (::) gets replaced by a dash (-), so --help will
    return:

        --foo-bar-option   Description.
        --foo-bar-option2  Description 2.

    and so on..

    See the SYNOPSYS section for examples.

    Notes:

    *   The use of short aliases is not supported for options defined in
        modules, this feature (provided by Getopt) is only available in the
        main script (.pl)

    *   In your perl script (.pl) remember to call parse_opts otherwise the
        values of the options you request might be undef, empty or have
        their default values.

    *   *Remember:* ARGV is ONLY parsed when parse_opt is called.

SYNOPSYS
        package Your::Package;

        use Getopt::Awesome qw(:common);
        define_option('foo=s', 'Foo bar');
        # ...or...

        define_options(
            ('foo=s', 'Foo'),
            ('bar=s', 'Bar'));

        parse_opts();
        my $foo_val = get_opt('option_name', 'Default value');

AUTHOR
    Pablo Fischer (pablo@pablo.com.mx).

COPYRIGHT
    Copyright (C) 2009 by Pablo Fischer

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

FUNCTIONS
    define_options (@options)
            use Getopt::Awesome;
            Getopt::Awesome qw(:common);

            define_options(
                ('option_name', 'Option description')
            );

        It defines the given options for the package/script that is making
        *the call*.

        Please note the options defined in the current caller package are
        not shared with other modules unless it's explicitly specified (see
        *get_opt()*).

        Each array item should consist at least of 1 item with a max of 2.
        The first parameter should be the option name while the second one
        (optional) is the description.

        Some notes about the option name, the first item of every array:

        *   It's a required parameter.

        *   It accepts any of the "Getopt::Long" option name styles (=s, !,
            =s@, etc).

    define_option( $name, $description )
            use Getopt::Awesome qw(:common);

            define_option('option_name', 'Description');

        It calls the *define_options* subroutine for adding the given option
        (*$name*) with an optional description (*$description*).

        Please refer to the documentation of "define_options" for a more
        complete description about it, but basically some notes:

        *   The option name is a required parameter

        *   The option accepts any of te "Getopt::Long" option name styles.

    get_opt($option_name, $default_value)
            use Getopt::Awesome qw(:common);

            my $val = get_opt('option_name', 'Some default opt');
            # Gets the 'foome' option value of Foo::Bar module and defaults to 'foobie'
            my $val = get_opt('Foo::Bar::foome', 'foobie');

        It will return the value of the given option, if there's no option
        set then undefined will be returned.

        Please note that if the option is set to expect a list you will
        receive a list, same for integer, strings, booleans, etc. Same as it
        happens with the Getopt::Long.

    set_opt ($option_name, $value)
            use Getopt::Awesome qw(:common);

            set_opt('option_name', 'Value');
            # Sets the 'foome' option value to foobie of the Foo::Bar package.
            set_opt('Foo::Bar::foome', 'foobie')

        Sets the given value to the given option.

    parse_opts()
        This subroutine should never be called directly unless you want to
        re-parse the arguments or that your module is not getting called
        from a perl script (.pl).

        In case you want to call it:

            use Getopt::Awesome qw(:common);

            parse_opts();

    usage()
        Based on all the current options it returns a nice and helpful
        'guide' of all the available options.

        Although the usage gets called directly if a -h or --help is passed
        and also if no_usage is set you can call it directly:

            use Getopt::Awesome qw(:all);

            usage();