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.
    
    =head1 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

SEE ALSO

the Config::Auto manpage, the Getopt::Long manpage