diff options
author | Burdette Lamar <BurdetteLamar@Yahoo.com> | 2021-04-15 09:32:02 -0500 |
---|---|---|
committer | Hiroshi SHIBATA <hsbt@ruby-lang.org> | 2021-07-28 20:13:39 +0900 |
commit | 98ccb49ac3bea0e2233d2b3f642a3e0579801988 (patch) | |
tree | f6021bcf940ddd56978f13d6f3858fa469ced531 /doc | |
parent | 43af561e0878ca856513edd3db56ce7dff8e7fe3 (diff) |
[ruby/optparse] More on tutorial (https://github.com/ruby/optparse/pull/22)
Adds argument abbreviation in option_params.rdoc.
Adds entire Argument Values section to tutorial.rdoc.
https://github.com/ruby/optparse/commit/9c5b3f244b
Diffstat (limited to 'doc')
-rw-r--r-- | doc/optparse/option_params.rdoc | 14 | ||||
-rw-r--r-- | doc/optparse/ruby/help.rb | 3 | ||||
-rw-r--r-- | doc/optparse/ruby/name_abbrev.rb (renamed from doc/optparse/ruby/abbreviation.rb) | 0 | ||||
-rw-r--r-- | doc/optparse/tutorial.rdoc | 142 |
4 files changed, 135 insertions, 24 deletions
diff --git a/doc/optparse/option_params.rdoc b/doc/optparse/option_params.rdoc index 0d06b41e7d..c1f83eda88 100644 --- a/doc/optparse/option_params.rdoc +++ b/doc/optparse/option_params.rdoc @@ -319,7 +319,7 @@ You can specify argument values in either of two ways: ===== Explicit Values in Array You can specify explicit argument values in an array of strings. -The argument value must be one of those strings. +The argument value must be one of those strings, or an unambiguous abbreviation. File +explicit_array_values.rb+ defines options with explicit argument values. @@ -335,8 +335,12 @@ Executions: 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 + ["-x", "foo"] $ 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) $ ruby explicit_array_values.rb -x baz explicit_array_values.rb:9:in `<main>': invalid argument: -x baz (OptionParser::InvalidArgument) @@ -344,8 +348,8 @@ Executions: ===== 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. +The value passed must be one of those keys, or an unambiguous abbreviation; +the value yielded will be the value for that key. File +explicit_hash_values.rb+ defines options with explicit argument values. @@ -361,6 +365,8 @@ Executions: 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 + ["-x", 0] $ ruby explicit_hash_values.rb -x bar ["-x", 1] $ ruby explicit_hash_values.rb -x baz @@ -371,6 +377,8 @@ Executions: ["-y", 2] $ 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) $ ruby explicit_hash_values.rb -y bam ["-y", nil] diff --git a/doc/optparse/ruby/help.rb b/doc/optparse/ruby/help.rb index 72f1b93527..95bcde1d77 100644 --- a/doc/optparse/ruby/help.rb +++ b/doc/optparse/ruby/help.rb @@ -16,6 +16,3 @@ parser.on( 'nec, pellentesque eu, pretium quis, sem.', ) parser.parse! - - - diff --git a/doc/optparse/ruby/abbreviation.rb b/doc/optparse/ruby/name_abbrev.rb index b438c1b3dd..b438c1b3dd 100644 --- a/doc/optparse/ruby/abbreviation.rb +++ b/doc/optparse/ruby/name_abbrev.rb diff --git a/doc/optparse/tutorial.rdoc b/doc/optparse/tutorial.rdoc index a70146256d..dfdc244fe2 100644 --- a/doc/optparse/tutorial.rdoc +++ b/doc/optparse/tutorial.rdoc @@ -40,12 +40,18 @@ The class also has: - {Short Option Names}[#label-Short+Option+Names] - {Long Option Names}[#label-Long+Option+Names] - {Mixing Option Names}[#label-Mixing+Option+Names] - - {Command-Line Abbreviations}[#label-Command-Line+Abbreviations] + - {Option Name Abbreviations}[#label-Option+Name+Abbreviations] - {Option Arguments}[#label-Option+Arguments] - {Option with No Argument}[#label-Option+with+No+Argument] - {Option with Required Argument}[#label-Option+with+Required+Argument] - {Option with Optional Argument}[#label-Option+with+Optional+Argument] -- {Keyword Argument <tt>into</tt>}[#label-Keyword+Argument+into] + - {Argument Abbreviations}[#label-Argument+Abbreviations] +- {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] +- {Keyword Argument into}[#label-Keyword+Argument+into] - {Collecting Options}[#label-Collecting+Options] - {Checking for Missing Options}[#label-Checking+for+Missing+Options] - {Default Values for Options}[#label-Default+Values+for+Options] @@ -264,34 +270,34 @@ Executions: $ ruby mixed_names.rb --zzz BAT ["--zzz", "BAT"] -==== Command-Line Abbreviations +==== Option Name Abbreviations -By default, abbreviations for command-line option names are allowed. -An abbreviated option is valid if it is unique among abbreviated option names. +By default, abbreviated option names on the command-line are allowed. +An abbreviated name is valid if it is unique among abbreviated option names. - :include: ruby/abbreviation.rb + :include: ruby/name_abbrev.rb Executions: - $ ruby abbreviation.rb --help - Usage: abbreviation [options] + $ ruby name_abbrev.rb --help + Usage: name_abbrev [options] -n, --dry-run -d, --draft - $ ruby abbreviation.rb -n + $ ruby name_abbrev.rb -n ["--dry-run", true] - $ ruby abbreviation.rb --dry-run + $ ruby name_abbrev.rb --dry-run ["--dry-run", true] - $ ruby abbreviation.rb -d + $ ruby name_abbrev.rb -d ["--draft", true] - $ ruby abbreviation.rb --draft + $ ruby name_abbrev.rb --draft ["--draft", true] - $ ruby abbreviation.rb --d - abbreviation.rb:9:in `<main>': ambiguous option: --d (OptionParser::AmbiguousOption) - $ ruby abbreviation.rb --dr - abbreviation.rb:9:in `<main>': ambiguous option: --dr (OptionParser::AmbiguousOption) - $ ruby abbreviation.rb --dry + $ ruby name_abbrev.rb --d + 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) + $ ruby name_abbrev.rb --dry ["--dry-run", true] - $ ruby abbreviation.rb --dra + $ ruby name_abbrev.rb --dra ["--draft", true] You can disable abbreviation using method +require_exact+. @@ -367,6 +373,106 @@ Executions: Omitting an optional argument does not raise an error. +=== 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, or an unambiguous abbreviation. + +File +explicit_array_values.rb+ defines options with explicit argument values. + + :include: ruby/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 f + ["-x", "foo"] + $ 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) + $ 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, or an unambiguous abbreviation; +the value yielded will be the value for that key. + +File +explicit_hash_values.rb+ defines options with explicit argument values. + + :include: ruby/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 f + ["-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 ba + 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. + +File +matched_values.rb+ defines options with matched argument values. + + :include: ruby/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) + === Keyword Argument +into+ In parsing options, you can add keyword option +into+ with a hash-like argument; |