mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
[ruby/optparse] Rdoc (#15)
* Resolve shared mixed_names.rb * Add long option with negation * Show --help for all examples * Table of contents for tutorial * Move argument converters to separate rdoc * Add references to argument_converters.rdoc * Tune up argument converters * Change explicit links to auto-links https://github.com/ruby/optparse/commit/c91ed8d33d
This commit is contained in:
Burdette Lamar
Nobuyoshi Nakada
parent
c795f30ef0
commit
ff0dac1849
10 changed files with 487 additions and 365 deletions
362
doc/argument_converters.rdoc
Normal file
362
doc/argument_converters.rdoc
Normal file
|
|
@ -0,0 +1,362 @@
|
|||
== Argument Converters
|
||||
|
||||
An option can specify that its argument is to be converted
|
||||
from the default \String to an instance of another class.
|
||||
|
||||
=== Contents
|
||||
|
||||
- {Built-In Argument Converters}[#label-Built-In+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]
|
||||
- {Custom Argument Converters}[#label-Custom+Argument+Converters]
|
||||
|
||||
=== Built-In Argument Converters
|
||||
|
||||
\OptionParser has a number of built-in argument 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.
|
||||
|
||||
: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.
|
||||
|
||||
: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 or Time#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.
|
||||
|
||||
: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.
|
||||
|
||||
: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.
|
||||
|
||||
: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.
|
||||
|
||||
: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,
|
||||
Kernel#Float, or Kernel#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.
|
||||
|
||||
: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.
|
||||
|
||||
: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
|
||||
|
||||
: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?.
|
||||
|
||||
: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?.
|
||||
|
||||
: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:
|
||||
|
||||
$ ruby regexp.rb --regexp foo
|
||||
|
||||
=== Custom Argument Converters
|
||||
|
||||
You can create custom argument converters.
|
||||
To create a custom converter, call OptionParser#accept with a class argument,
|
||||
along with a block that converts the argument and returns the converted value.
|
||||
|
||||
:include: ruby/custom_converter.rb
|
||||
|
||||
Executions:
|
||||
|
||||
$ ruby custom_converter.rb --complex 0
|
||||
[(0+0i), Complex]
|
||||
$ ruby custom_converter.rb --complex 1
|
||||
[(1+0i), Complex]
|
||||
$ ruby custom_converter.rb --complex 1+2i
|
||||
[(1+2i), Complex]
|
||||
$ ruby custom_converter.rb --complex 0.3-0.5i
|
||||
[(0.3-0.5i), Complex]
|
||||
|
|
@ -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.
|
||||
There are a number of built-in converters.
|
||||
You can also define custom converters.
|
||||
|
||||
==== \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:
|
||||
|
||||
$ ruby regexp.rb --regexp foo
|
||||
See {Argument Converters}[./argument_converters_rdoc.html].
|
||||
|
||||
=== Descriptions
|
||||
|
||||
|
|
|
|||
9
doc/ruby/custom_converter.rb
Normal file
9
doc/ruby/custom_converter.rb
Normal file
|
|
@ -0,0 +1,9 @@
|
|||
require 'optparse/date'
|
||||
parser = OptionParser.new
|
||||
parser.accept(Complex) do |value|
|
||||
value.to_c
|
||||
end
|
||||
parser.on('--complex COMPLEX', Complex) do |value|
|
||||
p [value, value.class]
|
||||
end
|
||||
parser.parse!
|
||||
|
|
@ -1,9 +1,9 @@
|
|||
require 'optparse'
|
||||
parser = OptionParser.new
|
||||
parser.on('--xxx') do |value|
|
||||
parser.on('--xxx', 'Long name') do |value|
|
||||
p ['-xxx', value]
|
||||
end
|
||||
parser.on('--y1%', '--z2#') do |value|
|
||||
parser.on('--y1%', '--z2#', "Two long names") do |value|
|
||||
p ['--y1% or --z2#', value]
|
||||
end
|
||||
parser.parse!
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
require 'optparse'
|
||||
parser = OptionParser.new
|
||||
parser.on('--[no-]binary') do |value|
|
||||
parser.on('--[no-]binary', 'Long name with negation') do |value|
|
||||
p [value, value.class]
|
||||
end
|
||||
parser.parse!
|
||||
|
|
@ -1,9 +1,12 @@
|
|||
require 'optparse'
|
||||
parser = OptionParser.new
|
||||
parser.on('-x', '--xxx') do |value|
|
||||
parser.on('-x', '--xxx', 'Short and long, no argument') do |value|
|
||||
p ['--xxx', value]
|
||||
end
|
||||
parser.on('-y', '--y1%') do |value|
|
||||
p ['--y1%', value]
|
||||
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!
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
require 'optparse'
|
||||
parser = OptionParser.new
|
||||
parser.on('-x [XXX]', '--xxx') do |value|
|
||||
parser.on('-x [XXX]', '--xxx', 'Optional argument via short name') do |value|
|
||||
p ['--xxx', value]
|
||||
end
|
||||
parser.on('-y', '--yyy [YYY]') do |value|
|
||||
parser.on('-y', '--yyy [YYY]', 'Optional argument via long name') do |value|
|
||||
p ['--yyy', value]
|
||||
end
|
||||
parser.parse!
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
require 'optparse'
|
||||
parser = OptionParser.new
|
||||
parser.on('-x XXX', '--xxx') do |value|
|
||||
parser.on('-x XXX', '--xxx', 'Required argument via short name') do |value|
|
||||
p ['--xxx', value]
|
||||
end
|
||||
parser.on('-y', '--y YYY') do |value|
|
||||
parser.on('-y', '--y YYY', 'Required argument via long name') do |value|
|
||||
p ['--yyy', value]
|
||||
end
|
||||
parser.parse!
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
require 'optparse'
|
||||
parser = OptionParser.new
|
||||
parser.on('-x') do |value|
|
||||
parser.on('-x', 'Short name') do |value|
|
||||
p ['x', value]
|
||||
end
|
||||
parser.on('-1', '-%') do |value|
|
||||
parser.on('-1', '-%', 'Two short names') do |value|
|
||||
p ['-1 or -%', value]
|
||||
end
|
||||
parser.parse!
|
||||
|
|
|
|||
|
|
@ -32,6 +32,19 @@ The class also has:
|
|||
- Method #summarize: returns a text summary of the options.
|
||||
- Method #help: displays automatically-generated help text.
|
||||
|
||||
=== Contents
|
||||
|
||||
- {Defining Options}[#label-Defining+Options]
|
||||
- {Option Names}[#label-Option+Names]
|
||||
- {Short Option Names}[#label-Short+Option+Names]
|
||||
- {Long Option Names}[#label-Long+Option+Names]
|
||||
- {Mixing Option Names}[#label-Mixing+Option+Names]
|
||||
- {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]
|
||||
- {Argument Converters}[#label-Argument+Converters]
|
||||
|
||||
=== Defining Options
|
||||
|
||||
A common way to define an option in \OptionParser
|
||||
|
|
@ -71,6 +84,10 @@ and an option with two short names (aliases, in effect) <tt>-y</tt> and <tt>-z</
|
|||
|
||||
Executions:
|
||||
|
||||
$ ruby short_names.rb --help
|
||||
Usage: short_names [options]
|
||||
-x Short name
|
||||
-1, -% Two short names
|
||||
$ ruby short_names.rb -x
|
||||
["x", true]
|
||||
$ ruby short_names.rb -1
|
||||
|
|
@ -103,6 +120,10 @@ and an option with two long names (aliases, in effect) <tt>--y1%</tt> and <tt>--
|
|||
|
||||
Executions:
|
||||
|
||||
$ ruby long_names.rb --help
|
||||
Usage: long_names [options]
|
||||
--xxx Long name
|
||||
--y1%, --z2# Two long names
|
||||
$ ruby long_names.rb --xxx
|
||||
["-xxx", true]
|
||||
$ ruby long_names.rb --y1%
|
||||
|
|
@ -110,6 +131,22 @@ Executions:
|
|||
$ ruby long_names.rb --z2#
|
||||
["--y1% or --z2#", true]
|
||||
|
||||
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]
|
||||
|
||||
==== Mixing Option Names
|
||||
|
||||
Many developers like to mix short and long option names,
|
||||
|
|
@ -122,14 +159,31 @@ defines options that each have both a short and a long name.
|
|||
|
||||
Executions:
|
||||
|
||||
$ ruby mixed_names.rb --help
|
||||
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
|
||||
["--xxx", true]
|
||||
$ ruby mixed_names.rb -y
|
||||
["--y1%", true]
|
||||
$ ruby mixed_names.rb --y1%
|
||||
["--y1%", true]
|
||||
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"]
|
||||
|
||||
=== Option Arguments
|
||||
|
||||
|
|
@ -153,6 +207,10 @@ When an option is found, the given argument is yielded.
|
|||
|
||||
Executions:
|
||||
|
||||
$ ruby required_argument.rb --help
|
||||
Usage: required_argument [options]
|
||||
-x, --xxx XXX Required argument via short name
|
||||
-y, --y YYY Required argument via long name
|
||||
$ ruby required_argument.rb -x AAA
|
||||
["--xxx", "AAA"]
|
||||
$ ruby required_argument.rb -y BBB
|
||||
|
|
@ -178,9 +236,23 @@ When an option with an argument is found, the given argument yielded.
|
|||
|
||||
Executions:
|
||||
|
||||
$ ruby optional_argument.rb --help
|
||||
Usage: optional_argument [options]
|
||||
-x, --xxx [XXX] Optional argument via short name
|
||||
-y, --yyy [YYY] Optional argument via long name
|
||||
$ ruby optional_argument.rb -x AAA
|
||||
["--xxx", "AAA"]
|
||||
$ ruby optional_argument.rb -y BBB
|
||||
["--yyy", "BBB"]
|
||||
|
||||
Omitting an optional argument does not raise an error.
|
||||
|
||||
=== Argument Converters
|
||||
|
||||
An option can specify that its argument is to be converted
|
||||
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].
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue