diff options
Diffstat (limited to 'doc/option_params.rdoc')
| -rw-r--r-- | doc/option_params.rdoc | 376 |
1 files changed, 26 insertions, 350 deletions
diff --git a/doc/option_params.rdoc b/doc/option_params.rdoc index 98d9630a38..0d06b41e7d 100644 --- a/doc/option_params.rdoc +++ b/doc/option_params.rdoc @@ -29,6 +29,7 @@ Contents: - {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] + - {Long Names with Negation}[#label-Long+Names+with+Negation] - {Mixed Names}[#label-Mixed+Names] - {Argument Styles}[#label-Argument+Styles] - {Argument Values}[#label-Argument+Values] @@ -37,23 +38,6 @@ Contents: - {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] - {Option Handlers}[#label-Option+Handlers] - {Handler Blocks}[#label-Handler+Blocks] @@ -222,6 +206,24 @@ Executions: $ ruby long_optional.rb --xxx FOO ["--xxx", "FOO"] +===== Long Names with Negation + +A long name may be defined with both positive and negative senses. + +File +long_with_negation.rb+ defines an option that has both senses. + + :include: ruby/long_with_negation.rb + +Executions: + + $ ruby long_with_negation.rb --help + Usage: long_with_negation [options] + --[no-]binary Long name with negation + $ ruby long_with_negation.rb --binary + [true, TrueClass] + $ ruby long_with_negation.rb --no-binary + [false, FalseClass] + ==== Mixed Names An option may have both short and long names. @@ -233,12 +235,10 @@ File +mixed_names.rb+ defines a mixture of short and long names. 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 +Usage: mixed_names [options] + -x, --xxx Short and long, no argument + -y, --yyyYYY Short and long, required argument + -z, --zzz [ZZZ] Short and long, optional argument $ ruby mixed_names.rb -x ["--xxx", true] $ ruby mixed_names.rb --xxx @@ -400,334 +400,10 @@ Executions: 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: ruby/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: ruby/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: ruby/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: ruby/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: ruby/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: ruby/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: ruby/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: ruby/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: ruby/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: ruby/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: ruby/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: ruby/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: ruby/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: ruby/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: ruby/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: ruby/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: ruby/regexp.rb - -Executions: +There are a number of built-in converters. +You can also define custom converters. - $ ruby regexp.rb --regexp foo +See {Argument Converters}[./argument_converters_rdoc.html]. === Descriptions |