класс GetoptLong

Класс GetoptLong предоставляет разбор как опций, так и обычных аргументов.

С помощью GetoptLong вы можете определить опции для вашей программы. Программа затем может захватывать и реагировать на любые опции, включенные в команду, выполняющую программу.

Простой пример: файл simple.rb:

require 'getoptlong'

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

Если вы немного знакомы с опциями, вы можете перейти к этому полному примеру.

Опции

Опция GetoptLong имеет:

• Строку имя опции.

• Ноль или более строковых псевдонимов для имени.

• Тип опции.

Опции могут быть определены вызовом метода-синглетона GetoptLong.new, который возвращает новый объект GetoptLong. Опции затем могут быть обработаны вызовом других методов, таких как GetoptLong#each.

Имя опции и псевдонимы

В массиве, определяющем опцию, первый элемент — это строка имени опции. Часто имя принимает «длинную» форму, начинающуюся с двух дефисов.

Имя опции может иметь любое количество псевдонимов, которые определяются дополнительными строковыми элементами.

Имя и каждый псевдоним должны быть одного из двух типов:

• Два дефиса, за которыми следуют одна или несколько букв.

• Один дефис, за которым следует одна буква.

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

Опцию можно указать по ее имени или любому из ее псевдонимов; обработанная опция всегда сообщает имя, а не псевдоним:

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

Вывод:

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

Опцию также можно указать сокращением ее имени или любого псевдонима, при условии, что это сокращение уникально среди опций.

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

Командная строка:

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

Вывод:

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

Эта командная строка вызывает GetoptLong::AmbiguousOption:

$ ruby abbrev.rb --x

Повторение

Опцию можно указать более одного раза:

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

Вывод:

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

Обработка оставшихся опций как аргументов

Токен, похожий на опцию, появляющийся где-либо после токена -- рассматривается как обычный аргумент и не обрабатывается как опция:

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

Вывод:

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

Типы опций

В каждом определении опции указан тип опции, который управляет тем, принимает ли опция аргумент.

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

Обратите внимание, что тип опции связан с аргументом опции (является ли он обязательным, необязательным или запрещенным), а не с тем, обязательна ли сама опция.

Опция с обязательным аргументом

Опция типа GetoptLong::REQUIRED_ARGUMENT должна следовать за аргументом, который связан с этой опцией:

$ ruby types.rb --xxx foo

Вывод:

["--xxx", "foo"]

Если опция не последняя, ее аргументом является то, что следует за ней (даже если аргумент выглядит как другая опция):

$ ruby types.rb --xxx --yyy

Вывод:

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

Если опция последняя, генерируется исключение:

$ ruby types.rb
# Raises GetoptLong::MissingArgument

Опция с необязательным аргументом

Опция типа GetoptLong::OPTIONAL_ARGUMENT может следовать за аргументом, который, если задан, связывается с этой опцией.

Если опция последняя, она не имеет аргумента:

$ ruby types.rb --yyy

Вывод:

["--yyy", ""]

Если за опцией следует другая опция, у нее нет аргумента:

$ ruby types.rb --yyy --zzz

Вывод:

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

В противном случае за опцией следует ее аргумент, который связан с этой опцией:

$ ruby types.rb --yyy foo

Вывод:

["--yyy", "foo"]

Опция без аргумента

Опция типа GetoptLong::NO_ARGUMENT не принимает аргумент:

ruby types.rb --zzz foo

Вывод:

["--zzz", ""]

ARGV

Вы можете обработать опции либо с помощью метода each и блока, либо с помощью метода get.

Во время обработки каждая найденная опция удаляется вместе со своим аргументом, если он есть. После обработки каждый оставшийся элемент не был ни опцией, ни аргументом для опции.

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}"

Командная строка:

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

Вывод:

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

Порядок

Существует три параметра, которые контролируют способ интерпретации опций:

• PERMUTE.

• REQUIRE_ORDER.

• RETURN_IN_ORDER.

Начальное значение для нового объекта GetoptLong — REQUIRE_ORDER если переменная окружения POSIXLY_CORRECT определена, PERMUTE в противном случае.

Порядок PERMUTE

В порядке PERMUTE опции и другие, не являющиеся опциями, аргументы могут появляться в любом порядке и любой комбинации.

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}"

Командная строка:

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

Вывод:

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

В порядке REQUIRE_ORDER все опции предшествуют всем неопциям; то есть каждое слово после первого слова, не являющегося опцией, обрабатывается как слово, не являющееся опцией (даже если оно начинается с дефиса).

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}"

Командная строка:

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

Вывод:

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

Порядок RETURN_IN_ORDER

В порядке RETURN_IN_ORDER каждое слово обрабатывается как опция. Слово, начинающееся с дефиса (или двух), обрабатывается обычным образом; слово word , которое не начинается так, обрабатывается как опция, имя которой пустая строка, а значение — 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}"

Командная строка:

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

Вывод:

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

Полный пример

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)

Командная строка:

$ ruby fibonacci.rb

Вывод:

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.

Командная строка:

$ ruby fibonacci.rb --number

Вызывает GetoptLong::MissingArgument:

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

Командная строка:

$ ruby fibonacci.rb --number 6

Вывод:

8

Командная строка:

$ ruby fibonacci.rb –number 6 –verbose yes

Вывод:

--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.