cli-option_parser.rb 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (106) hide show
  1. checksums.yaml +7 -0
  2. data/.bundle/config +2 -0
  3. data/.document +7 -0
  4. data/.editorconfig +13 -0
  5. data/.github/dependabot.yml +6 -0
  6. data/.github/workflows/test.yml +26 -0
  7. data/.gitignore +13 -0
  8. data/.rdoc_options +4 -0
  9. data/COPYING +56 -0
  10. data/Gemfile +5 -0
  11. data/README.md +59 -0
  12. data/Rakefile +14 -0
  13. data/cli-option_parser.rb.gemspec +23 -0
  14. data/doc/optparse/.document +1 -0
  15. data/doc/optparse/argument_converters.rdoc +380 -0
  16. data/doc/optparse/creates_option.rdoc +7 -0
  17. data/doc/optparse/option_params.rdoc +509 -0
  18. data/doc/optparse/ruby/argument_abbreviation.rb +9 -0
  19. data/doc/optparse/ruby/argument_keywords.rb +6 -0
  20. data/doc/optparse/ruby/argument_strings.rb +6 -0
  21. data/doc/optparse/ruby/argv.rb +2 -0
  22. data/doc/optparse/ruby/array.rb +6 -0
  23. data/doc/optparse/ruby/basic.rb +17 -0
  24. data/doc/optparse/ruby/block.rb +9 -0
  25. data/doc/optparse/ruby/collected_options.rb +8 -0
  26. data/doc/optparse/ruby/custom_converter.rb +9 -0
  27. data/doc/optparse/ruby/date.rb +6 -0
  28. data/doc/optparse/ruby/datetime.rb +6 -0
  29. data/doc/optparse/ruby/decimal_integer.rb +7 -0
  30. data/doc/optparse/ruby/decimal_numeric.rb +7 -0
  31. data/doc/optparse/ruby/default_values.rb +8 -0
  32. data/doc/optparse/ruby/descriptions.rb +15 -0
  33. data/doc/optparse/ruby/explicit_array_values.rb +9 -0
  34. data/doc/optparse/ruby/explicit_hash_values.rb +9 -0
  35. data/doc/optparse/ruby/false_class.rb +6 -0
  36. data/doc/optparse/ruby/float.rb +6 -0
  37. data/doc/optparse/ruby/help.rb +18 -0
  38. data/doc/optparse/ruby/help_banner.rb +7 -0
  39. data/doc/optparse/ruby/help_format.rb +25 -0
  40. data/doc/optparse/ruby/help_program_name.rb +7 -0
  41. data/doc/optparse/ruby/integer.rb +6 -0
  42. data/doc/optparse/ruby/long_names.rb +9 -0
  43. data/doc/optparse/ruby/long_optional.rb +6 -0
  44. data/doc/optparse/ruby/long_required.rb +6 -0
  45. data/doc/optparse/ruby/long_simple.rb +9 -0
  46. data/doc/optparse/ruby/long_with_negation.rb +6 -0
  47. data/doc/optparse/ruby/match_converter.rb +9 -0
  48. data/doc/optparse/ruby/matched_values.rb +6 -0
  49. data/doc/optparse/ruby/method.rb +11 -0
  50. data/doc/optparse/ruby/missing_options.rb +12 -0
  51. data/doc/optparse/ruby/mixed_names.rb +12 -0
  52. data/doc/optparse/ruby/name_abbrev.rb +9 -0
  53. data/doc/optparse/ruby/no_abbreviation.rb +10 -0
  54. data/doc/optparse/ruby/numeric.rb +6 -0
  55. data/doc/optparse/ruby/object.rb +6 -0
  56. data/doc/optparse/ruby/octal_integer.rb +7 -0
  57. data/doc/optparse/ruby/optional_argument.rb +9 -0
  58. data/doc/optparse/ruby/parse.rb +13 -0
  59. data/doc/optparse/ruby/parse_bang.rb +13 -0
  60. data/doc/optparse/ruby/proc.rb +13 -0
  61. data/doc/optparse/ruby/regexp.rb +6 -0
  62. data/doc/optparse/ruby/required_argument.rb +9 -0
  63. data/doc/optparse/ruby/shellwords.rb +6 -0
  64. data/doc/optparse/ruby/short_names.rb +9 -0
  65. data/doc/optparse/ruby/short_optional.rb +6 -0
  66. data/doc/optparse/ruby/short_range.rb +6 -0
  67. data/doc/optparse/ruby/short_required.rb +6 -0
  68. data/doc/optparse/ruby/short_simple.rb +9 -0
  69. data/doc/optparse/ruby/string.rb +6 -0
  70. data/doc/optparse/ruby/terminator.rb +6 -0
  71. data/doc/optparse/ruby/time.rb +6 -0
  72. data/doc/optparse/ruby/true_class.rb +6 -0
  73. data/doc/optparse/ruby/uri.rb +6 -0
  74. data/doc/optparse/tutorial.rdoc +858 -0
  75. data/lib/cli/option_parser/ac.rb +52 -0
  76. data/lib/cli/option_parser/date.rb +16 -0
  77. data/lib/cli/option_parser/kwargs.rb +21 -0
  78. data/lib/cli/option_parser/shellwords.rb +4 -0
  79. data/lib/cli/option_parser/time.rb +9 -0
  80. data/lib/cli/option_parser/uri.rb +4 -0
  81. data/lib/cli/option_parser/version.rb +71 -0
  82. data/lib/cli/option_parser.rb +2353 -0
  83. data/lib/cli-option_parser.rb +1 -0
  84. data/misc/rb_optparse.bash +21 -0
  85. data/misc/rb_optparse.zsh +39 -0
  86. data/rakelib/.document +0 -0
  87. data/rakelib/changelogs.rake +34 -0
  88. data/rakelib/epoch.rake +5 -0
  89. data/rakelib/version.rake +51 -0
  90. data/test/lib/helper.rb +4 -0
  91. data/test/optparse/test_acceptable.rb +198 -0
  92. data/test/optparse/test_autoconf.rb +69 -0
  93. data/test/optparse/test_bash_completion.rb +46 -0
  94. data/test/optparse/test_cclass.rb +18 -0
  95. data/test/optparse/test_did_you_mean.rb +48 -0
  96. data/test/optparse/test_getopts.rb +49 -0
  97. data/test/optparse/test_kwargs.rb +38 -0
  98. data/test/optparse/test_load.rb +141 -0
  99. data/test/optparse/test_noarg.rb +79 -0
  100. data/test/optparse/test_optarg.rb +60 -0
  101. data/test/optparse/test_optparse.rb +127 -0
  102. data/test/optparse/test_placearg.rb +76 -0
  103. data/test/optparse/test_reqarg.rb +95 -0
  104. data/test/optparse/test_summary.rb +81 -0
  105. data/test/optparse/test_zsh_completion.rb +21 -0
  106. metadata +154 -0
@@ -0,0 +1,858 @@
1
+ == Tutorial
2
+
3
+ === Why +OptionParser+?
4
+
5
+ When a Ruby program executes, it captures its command-line arguments
6
+ and options into variable ARGV.
7
+ This simple program just prints its +ARGV+:
8
+
9
+ :include: ruby/argv.rb
10
+
11
+ Execution, with arguments and options:
12
+
13
+ $ ruby argv.rb foo --bar --baz bat bam
14
+ ["foo", "--bar", "--baz", "bat", "bam"]
15
+
16
+ The executing program is responsible for parsing and handling
17
+ the command-line options.
18
+
19
+ OptionParser offers methods for parsing and handling those options.
20
+
21
+ With +OptionParser+, you can define options so that for each option:
22
+
23
+ - The code that defines the option and code that handles that option
24
+ are in the same place.
25
+ - The option may take no argument, a required argument, or an optional argument.
26
+ - The argument may be automatically converted to a specified class.
27
+ - The argument may be restricted to specified _forms_.
28
+ - The argument may be restricted to specified _values_.
29
+
30
+ The class also has method #help, which displays automatically-generated help text.
31
+
32
+ === Contents
33
+
34
+ - {To Begin With}[#label-To+Begin+With]
35
+ - {Defining Options}[#label-Defining+Options]
36
+ - {Option Names}[#label-Option+Names]
37
+ - {Short Option Names}[#label-Short+Option+Names]
38
+ - {Long Option Names}[#label-Long+Option+Names]
39
+ - {Mixing Option Names}[#label-Mixing+Option+Names]
40
+ - {Option Name Abbreviations}[#label-Option+Name+Abbreviations]
41
+ - {Option Arguments}[#label-Option+Arguments]
42
+ - {Option with No Argument}[#label-Option+with+No+Argument]
43
+ - {Option with Required Argument}[#label-Option+with+Required+Argument]
44
+ - {Option with Optional Argument}[#label-Option+with+Optional+Argument]
45
+ - {Argument Abbreviations}[#label-Argument+Abbreviations]
46
+ - {Argument Values}[#label-Argument+Values]
47
+ - {Explicit Argument Values}[#label-Explicit+Argument+Values]
48
+ - {Explicit Values in Array}[#label-Explicit+Values+in+Array]
49
+ - {Explicit Values in Hash}[#label-Explicit+Values+in+Hash]
50
+ - {Argument Value Patterns}[#label-Argument+Value+Patterns]
51
+ - {Keyword Argument into}[#label-Keyword+Argument+into]
52
+ - {Collecting Options}[#label-Collecting+Options]
53
+ - {Checking for Missing Options}[#label-Checking+for+Missing+Options]
54
+ - {Default Values for Options}[#label-Default+Values+for+Options]
55
+ - {Argument Converters}[#label-Argument+Converters]
56
+ - {Help}[#label-Help]
57
+ - {Top List and Base List}[#label-Top+List+and+Base+List]
58
+ - {Methods for Defining Options}[#label-Methods+for+Defining+Options]
59
+ - {Parsing}[#label-Parsing]
60
+ - {Method parse!}[#label-Method+parse-21]
61
+ - {Method parse}[#label-Method+parse]
62
+ - {Method order!}[#label-Method+order-21]
63
+ - {Method order}[#label-Method+order]
64
+ - {Method permute!}[#label-Method+permute-21]
65
+ - {Method permute}[#label-Method+permute]
66
+
67
+ === To Begin With
68
+
69
+ To use +OptionParser+:
70
+
71
+ 1. Require the +OptionParser+ code.
72
+ 2. Create an +OptionParser+ object.
73
+ 3. Define one or more options.
74
+ 4. Parse the command line.
75
+
76
+ File +basic.rb+ defines three options, <tt>-x</tt>,
77
+ <tt>-y</tt>, and <tt>-z</tt>, each with a descriptive string,
78
+ and each with a block.
79
+
80
+ :include: ruby/basic.rb
81
+
82
+ From these defined options, the parser automatically builds help text:
83
+
84
+ $ ruby basic.rb --help
85
+ Usage: basic [options]
86
+ -x Whether to X
87
+ -y Whether to Y
88
+ -z Whether to Z
89
+
90
+ When an option is found during parsing,
91
+ the block defined for the option is called with the argument value.
92
+ An invalid option raises an exception.
93
+
94
+ Method #parse!, which is used most often in this tutorial,
95
+ removes from +ARGV+ the options and arguments it finds,
96
+ leaving other non-option arguments for the program to handle on its own.
97
+ The method returns the possibly-reduced +ARGV+ array.
98
+
99
+ Executions:
100
+
101
+ $ ruby basic.rb -x -z
102
+ ["x", true]
103
+ ["z", true]
104
+ []
105
+ $ ruby basic.rb -z -y -x
106
+ ["z", true]
107
+ ["y", true]
108
+ ["x", true]
109
+ []
110
+ $ ruby basic.rb -x input_file.txt output_file.txt
111
+ ["x", true]
112
+ ["input_file.txt", "output_file.txt"]
113
+ $ ruby basic.rb -a
114
+ basic.rb:16:in `<main>': invalid option: -a (OptionParser::InvalidOption)
115
+
116
+ === Defining Options
117
+
118
+ A common way to define an option in +OptionParser+
119
+ is with instance method OptionParser#on.
120
+
121
+ The method may be called with any number of arguments
122
+ (whose order does not matter),
123
+ and may also have a trailing optional keyword argument +into+.
124
+
125
+ The given arguments determine the characteristics of the new option.
126
+ These may include:
127
+
128
+ - One or more short option names.
129
+ - One or more long option names.
130
+ - Whether the option takes no argument, an optional argument, or a required argument.
131
+ - Acceptable _forms_ for the argument.
132
+ - Acceptable _values_ for the argument.
133
+ - A proc or method to be called when the parser encounters the option.
134
+ - String descriptions for the option.
135
+
136
+ === Option Names
137
+
138
+ You can give an option one or more names of two types:
139
+
140
+ - Short (1-character) name, beginning with one hyphen (<tt>-</tt>).
141
+ - Long (multi-character) name, beginning with two hyphens (<tt>--</tt>).
142
+
143
+ ==== Short Option Names
144
+
145
+ A short option name consists of a hyphen and a single character.
146
+
147
+ File +short_names.rb+
148
+ defines an option with a short name, <tt>-x</tt>,
149
+ and an option with two short names (aliases, in effect) <tt>-y</tt> and <tt>-z</tt>.
150
+
151
+ :include: ruby/short_names.rb
152
+
153
+ Executions:
154
+
155
+ $ ruby short_names.rb --help
156
+ Usage: short_names [options]
157
+ -x Short name
158
+ -1, -% Two short names
159
+ $ ruby short_names.rb -x
160
+ ["x", true]
161
+ $ ruby short_names.rb -1
162
+ ["-1 or -%", true]
163
+ $ ruby short_names.rb -%
164
+ ["-1 or -%", true]
165
+
166
+ Multiple short names can "share" a hyphen:
167
+
168
+ $ ruby short_names.rb -x1%
169
+ ["x", true]
170
+ ["-1 or -%", true]
171
+ ["-1 or -%", true]
172
+
173
+ ==== Long Option Names
174
+
175
+ A long option name consists of two hyphens and a one or more characters
176
+ (usually two or more characters).
177
+
178
+ File +long_names.rb+
179
+ defines an option with a long name, <tt>--xxx</tt>,
180
+ and an option with two long names (aliases, in effect) <tt>--y1%</tt> and <tt>--z2#</tt>.
181
+
182
+ :include: ruby/long_names.rb
183
+
184
+ Executions:
185
+
186
+ $ ruby long_names.rb --help
187
+ Usage: long_names [options]
188
+ --xxx Long name
189
+ --y1%, --z2# Two long names
190
+ $ ruby long_names.rb --xxx
191
+ ["-xxx", true]
192
+ $ ruby long_names.rb --y1%
193
+ ["--y1% or --z2#", true]
194
+ $ ruby long_names.rb --z2#
195
+ ["--y1% or --z2#", true]
196
+
197
+ A long name may be defined with both positive and negative senses.
198
+
199
+ File +long_with_negation.rb+ defines an option that has both senses.
200
+
201
+ :include: ruby/long_with_negation.rb
202
+
203
+ Executions:
204
+
205
+ $ ruby long_with_negation.rb --help
206
+ Usage: long_with_negation [options]
207
+ --[no-]binary Long name with negation
208
+ $ ruby long_with_negation.rb --binary
209
+ [true, TrueClass]
210
+ $ ruby long_with_negation.rb --no-binary
211
+ [false, FalseClass]
212
+
213
+ ==== Mixing Option Names
214
+
215
+ Many developers like to mix short and long option names,
216
+ so that a short name is in effect an abbreviation of a long name.
217
+
218
+ File +mixed_names.rb+
219
+ defines options that each have both a short and a long name.
220
+
221
+ :include: ruby/mixed_names.rb
222
+
223
+ Executions:
224
+
225
+ $ ruby mixed_names.rb --help
226
+ Usage: mixed_names [options]
227
+ -x, --xxx Short and long, no argument
228
+ -y, --yyyYYY Short and long, required argument
229
+ -z, --zzz [ZZZ] Short and long, optional argument
230
+ $ ruby mixed_names.rb -x
231
+ ["--xxx", true]
232
+ $ ruby mixed_names.rb --xxx
233
+ ["--xxx", true]
234
+ $ ruby mixed_names.rb -y
235
+ mixed_names.rb:12:in `<main>': missing argument: -y (OptionParser::MissingArgument)
236
+ $ ruby mixed_names.rb -y FOO
237
+ ["--yyy", "FOO"]
238
+ $ ruby mixed_names.rb --yyy
239
+ mixed_names.rb:12:in `<main>': missing argument: --yyy (OptionParser::MissingArgument)
240
+ $ ruby mixed_names.rb --yyy BAR
241
+ ["--yyy", "BAR"]
242
+ $ ruby mixed_names.rb -z
243
+ ["--zzz", nil]
244
+ $ ruby mixed_names.rb -z BAZ
245
+ ["--zzz", "BAZ"]
246
+ $ ruby mixed_names.rb --zzz
247
+ ["--zzz", nil]
248
+ $ ruby mixed_names.rb --zzz BAT
249
+ ["--zzz", "BAT"]
250
+
251
+ ==== Option Name Abbreviations
252
+
253
+ By default, abbreviated option names on the command-line are allowed.
254
+ An abbreviated name is valid if it is unique among abbreviated option names.
255
+
256
+ :include: ruby/name_abbrev.rb
257
+
258
+ Executions:
259
+
260
+ $ ruby name_abbrev.rb --help
261
+ Usage: name_abbrev [options]
262
+ -n, --dry-run
263
+ -d, --draft
264
+ $ ruby name_abbrev.rb -n
265
+ ["--dry-run", true]
266
+ $ ruby name_abbrev.rb --dry-run
267
+ ["--dry-run", true]
268
+ $ ruby name_abbrev.rb -d
269
+ ["--draft", true]
270
+ $ ruby name_abbrev.rb --draft
271
+ ["--draft", true]
272
+ $ ruby name_abbrev.rb --d
273
+ name_abbrev.rb:9:in `<main>': ambiguous option: --d (OptionParser::AmbiguousOption)
274
+ $ ruby name_abbrev.rb --dr
275
+ name_abbrev.rb:9:in `<main>': ambiguous option: --dr (OptionParser::AmbiguousOption)
276
+ $ ruby name_abbrev.rb --dry
277
+ ["--dry-run", true]
278
+ $ ruby name_abbrev.rb --dra
279
+ ["--draft", true]
280
+
281
+ You can disable abbreviation using method +require_exact+.
282
+
283
+ :include: ruby/no_abbreviation.rb
284
+
285
+ Executions:
286
+
287
+ $ ruby no_abbreviation.rb --dry-ru
288
+ no_abbreviation.rb:10:in `<main>': invalid option: --dry-ru (OptionParser::InvalidOption)
289
+ $ ruby no_abbreviation.rb --dry-run
290
+ ["--dry-run", true]
291
+
292
+ === Option Arguments
293
+
294
+ An option may take no argument, a required argument, or an optional argument.
295
+
296
+ ==== Option with No Argument
297
+
298
+ All the examples above define options with no argument.
299
+
300
+ ==== Option with Required Argument
301
+
302
+ Specify a required argument for an option by adding a dummy word
303
+ to its name definition.
304
+
305
+ File +required_argument.rb+ defines two options;
306
+ each has a required argument because the name definition has a following dummy word.
307
+
308
+ :include: ruby/required_argument.rb
309
+
310
+ When an option is found, the given argument is yielded.
311
+
312
+ Executions:
313
+
314
+ $ ruby required_argument.rb --help
315
+ Usage: required_argument [options]
316
+ -x, --xxx XXX Required argument via short name
317
+ -y, --y YYY Required argument via long name
318
+ $ ruby required_argument.rb -x AAA
319
+ ["--xxx", "AAA"]
320
+ $ ruby required_argument.rb -y BBB
321
+ ["--yyy", "BBB"]
322
+
323
+ Omitting a required argument raises an error:
324
+
325
+ $ ruby required_argument.rb -x
326
+ required_argument.rb:9:in `<main>': missing argument: -x (OptionParser::MissingArgument)
327
+
328
+ ==== Option with Optional Argument
329
+
330
+ Specify an optional argument for an option by adding a dummy word
331
+ enclosed in square brackets to its name definition.
332
+
333
+ File +optional_argument.rb+ defines two options;
334
+ each has an optional argument because the name definition has a following dummy word
335
+ in square brackets.
336
+
337
+ :include: ruby/optional_argument.rb
338
+
339
+ When an option with an argument is found, the given argument yielded.
340
+
341
+ Executions:
342
+
343
+ $ ruby optional_argument.rb --help
344
+ Usage: optional_argument [options]
345
+ -x, --xxx [XXX] Optional argument via short name
346
+ -y, --yyy [YYY] Optional argument via long name
347
+ $ ruby optional_argument.rb -x AAA
348
+ ["--xxx", "AAA"]
349
+ $ ruby optional_argument.rb -y BBB
350
+ ["--yyy", "BBB"]
351
+
352
+ Omitting an optional argument does not raise an error.
353
+
354
+ ==== Argument Abbreviations
355
+
356
+ Specify an argument list as an Array or a Hash.
357
+
358
+ :include: ruby/argument_abbreviation.rb
359
+
360
+ When an argument is abbreviated, the expanded argument yielded.
361
+
362
+ Executions:
363
+
364
+ $ ruby argument_abbreviation.rb --help
365
+ Usage: argument_abbreviation [options]
366
+ Usage: argument_abbreviation [options]
367
+ -x, --xxx=VALUE Argument abbreviations
368
+ -y, --yyy=VALUE Argument abbreviations
369
+ $ ruby argument_abbreviation.rb --xxx A
370
+ ["--xxx", "ABC"]
371
+ $ ruby argument_abbreviation.rb --xxx c
372
+ argument_abbreviation.rb:9:in `<main>': invalid argument: --xxx c (OptionParser::InvalidArgument)
373
+ $ ruby argument_abbreviation.rb --yyy a --yyy d
374
+ ["--yyy", "XYZ"]
375
+ ["--yyy", "FOO"]
376
+
377
+ === Argument Values
378
+
379
+ Permissible argument values may be restricted
380
+ either by specifying explicit values
381
+ or by providing a pattern that the given value must match.
382
+
383
+ ==== Explicit Argument Values
384
+
385
+ You can specify argument values in either of two ways:
386
+
387
+ - Specify values an array of strings.
388
+ - Specify values a hash.
389
+
390
+ ===== Explicit Values in Array
391
+
392
+ You can specify explicit argument values in an array of strings.
393
+ The argument value must be one of those strings, or an unambiguous abbreviation.
394
+
395
+ File +explicit_array_values.rb+ defines options with explicit argument values.
396
+
397
+ :include: ruby/explicit_array_values.rb
398
+
399
+ Executions:
400
+
401
+ $ ruby explicit_array_values.rb --help
402
+ Usage: explicit_array_values [options]
403
+ -xXXX Values for required argument
404
+ -y [YYY] Values for optional argument
405
+ $ ruby explicit_array_values.rb -x
406
+ explicit_array_values.rb:9:in `<main>': missing argument: -x (OptionParser::MissingArgument)
407
+ $ ruby explicit_array_values.rb -x foo
408
+ ["-x", "foo"]
409
+ $ ruby explicit_array_values.rb -x f
410
+ ["-x", "foo"]
411
+ $ ruby explicit_array_values.rb -x bar
412
+ ["-x", "bar"]
413
+ $ ruby explicit_array_values.rb -y ba
414
+ explicit_array_values.rb:9:in `<main>': ambiguous argument: -y ba (OptionParser::AmbiguousArgument)
415
+ $ ruby explicit_array_values.rb -x baz
416
+ explicit_array_values.rb:9:in `<main>': invalid argument: -x baz (OptionParser::InvalidArgument)
417
+
418
+
419
+ ===== Explicit Values in Hash
420
+
421
+ You can specify explicit argument values in a hash with string keys.
422
+ The value passed must be one of those keys, or an unambiguous abbreviation;
423
+ the value yielded will be the value for that key.
424
+
425
+ File +explicit_hash_values.rb+ defines options with explicit argument values.
426
+
427
+ :include: ruby/explicit_hash_values.rb
428
+
429
+ Executions:
430
+
431
+ $ ruby explicit_hash_values.rb --help
432
+ Usage: explicit_hash_values [options]
433
+ -xXXX Values for required argument
434
+ -y [YYY] Values for optional argument
435
+ $ ruby explicit_hash_values.rb -x
436
+ explicit_hash_values.rb:9:in `<main>': missing argument: -x (OptionParser::MissingArgument)
437
+ $ ruby explicit_hash_values.rb -x foo
438
+ ["-x", 0]
439
+ $ ruby explicit_hash_values.rb -x f
440
+ ["-x", 0]
441
+ $ ruby explicit_hash_values.rb -x bar
442
+ ["-x", 1]
443
+ $ ruby explicit_hash_values.rb -x baz
444
+ explicit_hash_values.rb:9:in `<main>': invalid argument: -x baz (OptionParser::InvalidArgument)
445
+ $ ruby explicit_hash_values.rb -y
446
+ ["-y", nil]
447
+ $ ruby explicit_hash_values.rb -y baz
448
+ ["-y", 2]
449
+ $ ruby explicit_hash_values.rb -y bat
450
+ ["-y", 3]
451
+ $ ruby explicit_hash_values.rb -y ba
452
+ explicit_hash_values.rb:9:in `<main>': ambiguous argument: -y ba (OptionParser::AmbiguousArgument)
453
+ $ ruby explicit_hash_values.rb -y bam
454
+ ["-y", nil]
455
+
456
+ ==== Argument Value Patterns
457
+
458
+ You can restrict permissible argument values
459
+ by specifying a Regexp that the given argument must match.
460
+
461
+ File +matched_values.rb+ defines options with matched argument values.
462
+
463
+ :include: ruby/matched_values.rb
464
+
465
+ Executions:
466
+
467
+ $ ruby matched_values.rb --help
468
+ Usage: matched_values [options]
469
+ --xxx XXX Matched values
470
+ $ ruby matched_values.rb --xxx foo
471
+ ["--xxx", "foo"]
472
+ $ ruby matched_values.rb --xxx FOO
473
+ ["--xxx", "FOO"]
474
+ $ ruby matched_values.rb --xxx bar
475
+ matched_values.rb:6:in `<main>': invalid argument: --xxx bar (OptionParser::InvalidArgument)
476
+
477
+ === Keyword Argument +into+
478
+
479
+ In parsing options, you can add keyword option +into+ with a hash-like argument;
480
+ each parsed option will be added as a name/value pair.
481
+
482
+ This is useful for:
483
+
484
+ - Collecting options.
485
+ - Checking for missing options.
486
+ - Providing default values for options.
487
+
488
+ ==== Collecting Options
489
+
490
+ Use keyword argument +into+ to collect options.
491
+
492
+ :include: ruby/collected_options.rb
493
+
494
+ Executions:
495
+
496
+ $ ruby collected_options.rb --help
497
+ Usage: into [options]
498
+ -x, --xxx Short and long, no argument
499
+ -y, --yyyYYY Short and long, required argument
500
+ -z, --zzz [ZZZ] Short and long, optional argument
501
+ $ ruby collected_options.rb --xxx
502
+ {:xxx=>true}
503
+ $ ruby collected_options.rb --xxx --yyy FOO
504
+ {:xxx=>true, :yyy=>"FOO"}
505
+ $ ruby collected_options.rb --xxx --yyy FOO --zzz Bar
506
+ {:xxx=>true, :yyy=>"FOO", :zzz=>"Bar"}
507
+ $ ruby collected_options.rb --xxx --yyy FOO --yyy BAR
508
+ {:xxx=>true, :yyy=>"BAR"}
509
+
510
+ Note in the last execution that the argument value for option <tt>--yyy</tt>
511
+ was overwritten.
512
+
513
+ ==== Checking for Missing Options
514
+
515
+ Use the collected options to check for missing options.
516
+
517
+ :include: ruby/missing_options.rb
518
+
519
+ Executions:
520
+
521
+ $ ruby missing_options.rb --help
522
+ Usage: missing_options [options]
523
+ -x, --xxx Short and long, no argument
524
+ -y, --yyyYYY Short and long, required argument
525
+ -z, --zzz [ZZZ] Short and long, optional argument
526
+ $ ruby missing_options.rb --yyy FOO
527
+ missing_options.rb:11:in `<main>': Missing required options: [:xxx, :zzz] (RuntimeError)
528
+
529
+ ==== Default Values for Options
530
+
531
+ Initialize the +into+ argument to define default values for options.
532
+
533
+ :include: ruby/default_values.rb
534
+
535
+ Executions:
536
+
537
+ $ ruby default_values.rb --help
538
+ Usage: default_values [options]
539
+ -x, --xxx Short and long, no argument
540
+ -y, --yyyYYY Short and long, required argument
541
+ -z, --zzz [ZZZ] Short and long, optional argument
542
+ $ ruby default_values.rb --yyy FOO
543
+ {:yyy=>"FOO", :zzz=>"BBB"}
544
+
545
+ === Argument Converters
546
+
547
+ An option can specify that its argument is to be converted
548
+ from the default +String+ to an instance of another class.
549
+ There are a number of built-in converters.
550
+
551
+ Example: File +date.rb+
552
+ defines an option whose argument is to be converted to a +Date+ object.
553
+ The argument is converted by method Date#parse.
554
+
555
+ :include: ruby/date.rb
556
+
557
+ Executions:
558
+
559
+ $ ruby date.rb --date 2001-02-03
560
+ [#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date]
561
+ $ ruby date.rb --date 20010203
562
+ [#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date]
563
+ $ ruby date.rb --date "3rd Feb 2001"
564
+ [#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date]
565
+
566
+ You can also define custom converters.
567
+ See {Argument Converters}[./argument_converters.rdoc]
568
+ for both built-in and custom converters.
569
+
570
+ === Help
571
+
572
+ +OptionParser+ makes automatically generated help text available.
573
+
574
+ The help text consists of:
575
+
576
+ - A banner, showing the usage.
577
+ - Option short and long names.
578
+ - Option dummy argument names.
579
+ - Option descriptions.
580
+
581
+ Example code:
582
+
583
+ :include: ruby/help.rb
584
+
585
+ The option names and dummy argument names are defined as described above.
586
+
587
+ The option description consists of the strings that are not themselves option names;
588
+ An option can have more than one description string.
589
+ Execution:
590
+
591
+ Usage: help [options]
592
+ -x, --xxx Adipiscing elit. Aenean commodo ligula eget.
593
+ Aenean massa. Cum sociis natoque penatibus
594
+ -y, --yyy YYY Lorem ipsum dolor sit amet, consectetuer.
595
+ -z, --zzz [ZZZ] Et magnis dis parturient montes, nascetur
596
+ ridiculus mus. Donec quam felis, ultricies
597
+ nec, pellentesque eu, pretium quis, sem.
598
+
599
+ The program name is included in the default banner:
600
+ <tt>Usage: #{program_name} [options]</tt>;
601
+ you can change the program name.
602
+
603
+ :include: ruby/help_program_name.rb
604
+
605
+ Execution:
606
+
607
+ $ ruby help_program_name.rb --help
608
+ Usage: help_program_name.rb [options]
609
+
610
+ You can also change the entire banner.
611
+
612
+ :include: ruby/help_banner.rb
613
+
614
+ Execution:
615
+
616
+ $ ruby help_banner.rb --help
617
+ Usage: ruby help_banner.rb
618
+
619
+ By default, the option names are indented 4 spaces
620
+ and the width of the option-names field is 32 spaces.
621
+
622
+ You can change these values, along with the banner,
623
+ by passing parameters to OptionParser.new.
624
+
625
+ :include: ruby/help_format.rb
626
+
627
+ Execution:
628
+
629
+ $ ruby help_format.rb --help
630
+ ruby help_format.rb [options]
631
+ -x, --xxx Adipiscing elit. Aenean commodo ligula eget.
632
+ Aenean massa. Cum sociis natoque penatibus
633
+ -y, --yyy YYY Lorem ipsum dolor sit amet, consectetuer.
634
+ -z, --zzz [ZZZ] Et magnis dis parturient montes, nascetur
635
+ ridiculus mus. Donec quam felis, ultricies
636
+ nec, pellentesque eu, pretium quis, sem.
637
+
638
+ === Top List and Base List
639
+
640
+ An +OptionParser+ object maintains a stack of OptionParser::List objects,
641
+ each of which has a collection of zero or more options.
642
+ It is unlikely that you'll need to add or take away from that stack.
643
+
644
+ The stack includes:
645
+
646
+ - The <em>top list</em>, given by OptionParser#top.
647
+ - The <em>base list</em>, given by OptionParser#base.
648
+
649
+ When +OptionParser+ builds its help text, the options in the top list
650
+ precede those in the base list.
651
+
652
+ === Methods for Defining Options
653
+
654
+ Option-defining methods allow you to create an option, and also append/prepend it
655
+ to the top list or append it to the base list.
656
+
657
+ Each of these next three methods accepts a sequence of parameter arguments and a block,
658
+ creates an option object using method OptionParser#make_switch (see below),
659
+ and returns the created option:
660
+
661
+ - \Method OptionParser#define appends the created option to the top list.
662
+
663
+ - \Method OptionParser#define_head prepends the created option to the top list.
664
+
665
+ - \Method OptionParser#define_tail appends the created option to the base list.
666
+
667
+ These next three methods are identical to the three above,
668
+ except for their return values:
669
+
670
+ - \Method OptionParser#on is identical to method OptionParser#define,
671
+ except that it returns the parser object +self+.
672
+
673
+ - \Method OptionParser#on_head is identical to method OptionParser#define_head,
674
+ except that it returns the parser object +self+.
675
+
676
+ - \Method OptionParser#on_tail is identical to method OptionParser#define_tail,
677
+ except that it returns the parser object +self+.
678
+
679
+ Though you may never need to call it directly,
680
+ here's the core method for defining an option:
681
+
682
+ - \Method OptionParser#make_switch accepts an array of parameters and a block.
683
+ See {Parameters for New Options}[optparse/option_params.rdoc].
684
+ This method is unlike others here in that it:
685
+ - Accepts an <em>array of parameters</em>;
686
+ others accept a <em>sequence of parameter arguments</em>.
687
+ - Returns an array containing the created option object,
688
+ option names, and other values;
689
+ others return either the created option object
690
+ or the parser object +self+.
691
+
692
+ === Parsing
693
+
694
+ +OptionParser+ has six instance methods for parsing.
695
+
696
+ Three have names ending with a "bang" (<tt>!</tt>):
697
+
698
+ - parse!
699
+ - order!
700
+ - permute!
701
+
702
+ Each of these methods:
703
+
704
+ - Accepts an optional array of string arguments +argv+;
705
+ if not given, +argv+ defaults to the value of OptionParser#default_argv,
706
+ whose initial value is ARGV.
707
+ - Accepts an optional keyword argument +into+
708
+ (see {Keyword Argument into}[#label-Keyword+Argument+into]).
709
+ - Returns +argv+, possibly with some elements removed.
710
+
711
+ The three other methods have names _not_ ending with a "bang":
712
+
713
+ - parse
714
+ - order
715
+ - permute
716
+
717
+ Each of these methods:
718
+
719
+ - Accepts an array of string arguments
720
+ _or_ zero or more string arguments.
721
+ - Accepts an optional keyword argument +into+ and its value _into_.
722
+ (see {Keyword Argument into}[#label-Keyword+Argument+into]).
723
+ - Returns +argv+, possibly with some elements removed.
724
+
725
+ ==== \Method +parse!+
726
+
727
+ \Method +parse!+:
728
+
729
+ - Accepts an optional array of string arguments +argv+;
730
+ if not given, +argv+ defaults to the value of OptionParser#default_argv,
731
+ whose initial value is ARGV.
732
+ - Accepts an optional keyword argument +into+
733
+ (see {Keyword Argument into}[#label-Keyword+Argument+into]).
734
+ - Returns +argv+, possibly with some elements removed.
735
+
736
+ The method processes the elements in +argv+ beginning at <tt>argv[0]</tt>,
737
+ and ending, by default, at the end.
738
+
739
+ Otherwise processing ends and the method returns when:
740
+
741
+ - The terminator argument <tt>--</tt> is found;
742
+ the terminator argument is removed before the return.
743
+ - Environment variable +POSIXLY_CORRECT+ is defined
744
+ and a non-option argument is found;
745
+ the non-option argument is not removed.
746
+ Note that the _value_ of that variable does not matter,
747
+ as only its existence is checked.
748
+
749
+ File +parse_bang.rb+:
750
+
751
+ :include: ruby/parse_bang.rb
752
+
753
+ Help:
754
+
755
+ $ ruby parse_bang.rb --help
756
+ Usage: parse_bang [options]
757
+ --xxx
758
+ --yyy YYY
759
+ --zzz [ZZZ]
760
+
761
+ Default behavior:
762
+
763
+ $ ruby parse_bang.rb input_file.txt output_file.txt --xxx --yyy FOO --zzz BAR
764
+ ["--xxx", true]
765
+ ["--yyy", "FOO"]
766
+ ["--zzz", "BAR"]
767
+ Returned: ["input_file.txt", "output_file.txt"] (Array)
768
+
769
+ Processing ended by terminator argument:
770
+
771
+ $ ruby parse_bang.rb input_file.txt output_file.txt --xxx --yyy FOO -- --zzz BAR
772
+ ["--xxx", true]
773
+ ["--yyy", "FOO"]
774
+ Returned: ["input_file.txt", "output_file.txt", "--zzz", "BAR"] (Array)
775
+
776
+ Processing ended by non-option found when +POSIXLY_CORRECT+ is defined:
777
+
778
+ $ POSIXLY_CORRECT=true ruby parse_bang.rb --xxx input_file.txt output_file.txt -yyy FOO
779
+ ["--xxx", true]
780
+ Returned: ["input_file.txt", "output_file.txt", "-yyy", "FOO"] (Array)
781
+
782
+ ==== \Method +parse+
783
+
784
+ \Method +parse+:
785
+
786
+ - Accepts an array of string arguments
787
+ _or_ zero or more string arguments.
788
+ - Accepts an optional keyword argument +into+ and its value _into_.
789
+ (see {Keyword Argument into}[#label-Keyword+Argument+into]).
790
+ - Returns +argv+, possibly with some elements removed.
791
+
792
+ If given an array +ary+, the method forms array +argv+ as <tt>ary.dup</tt>.
793
+ If given zero or more string arguments, those arguments are formed
794
+ into array +argv+.
795
+
796
+ The method calls
797
+
798
+ parse!(argv, into: into)
799
+
800
+ Note that environment variable +POSIXLY_CORRECT+
801
+ and the terminator argument <tt>--</tt> are honored.
802
+
803
+ File +parse.rb+:
804
+
805
+ :include: ruby/parse.rb
806
+
807
+ Help:
808
+
809
+ $ ruby parse.rb --help
810
+ Usage: parse [options]
811
+ --xxx
812
+ --yyy YYY
813
+ --zzz [ZZZ]
814
+
815
+ Default behavior:
816
+
817
+ $ ruby parse.rb input_file.txt output_file.txt --xxx --yyy FOO --zzz BAR
818
+ ["--xxx", true]
819
+ ["--yyy", "FOO"]
820
+ ["--zzz", "BAR"]
821
+ Returned: ["input_file.txt", "output_file.txt"] (Array)
822
+
823
+ Processing ended by terminator argument:
824
+
825
+ $ ruby parse.rb input_file.txt output_file.txt --xxx --yyy FOO -- --zzz BAR
826
+ ["--xxx", true]
827
+ ["--yyy", "FOO"]
828
+ Returned: ["input_file.txt", "output_file.txt", "--zzz", "BAR"] (Array)
829
+
830
+ Processing ended by non-option found when +POSIXLY_CORRECT+ is defined:
831
+
832
+ $ POSIXLY_CORRECT=true ruby parse.rb --xxx input_file.txt output_file.txt -yyy FOO
833
+ ["--xxx", true]
834
+ Returned: ["input_file.txt", "output_file.txt", "-yyy", "FOO"] (Array)
835
+
836
+ ==== \Method +order!+
837
+
838
+ Calling method OptionParser#order! gives exactly the same result as
839
+ calling method OptionParser#parse! with environment variable
840
+ +POSIXLY_CORRECT+ defined.
841
+
842
+ ==== \Method +order+
843
+
844
+ Calling method OptionParser#order gives exactly the same result as
845
+ calling method OptionParser#parse with environment variable
846
+ +POSIXLY_CORRECT+ defined.
847
+
848
+ ==== \Method +permute!+
849
+
850
+ Calling method OptionParser#permute! gives exactly the same result as
851
+ calling method OptionParser#parse! with environment variable
852
+ +POSIXLY_CORRECT+ _not_ defined.
853
+
854
+ ==== \Method +permute+
855
+
856
+ Calling method OptionParser#permute gives exactly the same result as
857
+ calling method OptionParser#parse with environment variable
858
+ +POSIXLY_CORRECT+ _not_ defined.