mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
845 lines
24 KiB
Text
845 lines
24 KiB
Text
== 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]
|
|
- {Option Handlers}[#label-Option+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]
|
|
|
|
=== Option 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]
|