summaryrefslogtreecommitdiff
path: root/doc/optparse
diff options
context:
space:
mode:
Diffstat (limited to 'doc/optparse')
-rw-r--r--doc/optparse/argument_converters.rdoc2
-rw-r--r--doc/optparse/option_params.rdoc41
-rw-r--r--doc/optparse/ruby/argument_abbreviation.rb9
-rw-r--r--doc/optparse/ruby/matched_values.rb6
-rw-r--r--doc/optparse/tutorial.rdoc53
5 files changed, 80 insertions, 31 deletions
diff --git a/doc/optparse/argument_converters.rdoc b/doc/optparse/argument_converters.rdoc
index 4b4b30e8de..532729871c 100644
--- a/doc/optparse/argument_converters.rdoc
+++ b/doc/optparse/argument_converters.rdoc
@@ -377,4 +377,4 @@ Executions:
$ ruby match_converter.rb --capitalize foo
["Foo", String]
$ ruby match_converter.rb --capitalize "foo bar"
- match_converter.rb:9:in `<main>': invalid argument: --capitalize foo bar (OptionParser::InvalidArgument)
+ match_converter.rb:9:in '<main>': invalid argument: --capitalize foo bar (OptionParser::InvalidArgument)
diff --git a/doc/optparse/option_params.rdoc b/doc/optparse/option_params.rdoc
index 55f9b53dff..575ee66cdb 100644
--- a/doc/optparse/option_params.rdoc
+++ b/doc/optparse/option_params.rdoc
@@ -31,7 +31,7 @@ Contents:
- {Long Names with Optional Arguments}[#label-Long+Names+with+Optional+Arguments]
- {Long Names with Negation}[#label-Long+Names+with+Negation]
- {Mixed Names}[#label-Mixed+Names]
-- {Argument Styles}[#label-Argument+Styles]
+- {Argument Strings}[#label-Argument+Strings]
- {Argument Values}[#label-Argument+Values]
- {Explicit Argument Values}[#label-Explicit+Argument+Values]
- {Explicit Values in Array}[#label-Explicit+Values+in+Array]
@@ -91,7 +91,7 @@ Executions:
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)
+ short_required.rb:6:in '<main>': missing argument: -x (OptionParser::MissingArgument)
$ ruby short_required.rb -x FOO
["-x", "FOO"]
@@ -181,7 +181,7 @@ Executions:
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)
+ long_required.rb:6:in '<main>': missing argument: --xxx (OptionParser::MissingArgument)
$ ruby long_required.rb --xxx FOO
["--xxx", "FOO"]
@@ -243,11 +243,11 @@ Usage: mixed_names [options]
$ ruby mixed_names.rb --xxx
["--xxx", true]
$ ruby mixed_names.rb -y
- mixed_names.rb:12:in `<main>': missing argument: -y (OptionParser::MissingArgument)
+ 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)
+ mixed_names.rb:12:in '<main>': missing argument: --yyy (OptionParser::MissingArgument)
$ ruby mixed_names.rb --yyy BAR
["--yyy", "BAR"]
$ ruby mixed_names.rb -z
@@ -279,7 +279,7 @@ Executions:
Usage: argument_keywords [options]
-x, --xxx Required argument
$ ruby argument_styles.rb --xxx
- argument_styles.rb:6:in `<main>': missing argument: --xxx (OptionParser::MissingArgument)
+ argument_styles.rb:6:in '<main>': missing argument: --xxx (OptionParser::MissingArgument)
$ ruby argument_styles.rb --xxx FOO
["--xxx", "FOO"]
@@ -298,7 +298,7 @@ Executions:
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)
+ argument_strings.rb:9:in '<main>': missing argument: --xxx (OptionParser::MissingArgument)
$ ruby argument_strings.rb --xxx FOO
["--xxx", "FOO"]
@@ -331,7 +331,7 @@ Executions:
-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)
+ 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 f
@@ -339,9 +339,9 @@ Executions:
$ ruby explicit_array_values.rb -x bar
["-x", "bar"]
$ ruby explicit_array_values.rb -y ba
- explicit_array_values.rb:9:in `<main>': ambiguous argument: -y ba (OptionParser::AmbiguousArgument)
+ explicit_array_values.rb:9:in '<main>': ambiguous argument: -y ba (OptionParser::AmbiguousArgument)
$ ruby explicit_array_values.rb -x baz
- explicit_array_values.rb:9:in `<main>': invalid argument: -x baz (OptionParser::InvalidArgument)
+ explicit_array_values.rb:9:in '<main>': invalid argument: -x baz (OptionParser::InvalidArgument)
===== Explicit Values in Hash
@@ -361,7 +361,7 @@ Executions:
-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)
+ 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 f
@@ -369,7 +369,7 @@ Executions:
$ 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)
+ 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
@@ -377,14 +377,15 @@ Executions:
$ ruby explicit_hash_values.rb -y bat
["-y", 3]
$ ruby explicit_hash_values.rb -y ba
- explicit_hash_values.rb:9:in `<main>': ambiguous argument: -y ba (OptionParser::AmbiguousArgument)
+ explicit_hash_values.rb:9:in '<main>': ambiguous argument: -y ba (OptionParser::AmbiguousArgument)
$ 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.
+by specifying a +Regexp+ that the given argument must match,
+or a +Range+ or +Array+ that the converted value must be included in.
File +matched_values.rb+ defines options with matched argument values.
@@ -395,12 +396,22 @@ Executions:
$ ruby matched_values.rb --help
Usage: matched_values [options]
--xxx XXX Matched values
+ --yyy YYY Check by range
+ --zzz ZZZ Check by list
$ 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)
+ matched_values.rb:12:in '<main>': invalid argument: --xxx bar (OptionParser::InvalidArgument)
+ $ ruby matched_values.rb --yyy 1
+ ["--yyy", 1]
+ $ ruby matched_values.rb --yyy 4
+ matched_values.rb:12:in '<main>': invalid argument: --yyy 4 (OptionParser::InvalidArgument)
+ $ ruby matched_values.rb --zzz 1
+ ["--zzz", 1]
+ $ ruby matched_values.rb --zzz 2
+ matched_values.rb:12:in '<main>': invalid argument: --zzz 2 (OptionParser::InvalidArgument)
=== Argument Converters
diff --git a/doc/optparse/ruby/argument_abbreviation.rb b/doc/optparse/ruby/argument_abbreviation.rb
new file mode 100644
index 0000000000..49007ebe69
--- /dev/null
+++ b/doc/optparse/ruby/argument_abbreviation.rb
@@ -0,0 +1,9 @@
+require 'optparse'
+parser = OptionParser.new
+parser.on('-x', '--xxx=VALUE', %w[ABC def], 'Argument abbreviations') do |value|
+ p ['--xxx', value]
+end
+parser.on('-y', '--yyy=VALUE', {"abc"=>"XYZ", def: "FOO"}, 'Argument abbreviations') do |value|
+ p ['--yyy', value]
+end
+parser.parse!
diff --git a/doc/optparse/ruby/matched_values.rb b/doc/optparse/ruby/matched_values.rb
index f184ca8474..a1aba140e6 100644
--- a/doc/optparse/ruby/matched_values.rb
+++ b/doc/optparse/ruby/matched_values.rb
@@ -3,4 +3,10 @@ parser = OptionParser.new
parser.on('--xxx XXX', /foo/i, 'Matched values') do |value|
p ['--xxx', value]
end
+parser.on('--yyy YYY', Integer, 'Check by range', 1..3) do |value|
+ p ['--yyy', value]
+end
+parser.on('--zzz ZZZ', Integer, 'Check by list', [1, 3, 4]) do |value|
+ p ['--zzz', value]
+end
parser.parse!
diff --git a/doc/optparse/tutorial.rdoc b/doc/optparse/tutorial.rdoc
index b104379cf7..1134f94ddf 100644
--- a/doc/optparse/tutorial.rdoc
+++ b/doc/optparse/tutorial.rdoc
@@ -111,7 +111,7 @@ Executions:
["x", true]
["input_file.txt", "output_file.txt"]
$ ruby basic.rb -a
- basic.rb:16:in `<main>': invalid option: -a (OptionParser::InvalidOption)
+ basic.rb:16:in '<main>': invalid option: -a (OptionParser::InvalidOption)
=== Defining Options
@@ -232,11 +232,11 @@ Executions:
$ ruby mixed_names.rb --xxx
["--xxx", true]
$ ruby mixed_names.rb -y
- mixed_names.rb:12:in `<main>': missing argument: -y (OptionParser::MissingArgument)
+ 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)
+ mixed_names.rb:12:in '<main>': missing argument: --yyy (OptionParser::MissingArgument)
$ ruby mixed_names.rb --yyy BAR
["--yyy", "BAR"]
$ ruby mixed_names.rb -z
@@ -270,9 +270,9 @@ Executions:
$ ruby name_abbrev.rb --draft
["--draft", true]
$ ruby name_abbrev.rb --d
- name_abbrev.rb:9:in `<main>': ambiguous option: --d (OptionParser::AmbiguousOption)
+ name_abbrev.rb:9:in '<main>': ambiguous option: --d (OptionParser::AmbiguousOption)
$ ruby name_abbrev.rb --dr
- name_abbrev.rb:9:in `<main>': ambiguous option: --dr (OptionParser::AmbiguousOption)
+ name_abbrev.rb:9:in '<main>': ambiguous option: --dr (OptionParser::AmbiguousOption)
$ ruby name_abbrev.rb --dry
["--dry-run", true]
$ ruby name_abbrev.rb --dra
@@ -285,7 +285,7 @@ You can disable abbreviation using method +require_exact+.
Executions:
$ ruby no_abbreviation.rb --dry-ru
- no_abbreviation.rb:10:in `<main>': invalid option: --dry-ru (OptionParser::InvalidOption)
+ no_abbreviation.rb:10:in '<main>': invalid option: --dry-ru (OptionParser::InvalidOption)
$ ruby no_abbreviation.rb --dry-run
["--dry-run", true]
@@ -323,7 +323,7 @@ Executions:
Omitting a required argument raises an error:
$ ruby required_argument.rb -x
- required_argument.rb:9:in `<main>': missing argument: -x (OptionParser::MissingArgument)
+ required_argument.rb:9:in '<main>': missing argument: -x (OptionParser::MissingArgument)
==== Option with Optional Argument
@@ -351,6 +351,29 @@ Executions:
Omitting an optional argument does not raise an error.
+==== Argument Abbreviations
+
+Specify an argument list as an Array or a Hash.
+
+ :include: ruby/argument_abbreviation.rb
+
+When an argument is abbreviated, the expanded argument yielded.
+
+Executions:
+
+ $ ruby argument_abbreviation.rb --help
+ Usage: argument_abbreviation [options]
+ Usage: argument_abbreviation [options]
+ -x, --xxx=VALUE Argument abbreviations
+ -y, --yyy=VALUE Argument abbreviations
+ $ ruby argument_abbreviation.rb --xxx A
+ ["--xxx", "ABC"]
+ $ ruby argument_abbreviation.rb --xxx c
+ argument_abbreviation.rb:9:in '<main>': invalid argument: --xxx c (OptionParser::InvalidArgument)
+ $ ruby argument_abbreviation.rb --yyy a --yyy d
+ ["--yyy", "XYZ"]
+ ["--yyy", "FOO"]
+
=== Argument Values
Permissible argument values may be restricted
@@ -380,7 +403,7 @@ Executions:
-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)
+ 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 f
@@ -388,9 +411,9 @@ Executions:
$ ruby explicit_array_values.rb -x bar
["-x", "bar"]
$ ruby explicit_array_values.rb -y ba
- explicit_array_values.rb:9:in `<main>': ambiguous argument: -y ba (OptionParser::AmbiguousArgument)
+ explicit_array_values.rb:9:in '<main>': ambiguous argument: -y ba (OptionParser::AmbiguousArgument)
$ ruby explicit_array_values.rb -x baz
- explicit_array_values.rb:9:in `<main>': invalid argument: -x baz (OptionParser::InvalidArgument)
+ explicit_array_values.rb:9:in '<main>': invalid argument: -x baz (OptionParser::InvalidArgument)
===== Explicit Values in Hash
@@ -410,7 +433,7 @@ Executions:
-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)
+ 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 f
@@ -418,7 +441,7 @@ Executions:
$ 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)
+ 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
@@ -426,7 +449,7 @@ Executions:
$ ruby explicit_hash_values.rb -y bat
["-y", 3]
$ ruby explicit_hash_values.rb -y ba
- explicit_hash_values.rb:9:in `<main>': ambiguous argument: -y ba (OptionParser::AmbiguousArgument)
+ explicit_hash_values.rb:9:in '<main>': ambiguous argument: -y ba (OptionParser::AmbiguousArgument)
$ ruby explicit_hash_values.rb -y bam
["-y", nil]
@@ -449,7 +472,7 @@ Executions:
$ 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)
+ matched_values.rb:6:in '<main>': invalid argument: --xxx bar (OptionParser::InvalidArgument)
=== Keyword Argument +into+
@@ -501,7 +524,7 @@ Executions:
-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)
+ missing_options.rb:11:in '<main>': Missing required options: [:xxx, :zzz] (RuntimeError)
==== Default Values for Options
generated by cgit v1.2.3 (git 2.25.1) at 2026-05-30 02:34:59 +0000