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();