diff --git a/doc/option_params/argument_keywords.rb b/doc/option_params/argument_keywords.rb
new file mode 100644
index 0000000000..8533257c67
--- /dev/null
+++ b/doc/option_params/argument_keywords.rb
@@ -0,0 +1,6 @@
+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
new file mode 100644
index 0000000000..77861dda30
--- /dev/null
+++ b/doc/option_params/argument_strings.rb
@@ -0,0 +1,6 @@
+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
new file mode 100644
index 0000000000..7c6c14fad4
--- /dev/null
+++ b/doc/option_params/array.rb
@@ -0,0 +1,6 @@
+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
new file mode 100644
index 0000000000..c4dfdeb31e
--- /dev/null
+++ b/doc/option_params/block.rb
@@ -0,0 +1,9 @@
+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
new file mode 100644
index 0000000000..5994ad6a85
--- /dev/null
+++ b/doc/option_params/date.rb
@@ -0,0 +1,6 @@
+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
new file mode 100644
index 0000000000..b9b591d5f6
--- /dev/null
+++ b/doc/option_params/datetime.rb
@@ -0,0 +1,6 @@
+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
new file mode 100644
index 0000000000..360bd284f8
--- /dev/null
+++ b/doc/option_params/decimal_integer.rb
@@ -0,0 +1,7 @@
+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
new file mode 100644
index 0000000000..954da13561
--- /dev/null
+++ b/doc/option_params/decimal_numeric.rb
@@ -0,0 +1,7 @@
+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
new file mode 100644
index 0000000000..9aec80aae2
--- /dev/null
+++ b/doc/option_params/descriptions.rb
@@ -0,0 +1,15 @@
+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
new file mode 100644
index 0000000000..64f930a4bc
--- /dev/null
+++ b/doc/option_params/explicit_array_values.rb
@@ -0,0 +1,9 @@
+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
new file mode 100644
index 0000000000..9c9e6a48ed
--- /dev/null
+++ b/doc/option_params/explicit_hash_values.rb
@@ -0,0 +1,9 @@
+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
new file mode 100644
index 0000000000..04fe335ede
--- /dev/null
+++ b/doc/option_params/false_class.rb
@@ -0,0 +1,6 @@
+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
new file mode 100644
index 0000000000..390df7f7bd
--- /dev/null
+++ b/doc/option_params/float.rb
@@ -0,0 +1,6 @@
+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
new file mode 100644
index 0000000000..f10656ff1a
--- /dev/null
+++ b/doc/option_params/integer.rb
@@ -0,0 +1,6 @@
+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
new file mode 100644
index 0000000000..8eccecaf3a
--- /dev/null
+++ b/doc/option_params/long_binary.rb
@@ -0,0 +1,6 @@
+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
new file mode 100644
index 0000000000..38dd82166b
--- /dev/null
+++ b/doc/option_params/long_optional.rb
@@ -0,0 +1,6 @@
+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
new file mode 100644
index 0000000000..b76c997339
--- /dev/null
+++ b/doc/option_params/long_required.rb
@@ -0,0 +1,6 @@
+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
new file mode 100644
index 0000000000..4e489c43ed
--- /dev/null
+++ b/doc/option_params/long_simple.rb
@@ -0,0 +1,9 @@
+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
new file mode 100644
index 0000000000..f184ca8474
--- /dev/null
+++ b/doc/option_params/matched_values.rb
@@ -0,0 +1,6 @@
+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
new file mode 100644
index 0000000000..3f02ff5798
--- /dev/null
+++ b/doc/option_params/method.rb
@@ -0,0 +1,11 @@
+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
new file mode 100644
index 0000000000..fe6c554bdc
--- /dev/null
+++ b/doc/option_params/mixed_names.rb
@@ -0,0 +1,12 @@
+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
new file mode 100644
index 0000000000..d7021f154a
--- /dev/null
+++ b/doc/option_params/numeric.rb
@@ -0,0 +1,6 @@
+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
new file mode 100644
index 0000000000..0f5ae8b922
--- /dev/null
+++ b/doc/option_params/object.rb
@@ -0,0 +1,6 @@
+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
new file mode 100644
index 0000000000..b9644a076b
--- /dev/null
+++ b/doc/option_params/octal_integer.rb
@@ -0,0 +1,7 @@
+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
new file mode 100644
index 0000000000..7cf5ef890c
--- /dev/null
+++ b/doc/option_params/option_params.rdoc
@@ -0,0 +1,845 @@
+== 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
new file mode 100644
index 0000000000..9c669fdc92
--- /dev/null
+++ b/doc/option_params/proc.rb
@@ -0,0 +1,13 @@
+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
new file mode 100644
index 0000000000..6aba45ce76
--- /dev/null
+++ b/doc/option_params/regexp.rb
@@ -0,0 +1,6 @@
+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
new file mode 100644
index 0000000000..d181d4a4f6
--- /dev/null
+++ b/doc/option_params/shellwords.rb
@@ -0,0 +1,6 @@
+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
new file mode 100644
index 0000000000..6eebf01c5f
--- /dev/null
+++ b/doc/option_params/short_optional.rb
@@ -0,0 +1,6 @@
+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
new file mode 100644
index 0000000000..f5b870a4bd
--- /dev/null
+++ b/doc/option_params/short_range.rb
@@ -0,0 +1,6 @@
+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
new file mode 100644
index 0000000000..867c02c9f5
--- /dev/null
+++ b/doc/option_params/short_required.rb
@@ -0,0 +1,6 @@
+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
new file mode 100644
index 0000000000..d3d489e2dc
--- /dev/null
+++ b/doc/option_params/short_simple.rb
@@ -0,0 +1,9 @@
+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
new file mode 100644
index 0000000000..fee84a17ea
--- /dev/null
+++ b/doc/option_params/string.rb
@@ -0,0 +1,6 @@
+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
new file mode 100644
index 0000000000..c718ac1a97
--- /dev/null
+++ b/doc/option_params/terminator.rb
@@ -0,0 +1,6 @@
+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
new file mode 100644
index 0000000000..aa8b0cfa16
--- /dev/null
+++ b/doc/option_params/time.rb
@@ -0,0 +1,6 @@
+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
new file mode 100644
index 0000000000..40db9d07c5
--- /dev/null
+++ b/doc/option_params/true_class.rb
@@ -0,0 +1,6 @@
+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
new file mode 100644
index 0000000000..b492835b4f
--- /dev/null
+++ b/doc/option_params/uri.rb
@@ -0,0 +1,6 @@
+require 'optparse/uri'
+parser = OptionParser.new
+parser.on('--uri=URI', URI) do |value|
+  p [value, value.class]
+end
+parser.parse!