1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
|
-----------------
Examples of Usage
-----------------
Preamble
The simplicity in JOpt "Simple" arises from two guiding principles:
* Stick as often as possible to supporting conventional Unix option syntaxes.
* Keep the surface area of the published API as small and simple as possible.
[]
To the first principle: You will not see support in JOpt Simple for option "groups",
alternative option prefixes (<<<+>>>, <<</>>>), enforced multiplicity of option
arguments, etc. JOpt Simple believes you can create a useful and understandable CLI
without all that stuff. If you feel as though you need any of those features, there
are lots of other choices out there. The author of JOpt Simple believes you'll want
to leverage its easy configuration, parsing, and option interrogation APIs instead of
using more feature-laden, but perhaps more confusing libraries.
To the second principle: JOpt Simple will make every attempt to keep the API free
of clutter. The API is well factored, making it intuitive to use, and the entire
library is well tested, making it more reliable and predictable. If you cannot look
at the Javadoc and quickly get a sense of what you need to do to use JOpt Simple,
then JOpt Simple has failed. So by all means, let the author know what needs
improved.
With that said, let's take a tour through JOpt Simple's features.
Options
JOpt Simple supports short options and long options, using a syntax that attempts to
take from the best of POSIX <<<getopt()>>> and GNU <<<getopt_long()>>>.
* Short Options
Short options begin with a single hyphen (<<<->>>) followed by a single letter or
digit, or question mark (<<<?>>>), or dot (<<<.>>>).
+----------------------------------------------------------------------------------------
@SHORT_OPTIONS_EXAMPLE@
+----------------------------------------------------------------------------------------
When you construct an <<<OptionParser>>> with a string of short option characters,
you configure that parser to recognize the options with those characters.
** Arguments of Options
Short options can accept single arguments. The argument can be made required or
optional. When you construct an <<<OptionParser>>> with a string of short option
characters, append a single colon (<<<:>>>) to an option character to configure
that option to require an argument. Append two colons (<<<::>>>) to an option
character to configure that option to accept an optional argument. Append an
asterisk (<<<*>>>) to an option character, but before any "argument" indicators,
to configure that option as a "help" option.
The syntax of the option specification string given to the <<<OptionParser>>>
constructor should look familiar to you if you have used GNU's <<<getopt()>>>
before.
+----------------------------------------------------------------------------------------
@SHORT_OPTIONS_WITH_ARGUMENTS_EXAMPLE@
+----------------------------------------------------------------------------------------
*** Specifying Arguments for a Short Option on the Command Line
A short option's argument can occur:
* in the position on the command line after the option
* right up against the option
* right up against the option separated by an equals sign (<<<=>>>)
[]
+----------------------------------------------------------------------------------------
@SHORT_OPTIONS_WITH_ARGUMENT_POSITIONING_EXAMPLE@
+----------------------------------------------------------------------------------------
*** Multiple Arguments for a Single Option
To specify <n> arguments for a single option, specify the option <n> times on the
command line, once for each argument. JOpt Simple reports the arguments given to the
option in the order in which they were encountered on the command line.
+----------------------------------------------------------------------------------------
@SHORT_OPTIONS_WITH_MULTIPLE_ARGUMENTS_FOR_SINGLE_OPTION_EXAMPLE@
+----------------------------------------------------------------------------------------
** Clustering Short Options
Short options can be <clustered> in a single argument.
+----------------------------------------------------------------------------------------
@SHORT_OPTIONS_CLUSTERING_EXAMPLE@
+----------------------------------------------------------------------------------------
If one of the short options can accept an argument, the remaining characters are interpreted
as the argument for that option.
+----------------------------------------------------------------------------------------
@SHORT_OPTIONS_CLUSTERING_WITH_ARGUMENT_EXAMPLE@
+----------------------------------------------------------------------------------------
* Long Options/Fluent Interface
Long options begin with two hyphens (<<<-->>>), followed by multiple letters,
digits, hyphens, question marks, or dots. A hyphen cannot be the first character of
a long option specification when configuring the parser.
Whereas short options can be configured using a constructor argument to
<<<OptionParser>>>, both long and short options can be configured using a "fluent
interface" API, that enables some very descriptive and powerful features.
+----------------------------------------------------------------------------------------
@LONG_OPTIONS_EXAMPLE@
+----------------------------------------------------------------------------------------
** Arguments of Options
Like short options, long options can accept single arguments. The argument can be
made required or optional. Use the methods <<<withRequiredArg()>>> and
<<<withOptionalArg()>>> on the return value of <<<OptionParser.accepts()>>> to signal
that an option takes a required or optional argument.
+----------------------------------------------------------------------------------------
@LONG_OPTIONS_WITH_ARGUMENTS_EXAMPLE@
+----------------------------------------------------------------------------------------
** Abbreviating Long Options
Notice in the example above that the command line uses abbreviations of command line
options. You can abbreviate options so long as the abbreviation is unambiguous.
Even though you can abbreviate the options on the command line, you cannot address
the <<<OptionSet>>> using those abbreviations. You can use a special constructor
for the <<<OptionParser>>> that turns off abbreviation matching.
** Using Single Hyphen on Long Options
As demonstrated in the example above, you can use a single hyphen instead of a
double hyphen to specify a long option -- but be careful that doing so doesn't
introduce ambiguity.
*** Specifying Arguments for a Long Option on the Command Line
A long option's argument can occur:
* in the position on the command line after the option
* right up against the option separated by an equals sign (<<<=>>>)
[]
+----------------------------------------------------------------------------------------
@LONG_OPTIONS_WITH_ARGUMENT_POSITIONING_EXAMPLE@
+----------------------------------------------------------------------------------------
*** Multiple Arguments for a Single Option
Specify multiple arguments for a long option in the same manner as for short options
(see above).
** Alternative Form of Long Options
The option <<<-W>>> is reserved. If you tell the parser to recognize alternative
long options, then it will treat, for example, <<<-W foo=bar>>> as the long option
<<<foo>>> with argument bar, as though you had written <<<--foo=bar>>>.
You can specify <<<-W>>> as a valid short option, or use it as an abbreviation for a
long option, but recognizing alternative long options will always supersede this
behavior.
To recognize alternative long options, either construct an <<<OptionParser>>> with a
string of short option characters containing the sequence <<<W;>>> (a capital W
followed by a semicolon), or call the method
<<<OptionParser.recognizeAlternativeLongOptions()>>>.
+----------------------------------------------------------------------------------------
@ALTERNATIVE_LONG_OPTIONS_EXAMPLE@
+----------------------------------------------------------------------------------------
* Other Features
** Converting Option Arguments to Other Types
Without action other than the <<<with*Arg()>>> methods, arguments of options are
returned as <<<String>>>s. For backwards compatibility,
<<<OptionSet.valueOf(String)>>> and <<<OptionSet.valuesOf(String)>>> return
<<<Object>>> and <<<List<?>>>>, respectively, so to get the values out as
<<<String>>>s, you will need to downcast the results of those methods.
You can tell JOpt Simple to convert the arguments of options to different Java types
via the <<<ofType()>>> method on the return value of <<<with*Arg()>>>. The
<<<Class>>> argument of <<<ofType()>>> must represent a Java class that has either:
* a <<<public static>>> method called <<<valueOf()>>> which accepts a single
<<<String>>> argument and whose return type is the type itself, or
* a <<<public>>> constructor which takes a single <<<String>>> argument.
[]
If the class has both, the <<<valueOf()>>> method is used.
Note that <<<enum>>>s have a <<<valueOf()>>> method.
+----------------------------------------------------------------------------------------
@OPTION_ARGUMENT_VALUE_TYPE_EXAMPLE@
+----------------------------------------------------------------------------------------
Another way to convert arguments of options is to specify a converter object via
<<<withValuesConvertedBy()>>>. This is useful when the desired type for the arguments
does not meet the requirements that <<<ofType()>>> sets forth. Such objects may not
perform any "conversion" at all, but rather can validate that arguments conform to
certain restrictions before passing through as-is.
You can also do this for the non-option arguments of your command line, if you desire
to treat them all as a single type.
+----------------------------------------------------------------------------------------
@OPTION_ARGUMENT_CONVERTER_EXAMPLE@
+----------------------------------------------------------------------------------------
** Retrieving Arguments of Options in a Type-Safe Manner
In the previous examples, we have been discarding the return values of the methods
of JOpt Simple's fluent interface. If instead you retain them in variables of type
<<<OptionSpec>>>, you can use them to retrieve arguments of options in a type-safe
manner.
You can also do this for the non-option arguments of your command line, if you desire
to treat them all as a single type.
+----------------------------------------------------------------------------------------
@TYPESAFE_OPTION_ARGUMENT_RETRIEVAL_EXAMPLE@
+----------------------------------------------------------------------------------------
** Exporting Options and Arguments to other Code
As an integration aid for other libraries, you can use <<<OptionSet.asMap()>>> to
obtain a mapping of <<<OptionSpec>>> to option values, for example to create a
properties map of options.
Here is sample code to create properties whose keys have a common prefix. The key is
choosen as the first non-short option:
+----------------------------------------------------------------------------------------
@EXPORTING_OPTIONS_AND_ARGUMENTS_EXAMPLE@
+----------------------------------------------------------------------------------------
** Default Values for Option Arguments
Often it is convenient to specify default values for the arguments of certain
command line options. To do this, call the <<<defaultsTo()>>> method.
+----------------------------------------------------------------------------------------
@DEFAULT_VALUES_FOR_OPTION_ARGUMENTS_EXAMPLE@
+----------------------------------------------------------------------------------------
You can see that <<<defaultsTo()>>> should relieve you of the burden of having to
check <<<has()>>> and/or <<<hasArgument()>>> on an <<<OptionSet>>> for a given option,
and has no bearing on the return values of those methods. Specifying a default value
for an option with a required argument does not mean that you can elide an argument for
the option on the command line.
The type of values <<<defaultsTo()>>> expects is dictated by the class given by a
previous call to <<<ofType()>>> or <<<withValuesConvertedBy()>>>; if no such call has
been made, the type is <<<String>>>.
** "Required" Options
You can indicate that a given option must be present on the command line via the
<<<required()>>> method. Only options that accept arguments can be made "required".
An option designated as a "help" option via <<<forHelp()>>>, when present on the
command line, causes missing "required" options not to reject the command line.
+----------------------------------------------------------------------------------------
@REQUIRED_OPTIONS_EXAMPLE@
+----------------------------------------------------------------------------------------
** "Required" Dependent Options
You can indicate that a given option must be present on the command line if some
other option is present on the command line via the <<<requiredIf()>>> method.
Any option can be made "required if".
An option designated as a "help" option via <<<forHelp()>>>, when present on the
command line, causes missing "required if" options not to reject the command line.
+----------------------------------------------------------------------------------------
@REQUIRED_IF_OPTIONS_EXAMPLE@
+----------------------------------------------------------------------------------------
You can also indicate that a given option must be present on the command line if some
other option is NOT present on the command line via the <<<requiredUnless()>>> method.
Any option can be made "required unless", but, to avoid potential conflicts, it should
not be "required if" at the same time.
+----------------------------------------------------------------------------------------
@REQUIRED_UNLESS_OPTIONS_EXAMPLE@
+----------------------------------------------------------------------------------------
** "Available" Dependent Options
Similarly to <<<requiredIf()>>> and <<<requiredUnless()>>>, you can indicate that a
given option can be present on the command line only if/unless some other option is
present on the command line, via the <<<availableIf()>>> and <<<availableUnless()>>>
methods.
** Synonyms of Options
Sometimes it is useful to allow many different options to share the same meaning in
the program that uses them. To specify that options are to be treated as synonymous,
use the <<<acceptsAll()>>> method of <<<OptionParser>>>.
+----------------------------------------------------------------------------------------
@OPTION_SYNONYM_EXAMPLE@
+----------------------------------------------------------------------------------------
** Concise Specification of Multiple Arguments for an Option
Another way to specify multiple arguments for an option is to tell the parser to
treat a single argument containing multiple delimited values as multiple arguments
for the option using the <<<withValuesSeparatedBy()>>> method.
+----------------------------------------------------------------------------------------
@MULTIPLE_DELIMITED_ARGUMENTS_EXAMPLE@
+----------------------------------------------------------------------------------------
** Signalling End of Options
An argument consisting only of two hyphens (<<<-->>>) signals that the remaining
arguments are to be treated as non-options.
An argument consisting only of a single hyphen is considered a non-option argument
(though it can be an argument of an option). Many Unix programs treat single hyphens
as stand-ins for the standard input or standard output stream.
*** Non-Option Arguments
Any arguments which are not options or arguments of options can be retrieved via
method <<<nonOptionArguments()>>> on <<<OptionSet>>>. If the double hyphen is an
argument, it is ignored and is not a non-option argument.
+----------------------------------------------------------------------------------------
@SIGNALLING_END_OF_OPTIONS_EXAMPLE@
+----------------------------------------------------------------------------------------
** "POSIX-ly Correct"-ness
By default, as with GNU <<<getopt()>>>, JOpt Simple allows intermixing of options and
non-options. If, however, the parser has been created to be "POSIX-ly correct", then
the first argument that does not look lexically like an option, and is not a required
argument of a preceding option, signals the end of options. You can still bind
optional arguments to their options using the abutting (for short options) or
<<<=>>> syntax.
Unlike GNU <<<getopt()>>>, JOptSimple does not honor the environment variable
<<<POSIXLY_CORRECT>>>. "POSIX-ly correct" parsers are configured by either:
* using the method <<<OptionParser.posixlyCorrect()>>>
* using the <<<OptionParser>>> constructor with an argument whose first character is
a plus sign (<<<+>>>)
[]
+----------------------------------------------------------------------------------------
@POSIXLY_CORRECT_EXAMPLE@
+----------------------------------------------------------------------------------------
** Special Optional Argument Handling
If the parser detects an option whose argument is optional, and the next argument
"looks like" an option, that argument is not treated as the argument to the option,
but as a potentially valid option. If, on the other hand, the optional argument is
typed as a derivative of <<<Number>>>, then that argument is treated as the negative
number argument of the option, even if the parser recognizes the corresponding numeric
option.
+----------------------------------------------------------------------------------------
@SPECIAL_OPTIONAL_ARGUMENT_HANDLING_EXAMPLE@
+----------------------------------------------------------------------------------------
Generating Command Line Help
When you call method <<<OptionParser.printHelpOn()>>>, JOpt Simple will write a
help screen (80-column width) describing all the options it is configured with,
along with types of option arguments, whether the option is required (in angle
brackets) or optional (in square brackets), etc. To give an option a description,
use <<<OptionParser.accepts*()>>> with a description argument. To give an option
argument a description, use <<<describedAs()>>> on the return value of
<<<with*Arg()>>>.
+----------------------------------------------------------------------------------------
@HELP_SCREEN_EXAMPLE@
+----------------------------------------------------------------------------------------
Here is what the help screen looks like for the example above:
+----------------------------------------------------------------------------------------
@HELP_SCREEN_EXAMPLE_HELP@
+----------------------------------------------------------------------------------------
If you want to create your own help screen, give method
<<<OptionParser.formatHelpWith()>>> a <<<HelpFormatter>>> that builds the help screen
as a String. When you call <<<OptionParser.printHelpOn()>>>, JOpt Simple will use
your <<<HelpFormatter>>> to produce the help and write it to the given stream.
For example, this program:
+----------------------------------------------------------------------------------------
@HELP_FORMATTER_EXAMPLE@
+----------------------------------------------------------------------------------------
yields the following output:
+----------------------------------------------------------------------------------------
@HELP_FORMATTER_EXAMPLE_OUTPUT@
+----------------------------------------------------------------------------------------
Handling Exceptions
JOpt Simple's classes raise some derivative of <<<OptionException>>> if they encounter
problems during parsing. These exceptions are unchecked, so you don't have to do
anything with such an exception if you don't want to. The rationale behind this
decision is that you will most likely be invoking JOpt Simple's functionality from a
<<<main()>>> method or very near to it, where a failure such as unrecognized arguments
can just stop down the JVM and yield a stack trace without much user or programmer
inconvenience. So, without any exception handling at all, a user would see something
like this:
+----------------------------------------------------------------------------------------
@EXAMPLE_STACK_TRACE@
+----------------------------------------------------------------------------------------
If you want to handle the exception yourself, you can catch <<<OptionException>>> in
your code, and do whatever you please with the contents of the exception, perhaps
using the help generation facility.
* Suppressing <<<UnrecognizedOptionException>>>
Sometimes you want to ignore unrecognized options on the command line.
For example, you might be interested in handling only a part of the arguments given.
Or you might want to pass on options to another program and not bother the user with
providing two hyphens (<<<-->>>) to indicate the end of known options. Or maybe
you want to provide future forwards/backwards compatibility when you foresee passing
in new options to old code (or old code invoking new code with "old" arguments).
You can achieve this by using the method <<<OptionParser.allowsUnrecognizedOptions()>>>.
When you call this method, then any unrecognized options handed to <<<parse()>>> are
treated as non-option arguments, rather than causing an exception to be raised.
+----------------------------------------------------------------------------------------
@UNRECOGNIZED_OPTIONS_ALLOWED_EXAMPLE@
+----------------------------------------------------------------------------------------
|