Skip to content

tutorial.rdoc

Latest commit

 

History

History
186 lines (124 loc) · 5.01 KB

tutorial.rdoc

File metadata and controls

186 lines (124 loc) · 5.01 KB

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: ruby/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 (-).

  • Long (multi-character) name, beginning with two hyphens (--).

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, -x, and an option with two short names (aliases, in effect) -y and -z.

:include: ruby/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, --xxx, and an option with two long names (aliases, in effect) --y1% and --z2#.

:include: ruby/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: ruby/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: ruby/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: ruby/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.