diff options
Diffstat (limited to 'doc/optparse/option_params.rdoc')
| -rw-r--r-- | doc/optparse/option_params.rdoc | 81 |
1 files changed, 40 insertions, 41 deletions
diff --git a/doc/optparse/option_params.rdoc b/doc/optparse/option_params.rdoc index 0d06b41e7d..575ee66cdb 100644 --- a/doc/optparse/option_params.rdoc +++ b/doc/optparse/option_params.rdoc @@ -1,6 +1,6 @@ == Parameters for New Options -Option-creating methods in \OptionParser +Option-creating methods in +OptionParser+ accept arguments that determine the behavior of a new option: - OptionParser#on @@ -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] @@ -43,7 +43,6 @@ Contents: - {Handler Blocks}[#label-Handler+Blocks] - {Handler Procs}[#label-Handler+Procs] - {Handler Methods}[#label-Handler+Methods] -- {Terminators}[#label-Terminators] === Option Names @@ -92,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"] @@ -182,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"] @@ -244,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 @@ -280,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"] @@ -299,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"] @@ -319,7 +318,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. @@ -332,20 +331,24 @@ 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 + ["-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_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. +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. @@ -358,26 +361,31 @@ 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 + ["-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) + 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. +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. @@ -388,22 +396,32 @@ 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 An option can specify that its argument is to be converted -from the default \String to an instance of another class. +from the default +String+ to an instance of another class. There are a number of built-in converters. You can also define custom converters. -See {Argument Converters}[./argument_converters_rdoc.html]. +See {Argument Converters}[./argument_converters.rdoc]. === Descriptions @@ -411,7 +429,7 @@ 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. +in other words, it does not begin with a hyphen. You may give any number of description parameters; each becomes a line in the text generated by option <tt>--help</tt>. @@ -446,7 +464,7 @@ when the option is encountered. The handler may be: ==== Handler Blocks -An option hadler may be a block. +An option handler may be a block. File +block.rb+ defines an option that has a handler block. @@ -500,22 +518,3 @@ Executions: ["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: ruby/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] |