kotovalexarian-likes-github/ruby--ruby
1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2022-11-09 12:17:21 -05:00
Code Releases Activity

Manually picking https://github.com/ruby/optparse/pull/14

Browse source
This commit is contained in:
Hiroshi SHIBATA 2021-07-28 15:24:19 +09:00
parent 3026ee56b1
commit 23ef326656
No known key found for this signature in database
GPG key ID: F9CF13417264FAC2
44 changed files with 0 additions and 1339 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
doc/option_params/argument_keywords.rb
View file

@ -1,6 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on('-x', '--xxx', :REQUIRED, 'Required argument') do |value|
p ['--xxx', value]
end
parser.parse!

6
doc/option_params/argument_strings.rb
View file

@ -1,6 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on('-x', '--xxx', '=XXX', 'Required argument') do |value|
p ['--xxx', value]
end
parser.parse!

6
doc/option_params/array.rb
View file

@ -1,6 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on('--array=ARRAY', Array) do |value|
p [value, value.class]
end
parser.parse!

9
doc/option_params/block.rb
View file

@ -1,9 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on('--xxx', 'Option with no argument') do |value|
p ['Handler block for -xxx called with value:', value]
end
parser.on('--yyy YYY', 'Option with required argument') do |value|
p ['Handler block for -yyy called with value:', value]
end
parser.parse!

6
doc/option_params/date.rb
View file

@ -1,6 +0,0 @@
require 'optparse/date'
parser = OptionParser.new
parser.on('--date=DATE', Date) do |value|
p [value, value.class]
end
parser.parse!

6
doc/option_params/datetime.rb
View file

@ -1,6 +0,0 @@
require 'optparse/date'
parser = OptionParser.new
parser.on('--datetime=DATETIME', DateTime) do |value|
p [value, value.class]
end
parser.parse!

7
doc/option_params/decimal_integer.rb
View file

@ -1,7 +0,0 @@
require 'optparse'
include OptionParser::Acceptables
parser = OptionParser.new
parser.on('--decimal_integer=DECIMAL_INTEGER', DecimalInteger) do |value|
p [value, value.class]
end
parser.parse!

7
doc/option_params/decimal_numeric.rb
View file

@ -1,7 +0,0 @@
require 'optparse'
include OptionParser::Acceptables
parser = OptionParser.new
parser.on('--decimal_numeric=DECIMAL_NUMERIC', DecimalNumeric) do |value|
p [value, value.class]
end
parser.parse!

15
doc/option_params/descriptions.rb
View file

@ -1,15 +0,0 @@
require 'optparse'
parser = OptionParser.new
description = <<-EOT
Lorem ipsum dolor sit amet, consectetuer
adipiscing elit. Aenean commodo ligula eget.
Aenean massa. Cum sociis natoque penatibus
et magnis dis parturient montes, nascetur
ridiculus mus. Donec quam felis, ultricies
nec, pellentesque eu, pretium quis, sem.
EOT
descriptions = description.split($/)
parser.on('--xxx', *descriptions) do |value|
p ['--xxx', value]
end
parser.parse!

9
doc/option_params/explicit_array_values.rb
View file

@ -1,9 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on('-xXXX', ['foo', 'bar'], 'Values for required argument' ) do |value|
p ['-x', value]
end
parser.on('-y [YYY]', ['baz', 'bat'], 'Values for optional argument') do |value|
p ['-y', value]
end
parser.parse!

9
doc/option_params/explicit_hash_values.rb
View file

@ -1,9 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on('-xXXX', {foo: 0, bar: 1}, 'Values for required argument' ) do |value|
p ['-x', value]
end
parser.on('-y [YYY]', {baz: 2, bat: 3}, 'Values for optional argument') do |value|
p ['-y', value]
end
parser.parse!

6
doc/option_params/false_class.rb
View file

@ -1,6 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on('--false_class=FALSE_CLASS', FalseClass) do |value|
p [value, value.class]
end
parser.parse!

6
doc/option_params/float.rb
View file

@ -1,6 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on('--float=FLOAT', Float) do |value|
p [value, value.class]
end
parser.parse!

6
doc/option_params/integer.rb
View file

@ -1,6 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on('--integer=INTEGER', Integer) do |value|
p [value, value.class]
end
parser.parse!

6
doc/option_params/long_binary.rb
View file

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

6
doc/option_params/long_optional.rb
View file

@ -1,6 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on('--xxx [XXX]', 'Long name with optional argument') do |value|
p ['--xxx', value]
end
parser.parse!

6
doc/option_params/long_required.rb
View file

@ -1,6 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on('--xxx XXX', 'Long name with required argument') do |value|
p ['--xxx', value]
end
parser.parse!

9
doc/option_params/long_simple.rb
View file

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

6
doc/option_params/matched_values.rb
View file

@ -1,6 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on('--xxx XXX', /foo/i, 'Matched values') do |value|
p ['--xxx', value]
end
parser.parse!

11
doc/option_params/method.rb
View file

@ -1,11 +0,0 @@
require 'optparse'
parser = OptionParser.new
def xxx_handler(value)
p ['Handler method for -xxx called with value:', value]
end
parser.on('--xxx', 'Option with no argument', method(:xxx_handler))
def yyy_handler(value)
p ['Handler method for -yyy called with value:', value]
end
parser.on('--yyy YYY', 'Option with required argument', method(:yyy_handler))
parser.parse!

12
doc/option_params/mixed_names.rb
View file

@ -1,12 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on('-x', '--xxx', 'Short and long, simple') do |value|
p ['--xxx', value]
end
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!

6
doc/option_params/numeric.rb
View file

@ -1,6 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on('--numeric=NUMERIC', Numeric) do |value|
p [value, value.class]
end
parser.parse!

6
doc/option_params/object.rb
View file

@ -1,6 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on('--object=OBJECT', Object) do |value|
p [value, value.class]
end
parser.parse!

7
doc/option_params/octal_integer.rb
View file

@ -1,7 +0,0 @@
require 'optparse'
include OptionParser::Acceptables
parser = OptionParser.new
parser.on('--octal_integer=OCTAL_INTEGER', OctalInteger) do |value|
p [value, value.class]
end
parser.parse!

845
doc/option_params/option_params.rdoc
View file

@ -1,845 +0,0 @@
== Parameters for New Options
Option-creating methods in \OptionParser
accept arguments that determine the behavior of a new option:
- OptionParser#on
- OptionParser#on_head
- OptionParser#on_tail
- OptionParser#define
- OptionParser#define_head
- OptionParser#define_tail
- OptionParser#make_switch
The code examples on this page use:
- OptionParser#on, to define options.
- OptionParser#parse!, to parse the command line.
- Built-in option <tt>--help</tt>, to display defined options.
Contents:
- {Option Names}[#label-Option+Names]
- {Short Names}[#label-Short+Names]
- {Simple Short Names}[#label-Simple+Short+Names]
- {Short Names with Required Arguments}[#label-Short+Names+with+Required+Arguments]
- {Short Names with Optional Arguments}[#label-Short+Names+with+Optional+Arguments]
- {Short Names from Range}[#label-Short+Names+from+Range]
- {Long Names}[#label-Long+Names]
- {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]
- {Mixed Names}[#label-Mixed+Names]
- {Argument Styles}[#label-Argument+Styles]
- {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]
- {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]
- {Handlers}[#label-Handlers]
- {Handler Blocks}[#label-Handler+Blocks]
- {Handler Procs}[#label-Handler+Procs]
- {Handler Methods}[#label-Handler+Methods]
- {Terminators}[#label-Terminators]
=== Option Names
There are two kinds of option names:
- Short option name, consisting of a single hyphen and a single character.
- Long option name, consisting of two hyphens and one or more characters.
==== Short Names
===== Simple Short Names
File +short_simple.rb+ defines two options:
- One with short name <tt>-x</tt>.
- The other with two short names, in effect, aliases, <tt>-1</tt> and <tt>-%</tt>.
:include: short_simple.rb
Executions:
$ ruby short_simple.rb --help
Usage: short_simple [options]
-x One short name
-1, -% Two short names (aliases)
$ ruby short_simple.rb -x
["-x", true]
$ ruby short_simple.rb -1 -x -%
["-1 or -%", true]
["-x", true]
["-1 or -%", true]
===== Short Names with Required Arguments
A short name followed (no whitespace) by a dummy word
defines an option that requires an argument.
File +short_required.rb+ defines an option <tt>-x</tt>
that requires an argument.
:include: short_required.rb
Executions:
$ ruby short_required.rb --help
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)
$ ruby short_required.rb -x FOO
["-x", "FOO"]
===== Short Names with Optional Arguments
A short name followed (with whitespace) by a dummy word in square brackets
defines an option that allows an optional argument.
File +short_optional.rb+ defines an option <tt>-x</tt>
that allows an optional argument.
:include: short_optional.rb
Executions:
$ ruby short_optional.rb --help
Usage: short_optional [options]
-x [XXX] Short name with optional argument
$ ruby short_optional.rb -x
["-x", nil]
$ ruby short_optional.rb -x FOO
["-x", "FOO"]
===== Short Names from Range
You can define an option with multiple short names
taken from a range of characters.
The parser yields both the actual character cited and the value.
File +short_range.rb+ defines an option with short names
for all printable characters from <tt>!</tt> to <tt>~</tt>:
:include: short_range.rb
Executions:
$ ruby short_range.rb --help
Usage: short_range [options]
-[!-~] Short names in (very large) range
$ ruby short_range.rb -!
["!-~", "!", nil]
$ ruby short_range.rb -!
["!-~", "!", nil]
$ ruby short_range.rb -A
["!-~", "A", nil]
$ ruby short_range.rb -z
["!-~", "z", nil]
==== Long Names
===== Simple Long Names
File +long_simple.rb+ defines two options:
- One with long name <tt>-xxx</tt>.
- The other with two long names, in effect, aliases,
<tt>--y1%</tt> and <tt>--z2#</tt>.
:include: long_simple.rb
Executions:
$ ruby long_simple.rb --help
Usage: long_simple [options]
--xxx One long name
--y1%, --z2# Two long names (aliases)
$ ruby long_simple.rb --xxx
["--xxx", true]
$ ruby long_simple.rb --y1% --xxx --z2#
["--y1% or --z2#", true]
["--xxx", true]
["--y1% or --z2#", true]
===== Long Names with Required Arguments
A long name followed (with whitespace) by a dummy word
defines an option that requires an argument.
File +long_required.rb+ defines an option <tt>--xxx</tt>
that requires an argument.
:include: long_required.rb
Executions:
$ ruby long_required.rb --help
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)
$ ruby long_required.rb --xxx FOO
["--xxx", "FOO"]
===== Long Names with Optional Arguments
A long name followed (with whitespace) by a dummy word in square brackets
defines an option that allows an optional argument.
File +long_optional.rb+ defines an option <tt>--xxx</tt>
that allows an optional argument.
:include: long_optional.rb
Executions:
$ ruby long_optional.rb --help
Usage: long_optional [options]
--xxx [XXX] Long name with optional argument
$ ruby long_optional.rb --xxx
["--xxx", nil]
$ ruby long_optional.rb --xxx FOO
["--xxx", "FOO"]
==== Mixed Names
An option may have both short and long names.
File +mixed_names.rb+ defines a mixture of short and long names.
:include: mixed_names.rb
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
$ ruby mixed_names.rb -x
["--xxx", true]
$ ruby mixed_names.rb --xxx
["--xxx", true]
$ ruby mixed_names.rb -y
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"]
=== Argument Keywords
As seen above, a given option name string may itself
indicate whether the option has no argument, a required argument,
or an optional argument.
An alternative is to use a separate symbol keyword,
which is one of <tt>:NONE</tt> (the default),
<tt>:REQUIRED</tt>, <tt>:OPTIONAL</tt>.
File +argument_keywords.rb+ defines an option with a required argument.
:include: argument_keywords.rb
Executions:
$ ruby argument_keywords.rb --help
Usage: argument_keywords [options]
-x, --xxx Required argument
$ ruby argument_styles.rb --xxx
argument_styles.rb:6:in `<main>': missing argument: --xxx (OptionParser::MissingArgument)
$ ruby argument_styles.rb --xxx FOO
["--xxx", "FOO"]
=== Argument Strings
Still another way to specify a required argument
is to define it in a string separate from the name string.
File +argument_strings.rb+ defines an option with a required argument.
:include: argument_strings.rb
Executions:
$ ruby argument_strings.rb --help
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)
$ ruby argument_strings.rb --xxx FOO
["--xxx", "FOO"]
=== 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.
File +explicit_array_values.rb+ defines options with explicit argument values.
:include: 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 bar
["-x", "bar"]
$ 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,
and the value yielded will be the value for that key.
File +explicit_hash_values.rb+ defines options with explicit argument values.
:include: 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 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 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: 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)
=== Argument Converters
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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: regexp.rb
Executions:
$ ruby regexp.rb --regexp foo
=== Descriptions
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.
You may give any number of description parameters;
each becomes a line in the text generated by option <tt>--help</tt>.
File +descriptions.rb+ has six strings in its array +descriptions+.
These are all passed as parameters to OptionParser#on, so that they
all, line for line, become the option's description.
:include: descriptions.rb
Executions:
$ ruby descriptions.rb --help
Usage: descriptions [options]
--xxx Lorem ipsum dolor sit amet, consectetuer
adipiscing elit. Aenean commodo ligula eget.
Aenean massa. Cum sociis natoque penatibus
et magnis dis parturient montes, nascetur
ridiculus mus. Donec quam felis, ultricies
nec, pellentesque eu, pretium quis, sem.
$ ruby descriptions.rb --xxx
["--xxx", true]
=== Handlers
The handler for an option is an executable that will be called
when the option is encountered. The handler may be:
- A block (this is most often seen).
- A proc.
- A method.
==== Handler Blocks
An option hadler may be a block.
File +block.rb+ defines an option that has a handler block.
:include: block.rb
Executions:
$ ruby block.rb --help
Usage: block [options]
--xxx Option with no argument
--yyy YYY Option with required argument
$ ruby block.rb --xxx
["Handler block for -xxx called with value:", true]
$ ruby block.rb --yyy FOO
["Handler block for -yyy called with value:", "FOO"]
==== Handler Procs
An option handler may be a Proc.
File +proc.rb+ defines an option that has a handler proc.
:include: proc.rb
Executions:
$ ruby proc.rb --help
Usage: proc [options]
--xxx Option with no argument
--yyy YYY Option with required argument
$ ruby proc.rb --xxx
["Handler proc for -xxx called with value:", true]
$ ruby proc.rb --yyy FOO
["Handler proc for -yyy called with value:", "FOO"]
==== Handler Methods
An option handler may be a Method.
File +proc.rb+ defines an option that has a handler method.
:include: method.rb
Executions:
$ ruby method.rb --help
Usage: method [options]
--xxx Option with no argument
--yyy YYY Option with required argument
$ ruby method.rb --xxx
["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: 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]

13
doc/option_params/proc.rb
View file

@ -1,13 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on(
'--xxx',
'Option with no argument',
->(value) {p ['Handler proc for -xxx called with value:', value]}
)
parser.on(
'--yyy YYY',
'Option with required argument',
->(value) {p ['Handler proc for -yyy called with value:', value]}
)
parser.parse!

6
doc/option_params/regexp.rb
View file

@ -1,6 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on('--regexp=REGEXP', Regexp) do |value|
p [value, value.class]
end
parser.parse!

6
doc/option_params/shellwords.rb
View file

@ -1,6 +0,0 @@
require 'optparse/shellwords'
parser = OptionParser.new
parser.on('--shellwords=SHELLWORDS', Shellwords) do |value|
p [value, value.class]
end
parser.parse!

6
doc/option_params/short_optional.rb
View file

@ -1,6 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on('-x [XXX]', 'Short name with optional argument') do |value|
p ['-x', value]
end
parser.parse!

6
doc/option_params/short_range.rb
View file

@ -1,6 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on('-[!-~]', 'Short names in (very large) range') do |name, value|
p ['!-~', name, value]
end
parser.parse!

6
doc/option_params/short_required.rb
View file

@ -1,6 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on('-xXXX', 'Short name with required argument') do |value|
p ['-x', value]
end
parser.parse!

9
doc/option_params/short_simple.rb
View file

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

6
doc/option_params/string.rb
View file

@ -1,6 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on('--string=STRING', String) do |value|
p [value, value.class]
end
parser.parse!

6
doc/option_params/terminator.rb
View file

@ -1,6 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on('--my_option XXX') do |value|
p [value, value.class]
end
parser.parse!

6
doc/option_params/time.rb
View file

@ -1,6 +0,0 @@
require 'optparse/time'
parser = OptionParser.new
parser.on('--time=TIME', Time) do |value|
p [value, value.class]
end
parser.parse!

6
doc/option_params/true_class.rb
View file

@ -1,6 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on('--true_class=TRUE_CLASS', TrueClass) do |value|
p [value, value.class]
end
parser.parse!

6
doc/option_params/uri.rb
View file

@ -1,6 +0,0 @@
require 'optparse/uri'
parser = OptionParser.new
parser.on('--uri=URI', URI) do |value|
p [value, value.class]
end
parser.parse!

2
doc/tutorial/argv.rb
View file

@ -1,2 +0,0 @@
p ARGV

9
doc/tutorial/long_names.rb
View file

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

9
doc/tutorial/mixed_names.rb
View file

@ -1,9 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on('-x', '--xxx') do |value|
p ['--xxx', value]
end
parser.on('-y', '--y1%') do |value|
p ['--y1%', value]
end
parser.parse!

9
doc/tutorial/optional_argument.rb
View file

@ -1,9 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on('-x [XXX]', '--xxx') do |value|
p ['--xxx', value]
end
parser.on('-y', '--yyy [YYY]') do |value|
p ['--yyy', value]
end
parser.parse!

9
doc/tutorial/required_argument.rb
View file

@ -1,9 +0,0 @@
require 'optparse'
parser = OptionParser.new
parser.on('-x XXX', '--xxx') do |value|
p ['--xxx', value]
end
parser.on('-y', '--y YYY') do |value|
p ['--yyy', value]
end
parser.parse!

9
doc/tutorial/short_names.rb
View file

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

186
doc/tutorial/tutorial.rdoc
View file

@ -1,186 +0,0 @@
== Tutorial
=== Why OptionParser?
When a Ruby program executes, it captures its command-line arguments
and options into variable ARGV.
This simple program just prints its \ARGV:
:include: argv.rb
Execution, with arguments and options:
$ ruby argv.rb foo --bar --baz bat bam
["foo", "--bar", "--baz", "bat", "bam"]
The executing program is responsible for parsing and handling
the command-line options.
OptionParser offers methods for parsing and handling those options.
With \OptionParser, you can define options so that for each option:
- The code that defines the option and code that handles that option
are in the same place.
- The option may take no argument, a required argument, or an optional argument.
- The argument may be automatically converted to a specified class.
- The argument may be restricted to specified _forms_.
- The argument may be restricted to specified _values_.
The class also has:
- Method #summarize: returns a text summary of the options.
- Method #help: displays automatically-generated help text.
=== Defining Options
A common way to define an option in \OptionParser
is with instance method OptionParser#on.
The method may be called with any number of arguments
(whose order does not matter),
and may also have a trailing optional keyword argument +into+.
The given arguments determine the characteristics of the new option.
These may include:
- One or more short option names.
- One or more long option names.
- Whether the option takes no argument, an optional argument, or a required argument.
- Acceptable _forms_ for the argument.
- Acceptable _values_ for the argument.
- A proc or method to be called when the parser encounters the option.
- String descriptions for the option.
=== Option Names
You can give an option one or more names of two types:
- Short (1-character) name, beginning with one hyphen (<tt>-</tt>).
- Long (multi-character) name, beginning with two hyphens (<tt>--</tt>).
==== Short Option Names
A short option name consists of a hyphen and a single character.
File +short_names.rb+
defines an option with a short name, <tt>-x</tt>,
and an option with two short names (aliases, in effect) <tt>-y</tt> and <tt>-z</tt>.
:include: short_names.rb
Executions:
$ ruby short_names.rb -x
["x", true]
$ ruby short_names.rb -1
["-1 or -%", true]
$ ruby short_names.rb -%
["-1 or -%", true]
Multiple short names can "share" a hyphen:
$ ruby short_names.rb -x1%
["x", true]
["-1 or -%", true]
["-1 or -%", true]
This is a good time to note that giving an undefined option raises an exception:
$ ruby short_names.rb -z
short_names.rb:9:in `<main>': invalid option: -z (OptionParser::InvalidOption)
==== Long Option Names
A long option name consists of two hyphens and a one or more characters
(usually two or more characters).
File +long_names.rb+
defines an option with a long name, <tt>--xxx</tt>,
and an option with two long names (aliases, in effect) <tt>--y1%</tt> and <tt>--z2#</tt>.
:include: long_names.rb
Executions:
$ ruby long_names.rb --xxx
["-xxx", true]
$ ruby long_names.rb --y1%
["--y1% or --z2#", true]
$ ruby long_names.rb --z2#
["--y1% or --z2#", true]
==== Mixing Option Names
Many developers like to mix short and long option names,
so that a short name is in effect an abbreviation of a long name.
File +mixed_names.rb+
defines options that each have both a short and a long name.
:include: mixed_names.rb
Executions:
$ 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]
=== Option Arguments
An option may take no argument, a required argument, or an optional argument.
==== Option with No Argument
All the examples above define options with no argument.
==== Option with Required Argument
Specify a required argument for an option by adding a dummy word
to its name definition.
File +required_argument.rb+ defines two options;
each has a required argument because the name definition has a following dummy word.
:include: required_argument.rb
When an option is found, the given argument is yielded.
Executions:
$ ruby required_argument.rb -x AAA
["--xxx", "AAA"]
$ ruby required_argument.rb -y BBB
["--yyy", "BBB"]
Omitting a required argument raises an error:
$ ruby required_argument.rb -x
required_argument.rb:9:in `<main>': missing argument: -x (OptionParser::MissingArgument)
==== Option with Optional Argument
Specify an optional argument for an option by adding a dummy word
enclosed in square brackets to its name definition.
File +optional_argument.rb+ defines two options;
each has an optional argument because the name definition has a following dummy word
in square brackets.
:include: optional_argument.rb
When an option with an argument is found, the given argument yielded.
Executions:
$ 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.