Manually picking https://github.com/ruby/optparse/pull/14

44 files changed, 0 insertions, 1339 deletions

diff --git a/doc/option_params/argument_keywords.rb b/doc/option_params/argument_keywords.rb
deleted file mode 100644
index 8533257c67..0000000000
--- a/doc/option_params/argument_keywords.rb
+++ /dev/null
@@ -1,6 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('-x', '--xxx', :REQUIRED, 'Required argument') do |value|
-  p ['--xxx', value]
-end
-parser.parse!
diff --git a/doc/option_params/argument_strings.rb b/doc/option_params/argument_strings.rb
deleted file mode 100644
index 77861dda30..0000000000
--- a/doc/option_params/argument_strings.rb
+++ /dev/null
@@ -1,6 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('-x', '--xxx', '=XXX', 'Required argument') do |value|
-  p ['--xxx', value]
-end
-parser.parse!
diff --git a/doc/option_params/array.rb b/doc/option_params/array.rb
deleted file mode 100644
index 7c6c14fad4..0000000000
--- a/doc/option_params/array.rb
+++ /dev/null
@@ -1,6 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('--array=ARRAY', Array) do |value|
-  p [value, value.class]
-end
-parser.parse!
diff --git a/doc/option_params/block.rb b/doc/option_params/block.rb
deleted file mode 100644
index c4dfdeb31e..0000000000
--- a/doc/option_params/block.rb
+++ /dev/null
@@ -1,9 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('--xxx', 'Option with no argument') do |value|
-  p ['Handler block for -xxx called with value:', value]
-end
-parser.on('--yyy YYY', 'Option with required argument') do |value|
-  p ['Handler block for -yyy called with value:', value]
-end
-parser.parse!
diff --git a/doc/option_params/date.rb b/doc/option_params/date.rb
deleted file mode 100644
index 5994ad6a85..0000000000
--- a/doc/option_params/date.rb
+++ /dev/null
@@ -1,6 +0,0 @@
-require 'optparse/date'
-parser = OptionParser.new
-parser.on('--date=DATE', Date) do |value|
-  p [value, value.class]
-end
-parser.parse!
diff --git a/doc/option_params/datetime.rb b/doc/option_params/datetime.rb
deleted file mode 100644
index b9b591d5f6..0000000000
--- a/doc/option_params/datetime.rb
+++ /dev/null
@@ -1,6 +0,0 @@
-require 'optparse/date'
-parser = OptionParser.new
-parser.on('--datetime=DATETIME', DateTime) do |value|
-  p [value, value.class]
-end
-parser.parse!
diff --git a/doc/option_params/decimal_integer.rb b/doc/option_params/decimal_integer.rb
deleted file mode 100644
index 360bd284f8..0000000000
--- a/doc/option_params/decimal_integer.rb
+++ /dev/null
@@ -1,7 +0,0 @@
-require 'optparse'
-include OptionParser::Acceptables
-parser = OptionParser.new
-parser.on('--decimal_integer=DECIMAL_INTEGER', DecimalInteger) do |value|
-  p [value, value.class]
-end
-parser.parse!
diff --git a/doc/option_params/decimal_numeric.rb b/doc/option_params/decimal_numeric.rb
deleted file mode 100644
index 954da13561..0000000000
--- a/doc/option_params/decimal_numeric.rb
+++ /dev/null
@@ -1,7 +0,0 @@
-require 'optparse'
-include OptionParser::Acceptables
-parser = OptionParser.new
-parser.on('--decimal_numeric=DECIMAL_NUMERIC', DecimalNumeric) do |value|
-  p [value, value.class]
-end
-parser.parse!
diff --git a/doc/option_params/descriptions.rb b/doc/option_params/descriptions.rb
deleted file mode 100644
index 9aec80aae2..0000000000
--- a/doc/option_params/descriptions.rb
+++ /dev/null
@@ -1,15 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-description = <<-EOT
-Lorem ipsum dolor sit amet, consectetuer
-adipiscing elit. Aenean commodo ligula eget.
-Aenean massa. Cum sociis natoque penatibus
-et magnis dis parturient montes, nascetur
-ridiculus mus. Donec quam felis, ultricies
-nec, pellentesque eu, pretium quis, sem.
-EOT
-descriptions = description.split($/)
-parser.on('--xxx', *descriptions) do |value|
-  p ['--xxx', value]
-end
-parser.parse!
diff --git a/doc/option_params/explicit_array_values.rb b/doc/option_params/explicit_array_values.rb
deleted file mode 100644
index 64f930a4bc..0000000000
--- a/doc/option_params/explicit_array_values.rb
+++ /dev/null
@@ -1,9 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('-xXXX', ['foo', 'bar'], 'Values for required argument' ) do |value|
-  p ['-x', value]
-end
-parser.on('-y [YYY]', ['baz', 'bat'], 'Values for optional argument') do |value|
-  p ['-y', value]
-end
-parser.parse!
diff --git a/doc/option_params/explicit_hash_values.rb b/doc/option_params/explicit_hash_values.rb
deleted file mode 100644
index 9c9e6a48ed..0000000000
--- a/doc/option_params/explicit_hash_values.rb
+++ /dev/null
@@ -1,9 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('-xXXX', {foo: 0, bar: 1}, 'Values for required argument' ) do |value|
-  p ['-x', value]
-end
-parser.on('-y [YYY]', {baz: 2, bat: 3}, 'Values for optional argument') do |value|
-  p ['-y', value]
-end
-parser.parse!
diff --git a/doc/option_params/false_class.rb b/doc/option_params/false_class.rb
deleted file mode 100644
index 04fe335ede..0000000000
--- a/doc/option_params/false_class.rb
+++ /dev/null
@@ -1,6 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('--false_class=FALSE_CLASS', FalseClass) do |value|
-  p [value, value.class]
-end
-parser.parse!
diff --git a/doc/option_params/float.rb b/doc/option_params/float.rb
deleted file mode 100644
index 390df7f7bd..0000000000
--- a/doc/option_params/float.rb
+++ /dev/null
@@ -1,6 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('--float=FLOAT', Float) do |value|
-  p [value, value.class]
-end
-parser.parse!
diff --git a/doc/option_params/integer.rb b/doc/option_params/integer.rb
deleted file mode 100644
index f10656ff1a..0000000000
--- a/doc/option_params/integer.rb
+++ /dev/null
@@ -1,6 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('--integer=INTEGER', Integer) do |value|
-  p [value, value.class]
-end
-parser.parse!
diff --git a/doc/option_params/long_binary.rb b/doc/option_params/long_binary.rb
deleted file mode 100644
index 8eccecaf3a..0000000000
--- a/doc/option_params/long_binary.rb
+++ /dev/null
@@ -1,6 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('--[no-]binary') do |value|
-  p [value, value.class]
-end
-parser.parse!
diff --git a/doc/option_params/long_optional.rb b/doc/option_params/long_optional.rb
deleted file mode 100644
index 38dd82166b..0000000000
--- a/doc/option_params/long_optional.rb
+++ /dev/null
@@ -1,6 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('--xxx [XXX]', 'Long name with optional argument') do |value|
-  p ['--xxx', value]
-end
-parser.parse!
diff --git a/doc/option_params/long_required.rb b/doc/option_params/long_required.rb
deleted file mode 100644
index b76c997339..0000000000
--- a/doc/option_params/long_required.rb
+++ /dev/null
@@ -1,6 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('--xxx XXX', 'Long name with required argument') do |value|
-  p ['--xxx', value]
-end
-parser.parse!
diff --git a/doc/option_params/long_simple.rb b/doc/option_params/long_simple.rb
deleted file mode 100644
index 4e489c43ed..0000000000
--- a/doc/option_params/long_simple.rb
+++ /dev/null
@@ -1,9 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('--xxx', 'One long name') do |value|
-  p ['--xxx', value]
-end
-parser.on('--y1%', '--z2#', 'Two long names (aliases)') do |value|
-  p ['--y1% or --z2#', value]
-end
-parser.parse!
diff --git a/doc/option_params/matched_values.rb b/doc/option_params/matched_values.rb
deleted file mode 100644
index f184ca8474..0000000000
--- a/doc/option_params/matched_values.rb
+++ /dev/null
@@ -1,6 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('--xxx XXX', /foo/i, 'Matched values') do |value|
-  p ['--xxx', value]
-end
-parser.parse!
diff --git a/doc/option_params/method.rb b/doc/option_params/method.rb
deleted file mode 100644
index 3f02ff5798..0000000000
--- a/doc/option_params/method.rb
+++ /dev/null
@@ -1,11 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-def xxx_handler(value)
-  p ['Handler method for -xxx called with value:', value]
-end
-parser.on('--xxx', 'Option with no argument', method(:xxx_handler))
-def yyy_handler(value)
-  p ['Handler method for -yyy called with value:', value]
-end
-parser.on('--yyy YYY', 'Option with required argument', method(:yyy_handler))
-parser.parse!
diff --git a/doc/option_params/mixed_names.rb b/doc/option_params/mixed_names.rb
deleted file mode 100644
index fe6c554bdc..0000000000
--- a/doc/option_params/mixed_names.rb
+++ /dev/null
@@ -1,12 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('-x', '--xxx', 'Short and long, simple') do |value|
-  p ['--xxx', value]
-end
-parser.on('-yYYY', '--yyy', 'Short and long, required argument') do |value|
-  p ['--yyy', value]
-end
-parser.on('-z [ZZZ]', '--zzz', 'Short and long, optional argument') do |value|
-  p ['--zzz', value]
-end
-parser.parse!
diff --git a/doc/option_params/numeric.rb b/doc/option_params/numeric.rb
deleted file mode 100644
index d7021f154a..0000000000
--- a/doc/option_params/numeric.rb
+++ /dev/null
@@ -1,6 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('--numeric=NUMERIC', Numeric) do |value|
-  p [value, value.class]
-end
-parser.parse!
diff --git a/doc/option_params/object.rb b/doc/option_params/object.rb
deleted file mode 100644
index 0f5ae8b922..0000000000
--- a/doc/option_params/object.rb
+++ /dev/null
@@ -1,6 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('--object=OBJECT', Object) do |value|
-  p [value, value.class]
-end
-parser.parse!
diff --git a/doc/option_params/octal_integer.rb b/doc/option_params/octal_integer.rb
deleted file mode 100644
index b9644a076b..0000000000
--- a/doc/option_params/octal_integer.rb
+++ /dev/null
@@ -1,7 +0,0 @@
-require 'optparse'
-include OptionParser::Acceptables
-parser = OptionParser.new
-parser.on('--octal_integer=OCTAL_INTEGER', OctalInteger) do |value|
-  p [value, value.class]
-end
-parser.parse!
diff --git a/doc/option_params/option_params.rdoc b/doc/option_params/option_params.rdoc
deleted file mode 100644
index 7cf5ef890c..0000000000
--- a/doc/option_params/option_params.rdoc
+++ /dev/null
@@ -1,845 +0,0 @@
-== Parameters for New Options
-
-Option-creating methods in \OptionParser
-accept arguments that determine the behavior of a new option:
-
-- OptionParser#on
-- OptionParser#on_head
-- OptionParser#on_tail
-- OptionParser#define
-- OptionParser#define_head
-- OptionParser#define_tail
-- OptionParser#make_switch
-
-The code examples on this page use:
-
-- OptionParser#on, to define options.
-- OptionParser#parse!, to parse the command line.
-- Built-in option <tt>--help</tt>, to display defined options.
-
-Contents:
-
-- {Option Names}[#label-Option+Names]
-  - {Short Names}[#label-Short+Names]
-    - {Simple Short Names}[#label-Simple+Short+Names]
-    - {Short Names with Required Arguments}[#label-Short+Names+with+Required+Arguments]
-    - {Short Names with Optional Arguments}[#label-Short+Names+with+Optional+Arguments]
-    - {Short Names from Range}[#label-Short+Names+from+Range]
-  - {Long Names}[#label-Long+Names]
-    - {Simple Long Names}[#label-Simple+Long+Names]
-    - {Long Names with Required Arguments}[#label-Long+Names+with+Required+Arguments]
-    - {Long Names with Optional Arguments}[#label-Long+Names+with+Optional+Arguments]
-  - {Mixed Names}[#label-Mixed+Names]
-- {Argument Styles}[#label-Argument+Styles]
-- {Argument Values}[#label-Argument+Values]
-  - {Explicit Argument Values}[#label-Explicit+Argument+Values]
-    - {Explicit Values in Array}[#label-Explicit+Values+in+Array]
-    - {Explicit Values in Hash}[#label-Explicit+Values+in+Hash]
-  - {Argument Value Patterns}[#label-Argument+Value+Patterns]
-- {Argument Converters}[#label-Argument+Converters]
-  - {Date}[#label-Date]
-  - {DateTime}[#label-DateTime]
-  - {Time}[#label-Time]
-  - {URI}[#label-URI]
-  - {Shellwords}[#label-Shellwords]
-  - {Integer}[#label-Integer]
-  - {Float}[#label-Float]
-  - {Numeric}[#label-Numeric]
-  - {DecimalInteger}[#label-DecimalInteger]
-  - {OctalInteger}[#label-OctalInteger]
-  - {DecimalNumeric}[#label-DecimalNumeric]
-  - {TrueClass}[#label-TrueClass]
-  - {FalseClass}[#label-FalseClass]
-  - {Object}[#label-Object]
-  - {String}[#label-String]
-  - {Array}[#label-Array]
-  - {Regexp}[#label-Regexp]
-- {Descriptions}[#label-Descriptions]
-- {Handlers}[#label-Handlers]
-  - {Handler Blocks}[#label-Handler+Blocks]
-  - {Handler Procs}[#label-Handler+Procs]
-  - {Handler Methods}[#label-Handler+Methods]
-- {Terminators}[#label-Terminators]
-
-=== Option Names
-
-There are two kinds of option names:
-
-- Short option name, consisting of a single hyphen and a single character.
-- Long option name, consisting of two hyphens and one or more characters.
-
-==== Short Names
-
-===== Simple Short Names
-
-File +short_simple.rb+ defines two options:
-
-- One with short name <tt>-x</tt>.
-- The other with two short names, in effect, aliases, <tt>-1</tt> and <tt>-%</tt>.
-
- :include: short_simple.rb
-
-Executions:
-
-  $ ruby short_simple.rb --help
-  Usage: short_simple [options]
-      -x                               One short name
-      -1, -%                           Two short names (aliases)
-  $ ruby short_simple.rb -x
-  ["-x", true]
-  $ ruby short_simple.rb -1 -x -%
-  ["-1 or -%", true]
-  ["-x", true]
-  ["-1 or -%", true]
-
-===== Short Names with Required Arguments
-
-A short name followed (no whitespace) by a dummy word
-defines an option that requires an argument.
-
-File +short_required.rb+ defines an option <tt>-x</tt>
-that requires an argument.
-
-  :include: short_required.rb
-
-Executions:
-
-  $ ruby short_required.rb --help
-  Usage: short_required [options]
-      -xXXX                            Short name with required argument
-  $ ruby short_required.rb -x
-  short_required.rb:6:in `<main>': missing argument: -x (OptionParser::MissingArgument)
-  $ ruby short_required.rb -x FOO
-  ["-x", "FOO"]
-
-===== Short Names with Optional Arguments
-
-A short name followed (with whitespace) by a dummy word in square brackets
-defines an option that allows an optional argument.
-
-File +short_optional.rb+ defines an option <tt>-x</tt>
-that allows an optional argument.
-
-  :include: short_optional.rb
-
-Executions:
-
-  $ ruby short_optional.rb --help
-  Usage: short_optional [options]
-      -x [XXX]                         Short name with optional argument
-  $ ruby short_optional.rb -x
-  ["-x", nil]
-  $ ruby short_optional.rb -x FOO
-  ["-x", "FOO"]
-
-===== Short Names from Range
-
-You can define an option with multiple short names
-taken from a range of characters.
-The parser yields both the actual character cited and the value.
-
-File +short_range.rb+ defines an option with short names
-for all printable characters from <tt>!</tt> to <tt>~</tt>:
-
-  :include: short_range.rb
-
-Executions:
-
-  $ ruby short_range.rb --help
-  Usage: short_range [options]
-      -[!-~]                           Short names in (very large) range
-  $ ruby short_range.rb -!
-  ["!-~", "!", nil]
-  $ ruby short_range.rb -!
-  ["!-~", "!", nil]
-  $ ruby short_range.rb -A
-  ["!-~", "A", nil]
-  $ ruby short_range.rb -z
-  ["!-~", "z", nil]
-
-==== Long Names
-
-===== Simple Long Names
-
-File +long_simple.rb+ defines two options:
-
-- One with long name <tt>-xxx</tt>.
-- The other with two long names, in effect, aliases,
-  <tt>--y1%</tt> and <tt>--z2#</tt>.
-
-  :include: long_simple.rb
-
-Executions:
-
-  $ ruby long_simple.rb --help
-  Usage: long_simple [options]
-          --xxx                        One long name
-          --y1%, --z2#                 Two long names (aliases)
-  $ ruby long_simple.rb --xxx
-  ["--xxx", true]
-  $ ruby long_simple.rb --y1% --xxx --z2#
-  ["--y1% or --z2#", true]
-  ["--xxx", true]
-  ["--y1% or --z2#", true]
-
-===== Long Names with Required Arguments
-
-A long name followed (with whitespace) by a dummy word
-defines an option that requires an argument.
-
-File +long_required.rb+ defines an option <tt>--xxx</tt>
-that requires an argument.
-
-  :include: long_required.rb
-
-Executions:
-
-  $ ruby long_required.rb --help
-  Usage: long_required [options]
-          --xxx XXX                    Long name with required argument
-  $ ruby long_required.rb --xxx
-  long_required.rb:6:in `<main>': missing argument: --xxx (OptionParser::MissingArgument)
-  $ ruby long_required.rb --xxx FOO
-  ["--xxx", "FOO"]
-
-===== Long Names with Optional Arguments
-
-A long name followed (with whitespace) by a dummy word in square brackets
-defines an option that allows an optional argument.
-
-File +long_optional.rb+ defines an option <tt>--xxx</tt>
-that allows an optional argument.
-
-  :include: long_optional.rb
-
-Executions:
-
-  $ ruby long_optional.rb --help
-  Usage: long_optional [options]
-          --xxx [XXX]                  Long name with optional argument
-  $ ruby long_optional.rb --xxx
-  ["--xxx", nil]
-  $ ruby long_optional.rb --xxx FOO
-  ["--xxx", "FOO"]
-
-==== Mixed Names
-
-An option may have both short and long names.
-
-File +mixed_names.rb+ defines a mixture of short and long names.
-
-  :include: mixed_names.rb
-
-Executions:
-
-  $ ruby mixed_names.rb --help
-  Usage: mixed_names [options]
-      -x, --xxx                        Short and long, simple
-          --yyy                        yYYY
-                                       Short and long, required argument
-          --zzz                        zZZZ
-                                       Short and long, optional argument
-  $ ruby mixed_names.rb -x
-  ["--xxx", true]
-  $ ruby mixed_names.rb --xxx
-  ["--xxx", true]
-  $ ruby mixed_names.rb -y
-  mixed_names.rb:12:in `<main>': missing argument: -y (OptionParser::MissingArgument)
-  $ ruby mixed_names.rb -y FOO
-  ["--yyy", "FOO"]
-  $ ruby mixed_names.rb --yyy
-  mixed_names.rb:12:in `<main>': missing argument: --yyy (OptionParser::MissingArgument)
-  $ ruby mixed_names.rb --yyy BAR
-  ["--yyy", "BAR"]
-  $ ruby mixed_names.rb -z
-  ["--zzz", nil]
-  $ ruby mixed_names.rb -z BAZ
-  ["--zzz", "BAZ"]
-  $ ruby mixed_names.rb --zzz
-  ["--zzz", nil]
-  $ ruby mixed_names.rb --zzz BAT
-  ["--zzz", "BAT"]
-
-=== Argument Keywords
-
-As seen above, a given option name string may itself
-indicate whether the option has no argument, a required argument,
-or an optional argument.
-
-An alternative is to use a separate symbol keyword,
-which is one of <tt>:NONE</tt> (the default),
-<tt>:REQUIRED</tt>, <tt>:OPTIONAL</tt>.
-
-File +argument_keywords.rb+ defines an option with a required argument.
-
-  :include: argument_keywords.rb
-
-Executions:
-
-  $ ruby argument_keywords.rb --help
-  Usage: argument_keywords [options]
-      -x, --xxx                        Required argument
-  $ ruby argument_styles.rb --xxx
-  argument_styles.rb:6:in `<main>': missing argument: --xxx (OptionParser::MissingArgument)
-  $ ruby argument_styles.rb --xxx FOO
-  ["--xxx", "FOO"]
-
-=== Argument Strings
-
-Still another way to specify a required argument
-is to define it in a string separate from the name string.
-
-File +argument_strings.rb+ defines an option with a required argument.
-
-  :include: argument_strings.rb
-
-Executions:
-
-  $ ruby argument_strings.rb --help
-  Usage: argument_strings [options]
-      -x, --xxx=XXX                    Required argument
-  $ ruby argument_strings.rb --xxx
-  argument_strings.rb:9:in `<main>': missing argument: --xxx (OptionParser::MissingArgument)
-  $ ruby argument_strings.rb --xxx FOO
-  ["--xxx", "FOO"]
-
-=== Argument Values
-
-Permissible argument values may be restricted
-either by specifying explicit values
-or by providing a pattern that the given value must match.
-
-==== Explicit Argument Values
-
-You can specify argument values in either of two ways:
-
-- Specify values an array of strings.
-- Specify values a hash.
-
-===== Explicit Values in Array
-
-You can specify explicit argument values in an array of strings.
-The argument value must be one of those strings.
-
-File +explicit_array_values.rb+ defines options with explicit argument values.
-
-  :include: explicit_array_values.rb
-
-Executions:
-
-  $ ruby explicit_array_values.rb --help
-  Usage: explicit_array_values [options]
-      -xXXX                            Values for required argument
-      -y [YYY]                         Values for optional argument
-  $ ruby explicit_array_values.rb -x
-  explicit_array_values.rb:9:in `<main>': missing argument: -x (OptionParser::MissingArgument)
-  $ ruby explicit_array_values.rb -x foo
-  ["-x", "foo"]
-  $ ruby explicit_array_values.rb -x bar
-  ["-x", "bar"]
-  $ ruby explicit_array_values.rb -x baz
-  explicit_array_values.rb:9:in `<main>': invalid argument: -x baz (OptionParser::InvalidArgument)
-
-
-===== Explicit Values in Hash
-
-You can specify explicit argument values in a hash with string keys.
-The value passed must be one of those keys,
-and the value yielded will be the value for that key.
-
-File +explicit_hash_values.rb+ defines options with explicit argument values.
-
-  :include: explicit_hash_values.rb
-
-Executions:
-
-  $ ruby explicit_hash_values.rb --help
-  Usage: explicit_hash_values [options]
-      -xXXX                            Values for required argument
-      -y [YYY]                         Values for optional argument
-  $ ruby explicit_hash_values.rb -x
-  explicit_hash_values.rb:9:in `<main>': missing argument: -x (OptionParser::MissingArgument)
-  $ ruby explicit_hash_values.rb -x foo
-  ["-x", 0]
-  $ ruby explicit_hash_values.rb -x bar
-  ["-x", 1]
-  $ ruby explicit_hash_values.rb -x baz
-  explicit_hash_values.rb:9:in `<main>': invalid argument: -x baz (OptionParser::InvalidArgument)
-  $ ruby explicit_hash_values.rb -y
-  ["-y", nil]
-  $ ruby explicit_hash_values.rb -y baz
-  ["-y", 2]
-  $ ruby explicit_hash_values.rb -y bat
-  ["-y", 3]
-  $ ruby explicit_hash_values.rb -y bam
-  ["-y", nil]
-
-==== Argument Value Patterns
-
-You can restrict permissible argument values
-by specifying a Regexp that the given argument must match.
-
-File +matched_values.rb+ defines options with matched argument values.
-
-  :include: matched_values.rb
-
-Executions:
-
-  $ ruby matched_values.rb --help
-  Usage: matched_values [options]
-          --xxx XXX                    Matched values
-  $ ruby matched_values.rb --xxx foo
-  ["--xxx", "foo"]
-  $ ruby matched_values.rb --xxx FOO
-  ["--xxx", "FOO"]
-  $ ruby matched_values.rb --xxx bar
-  matched_values.rb:6:in `<main>': invalid argument: --xxx bar (OptionParser::InvalidArgument)
-
-=== Argument Converters
-
-An option can specify that its argument is to be converted
-from the default \String to an instance of another class.
-
-\OptionParser has a number of built-in converters,
-which are demonstrated below.
-
-==== \Date
-
-File +date.rb+
-defines an option whose argument is to be converted to a \Date object.
-The argument is converted by method
-{Date.parse}[https://ruby-doc.org/stdlib/libdoc/date/rdoc/Date.html#method-c-parse].
-
-  :include: 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]
-
-==== \DateTime
-
-File +datetime.rb+
-defines an option whose argument is to be converted to a \DateTime object.
-The argument is converted by method
-{DateTime.parse}[https://ruby-doc.org/stdlib-2.6.1/libdoc/date/rdoc/DateTime.html#method-c-parse].
-
-  :include: datetime.rb
-
-Executions:
-
-  $ ruby datetime.rb --datetime 2001-02-03T04:05:06+07:00
-  [#<DateTime: 2001-02-03T04:05:06+07:00 ((2451943j,75906s,0n),+25200s,2299161j)>, DateTime]
-  $ ruby datetime.rb --datetime 20010203T040506+0700
-  [#<DateTime: 2001-02-03T04:05:06+07:00 ((2451943j,75906s,0n),+25200s,2299161j)>, DateTime]
-  $ ruby datetime.rb --datetime "3rd Feb 2001 04:05:06 PM"
-  [#<DateTime: 2001-02-03T16:05:06+00:00 ((2451944j,57906s,0n),+0s,2299161j)>, DateTime]
-
-==== \Time
-
-File +time.rb+
-defines an option whose argument is to be converted to a \Time object.
-The argument is converted by method
-{Time.httpdate}[https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html#method-c-httpdate] or
-{Time.parse}[https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html#method-c-parse].
-
-  :include: time.rb
-
-Executions:
-
-  $ ruby time.rb --time "Thu, 06 Oct 2011 02:26:12 GMT"
-  [2011-10-06 02:26:12 UTC, Time]
-  $ ruby time.rb --time 2010-10-31
-  [2010-10-31 00:00:00 -0500, Time]
-
-==== \URI
-
-File +uri.rb+
-defines an option whose argument is to be converted to a \URI object.
-The argument is converted by method
-{URI.parse}[https://ruby-doc.org/stdlib-2.7.2/libdoc/uri/rdoc/URI.html#method-c-parse].
-
-  :include: uri.rb
-
-Executions:
-
-  $ ruby uri.rb --uri https://github.com
-  [#<URI::HTTPS https://github.com>, URI::HTTPS]
-  $ ruby uri.rb --uri http://github.com
-  [#<URI::HTTP http://github.com>, URI::HTTP]
-  $ ruby uri.rb --uri file://~/var
-  [#<URI::File file://~/var>, URI::File]
-
-==== \Shellwords
-
-File +shellwords.rb+
-defines an option whose argument is to be converted to an \Array object by method
-{Shellwords.shellwords}[https://ruby-doc.org/stdlib-2.7.0/libdoc/shellwords/rdoc/Shellwords.html#method-c-shellwords].
-
-  :include: shellwords.rb
-
-Executions:
-
-  $ ruby shellwords.rb --shellwords "ruby my_prog.rb | less"
-  [["ruby", "my_prog.rb", "|", "less"], Array]
-  $ ruby shellwords.rb --shellwords "here are 'two words'"
-  [["here", "are", "two words"], Array]
-
-==== \Integer
-
-File +integer.rb+
-defines an option whose argument is to be converted to an \Integer object.
-The argument is converted by method
-{Kernel.Integer}[https://ruby-doc.org/core/Kernel.html#method-i-Integer].
-
-  :include: integer.rb
-
-Executions:
-
-  $ ruby integer.rb --integer 100
-  [100, Integer]
-  $ ruby integer.rb --integer -100
-  [-100, Integer]
-  $ ruby integer.rb --integer 0100
-  [64, Integer]
-  $ ruby integer.rb --integer 0x100
-  [256, Integer]
-  $ ruby integer.rb --integer 0b100
-  [4, Integer]
-
-==== \Float
-
-File +float.rb+
-defines an option whose argument is to be converted to a \Float object.
-The argument is converted by method
-{Kernel.Float}[https://ruby-doc.org/core/Kernel.html#method-i-Float].
-
-  :include: float.rb
-
-Executions:
-
-  $ ruby float.rb --float 1
-  [1.0, Float]
-  $ ruby float.rb --float 3.14159
-  [3.14159, Float]
-  $ ruby float.rb --float 1.234E2
-  [123.4, Float]
-  $ ruby float.rb --float 1.234E-2
-  [0.01234, Float]
-
-==== \Numeric
-
-File +numeric.rb+
-defines an option whose argument is to be converted to an instance
-of \Rational, \Float, or \Integer.
-The argument is converted by method
-{Kernel.Rational}[https://ruby-doc.org/core/Kernel.html#method-i-Rational],
-{Kernel.Float}[https://ruby-doc.org/core/Kernel.html#method-i-Float], or
-{Kernel.Integer}[https://ruby-doc.org/core/Kernel.html#method-i-Integer].
-
-  :include: numeric.rb
-
-Executions:
-
-  $ ruby numeric.rb --numeric 1/3
-  [(1/3), Rational]
-  $ ruby numeric.rb --numeric 3.333E-1
-  [0.3333, Float]
-  $ ruby numeric.rb --numeric 3
-  [3, Integer]
-
-==== \DecimalInteger
-
-File +decimal_integer.rb+
-defines an option whose argument is to be converted to an \Integer object.
-The argument is converted by method
-{Kernel.Integer}[https://ruby-doc.org/core/Kernel.html#method-i-Integer].
-
-  :include: decimal_integer.rb
-
-The argument may not be in a binary or hexadecimal format;
-a leading zero is ignored (not parsed as octal).
-
-Executions:
-
-  $ ruby decimal_integer.rb --decimal_integer 100
-  [100, Integer]
-  $ ruby decimal_integer.rb --decimal_integer -100
-  [-100, Integer]
-  $ ruby decimal_integer.rb --decimal_integer 0100
-  [100, Integer]
-  $ ruby decimal_integer.rb --decimal_integer -0100
-  [-100, Integer]
-
-==== \OctalInteger
-
-File +octal_integer.rb+
-defines an option whose argument is to be converted to an \Integer object.
-The argument is converted by method
-{Kernel.Integer}[https://ruby-doc.org/core/Kernel.html#method-i-Integer].
-
-  :include: octal_integer.rb
-
-The argument may not be in a binary or hexadecimal format;
-it is parsed as octal, regardless of whether it has a leading zero.
-
-Executions:
-
-  $ ruby octal_integer.rb --octal_integer 100
-  [64, Integer]
-  $ ruby octal_integer.rb --octal_integer -100
-  [-64, Integer]
-  $ ruby octal_integer.rb --octal_integer 0100
-  [64, Integer]
-
-==== \DecimalNumeric
-
-File +decimal_numeric.rb+
-defines an option whose argument is to be converted to an \Integer object.
-The argument is converted by method
-{Kernel.Integer}[https://ruby-doc.org/core/Kernel.html#method-i-Integer].
-
-  :include: decimal_numeric.rb
-
-The argument may not be in a binary or hexadecimal format;
-a leading zero causes the argument to be parsed as octal.
-
-Executions:
-
-  $ ruby decimal_numeric.rb --decimal_numeric 100
-  [100, Integer]
-  $ ruby decimal_numeric.rb --decimal_numeric -100
-  [-100, Integer]
-  $ ruby decimal_numeric.rb --decimal_numeric 0100
-  [64, Integer]
-
-==== \TrueClass
-
-File +true_class.rb+
-defines an option whose argument is to be converted to +true+ or +false+.
-The argument is evaluated by method
-{Object#nil?}[https://ruby-doc.org/core-3.0.0/Object.html#method-i-nil-3F].
-
-  :include: true_class.rb
-
-The argument may be any of those shown in the examples below.
-
-Executions:
-
-  $ ruby true_class.rb --true_class true
-  [true, TrueClass]
-  $ ruby true_class.rb --true_class yes
-  [true, TrueClass]
-  $ ruby true_class.rb --true_class +
-  [true, TrueClass]
-  $ ruby true_class.rb --true_class false
-  [false, FalseClass]
-  $ ruby true_class.rb --true_class no
-  [false, FalseClass]
-  $ ruby true_class.rb --true_class -
-  [false, FalseClass]
-  $ ruby true_class.rb --true_class nil
-  [false, FalseClass]
-
-==== \FalseClass
-
-File +false_class.rb+
-defines an option whose argument is to be converted to +true+ or +false+.
-The argument is evaluated by method
-{Object#nil?}[https://ruby-doc.org/core-3.0.0/Object.html#method-i-nil-3F].
-
-  :include: false_class.rb
-
-The argument may be any of those shown in the examples below.
-
-Executions:
-
-  $ ruby false_class.rb --false_class false
-  [false, FalseClass]
-  $ ruby false_class.rb --false_class no
-  [false, FalseClass]
-  $ ruby false_class.rb --false_class -
-  [false, FalseClass]
-  $ ruby false_class.rb --false_class nil
-  [false, FalseClass]
-  $ ruby false_class.rb --false_class true
-  [true, TrueClass]
-  $ ruby false_class.rb --false_class yes
-  [true, TrueClass]
-  $ ruby false_class.rb --false_class +
-  [true, TrueClass]
-
-==== \Object
-
-File +object.rb+
-defines an option whose argument is not to be converted from \String.
-
-  :include: object.rb
-
-Executions:
-
-  $ ruby object.rb --object foo
-  ["foo", String]
-  $ ruby object.rb --object nil
-  ["nil", String]
-
-==== \String
-
-File +string.rb+
-defines an option whose argument is not to be converted from \String.
-
-  :include: string.rb
-
-Executions:
-
-  $ ruby string.rb --string foo
-  ["foo", String]
-  $ ruby string.rb --string nil
-  ["nil", String]
-
-==== \Array
-
-File +array.rb+
-defines an option whose argument is to be converted from \String
-to an array of strings, based on comma-separated substrings.
-
-  :include: array.rb
-
-Executions:
-
-  $ ruby array.rb --array ""
-  [[], Array]
-  $ ruby array.rb --array foo,bar,baz
-  [["foo", "bar", "baz"], Array]
-  $ ruby array.rb --array "foo, bar, baz"
-  [["foo", " bar", " baz"], Array]
-
-==== \Regexp
-
-File +regexp.rb+
-defines an option whose argument is to be converted to a \Regexp object.
-
-  :include: regexp.rb
-
-Executions:
-
-  $ ruby regexp.rb --regexp foo
-
-=== Descriptions
-
-A description parameter is any string parameter
-that is not recognized as an
-{option name}[#label-Option+Names] or a
-{terminator}[#label-Terminators];
-in other words, it does not begin with a hypnen.
-
-You may give any number of description parameters;
-each becomes a line in the text generated by option <tt>--help</tt>.
-
-File +descriptions.rb+ has six strings in its array +descriptions+.
-These are all passed as parameters to OptionParser#on, so that they
-all, line for line, become the option's description.
-
-  :include: descriptions.rb
-
-Executions:
-
-  $ ruby descriptions.rb --help
-  Usage: descriptions [options]
-          --xxx                        Lorem ipsum dolor sit amet, consectetuer
-                                       adipiscing elit. Aenean commodo ligula eget.
-                                       Aenean massa. Cum sociis natoque penatibus
-                                       et magnis dis parturient montes, nascetur
-                                       ridiculus mus. Donec quam felis, ultricies
-                                       nec, pellentesque eu, pretium quis, sem.
-  $ ruby descriptions.rb --xxx
-  ["--xxx", true]
-
-=== Handlers
-
-The handler for an option is an executable that will be called
-when the option is encountered.  The handler may be:
-
-- A block (this is most often seen).
-- A proc.
-- A method.
-
-==== Handler Blocks
-
-An option hadler may be a block.
-
-File +block.rb+ defines an option that has a handler block.
-
-  :include: block.rb
-
-Executions:
-
-  $ ruby block.rb --help
-  Usage: block [options]
-          --xxx                        Option with no argument
-          --yyy YYY                    Option with required argument
-  $ ruby block.rb --xxx
-  ["Handler block for -xxx called with value:", true]
-  $ ruby block.rb --yyy FOO
-  ["Handler block for -yyy called with value:", "FOO"]
-
-==== Handler Procs
-
-An option handler may be a Proc.
-
-File +proc.rb+ defines an option that has a handler proc.
-
-  :include: proc.rb
-
-Executions:
-
-  $ ruby proc.rb --help
-  Usage: proc [options]
-          --xxx                        Option with no argument
-          --yyy YYY                    Option with required argument
-  $ ruby proc.rb --xxx
-  ["Handler proc for -xxx called with value:", true]
-  $ ruby proc.rb --yyy FOO
-  ["Handler proc for -yyy called with value:", "FOO"]
-
-==== Handler Methods
-
-An option handler may be a Method.
-
-File +proc.rb+ defines an option that has a handler method.
-
-  :include: method.rb
-
-Executions:
-
-  $ ruby method.rb --help
-  Usage: method [options]
-          --xxx                        Option with no argument
-          --yyy YYY                    Option with required argument
-  $ ruby method.rb --xxx
-  ["Handler method for -xxx called with value:", true]
-  $ ruby method.rb --yyy FOO
-  ["Handler method for -yyy called with value:", "FOO"]
-
-=== Terminators
-
-And finally, the terminator parameter <tt>--</tt> tells the options parser
-to ignore any options farther to the right.
-This can be useful if there are options not meant for the current program.
-
-File +terminator.rb+ defines one option <tt>--my_option</tt>.
-
-  :include: terminator.rb
-
-The first execution fails because <tt>--nosuch</tt> is not a defined option;
-the second succeeds because <tt>--</tt> causes that option to be ignored:
-
-  $ ruby terminator.rb --my_option FOO --other_option BAR
-  ["FOO", String]
-  terminator.rb:6:in `<main>': invalid option: --other_option (OptionParser::InvalidOption)
-  $ ruby terminator.rb --my_option FOO -- --other_option BAR
-  ["FOO", String]
diff --git a/doc/option_params/proc.rb b/doc/option_params/proc.rb
deleted file mode 100644
index 9c669fdc92..0000000000
--- a/doc/option_params/proc.rb
+++ /dev/null
@@ -1,13 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on(
-  '--xxx',
-  'Option with no argument',
-  ->(value) {p ['Handler proc for -xxx called with value:', value]}
-)
-parser.on(
-  '--yyy YYY',
-  'Option with required argument',
-  ->(value) {p ['Handler proc for -yyy called with value:', value]}
-)
-parser.parse!
diff --git a/doc/option_params/regexp.rb b/doc/option_params/regexp.rb
deleted file mode 100644
index 6aba45ce76..0000000000
--- a/doc/option_params/regexp.rb
+++ /dev/null
@@ -1,6 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('--regexp=REGEXP', Regexp) do |value|
-  p [value, value.class]
-end
-parser.parse!
diff --git a/doc/option_params/shellwords.rb b/doc/option_params/shellwords.rb
deleted file mode 100644
index d181d4a4f6..0000000000
--- a/doc/option_params/shellwords.rb
+++ /dev/null
@@ -1,6 +0,0 @@
-require 'optparse/shellwords'
-parser = OptionParser.new
-parser.on('--shellwords=SHELLWORDS', Shellwords) do |value|
-  p [value, value.class]
-end
-parser.parse!
diff --git a/doc/option_params/short_optional.rb b/doc/option_params/short_optional.rb
deleted file mode 100644
index 6eebf01c5f..0000000000
--- a/doc/option_params/short_optional.rb
+++ /dev/null
@@ -1,6 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('-x [XXX]', 'Short name with optional argument') do |value|
-  p ['-x', value]
-end
-parser.parse!
diff --git a/doc/option_params/short_range.rb b/doc/option_params/short_range.rb
deleted file mode 100644
index f5b870a4bd..0000000000
--- a/doc/option_params/short_range.rb
+++ /dev/null
@@ -1,6 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('-[!-~]', 'Short names in (very large) range') do |name, value|
-  p ['!-~', name, value]
-end
-parser.parse!
diff --git a/doc/option_params/short_required.rb b/doc/option_params/short_required.rb
deleted file mode 100644
index 867c02c9f5..0000000000
--- a/doc/option_params/short_required.rb
+++ /dev/null
@@ -1,6 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('-xXXX', 'Short name with required argument') do |value|
-  p ['-x', value]
-end
-parser.parse!
diff --git a/doc/option_params/short_simple.rb b/doc/option_params/short_simple.rb
deleted file mode 100644
index d3d489e2dc..0000000000
--- a/doc/option_params/short_simple.rb
+++ /dev/null
@@ -1,9 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('-x', 'One short name') do |value|
-  p ['-x', value]
-end
-parser.on('-1', '-%', 'Two short names (aliases)') do |value|
-  p ['-1 or -%', value]
-end
-parser.parse!
diff --git a/doc/option_params/string.rb b/doc/option_params/string.rb
deleted file mode 100644
index fee84a17ea..0000000000
--- a/doc/option_params/string.rb
+++ /dev/null
@@ -1,6 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('--string=STRING', String) do |value|
-  p [value, value.class]
-end
-parser.parse!
diff --git a/doc/option_params/terminator.rb b/doc/option_params/terminator.rb
deleted file mode 100644
index c718ac1a97..0000000000
--- a/doc/option_params/terminator.rb
+++ /dev/null
@@ -1,6 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('--my_option XXX') do |value|
-  p [value, value.class]
-end
-parser.parse!
diff --git a/doc/option_params/time.rb b/doc/option_params/time.rb
deleted file mode 100644
index aa8b0cfa16..0000000000
--- a/doc/option_params/time.rb
+++ /dev/null
@@ -1,6 +0,0 @@
-require 'optparse/time'
-parser = OptionParser.new
-parser.on('--time=TIME', Time) do |value|
-  p [value, value.class]
-end
-parser.parse!
diff --git a/doc/option_params/true_class.rb b/doc/option_params/true_class.rb
deleted file mode 100644
index 40db9d07c5..0000000000
--- a/doc/option_params/true_class.rb
+++ /dev/null
@@ -1,6 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('--true_class=TRUE_CLASS', TrueClass) do |value|
-  p [value, value.class]
-end
-parser.parse!
diff --git a/doc/option_params/uri.rb b/doc/option_params/uri.rb
deleted file mode 100644
index b492835b4f..0000000000
--- a/doc/option_params/uri.rb
+++ /dev/null
@@ -1,6 +0,0 @@
-require 'optparse/uri'
-parser = OptionParser.new
-parser.on('--uri=URI', URI) do |value|
-  p [value, value.class]
-end
-parser.parse!
diff --git a/doc/tutorial/argv.rb b/doc/tutorial/argv.rb
deleted file mode 100644
index 12495cfa1f..0000000000
--- a/doc/tutorial/argv.rb
+++ /dev/null
@@ -1,2 +0,0 @@
-p ARGV
-
diff --git a/doc/tutorial/long_names.rb b/doc/tutorial/long_names.rb
deleted file mode 100644
index a34b3382c2..0000000000
--- a/doc/tutorial/long_names.rb
+++ /dev/null
@@ -1,9 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('--xxx') do |value|
-  p ['-xxx', value]
-end
-parser.on('--y1%', '--z2#') do |value|
-  p ['--y1% or --z2#', value]
-end
-parser.parse!
diff --git a/doc/tutorial/mixed_names.rb b/doc/tutorial/mixed_names.rb
deleted file mode 100644
index e886049821..0000000000
--- a/doc/tutorial/mixed_names.rb
+++ /dev/null
@@ -1,9 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('-x', '--xxx') do |value|
-  p ['--xxx', value]
-end
-parser.on('-y', '--y1%') do |value|
-  p ['--y1%', value]
-end
-parser.parse!
diff --git a/doc/tutorial/optional_argument.rb b/doc/tutorial/optional_argument.rb
deleted file mode 100644
index ebff2f466d..0000000000
--- a/doc/tutorial/optional_argument.rb
+++ /dev/null
@@ -1,9 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('-x [XXX]', '--xxx') do |value|
-  p ['--xxx', value]
-end
-parser.on('-y', '--yyy [YYY]') do |value|
-  p ['--yyy', value]
-end
-parser.parse!
diff --git a/doc/tutorial/required_argument.rb b/doc/tutorial/required_argument.rb
deleted file mode 100644
index 7a5a868265..0000000000
--- a/doc/tutorial/required_argument.rb
+++ /dev/null
@@ -1,9 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('-x XXX', '--xxx') do |value|
-  p ['--xxx', value]
-end
-parser.on('-y', '--y YYY') do |value|
-  p ['--yyy', value]
-end
-parser.parse!
diff --git a/doc/tutorial/short_names.rb b/doc/tutorial/short_names.rb
deleted file mode 100644
index 6581dfe19a..0000000000
--- a/doc/tutorial/short_names.rb
+++ /dev/null
@@ -1,9 +0,0 @@
-require 'optparse'
-parser = OptionParser.new
-parser.on('-x') do |value|
-  p ['x', value]
-end
-parser.on('-1', '-%') do |value|
-  p ['-1 or -%', value]
-end
-parser.parse!
diff --git a/doc/tutorial/tutorial.rdoc b/doc/tutorial/tutorial.rdoc
deleted file mode 100644
index 60ead0a6c6..0000000000
--- a/doc/tutorial/tutorial.rdoc
+++ /dev/null
@@ -1,186 +0,0 @@
-== Tutorial
-
-=== Why OptionParser?
-
-When a Ruby program executes, it captures its command-line arguments
-and options into variable ARGV.
-This simple program just prints its \ARGV:
-
-  :include: argv.rb
-
-Execution, with arguments and options:
-
-  $ ruby argv.rb foo --bar --baz bat bam
-  ["foo", "--bar", "--baz", "bat", "bam"]
-
-The executing program is responsible for parsing and handling
-the command-line options.
-
-OptionParser offers methods for parsing and handling those options.
-
-With \OptionParser, you can define options so that for each option:
-
-- The code that defines the option and code that handles that option
-  are in the same place.
-- The option may take no argument, a required argument, or an optional argument.
-- The argument may be automatically converted to a specified class.
-- The argument may be restricted to specified _forms_.
-- The argument may be restricted to specified _values_.
-
-The class also has:
-
-- Method #summarize: returns a text summary of the options.
-- Method #help: displays automatically-generated help text.
-
-=== Defining Options
-
-A common way to define an option in \OptionParser
-is with instance method OptionParser#on.
-
-The method may be called with any number of arguments
-(whose order does not matter),
-and may also have a trailing optional keyword argument +into+.
-
-The given arguments determine the characteristics of the new option.
-These may include:
-
-- One or more short option names.
-- One or more long option names.
-- Whether the option takes no argument, an optional argument, or a required argument.
-- Acceptable _forms_ for the argument.
-- Acceptable _values_ for the argument.
-- A proc or method to be called when the parser encounters the option.
-- String descriptions for the option.
-
-=== Option Names
-
-You can give an option one or more names of two types:
-
-- Short (1-character) name, beginning with one hyphen (<tt>-</tt>).
-- Long (multi-character) name, beginning with two hyphens (<tt>--</tt>).
-
-==== Short Option Names
-
-A short option name consists of a hyphen and a single character.
-
-File +short_names.rb+
-defines an option with a short name, <tt>-x</tt>,
-and an option with two short names (aliases, in effect) <tt>-y</tt> and <tt>-z</tt>.
-
-  :include: short_names.rb
-
-Executions:
-
-  $ ruby short_names.rb -x
-  ["x", true]
-  $ ruby short_names.rb -1
-  ["-1 or -%", true]
-  $ ruby short_names.rb -%
-  ["-1 or -%", true]
-
-Multiple short names can "share" a hyphen:
-
-  $ ruby short_names.rb -x1%
-  ["x", true]
-  ["-1 or -%", true]
-  ["-1 or -%", true]
-
-This is a good time to note that giving an undefined option raises an exception:
-
-  $ ruby short_names.rb -z
-  short_names.rb:9:in `<main>': invalid option: -z (OptionParser::InvalidOption)
-
-==== Long Option Names
-
-A long option name consists of two hyphens and a one or more characters
-(usually two or more characters).
-
-File +long_names.rb+
-defines an option with a long name, <tt>--xxx</tt>,
-and an option with two long names (aliases, in effect) <tt>--y1%</tt> and <tt>--z2#</tt>.
-
-  :include: long_names.rb
-
-Executions:
-
-  $ ruby long_names.rb --xxx
-  ["-xxx", true]
-  $ ruby long_names.rb --y1%
-  ["--y1% or --z2#", true]
-  $ ruby long_names.rb --z2#
-  ["--y1% or --z2#", true]
-
-==== Mixing Option Names
-
-Many developers like to mix short and long option names,
-so that a short name is in effect an abbreviation of a long name.
-
-File +mixed_names.rb+
-defines options that each have both a short and a long name.
-
-  :include: mixed_names.rb
-
-Executions:
-
-  $ ruby mixed_names.rb -x
-  ["--xxx", true]
-  $ ruby mixed_names.rb --xxx
-  ["--xxx", true]
-  $ ruby mixed_names.rb -y
-  ["--y1%", true]
-  $ ruby mixed_names.rb --y1%
-  ["--y1%", true]
-
-=== Option Arguments
-
-An option may take no argument, a required argument, or an optional argument.
-
-==== Option with No Argument
-
-All the examples above define options with no argument.
-
-==== Option with Required Argument
-
-Specify a required argument for an option by adding a dummy word
-to its name definition.
-
-File +required_argument.rb+ defines two options;
-each has a required argument because the name definition has a following dummy word.
-
-  :include: required_argument.rb
-
-When an option is found, the given argument is yielded.
-
-Executions:
-
-  $ ruby required_argument.rb -x AAA
-  ["--xxx", "AAA"]
-  $ ruby required_argument.rb -y BBB
-  ["--yyy", "BBB"]
-
-Omitting a required argument raises an error:
-
-  $ ruby required_argument.rb -x
-  required_argument.rb:9:in `<main>': missing argument: -x (OptionParser::MissingArgument)
-
-==== Option with Optional Argument
-
-Specify an optional argument for an option by adding a dummy word
-enclosed in square brackets to its name definition.
-
-File +optional_argument.rb+ defines two options;
-each has an optional argument because the name definition has a following dummy word
-in square brackets.
-
-  :include: optional_argument.rb
-
-When an option with an argument is found, the given argument yielded.
-
-Executions:
-
-  $ ruby optional_argument.rb -x AAA
-  ["--xxx", "AAA"]
-  $ ruby optional_argument.rb -y BBB
-  ["--yyy", "BBB"]
-
-Omitting an optional argument does not raise an error.