8000 More on tutorial (#16) · ruby/optparse@39d3967 · GitHub
[go: up one dir, main page]
Skip to content

Commit 39d3967

Browse files
BurdetteLamarBurdetteLamar
authored
More on tutorial (#16)
- Added example in "Argument Converters"; it doesn't seem right for a tutorial to have no example in one of its topics (and instead just linking elsewhere). - Added section "Command-Line Abbreviations." - Added section "Keyword Argument into," showing how to: - Collect options. - Check for missing options. - Provide option defaults.
1 parent c91ed8d commit 39d3967

File tree

6 files changed

+180
-3
lines changed

6 files changed

+180
-3
lines changed

‎doc/ruby/abbreviation.rb

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
require 'optparse'
2+
parser = OptionParser.new
3+
parser.on('-n', '--dry-run',) do |value|
4+
p ['--dry-run', value]
5+
end
6+
parser.on('-d', '--draft',) do |value|
7+
p ['--draft', value]
8+
end
9+
parser.parse!

‎doc/ruby/collected_options.rb

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
require 'optparse'
2+
parser = OptionParser.new
3+
parser.on('-x', '--xxx', 'Short and long, no argument')
4+
parser.on('-yYYY', '--yyy', 'Short and long, required argument')
5+
parser.on('-z [ZZZ]', '--zzz', 'Short and long, optional argument')
6+
options = {}
7+
parser.parse!(into: options)
8+
p options

‎doc/ruby/default_values.rb

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
require 'optparse'
2+
parser = OptionParser.new
3+
parser.on('-x', '--xxx', 'Short and long, no argument')
4+
parser.on('-yYYY', '--yyy', 'Short and long, required argument')
5+
parser.on('-z [ZZZ]', '--zzz', 'Short and long, optional argument')
6+
options = {yyy: 'AAA', zzz: 'BBB'}
7+
parser.parse!(into: options)
8+
p options

‎doc/ruby/missing_options.rb

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
require 'optparse'
2+
parser = OptionParser.new
3+
parser.on('-x', '--xxx', 'Short and long, no argument')
4+
parser.on('-yYYY', '--yyy', 'Short and long, required argument')
5+
parser.on('-z [ZZZ]', '--zzz', 'Short and long, optional argument')
6+
options = {}
7+
parser.parse!(into: options)
8+
required_options = [:xxx, :zzz]
9+
missing_options = required_options - options.keys
10+
unless missing_options.empty?
11+
fail "Missing required options: #{missing_options}"
12+
end

‎doc/ruby/no_abbreviation.rb

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
require 'optparse'
2+
parser = OptionParser.new
3+
parser.on('-n', '--dry-run',) do |value|
4+
p ['--dry-run', value]
5+
end
6+
parser.on('-d', '--draft',) do |value|
7+
p ['--draft', value]
8+
end
9+
parser.require_exact = true
10+
parser.parse!

‎doc/tutorial.rdoc

Lines changed: 133 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -39,10 +39,15 @@ The class also has:
3939
- {Short Option Names}[#label-Short+Option+Names]
4040
- {Long Option Names}[#label-Long+Option+Names]
4141
- {Mixing Option Names}[#label-Mixing+Option+Names]
42+
- {Command-Line Abbreviations}[#label-Command-Line+Abbreviations]
4243
- {Option Arguments}[#label-Option+Arguments]
4344
- {Option with No Argument}[#label-Option+with+No+Argument]
4445
- {Option with Required Argument}[#label-Option+with+Required+Argument]
4546
- {Option with Optional Argument}[#label-Option+with+Optional+Argument]
47+
- {Keyword Argument <tt>into<tt>}[#label-Keyword+Argument+into]
48+
- {Collecting Options}[#label-Collecting+Options]
49+
- {Checking for Missing Options}[#label-Checking+for+Missing+Options]
50+
- {Default Values for Options}[#label-Default+Values+for+Options]
4651
- {Argument Converters}[#label-Argument+Converters]
4752

4853
=== Defining Options
@@ -185,6 +190,47 @@ Executions:
185190
$ ruby mixed_names.rb --zzz BAT
186191
["--zzz", "BAT"]
187192

193+
==== Command-Line Abbreviations
194+
195+
By default, abbreviations for command-line option names are allowed.
196+
An abbreviated option is valid if it is unique among abbreviated option names.
197+
198+
:include: ruby/abbreviation.rb
199+
200+
Executions:
201+
202+
$ ruby abbreviation.rb --help
203+
Usage: abbreviation [options]
204+
-n, --dry-run
205+
-d, --draft
206+
$ ruby abbreviation.rb -n
207+
["--dry-run", true]
208+
$ ruby abbreviation.rb --dry-run
209+
["--dry-run", true]
210+
$ ruby abbreviation.rb -d
211+
["--draft", true]
212+
$ ruby abbreviation.rb --draft
213+
["--draft", true]
214+
$ ruby abbreviation.rb --d
215+
abbreviation.rb:9:in `<main>': ambiguous option: --d (OptionParser::AmbiguousOption)
216+
$ ruby abbreviation.rb --dr
217+
abbreviation.rb:9:in `<main>': ambiguous option: --dr (OptionParser::AmbiguousOption)
218+
$ ruby abbreviation.rb --dry
219+
["--dry-run", true]
220+
$ ruby abbreviation.rb --dra
221+
["--draft", true]
222+
223+
You can disable abbreviation using method +require_exact+.
224+
225+
:include: ruby/no_abbreviation.rb
226+
227+
Executions:
228+
229+
$ ruby no_abbreviation.rb --dry-ru
230+
no_abbreviation.rb:10:in `<main>': invalid option: --dry-ru (OptionParser::InvalidOption)
231+
$ ruby no_abbreviation.rb --dry-run
232+
["--dry-run", true]
233+
188234
=== Option Arguments
189235

190236
An option may take no argument, a required argument, or an optional argument.
@@ -247,12 +293,96 @@ Executions:
247293

248294
Omitting an optional argument does not raise an error.
249295

296+
=== Keyword Argument +into+
297+
298+
In parsing options, you can add keyword option +into+ with a hash-like argument;
299+
each parsed option will be added as a name/value pair.
300+
301+
This is useful for:
302+
303+
- Collecting options.
304+
- Checking for missing options.
305+
- Providing default values for options.
306+
307+
==== Collecting Options
308+
309+
Use keyword argument +into+ to collect options.
310+
311+
:include: ruby/collected_options.rb
312+
313+
Executions:
314+
315+
$ ruby collected_options.rb --help
316+
Usage: into [options]
317+
-x, --xxx Short and long, no argument
318+
-y, --yyyYYY Short and long, required argument
319+
-z, --zzz [ZZZ] Short and long, optional argument
320+
$ ruby collected_options.rb --xxx
321+
{:xxx=>true}
322+
$ ruby collected_options.rb --xxx --yyy FOO
323+
{:xxx=>true, :yyy=>"FOO"}
324+
$ ruby collected_options.rb --xxx --yyy FOO --zzz Bar
325+
{:xxx=>true, :yyy=>"FOO", :zzz=>"Bar"}
326+
$ ruby collected_options.rb --xxx --yyy FOO --yyy BAR
327+
{:xxx=>true, :yyy=>"BAR"}
328+
329+
Note in the last execution that the argument value for option <tt>--yyy</tt>
330+
was overwritten.
331+
332+
==== Checking for Missing Options
333+
334+
Use the collected options to check for missing options.
335+
336+
:include: ruby/missing_options.rb
337+
338+
Executions:
339+
340+
$ ruby missing_options.rb --help
341+
Usage: missing_options [options]
342+
-x, --xxx Short and long, no argument
343+
-y, --yyyYYY Short and long, required argument
344+
-z, --zzz [ZZZ] Short and long, optional argument
345+
$ ruby missing_options.rb --yyy FOO
346+
missing_options.rb:11:in `<main>': Missing required options: [:xxx, :zzz] (RuntimeError)
347+
348+
==== Default Values for Options
349+
350+
Initialize the +into+ argument to define default values for options.
351+
352+
:include: ruby/default_values.rb
353+
354+
Executions:
355+
356+
$ ruby default_values.rb --help
357+
Usage: default_values [options]
358+
-x, --xxx Short and long, no argument
359+
-y, --yyyYYY Short and long, required argument
360+
-z, --zzz [ZZZ] Short and long, optional argument
361+
$ ruby default_values.rb --yyy FOO
362+
{:yyy=>"FOO", :zzz=>"BBB"}
363+
364+
250365
=== Argument Converters
251366

252367
An option can specify that its argument is to be converted
253368
from the default \String to an instance of another class.
254-
255369
There are a number of built-in converters.
256-
You can also define custom converters.
257370

258-
See {Argument Converters}[./argument_converters_rdoc.html].
371+
Example: File +date.rb+
372+
defines an option whose argument is to be converted to a \Date object.
373+
The argument is converted by method Date#parse.
374+
375+
:include: ruby/date.rb
376+
377+
Executions:
378+
379+
$ ruby date.rb --date 2001-02-03
380+
[#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date]
381+
$ ruby date.rb --date 20010203
382+
[#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date]
383+
$ ruby date.rb --date "3rd Feb 2001"
384+
[#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date]
385+
386+
You can also define custom converters.
387+
See {Argument Converters}[./argument_converters_rdoc.html]
388+
for both built-in and custom converters.

0 commit comments

Comments
 (0)
0