[ruby/optparse] 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.

https://github.com/ruby/optparse/commit/39d39676c4

doc/ruby/abbreviation.rb

@@ -0,0 +1,9 @@
+require 'optparse'
+parser = OptionParser.new
+parser.on('-n', '--dry-run',) do |value|
+  p ['--dry-run', value]
+end
+parser.on('-d', '--draft',) do |value|
+  p ['--draft', value]
+end
+parser.parse!

doc/ruby/collected_options.rb

@@ -0,0 +1,8 @@
+require 'optparse'
+parser = OptionParser.new
+parser.on('-x', '--xxx', 'Short and long, no argument')
+parser.on('-yYYY', '--yyy', 'Short and long, required argument')
+parser.on('-z [ZZZ]', '--zzz', 'Short and long, optional argument')
+options = {}
+parser.parse!(into: options)
+p options

doc/ruby/default_values.rb

@@ -0,0 +1,8 @@
+require 'optparse'
+parser = OptionParser.new
+parser.on('-x', '--xxx', 'Short and long, no argument')
+parser.on('-yYYY', '--yyy', 'Short and long, required argument')
+parser.on('-z [ZZZ]', '--zzz', 'Short and long, optional argument')
+options = {yyy: 'AAA', zzz: 'BBB'}
+parser.parse!(into: options)
+p options

doc/ruby/missing_options.rb

@@ -0,0 +1,12 @@
+require 'optparse'
+parser = OptionParser.new
+parser.on('-x', '--xxx', 'Short and long, no argument')
+parser.on('-yYYY', '--yyy', 'Short and long, required argument')
+parser.on('-z [ZZZ]', '--zzz', 'Short and long, optional argument')
+options = {}
+parser.parse!(into: options)
+required_options = [:xxx, :zzz]
+missing_options = required_options - options.keys
+unless missing_options.empty?
+  fail "Missing required options: #{missing_options}"
+end

doc/ruby/no_abbreviation.rb

@@ -0,0 +1,10 @@
+require 'optparse'
+parser = OptionParser.new
+parser.on('-n', '--dry-run',) do |value|
+  p ['--dry-run', value]
+end
+parser.on('-d', '--draft',) do |value|
+  p ['--draft', value]
+end
+parser.require_exact = true
+parser.parse!

doc/tutorial.rdoc

@@ -39,10 +39,15 @@ The class also has:
   - {Short Option Names}[#label-Short+Option+Names]
   - {Long Option Names}[#label-Long+Option+Names]
   - {Mixing Option Names}[#label-Mixing+Option+Names]
+  - {Command-Line Abbreviations}[#label-Command-Line+Abbreviations]
 - {Option Arguments}[#label-Option+Arguments]
   - {Option with No Argument}[#label-Option+with+No+Argument]
   - {Option with Required Argument}[#label-Option+with+Required+Argument]
   - {Option with Optional Argument}[#label-Option+with+Optional+Argument]
+- {Keyword Argument <tt>into<tt>}[#label-Keyword+Argument+into]
+  - {Collecting Options}[#label-Collecting+Options]
+  - {Checking for Missing Options}[#label-Checking+for+Missing+Options]
+  - {Default Values for Options}[#label-Default+Values+for+Options]
 - {Argument Converters}[#label-Argument+Converters]
 
 === Defining Options
@@ -185,6 +190,47 @@ Executions:
   $ ruby mixed_names.rb --zzz BAT
   ["--zzz", "BAT"]
 
+==== Command-Line Abbreviations
+
+By default, abbreviations for command-line option names are allowed.
+An abbreviated option is valid if it is unique among abbreviated option names.
+
+  :include: ruby/abbreviation.rb
+
+Executions:
+
+  $ ruby abbreviation.rb --help
+  Usage: abbreviation [options]
+      -n, --dry-run
+      -d, --draft
+  $ ruby abbreviation.rb -n
+  ["--dry-run", true]
+  $ ruby abbreviation.rb --dry-run
+  ["--dry-run", true]
+  $ ruby abbreviation.rb -d
+  ["--draft", true]
+  $ ruby abbreviation.rb --draft
+  ["--draft", true]
+  $ ruby abbreviation.rb --d
+  abbreviation.rb:9:in `<main>': ambiguous option: --d (OptionParser::AmbiguousOption)
+  $ ruby abbreviation.rb --dr
+  abbreviation.rb:9:in `<main>': ambiguous option: --dr (OptionParser::AmbiguousOption)
+  $ ruby abbreviation.rb --dry
+  ["--dry-run", true]
+  $ ruby abbreviation.rb --dra
+  ["--draft", true]
+
+You can disable abbreviation using method +require_exact+.
+
+  :include: ruby/no_abbreviation.rb
+
+Executions:
+
+  $ ruby no_abbreviation.rb --dry-ru
+  no_abbreviation.rb:10:in `<main>': invalid option: --dry-ru (OptionParser::InvalidOption)
+  $ ruby no_abbreviation.rb --dry-run
+  ["--dry-run", true]
+
 === Option Arguments
 
 An option may take no argument, a required argument, or an optional argument.
@@ -247,12 +293,96 @@ Executions:
 
 Omitting an optional argument does not raise an error.
 
+=== Keyword Argument +into+
+
+In parsing options, you can add keyword option +into+ with a hash-like argument;
+each parsed option will be added as a name/value pair.
+
+This is useful for:
+
+- Collecting options.
+- Checking for missing options.
+- Providing default values for options.
+
+==== Collecting Options
+
+Use keyword argument +into+ to collect options.
+
+  :include: ruby/collected_options.rb
+
+Executions:
+
+  $ ruby collected_options.rb --help
+  Usage: into [options]
+      -x, --xxx                        Short and long, no argument
+      -y, --yyyYYY                     Short and long, required argument
+      -z, --zzz [ZZZ]                  Short and long, optional argument
+  $ ruby collected_options.rb --xxx
+  {:xxx=>true}
+  $ ruby collected_options.rb --xxx --yyy FOO
+  {:xxx=>true, :yyy=>"FOO"}
+  $ ruby collected_options.rb --xxx --yyy FOO --zzz Bar
+  {:xxx=>true, :yyy=>"FOO", :zzz=>"Bar"}
+  $ ruby collected_options.rb --xxx --yyy FOO --yyy BAR
+  {:xxx=>true, :yyy=>"BAR"}
+
+Note in the last execution that the argument value for option <tt>--yyy</tt>
+was overwritten.
+
+==== Checking for Missing Options
+
+Use the collected options to check for missing options.
+
+  :include: ruby/missing_options.rb
+
+Executions:
+
+  $ ruby missing_options.rb --help
+  Usage: missing_options [options]
+      -x, --xxx                        Short and long, no argument
+      -y, --yyyYYY                     Short and long, required argument
+      -z, --zzz [ZZZ]                  Short and long, optional argument
+  $ ruby missing_options.rb --yyy FOO
+  missing_options.rb:11:in `<main>': Missing required options: [:xxx, :zzz] (RuntimeError)
+
+==== Default Values for Options
+
+Initialize the +into+ argument to define default values for options.
+
+  :include: ruby/default_values.rb
+
+Executions:
+
+  $ ruby default_values.rb --help
+  Usage: default_values [options]
+      -x, --xxx                        Short and long, no argument
+      -y, --yyyYYY                     Short and long, required argument
+      -z, --zzz [ZZZ]                  Short and long, optional argument
+  $ ruby default_values.rb --yyy FOO
+  {:yyy=>"FOO", :zzz=>"BBB"}
+
+
 === Argument Converters
 
 An option can specify that its argument is to be converted
 from the default \String to an instance of another class.
-
 There are a number of built-in converters.
-You can also define custom converters.
 
-See {Argument Converters}[./argument_converters_rdoc.html].
+Example: File +date.rb+
+defines an option whose argument is to be converted to a \Date object.
+The argument is converted by method Date#parse.
+
+  :include: ruby/date.rb
+
+Executions:
+
+  $ ruby date.rb --date 2001-02-03
+  [#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date]
+  $ ruby date.rb --date 20010203
+  [#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date]
+  $ ruby date.rb --date "3rd Feb 2001"
+  [#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date]
+
+You can also define custom converters.
+See {Argument Converters}[./argument_converters_rdoc.html]
+for both built-in and custom converters.