mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
fe72cff487
* More on tutorial: clearer example output https://github.com/ruby/optparse/commit/84dfd92d2a
186 lines
5 KiB
Text
186 lines
5 KiB
Text
== 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.
|