1berry/ruby
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[ruby/optparse] Rdoc (#15)

Browse Source 
* 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 2021-04-10 10:05:44 -05:00 committed by Nobuyoshi Nakada
parent c795f30ef0
commit ff0dac1849
10 changed files with 487 additions and 365 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

362
doc/argument_converters.rdoc Normal file
View 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]

376
doc/option_params.rdoc
View File

@ -29,6 +29,7 @@ Contents:
- {Simple Long Names}[#label-Simple+Long+Names] - {Simple Long Names}[#label-Simple+Long+Names]
- {Long Names with Required Arguments}[#label-Long+Names+with+Required+Arguments] - {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 Optional Arguments}[#label-Long+Names+with+Optional+Arguments]
- {Long Names with Negation}[#label-Long+Names+with+Negation]
- {Mixed Names}[#label-Mixed+Names] - {Mixed Names}[#label-Mixed+Names]
- {Argument Styles}[#label-Argument+Styles] - {Argument Styles}[#label-Argument+Styles]
- {Argument Values}[#label-Argument+Values] - {Argument Values}[#label-Argument+Values]
@ -37,23 +38,6 @@ Contents:
- {Explicit Values in Hash}[#label-Explicit+Values+in+Hash] - {Explicit Values in Hash}[#label-Explicit+Values+in+Hash]
- {Argument Value Patterns}[#label-Argument+Value+Patterns] - {Argument Value Patterns}[#label-Argument+Value+Patterns]
- {Argument Converters}[#label-Argument+Converters] - {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] - {Descriptions}[#label-Descriptions]
- {Option Handlers}[#label-Option+Handlers] - {Option Handlers}[#label-Option+Handlers]
- {Handler Blocks}[#label-Handler+Blocks] - {Handler Blocks}[#label-Handler+Blocks]
@ -222,6 +206,24 @@ Executions:
$ ruby long_optional.rb --xxx FOO $ ruby long_optional.rb --xxx FOO
["--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 ==== Mixed Names
An option may have both short and long 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: Executions:
$ ruby mixed_names.rb --help $ ruby mixed_names.rb --help
Usage: mixed_names [options] Usage: mixed_names [options]
-x, --xxx Short and long, simple -x, --xxx Short and long, no argument
--yyy yYYY -y, --yyyYYY Short and long, required argument
Short and long, required argument -z, --zzz [ZZZ] Short and long, optional argument
--zzz zZZZ
Short and long, optional argument
$ ruby mixed_names.rb -x $ ruby mixed_names.rb -x
["--xxx", true] ["--xxx", true]
$ ruby mixed_names.rb --xxx $ ruby mixed_names.rb --xxx
@ -400,334 +400,10 @@ Executions:
An option can specify that its argument is to be converted 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.
\OptionParser has a number of built-in converters, There are a number of built-in converters.
which are demonstrated below. You can also define custom converters.
==== \Date See {Argument Converters}[./argument_converters_rdoc.html].
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
=== Descriptions === Descriptions

9
doc/ruby/custom_converter.rb Normal file
View 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!

4
doc/ruby/long_names.rb
View File

@ -1,9 +1,9 @@
require 'optparse' require 'optparse'
parser = OptionParser.new parser = OptionParser.new
parser.on('--xxx') do |value| parser.on('--xxx', 'Long name') do |value|
p ['-xxx', value] p ['-xxx', value]
end end
parser.on('--y1%', '--z2#') do |value| parser.on('--y1%', '--z2#', "Two long names") do |value|
p ['--y1% or --z2#', value] p ['--y1% or --z2#', value]
end end
parser.parse! parser.parse!

2
doc/ruby/long_binary.rb → doc/ruby/long_with_negation.rb
View File

@ -1,6 +1,6 @@
require 'optparse' require 'optparse'
parser = OptionParser.new parser = OptionParser.new
parser.on('--[no-]binary') do |value| parser.on('--[no-]binary', 'Long name with negation') do |value|
p [value, value.class] p [value, value.class]
end end
parser.parse! parser.parse!

9
doc/ruby/mixed_names.rb
View File

@ -1,9 +1,12 @@
require 'optparse' require 'optparse'
parser = OptionParser.new parser = OptionParser.new
parser.on('-x', '--xxx') do |value| parser.on('-x', '--xxx', 'Short and long, no argument') do |value|
p ['--xxx', value] p ['--xxx', value]
end end
parser.on('-y', '--y1%') do |value| parser.on('-yYYY', '--yyy', 'Short and long, required argument') do |value|
p ['--y1%', value] p ['--yyy', value]
end
parser.on('-z [ZZZ]', '--zzz', 'Short and long, optional argument') do |value|
p ['--zzz', value]
end end
parser.parse! parser.parse!

4
doc/ruby/optional_argument.rb
View File

@ -1,9 +1,9 @@
require 'optparse' require 'optparse'
parser = OptionParser.new 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] p ['--xxx', value]
end end
parser.on('-y', '--yyy [YYY]') do |value| parser.on('-y', '--yyy [YYY]', 'Optional argument via long name') do |value|
p ['--yyy', value] p ['--yyy', value]
end end
parser.parse! parser.parse!

4
doc/ruby/required_argument.rb
View File

@ -1,9 +1,9 @@
require 'optparse' require 'optparse'
parser = OptionParser.new 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] p ['--xxx', value]
end end
parser.on('-y', '--y YYY') do |value| parser.on('-y', '--y YYY', 'Required argument via long name') do |value|
p ['--yyy', value] p ['--yyy', value]
end end
parser.parse! parser.parse!

4
doc/ruby/short_names.rb
View File

@ -1,9 +1,9 @@
require 'optparse' require 'optparse'
parser = OptionParser.new parser = OptionParser.new
parser.on('-x') do |value| parser.on('-x', 'Short name') do |value|
p ['x', value] p ['x', value]
end end
parser.on('-1', '-%') do |value| parser.on('-1', '-%', 'Two short names') do |value|
p ['-1 or -%', value] p ['-1 or -%', value]
end end
parser.parse! parser.parse!

78
doc/tutorial.rdoc
View File

@ -32,6 +32,19 @@ The class also has:
- Method #summarize: returns a text summary of the options. - Method #summarize: returns a text summary of the options.
- Method #help: displays automatically-generated help text. - 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 === Defining Options
A common way to define an option in \OptionParser 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: Executions:
$ ruby short_names.rb --help
Usage: short_names [options]
-x Short name
-1, -% Two short names
$ ruby short_names.rb -x $ ruby short_names.rb -x
["x", true] ["x", true]
$ ruby short_names.rb -1 $ 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: Executions:
$ ruby long_names.rb --help
Usage: long_names [options]
--xxx Long name
--y1%, --z2# Two long names
$ ruby long_names.rb --xxx $ ruby long_names.rb --xxx
["-xxx", true] ["-xxx", true]
$ ruby long_names.rb --y1% $ ruby long_names.rb --y1%
@ -110,6 +131,22 @@ Executions:
$ ruby long_names.rb --z2# $ ruby long_names.rb --z2#
["--y1% or --z2#", true] ["--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 ==== Mixing Option Names
Many developers like to mix short and long 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: 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 $ ruby mixed_names.rb -x
["--xxx", true] ["--xxx", true]
$ ruby mixed_names.rb --xxx $ ruby mixed_names.rb --xxx
["--xxx", true] ["--xxx", true]
$ ruby mixed_names.rb -y $ ruby mixed_names.rb -y
["--y1%", true] mixed_names.rb:12:in `<main>': missing argument: -y (OptionParser::MissingArgument)
$ ruby mixed_names.rb --y1% $ ruby mixed_names.rb -y FOO
["--y1%", true] ["--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 === Option Arguments
@ -153,6 +207,10 @@ When an option is found, the given argument is yielded.
Executions: 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 $ ruby required_argument.rb -x AAA
["--xxx", "AAA"] ["--xxx", "AAA"]
$ ruby required_argument.rb -y BBB $ ruby required_argument.rb -y BBB
@ -178,9 +236,23 @@ When an option with an argument is found, the given argument yielded.
Executions: 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 $ ruby optional_argument.rb -x AAA
["--xxx", "AAA"] ["--xxx", "AAA"]
$ ruby optional_argument.rb -y BBB $ ruby optional_argument.rb -y BBB
["--yyy", "BBB"] ["--yyy", "BBB"]
Omitting an optional argument does not raise an error. 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].