NAME
    `Getopt::Simple' - Provide a simple wrapper around Getopt::Long.

SYNOPSIS
            use Getopt::Simple;

            # Or ...
            # use Getopt::Simple qw($switch);

            my($options) =
            {
            'help' =>
                    {
                    'type'          => '',
                    'env'           => '-',
                    'default'       => '',
    #               'verbose'       => '',  # Not needed on every key.
                    'order'         => 1,
                    },
            'username' =>
                    {
                    'type'          => '=s',                        # As per Getopt::Long.
                    'env'           => '$USER',                     # Help text.
                    'default'       => $ENV{'USER'} || 'RonSavage', # In case $USER is undef.
                    'verbose'       => 'Specify the username on the remote machine',
                    'order'         => 3,                           # Help text sort order.
                    },
            'password' =>
                    {
                    'type'          => '=s',
                    'env'           => '-',
                    'default'       => 'password',
                    'verbose'       => 'Specify the password on the remote machine',
                    'order'         => 4,
                    },
            };

            my($option) = new Getopt::Simple;

            if (! $option -> getOptions($options, "Usage: testSimple.pl [options]") )
            {
                    exit(-1);       # Failure.
            }

            print "username: $option->{'switch'}{'username'}. \n";
            print "password: $option->{'switch'}{'password'}. \n";

            # Or, after 'use Getopt::Simple qw($switch);' ...
            # print "username: $switch->{'username'}. \n";
            # print "password: $switch->{'password'}. \n";

DESCRIPTION
    The `Getopt::Simple' module provides a simple way of specifying:

    *   Command line switches

    *   Type information for switch values

    *   Default values for the switches

    *   Help text per switch

The `getOptions()' function
    The `getOptions()' function takes 4 parameters:

    *   A hash defining the command line switches

    *   A string to display as a help text heading

    *   A Boolean. 0 = (Default) Use case-sensitive switch names. 1 =
        Ignore case

    *   A Boolean. 0 = Return after displaying help. 1 = (Default)
        Terminate with exit(0) after displaying help

The $classRef -> {'switch'} hash reference
    Command line option values are accessed in your code by
    dereferencing the hash reference $classRef -> {'switch'}. Two
    examples are given above, under synopsis.

    Alternately, you can use the hash reference $switch. See below.

The $switch hash reference
    Command line option values are accessed in your code by
    dereferencing the hash reference $switch. Two examples are given
    above, under synopsis.

    Alternately, you can use the hash reference $classRef ->
    {'switch'}. See above.

The `dumpOptions()' function
    `dumpOptions()' prints all your option's keys and their current
    values.

The `helpOptions()' function
    `helpOptions()' prints nicely formatted help text.

INSTALLATION
    You install `Getopt::Simple', as you would install any perl
    module library, by running these commands:

            perl Makefile.PL
            make
            make test
            make install

    If you want to install a private copy of `Getopt::Simple' in
    your home directory, then you should try to produce the initial
    Makefile with something like this command:

            perl Makefile.PL LIB=~/perl
                    or
            perl Makefile.PL LIB=C:/Perl/Site/Lib

    If, like me, you don't have permission to write man pages into
    unix system directories, use:

            make pure_install

    instead of make install. This option is secreted in the middle
    of p 414 of the second edition of the dromedary book.

WARNING re Perl bug
    As always, be aware that these 2 lines mean the same thing,
    sometimes:

    *   $self -> {'thing'}

    *   $self->{'thing'}

    The problem is the spaces around the ->. Inside double quotes,
    "...", the first space stops the dereference taking place.
    Outside double quotes the scanner correctly associates the $self
    token with the {'thing'} token.

    I regard this as a bug.

REQUIRED MODULES
    *   Exporter

    *   Getopt::Long

RETURN VALUES
    *   `dumpOptions()' returns nothing

    *   `helpOptions()' returns nothing

    *   `getOptions()' returns 0 for failure and 1 for success

AUTHOR
    `Getopt::Simple' was written by Ron Savage
    *<rpsavage@ozemail.com.au>* in 1997.

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