• NAME
• SYNOPSIS
• DESCRIPTION
• The getOptions() function
• The $classRef -> {'switch'} hash reference
• The $switch hash reference
• The dumpOptions() function
• The helpOptions() function
• INSTALLATION
• WARNING re Perl bug
• REQUIRED MODULES
• RETURN VALUES
• AUTHOR
• LICENCE

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 <ron@savage.net.au> in 1997.

LICENCE

Australian copyright (c) 1997-2002 Ron Savage.

        All Programs of mine are 'OSI Certified Open Source Software';
        you can redistribute them and/or modify them under the terms of
        The Artistic License, a copy of which is available at:
        http://www.opensource.org/licenses/index.html