класс 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

Вывод:

1
2
3
5
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.