[ruby/optparse] Tutorial: explain custom argument converters (https://github.com/ruby/optparse/pull/19)

https://github.com/ruby/optparse/commit/385dd4322d

doc/optparse/argument_converters.rdoc

@@ -345,8 +345,14 @@ Executions:
 === Custom Argument Converters
 
 You can create custom argument converters.
-To create a custom converter, call OptionParser#accept with a class argument,
-along with a block that converts the argument and returns the converted value.
+To create a custom converter, call OptionParser#accept with:
+
+- An identifier, which may be any object.
+- An optional match pattern, which defaults to <tt>/.*/m</tt>.
+- A block that accepts the argument and returns the converted value.
+
+This custom converter accepts any argument and converts it,
+if possible, to a \Complex object.
 
   :include: ruby/custom_converter.rb
 
@@ -360,3 +366,15 @@ Executions:
   [(1+2i), Complex]
   $ ruby custom_converter.rb --complex 0.3-0.5i
   [(0.3-0.5i), Complex]
+
+This custom converter accepts any 1-word argument
+and capitalizes it, if possible.
+
+  :include: ruby/match_converter.rb
+
+Executions:
+
+  $ ruby match_converter.rb --capitalize foo
+  ["Foo", String]
+  $ ruby match_converter.rb --capitalize "foo bar"
+  match_converter.rb:9:in `<main>': invalid argument: --capitalize foo bar (OptionParser::InvalidArgument)

doc/optparse/ruby/basic.rb

@@ -0,0 +1,16 @@
+# Require the OptionParser code.
+require 'optparse'
+# Create an OptionParser object.
+parser = OptionParser.new
+# Define one or more options.
+parser.on('-x', 'Whether to X') do |value|
+  p ['x', value]
+end
+parser.on('-y', 'Whether to Y') do |value|
+  p ['y', value]
+end
+parser.on('-z', 'Whether to Z') do |value|
+  p ['z', value]
+end
+# Parse the command line.
+parser.parse!

doc/optparse/ruby/match_converter.rb

@@ -0,0 +1,9 @@
+require 'optparse/date'
+parser = OptionParser.new
+parser.accept(:capitalize, /\w*/) do |value|
+  value.capitalize
+end
+parser.on('--capitalize XXX', :capitalize) do |value|
+  p [value, value.class]
+end
+parser.parse!

doc/optparse/tutorial.rdoc

@@ -1,6 +1,6 @@
 == Tutorial
 
-=== Why OptionParser?
+=== Why \OptionParser?
 
 When a Ruby program executes, it captures its command-line arguments
 and options into variable ARGV.
@@ -34,6 +34,7 @@ The class also has:
 
 === Contents
 
+- {To Begin With}[#label-To+Begin+With]
 - {Defining Options}[#label-Defining+Options]
 - {Option Names}[#label-Option+Names]
   - {Short Option Names}[#label-Short+Option+Names]
@@ -50,6 +51,42 @@ The class also has:
   - {Default Values for Options}[#label-Default+Values+for+Options]
 - {Argument Converters}[#label-Argument+Converters]
 
+=== To Begin With
+
+To use \OptionParser:
+
+1. Require the \OptionParser code.
+2. Create an \OptionParser object.
+3. Define one or more options.
+4. Parse the command line.
+
+File +basic.rb+ defines three options, <tt>-x</tt>,
+<tt>-y</tt>, and <tt>-z</tt>, each with a descriptive string,
+and each with a block.
+
+  :include: ruby/basic.rb
+
+From these defined options, the parser automatically builds help text:
+
+  $ ruby basic.rb --help
+  Usage: basic [options]
+      -x                               Whether to X
+      -y                               Whether to Y
+      -z                               Whether to Z
+
+When an option is found during parsing,
+the block defined for the option is called with the argument value.
+
+Executions:
+
+  $ ruby basic.rb -x -z
+  ["x", true]
+  ["z", true]
+  $ ruby basic.rb -z -y -x
+  ["z", true]
+  ["y", true]
+  ["x", true]
+
 === Defining Options
 
 A common way to define an option in \OptionParser
@@ -361,7 +398,6 @@ Executions:
   $ ruby default_values.rb --yyy FOO
   {:yyy=>"FOO", :zzz=>"BBB"}
 
-
 === Argument Converters
 
 An option can specify that its argument is to be converted