Skip to content

Commit 385dd43

Browse files
Tutorial: explain custom argument converters (#19)
1 parent f23d750 commit 385dd43

File tree

4 files changed

+83
-4
lines changed

4 files changed

+83
-4
lines changed

doc/optparse/argument_converters.rdoc

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -345,8 +345,14 @@ Executions:
345345
=== Custom Argument Converters
346346

347347
You can create custom argument converters.
348-
To create a custom converter, call OptionParser#accept with a class argument,
349-
along with a block that converts the argument and returns the converted value.
348+
To create a custom converter, call OptionParser#accept with:
349+
350+
- An identifier, which may be any object.
351+
- An optional match pattern, which defaults to <tt>/.*/m</tt>.
352+
- A block that accepts the argument and returns the converted value.
353+
354+
This custom converter accepts any argument and converts it,
355+
if possible, to a \Complex object.
350356

351357
:include: ruby/custom_converter.rb
352358

@@ -360,3 +366,15 @@ Executions:
360366
[(1+2i), Complex]
361367
$ ruby custom_converter.rb --complex 0.3-0.5i
362368
[(0.3-0.5i), Complex]
369+
370+
This custom converter accepts any 1-word argument
371+
and capitalizes it, if possible.
372+
373+
:include: ruby/match_converter.rb
374+
375+
Executions:
376+
377+
$ ruby match_converter.rb --capitalize foo
378+
["Foo", String]
379+
$ ruby match_converter.rb --capitalize "foo bar"
380+
match_converter.rb:9:in `<main>': invalid argument: --capitalize foo bar (OptionParser::InvalidArgument)

doc/optparse/ruby/basic.rb

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Require the OptionParser code.
2+
require 'optparse'
3+
# Create an OptionParser object.
4+
parser = OptionParser.new
5+
# Define one or more options.
6+
parser.on('-x', 'Whether to X') do |value|
7+
p ['x', value]
8+
end
9+
parser.on('-y', 'Whether to Y') do |value|
10+
p ['y', value]
11+
end
12+
parser.on('-z', 'Whether to Z') do |value|
13+
p ['z', value]
14+
end
15+
# Parse the command line.
16+
parser.parse!
Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
require 'optparse/date'
2+
parser = OptionParser.new
3+
parser.accept(:capitalize, /\w*/) do |value|
4+
value.capitalize
5+
end
6+
parser.on('--capitalize XXX', :capitalize) do |value|
7+
p [value, value.class]
8+
end
9+
parser.parse!

doc/optparse/tutorial.rdoc

Lines changed: 38 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
== Tutorial
22

3-
=== Why OptionParser?
3+
=== Why \OptionParser?
44

55
When a Ruby program executes, it captures its command-line arguments
66
and options into variable ARGV.
@@ -34,6 +34,7 @@ The class also has:
3434

3535
=== Contents
3636

37+
- {To Begin With}[#label-To+Begin+With]
3738
- {Defining Options}[#label-Defining+Options]
3839
- {Option Names}[#label-Option+Names]
3940
- {Short Option Names}[#label-Short+Option+Names]
@@ -50,6 +51,42 @@ The class also has:
5051
- {Default Values for Options}[#label-Default+Values+for+Options]
5152
- {Argument Converters}[#label-Argument+Converters]
5253

54+
=== To Begin With
55+
56+
To use \OptionParser:
57+
58+
1. Require the \OptionParser code.
59+
2. Create an \OptionParser object.
60+
3. Define one or more options.
61+
4. Parse the command line.
62+
63+
File +basic.rb+ defines three options, <tt>-x</tt>,
64+
<tt>-y</tt>, and <tt>-z</tt>, each with a descriptive string,
65+
and each with a block.
66+
67+
:include: ruby/basic.rb
68+
69+
From these defined options, the parser automatically builds help text:
70+
71+
$ ruby basic.rb --help
72+
Usage: basic [options]
73+
-x Whether to X
74+
-y Whether to Y
75+
-z Whether to Z
76+
77+
When an option is found during parsing,
78+
the block defined for the option is called with the argument value.
79+
80+
Executions:
81+
82+
$ ruby basic.rb -x -z
83+
["x", true]
84+
["z", true]
85+
$ ruby basic.rb -z -y -x
86+
["z", true]
87+
["y", true]
88+
["x", true]
89+
5390
=== Defining Options
5491

5592
A common way to define an option in \OptionParser
@@ -361,7 +398,6 @@ Executions:
361398
$ ruby default_values.rb --yyy FOO
362399
{:yyy=>"FOO", :zzz=>"BBB"}
363400

364-
365401
=== Argument Converters
366402

367403
An option can specify that its argument is to be converted

0 commit comments

Comments
 (0)