class GetoptLong

Class GetoptLong provides parsing both for options and for regular arguments.

Using GetoptLong, you can define options for your program. The program can then capture and respond to whatever options are included in the command that executes the program.

A simple example: file simple.rb:

require 'getoptlong'

options = GetoptLong.new(
  ['--number', '-n', GetoptLong::REQUIRED_ARGUMENT],
  ['--verbose', '-v', GetoptLong::OPTIONAL_ARGUMENT],
  ['--help', '-h', GetoptLong::NO_ARGUMENT]
)

If you are somewhat familiar with options, you may want to skip to this full example.

Options¶ ↑

A GetoptLong option has:

• A string option name.

• Zero or more string aliases for the name.

• An option type.

Options may be defined by calling singleton method GetoptLong.new, which returns a new GetoptLong object. Options may then be processed by calling other methods such as GetoptLong#each.

Option Name and Aliases¶ ↑

In the array that defines an option, the first element is the string option name. Often the name takes the ‘long’ form, beginning with two hyphens.

The option name may have any number of aliases, which are defined by additional string elements.

The name and each alias must be of one of two forms:

• Two hyphens, followed by one or more letters.

• One hyphen, followed by a single letter.

File aliases.rb:

require 'getoptlong'

options = GetoptLong.new(
  ['--xxx', '-x', '--aaa', '-a', '-p', GetoptLong::NO_ARGUMENT]
)
options.each do |option, argument|
  p [option, argument]
end

An option may be cited by its name, or by any of its aliases; the parsed option always reports the name, not an alias:

$ ruby aliases.rb -a -p --xxx --aaa -x

Output:

["--xxx", ""]
["--xxx", ""]
["--xxx", ""]
["--xxx", ""]
["--xxx", ""]

An option may also be cited by an abbreviation of its name or any alias, as long as that abbreviation is unique among the options.

File abbrev.rb:

require 'getoptlong'

options = GetoptLong.new(
  ['--xxx', GetoptLong::NO_ARGUMENT],
  ['--xyz', GetoptLong::NO_ARGUMENT]
)
options.each do |option, argument|
  p [option, argument]
end

Command line:

$ ruby abbrev.rb --xxx --xx --xyz --xy

Output:

["--xxx", ""]
["--xxx", ""]
["--xyz", ""]
["--xyz", ""]

This command line raises GetoptLong::AmbiguousOption:

$ ruby abbrev.rb --x

Repetition¶ ↑

An option may be cited more than once:

$ ruby abbrev.rb --xxx --xyz --xxx --xyz

Output:

["--xxx", ""]
["--xyz", ""]
["--xxx", ""]
["--xyz", ""]

Treating Remaining Options as Arguments¶ ↑

A option-like token that appears anywhere after the token -- is treated as an ordinary argument, and is not processed as an option:

$ ruby abbrev.rb --xxx --xyz -- --xxx --xyz

Output:

["--xxx", ""]
["--xyz", ""]

Option Types¶ ↑

Each option definition includes an option type, which controls whether the option takes an argument.

File types.rb:

require 'getoptlong'

options = GetoptLong.new(
  ['--xxx', GetoptLong::REQUIRED_ARGUMENT],
  ['--yyy', GetoptLong::OPTIONAL_ARGUMENT],
  ['--zzz', GetoptLong::NO_ARGUMENT]
)
options.each do |option, argument|
  p [option, argument]
end

Note that an option type has to do with the option argument (whether it is required, optional, or forbidden), not with whether the option itself is required.

Option with Required Argument¶ ↑

An option of type GetoptLong::REQUIRED_ARGUMENT must be followed by an argument, which is associated with that option:

$ ruby types.rb --xxx foo

Output:

["--xxx", "foo"]

If the option is not last, its argument is whatever follows it (even if the argument looks like another option):

$ ruby types.rb --xxx --yyy

Output:

["--xxx", "--yyy"]

If the option is last, an exception is raised:

$ ruby types.rb
# Raises GetoptLong::MissingArgument

Option with Optional Argument¶ ↑

An option of type GetoptLong::OPTIONAL_ARGUMENT may be followed by an argument, which if given is associated with that option.

If the option is last, it does not have an argument:

$ ruby types.rb --yyy

Output:

["--yyy", ""]

If the option is followed by another option, it does not have an argument:

$ ruby types.rb --yyy --zzz

Output:

["--yyy", ""]
["--zzz", ""]

Otherwise the option is followed by its argument, which is associated with that option:

$ ruby types.rb --yyy foo

Output:

["--yyy", "foo"]

Option with No Argument¶ ↑

An option of type GetoptLong::NO_ARGUMENT takes no argument:

ruby types.rb --zzz foo

Output:

["--zzz", ""]

ARGV¶ ↑

You can process options either with method each and a block, or with method get.

During processing, each found option is removed, along with its argument if there is one. After processing, each remaining element was neither an option nor the argument for an option.

File argv.rb:

require 'getoptlong'

options = GetoptLong.new(
  ['--xxx', GetoptLong::REQUIRED_ARGUMENT],
  ['--yyy', GetoptLong::OPTIONAL_ARGUMENT],
  ['--zzz', GetoptLong::NO_ARGUMENT]
)
puts "Original ARGV: #{ARGV}"
options.each do |option, argument|
  p [option, argument]
end
puts "Remaining ARGV: #{ARGV}"

Command line:

$ ruby argv.rb --xxx Foo --yyy Bar Baz --zzz Bat Bam

Output:

Original ARGV: ["--xxx", "Foo", "--yyy", "Bar", "Baz", "--zzz", "Bat", "Bam"]
["--xxx", "Foo"]
["--yyy", "Bar"]
["--zzz", ""]
Remaining ARGV: ["Baz", "Bat", "Bam"]

Ordering¶ ↑

There are three settings that control the way the options are interpreted:

• PERMUTE.

• REQUIRE_ORDER.

• RETURN_IN_ORDER.

The initial setting for a new GetoptLong object is REQUIRE_ORDER if environment variable POSIXLY_CORRECT is defined, PERMUTE otherwise.

PERMUTE Ordering¶ ↑

In the PERMUTE ordering, options and other, non-option, arguments may appear in any order and any mixture.

File permute.rb:

require 'getoptlong'

options = GetoptLong.new(
  ['--xxx', GetoptLong::REQUIRED_ARGUMENT],
  ['--yyy', GetoptLong::OPTIONAL_ARGUMENT],
  ['--zzz', GetoptLong::NO_ARGUMENT]
)
puts "Original ARGV: #{ARGV}"
options.each do |option, argument|
  p [option, argument]
end
puts "Remaining ARGV: #{ARGV}"

Command line:

$ ruby permute.rb Foo --zzz Bar --xxx Baz --yyy Bat Bam --xxx Bag Bah

Output:

Original ARGV: ["Foo", "--zzz", "Bar", "--xxx", "Baz", "--yyy", "Bat", "Bam", "--xxx", "Bag", "Bah"]
["--zzz", ""]
["--xxx", "Baz"]
["--yyy", "Bat"]
["--xxx", "Bag"]
Remaining ARGV: ["Foo", "Bar", "Bam", "Bah"]

REQUIRE_ORDER Ordering¶ ↑

In the REQUIRE_ORDER ordering, all options precede all non-options; that is, each word after the first non-option word is treated as a non-option word (even if it begins with a hyphen).

File require_order.rb:

require 'getoptlong'

options = GetoptLong.new(
  ['--xxx', GetoptLong::REQUIRED_ARGUMENT],
  ['--yyy', GetoptLong::OPTIONAL_ARGUMENT],
  ['--zzz', GetoptLong::NO_ARGUMENT]
)
options.ordering = GetoptLong::REQUIRE_ORDER
puts "Original ARGV: #{ARGV}"
options.each do |option, argument|
  p [option, argument]
end
puts "Remaining ARGV: #{ARGV}"

Command line:

$ ruby require_order.rb --xxx Foo Bar --xxx Baz --yyy Bat -zzz

Output:

Original ARGV: ["--xxx", "Foo", "Bar", "--xxx", "Baz", "--yyy", "Bat", "-zzz"]
["--xxx", "Foo"]
Remaining ARGV: ["Bar", "--xxx", "Baz", "--yyy", "Bat", "-zzz"]

RETURN_IN_ORDER Ordering¶ ↑

In the RETURN_IN_ORDER ordering, every word is treated as an option. A word that begins with a hyphen (or two) is treated in the usual way; a word word that does not so begin is treated as an option whose name is an empty string, and whose value is word.

File return_in_order.rb:

require 'getoptlong'

options = GetoptLong.new(
  ['--xxx', GetoptLong::REQUIRED_ARGUMENT],
  ['--yyy', GetoptLong::OPTIONAL_ARGUMENT],
  ['--zzz', GetoptLong::NO_ARGUMENT]
)
options.ordering = GetoptLong::RETURN_IN_ORDER
puts "Original ARGV: #{ARGV}"
options.each do |option, argument|
  p [option, argument]
end
puts "Remaining ARGV: #{ARGV}"

Command line:

$ ruby return_in_order.rb Foo --xxx Bar Baz --zzz Bat Bam

Output:

Original ARGV: ["Foo", "--xxx", "Bar", "Baz", "--zzz", "Bat", "Bam"]
["", "Foo"]
["--xxx", "Bar"]
["", "Baz"]
["--zzz", ""]
["", "Bat"]
["", "Bam"]
Remaining ARGV: []

Full Example¶ ↑

File fibonacci.rb:

require 'getoptlong'

options = GetoptLong.new(
  ['--number', '-n', GetoptLong::REQUIRED_ARGUMENT],
  ['--verbose', '-v', GetoptLong::OPTIONAL_ARGUMENT],
  ['--help', '-h', GetoptLong::NO_ARGUMENT]
)

def help(status = 0)
  puts <<~HELP
    Usage:

      -n n, --number n:
        Compute Fibonacci number for n.
      -v [boolean], --verbose [boolean]:
        Show intermediate results; default is 'false'.
      -h, --help:
        Show this help.
  HELP
  exit(status)
end

def print_fibonacci (number)
  return 0 if number == 0
  return 1 if number == 1 or number == 2
  i = 0
  j = 1
  (2..number).each do
    k = i + j
    i = j
    j = k
    puts j if @verbose
  end
  puts j unless @verbose
end

options.each do |option, argument|
  case option
  when '--number'
    @number = argument.to_i
  when '--verbose'
    @verbose = if argument.empty?
      true
    elsif argument.match(/true/i)
      true
    elsif argument.match(/false/i)
      false
    else
      puts '--verbose argument must be true or false'
      help(255)
    end
  when '--help'
    help
  end
end

unless @number
  puts 'Option --number is required.'
  help(255)
end

print_fibonacci(@number)

Command line:

$ ruby fibonacci.rb

Output:

Option --number is required.
Usage:

  -n n, --number n:
    Compute Fibonacci number for n.
  -v [boolean], --verbose [boolean]:
    Show intermediate results; default is 'false'.
  -h, --help:
    Show this help.

Command line:

$ ruby fibonacci.rb --number

Raises GetoptLong::MissingArgument:

fibonacci.rb: option `--number' requires an argument

Command line:

$ ruby fibonacci.rb --number 6

Output:

8

Command line:

$ ruby fibonacci.rb --number 6 --verbose

Output:

1
2
3
5
8

Command line:

$ ruby fibonacci.rb --number 6 --verbose yes

Output:

--verbose argument must be true or false
Usage:

  -n n, --number n:
    Compute Fibonacci number for n.
  -v [boolean], --verbose [boolean]:
    Show intermediate results; default is 'false'.
  -h, --help:
    Show this help.