NAME
Getopt::Auto - Framework for command-line applications
SYNOPSIS
Not very magical:
use Getopt::Auto
(
[ "--wibble", "Wibble to standard output" ],
[ "--wobble", "Wobble to standard output", \&Something::Wobble ]
[ "--wubble", "Wubble to standard output",
"We're not entirely sure what a wubble is, but this option does it.",
\&Something::Wubble ]
);
our $VERSION = "1.0";
Now yourprogram --wibble foo
will call wibble("foo")
.
Pretty magical:
use Getopt::Auto; # We'll work it out from the POD.
DESCRIPTION
Unix command line applications, rather than simple filters, are pretty unpleasant to write; as well as actually writing the functionality, there's the boring parsing of the command line arguments and so on. Even with Getopt::Long
or equivalent, you still have to dispatch the appropriate commands to the right subroutines, write a --help
and --version
handler, and so on. This module abstracts out that code, leaving you free just to concentrate on the functional part.
In the "non-magical" mode, you provide a list of lists. Each element contains the name of the command and a short help message; this may be followed by a longer help message, to be given when something like --help foo
is passed, and/or a code reference for the function to be called. If there isn't a code reference given, we assume it will be &main::foo
. If your command name contains hyphens, they will be flattened to semicolons: --foo-bar
will call foo_bar
.
Getopt::Auto
is happy for you to use "long" (--gnu-style
), "short" (-oldstyle
) or even "bare" command names, (myprogram edit foo.txt
, CVS-style) on the condition that you are consistent. Additionally, if you use bare or long style commands, then any short options passed before a command name will be sent into %main::options
. For instance, given
use Getopt::Auto (
"edit" => "open a file for editing",
"export" => "write out the data as an ASCII file"
);
yourprog -vt edit -x foo.txt
will perform the following:
$main::options{v} = 1
$main::options{t} = 1
edit("-x", "foo.txt");
HELP AND VERSION
Getopt::Auto
automatically provides help
and version
commands, following your chosen style (long, short or bare).
help
lists the commands available and the short help messages. If a help command
is given for a command name with a long message, the longer message will be printed instead.
version
displays your program name, plus $main::VERSION
. This means you must set our $VERSION = "whatever"
in your application!
MAGICAL MODE
Now, the premise of Getopt::Auto
is that it frees you from the boring stuff, right? And it could be argued that writing a specification to hand to Getopt::Auto
is itself boring stuff. Well, never fear.
If you don't want to write such a specification, you don't have to.
All you need to do is write your commands, and then write some POD in front of them, like so:
use Getopt::Auto;
our $VERSION = "1.0";
=head2 wibble - wibble to standard output
This command emits a simple wibble to standard output. It takes no
other options.
=cut
sub wibble { print "Aaargh!\n" }
Getopt::Auto
will go through and find the subroutines which have a corresponding bit of POD documentation, and turn them into long options; you can now say yourprogam --wibble
, and wibble()
will be called. --help
and --version
work as normal, and the documentation following the head2
will be taken as the long help text.
AUTHOR
Simon Cozens, simon@cpan.org