1Getopt::Simple(3pm)   User Contributed Perl Documentation  Getopt::Simple(3pm)
2
3
4

NAME

6       "Getopt::Simple" - Provide a simple wrapper around Getopt::Long.
7

SYNOPSIS

9               use Getopt::Simple;
10
11               # Or ...
12               # use Getopt::Simple qw($switch);
13
14               my($options) =
15               {
16               help =>
17                       {
18                       type    => '',
19                       env     => '-',
20                       default => '',
21       #               verbose => '',      # Not needed on every key.
22                       order   => 1,
23                       },
24               username =>
25                       {
26                       type    => '=s',    # As per Getopt::Long.
27                       env     => '$USER', # Help text.
28                       default => $ENV{'USER'} || 'RonSavage', # In case $USER is undef.
29                       verbose => 'Specify the username on the remote machine',
30                       order   => 3,       # Help text sort order.
31                       },
32               password =>
33                       {
34                       type    => '=s',
35                       env     => '-',
36                       default => 'password',
37                       verbose => 'Specify the password on the remote machine',
38                       order   => 4,
39                       },
40               };
41
42               my($option) = Getopt::Simple -> new();
43
44               if (! $option -> getOptions($options, "Usage: testSimple.pl [options]") )
45               {
46                       exit(-1);       # Failure.
47               }
48
49               print "username: $$option{'switch'}{'username'}. \n";
50               print "password: $$option{'switch'}{'password'}. \n";
51
52               # Or, after 'use Getopt::Simple qw($switch);' ...
53               # print "username: $$switch{'username'}. \n";
54               # print "password: $$switch{'password'}. \n";
55

DESCRIPTION

57       "Getopt::Simple" is a pure Perl module.
58
59       The "Getopt::Simple" module provides a simple way of specifying:
60
61       •   Command line switches
62
63       •   Type information for switch values
64
65       •   Default values for the switches
66
67       •   Help text per switch
68

Distributions

70       This module is available both as a Unix-style distro (*.tgz) and an
71       ActiveState-style distro (*.ppd). The latter is shipped in a *.zip
72       file.
73
74       See http://savage.net.au/Perl-modules.html for details.
75
76       See http://savage.net.au/Perl-modules/html/installing-a-module.html for
77       help on unpacking and installing each type of distro.
78

Constructor and initialization

80       new(...) returns a "Getopt::Simple" object.
81
82       This is the class's contructor.
83
84       Usage: Getopt::Simple -> new().
85
86       This method does not take any parameters.
87

The dumpOptions() function

89       dumpOptions() prints all your option's keys and their current values.
90
91       dumpOptions() does not return anything.
92

The getOptions() function

94       The getOptions() function takes 4 parameters:
95
96       •   A hash ref defining the command line switches
97
98           The structure of this hash ref is defined in the next section.
99
100           This parameter is mandatory.
101
102       •   A string to display as a help text heading
103
104           This parameter is mandatory.
105
106       •   A Boolean. 0 = (Default) Use case-sensitive switch names. 1 =
107           Ignore case
108
109           This parameter is optional.
110
111       •   A Boolean. 0 = Return after displaying help. 1 = (Default)
112           Terminate with exit(0) after displaying help
113
114           This parameter is optional.
115
116       getOptions() returns 0 for failure and 1 for success.
117

The hash ref of command line switches

119       •   Each key in the hash ref is the name of a command line switch
120
121       •   Each key points to a hash ref which defines the nature of that
122           command line switch
123
124           The keys and values of this nested hash ref are as follows.
125
126           •   default => 'Some value'
127
128               This key, value pair is mandatory.
129
130               This is the default value for this switch.
131
132               Examples:
133
134                       default => '/users/home/dir'
135                       default => $ENV{'REMOTEHOST'} || '127.0.0.1'
136
137           •   env => '-' || 'Some short help text'
138
139               This key, value pair is mandatory.
140
141               This is help test, to indicate that the calling program can use
142               an environment variable to set the default value of this
143               switch.
144
145               Use '-' to indicate that no environment variable is used.
146
147               Examples:
148
149                       env => '-'
150                       env => '$REMOTEHOST'
151
152               Note the use of ' to indicate we want the $ to appear in the
153               output.
154
155           •   type => 'Types as per Getopt::Long'
156
157               This key, value pair is mandatory.
158
159               This is the type of the command line switch, as defined by
160               Getopt::Long.
161
162               Examples:
163
164                       type => '=s'
165                       type => '=s@',
166
167           •   verbose => 'Some long help text'
168
169               This key, value pair is optional.
170
171               This is long, explanatory help text which is displayed below
172               the help containing the three columns of text: switch name, env
173               value, default value.
174
175               Examples:
176
177                       verbose => 'Specify the username on the remote machine',
178                       verbose => 'Specify the home directory on the remote machine'
179
180           •   order => \d+
181
182               This key, value pair is mandatory.
183
184               This is the sort order used to force the help text to display
185               the switches in a specific order down the page.
186
187               Examples:
188
189                       order => 1
190                       order => 9
191

The helpOptions() function

193       helpOptions() prints nicely formatted help text.
194
195       helpOptions() does not return anything.
196

The $$classRef{'switch'} hash reference

198       Command line option values are accessed in your code by dereferencing
199       the hash reference $$classRef{'switch'}. Two examples are given above,
200       under synopsis.
201
202       Alternately, you can use the hash reference $switch. See below.
203

The $switch hash reference

205       Command line option values are accessed in your code by dereferencing
206       the hash reference $switch. Two examples are given above, under
207       synopsis.
208
209       Alternately, you can use the hash reference $$classRef{'switch'}. See
210       above.
211

WARNING re Perl bug

213       As always, be aware that these 2 lines mean the same thing, sometimes:
214
215       •   $self -> {'thing'}
216
217       •   $self->{'thing'}
218
219       The problem is the spaces around the ->. Inside double quotes, "...",
220       the first space stops the dereference taking place. Outside double
221       quotes the scanner correctly associates the $self token with the
222       {'thing'} token.
223
224       I regard this as a bug.
225

AUTHOR

227       "Getopt::Simple" was written by Ron Savage <ron@savage.net.au> in 1997.
228

LICENCE

230       Australian copyright (c) 1997-2002 Ron Savage.
231
232               All Programs of mine are 'OSI Certified Open Source Software';
233               you can redistribute them and/or modify them under the terms of
234               The Artistic License, a copy of which is available at:
235               http://www.opensource.org/licenses/index.html
236
237
238
239perl v5.38.0                      2023-07-20               Getopt::Simple(3pm)
Impressum