Getopt::AsDocumented - declare options as pod documentation
=head1 Options ... =item -w, --what WHAT =cut sub main { my (@args) = @_; my $opt = Getopt::AsDocumented->process(\@args) or return; my $what = $opt->what; ... }
This module allows you to declare your program's command-line options as pod documentation. It provides syntax to declare types and defaults in a way which is also readable as documentation.
Note: This is built on Getopt::Base and some advanced features are still growing. Your help is welcome.
Loads the pod from your current file and processes the command-line arguments.
my $opt = Getopt::AsDocumented->process(\@args) or return;
If an option is followed by a word, it requires an opterand.
=item --foo FOO
Otherwise, it is a simple flag (boolean) option
=item --foo
Each boolean option will automatically generate a '--no-' form which negates it. You may choose to mention this and/or link aliases to it.
=item --foo Sets the fooness. =item -x, --ex-foo, --no-foo
Non-boolean options may be typed as strings, numbers, or integers. The type is included in parenthesis after the option spec. If the type is not mentioned, it defaults to string.
string
An integer.
=item --foo FOO (integer)
A floating-point number.
=item --foo FOO (number)
A string. This is the default, but may be included for clarity.
=item --foo FOO (string)
Any non-boolean option can take one of the following forms.
An option followed by a simple word means that only one value is assigned to it (if the user repeats it, a prior value is overwritten.)
A HASH option is followed by something of the form \w+=.*. Each opterand is treated as a $key=$value pair.
\w+=.*
=item --foo BAR=BAZ
A LIST option is followed by another mention of itself within [] brackets with an ellipsis to indicate optional additional elements.
=item --foo FOO [--foo ...]
If a list option requires an explicit type, this must be included after the bracketed text.
=item --foo FOO [--foo ...] (integer)
An option's default may be set by the string "DEFAULT: " at the beginning of a paragraph. The remainder of that paragraph contains the default value.
=item --foo FOO The setting for foo. DEFAULT: bar
Any leading whitespace after the ':' is removed.
A single leading backslash (if present) will be removed and the rest of the string will be treated as a literal.
A boolean default may be "NO". Without a value, a boolean will default to undef. Anything true will be translated to '1'.
=item --foo Whether to foo or not. DEFAULT: yes. Use --no-foo to disable this.
The strings "no" or "false" may also be used as "0".
If the default is enclosed with braces ({}), it is interpreted as a block of code. For literal braces, use a leading backslash.
=item --input FILENAME Input file. DEFAULT: {File::Fu->home + 'input.txt'}
Loads the user's configuration file. All of the values from the configuration will be loaded into the options object before any options from the command-line are processed.
$go->config_file_handler;
$self->load_config_file($file);
Wraps the super method in order to load the config file.
$obj = $self->make_object;
Accessor.
my $handler = $go->handler;
Prints the version from your handler/caller()'s package.
$go->version_handler;
Sets the quit flag.
Prints a help message based on the USAGE and OPTIONS sections from your pod. Uses the first sentence from each =item section, or alternatively: =for help content found within the =item section.
=item
=for help
$go->help_handler;
my $go = Getopt::AsDocumented->new(%settings);
$self->_init(%setup);
Eric Wilhelm @ <ewilhelm at cpan dot org>
http://scratchcomputing.com/
If you found this module on CPAN, please report any bugs or feature requests through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
If you pulled this development version from my /svn/, please contact me directly.
Copyright (C) 2009 Eric L. Wilhelm, All Rights Reserved.
Absolutely, positively NO WARRANTY, neither express or implied, is offered with this software. You use this software at your own risk. In case of loss, no person or entity owes you anything whatsoever. You have been warned.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Getopt::AsDocumented, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Getopt::AsDocumented
CPAN shell
perl -MCPAN -e shell install Getopt::AsDocumented
For more information on module installation, please visit the detailed CPAN module installation guide.