Tutorial — Ruby 3.2 | Spec-Zone.ru

Руководство

Зачем OptionParser?

Когда Ruby-программа выполняется, она захватывает аргументы и параметры командной строки в переменную ARGV. Эта простая программа просто выводит ARGV:

p ARGV

Выполнение с аргументами и параметрами:

$ ruby argv.rb foo --bar --baz bat bam
["foo", "--bar", "--baz", "bat", "bam"]

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

OptionParser предлагает методы для разбора и обработки этих параметров.

С OptionParser вы можете определить параметры так, чтобы для каждого параметра:

Код, который определяет параметр и код, который обрабатывает этот параметр, находятся в одном месте.
Параметр может не принимать аргумент, принимать обязательный аргумент или необязательный аргумент.
Аргумент может быть автоматически преобразован в указанный класс.
Аргумент может быть ограничен указанными формами.
Аргумент может быть ограничен указанными значениями.

Класс также имеет метод help, который отображает автоматически сгенерированный текст справки.

Содержание

Начать с
Определение параметров
Имена параметров
Аргументы параметров
Значения аргументов
- Явные значения аргументов
  - Явные значения в массиве
  - Явные значения в хэше
- Шаблоны значений аргументов
Ключевой аргумент в
Преобразователи аргументов
Справка
Список верхнего уровня и базовый список
Определение параметров
Разбор

Начать с

Для использования OptionParser:

Подключите код OptionParser.
Создайте объект OptionParser.
Определите один или несколько параметров.
Разберите командную строку.

File basic.rb определяет три параметра, -x, -y, и -z, каждый с описательной строкой и блоком.

# Require the OptionParser code.
require 'optparse'
# Create an OptionParser object.
parser = OptionParser.new
# Define one or more options.
parser.on('-x', 'Whether to X') do |value|
  p ['x', value]
end
parser.on('-y', 'Whether to Y') do |value|
  p ['y', value]
end
parser.on('-z', 'Whether to Z') do |value|
  p ['z', value]
end
# Parse the command line and return pared-down ARGV.
p parser.parse!

Из этих определённых параметров парсер автоматически создаёт текст справки:

$ ruby basic.rb --help
Usage: basic [options]
    -x                               Whether to X
    -y                               Whether to Y
    -z                               Whether to Z

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

Method parse!, который чаще всего используется в этом руководстве, удаляет из ARGV параметры и аргументы, которые он находит, оставляя другие аргументы, не являющиеся параметрами, для обработки программой самостоятельно. Метод возвращает массив ARGV, который, возможно, уменьшился.

Выполнения:

$ ruby basic.rb -x -z
["x", true]
["z", true]
[]
$ ruby basic.rb -z -y -x
["z", true]
["y", true]
["x", true]
[]
$ ruby basic.rb -x input_file.txt output_file.txt
["x", true]
["input_file.txt", "output_file.txt"]
$ ruby basic.rb -a
basic.rb:16:in `<main>': invalid option: -a (OptionParser::InvalidOption)

Определение параметров

Распространённый способ определения параметра в OptionParser — с помощью метода экземпляра OptionParser#on.

Метод можно вызвать с любым количеством аргументов (порядок не имеет значения), а также с необязательным ключевым аргументом into.

Указанные аргументы определяют характеристики нового параметра. Они могут включать:

Одно или несколько коротких имён параметров.
Одно или несколько длинных имён параметров.
Принимает ли параметр без аргумента, необязательный аргумент или обязательный аргумент.
Допустимые формы аргумента.
Допустимые значения аргумента.
Процедура или метод, который вызывается, когда парсер встречает параметр.
String описания параметра.

Имена параметров

Вы можете дать параметру одно или несколько имён двух типов:

Короткое (односимвольное) имя, начинающееся с одного дефиса (-).
Длинное (многосимвольное) имя, начинающееся с двух дефисов (--).

Короткие имена параметров

Короткое имя параметра состоит из дефиса и одного символа.

File short_names.rb определяет параметр с коротким именем -x, и параметр с двумя короткими именами (псевдонимами) -y и -z.

require 'optparse'
parser = OptionParser.new
parser.on('-x', 'Short name') do |value|
  p ['x', value]
end
parser.on('-1', '-%', 'Two short names') do |value|
  p ['-1 or -%', value]
end
parser.parse!

Выполнения:

$ ruby short_names.rb --help
Usage: short_names [options]
    -x                               Short name
    -1, -%                           Two short names
$ ruby short_names.rb -x
["x", true]
$ ruby short_names.rb -1
["-1 or -%", true]
$ ruby short_names.rb -%
["-1 or -%", true]

Несколько коротких имён могут «разделить» дефис:

$ ruby short_names.rb -x1%
["x", true]
["-1 or -%", true]
["-1 or -%", true]

Длинные имена параметров

Длинное имя параметра состоит из двух дефисов и одного или нескольких символов (обычно двух или более символов).

File long_names.rb определяет параметр с длинным именем --xxx, и параметр с двумя длинными именами (псевдонимами) --y1% и --z2#.

require 'optparse'
parser = OptionParser.new
parser.on('--xxx', 'Long name') do |value|
  p ['-xxx', value]
end
parser.on('--y1%', '--z2#', "Two long names") do |value|
  p ['--y1% or --z2#', value]
end
parser.parse!

Выполнения:

$ ruby long_names.rb --help
Usage: long_names [options]
        --xxx                        Long name
        --y1%, --z2#                 Two long names
$ 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]

Длинное имя может быть определено как с положительным, так и с отрицательным смыслом.

File long_with_negation.rb определяет параметр, который имеет оба смысла.

require 'optparse'
parser = OptionParser.new
parser.on('--[no-]binary', 'Long name with negation') do |value|
  p [value, value.class]
end
parser.parse!

Выполнения:

$ ruby long_with_negation.rb --help
Usage: long_with_negation [options]
        --[no-]binary                Long name with negation
$ ruby long_with_negation.rb --binary
[true, TrueClass]
$ ruby long_with_negation.rb --no-binary
[false, FalseClass]

Смешивание имён параметров

Многие разработчики предпочитают смешивать короткие и длинные имена параметров, чтобы короткое имя было по сути сокращением длинного имени.

File mixed_names.rb определяет параметры, каждый из которых имеет как короткое, так и длинное имя.

require 'optparse'
parser = OptionParser.new
parser.on('-x', '--xxx', 'Short and long, no argument') do |value|
  p ['--xxx', value]
end
parser.on('-yYYY', '--yyy', 'Short and long, required argument') do |value|
  p ['--yyy', value]
end
parser.on('-z [ZZZ]', '--zzz', 'Short and long, optional argument') do |value|
  p ['--zzz', value]
end
parser.parse!

Выполнения:

$ ruby mixed_names.rb --help
Usage: mixed_names [options]
    -x, --xxx                        Short and long, no argument
    -y, --yyyYYY                     Short and long, required argument
    -z, --zzz [ZZZ]                  Short and long, optional argument
$ ruby mixed_names.rb -x
["--xxx", true]
$ ruby mixed_names.rb --xxx
["--xxx", true]
$ ruby mixed_names.rb -y
mixed_names.rb:12:in `<main>': missing argument: -y (OptionParser::MissingArgument)
$ ruby mixed_names.rb -y FOO
["--yyy", "FOO"]
$ ruby mixed_names.rb --yyy
mixed_names.rb:12:in `<main>': missing argument: --yyy (OptionParser::MissingArgument)
$ ruby mixed_names.rb --yyy BAR
["--yyy", "BAR"]
$ ruby mixed_names.rb -z
["--zzz", nil]
$ ruby mixed_names.rb -z BAZ
["--zzz", "BAZ"]
$ ruby mixed_names.rb --zzz
["--zzz", nil]
$ ruby mixed_names.rb --zzz BAT
["--zzz", "BAT"]

Сокращения имён параметров

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

require 'optparse'
parser = OptionParser.new
parser.on('-n', '--dry-run',) do |value|
  p ['--dry-run', value]
end
parser.on('-d', '--draft',) do |value|
  p ['--draft', value]
end
parser.parse!

Выполнения:

$ ruby name_abbrev.rb --help
Usage: name_abbrev [options]
    -n, --dry-run
    -d, --draft
$ ruby name_abbrev.rb -n
["--dry-run", true]
$ ruby name_abbrev.rb --dry-run
["--dry-run", true]
$ ruby name_abbrev.rb -d
["--draft", true]
$ ruby name_abbrev.rb --draft
["--draft", true]
$ ruby name_abbrev.rb --d
name_abbrev.rb:9:in `<main>': ambiguous option: --d (OptionParser::AmbiguousOption)
$ ruby name_abbrev.rb --dr
name_abbrev.rb:9:in `<main>': ambiguous option: --dr (OptionParser::AmbiguousOption)
$ ruby name_abbrev.rb --dry
["--dry-run", true]
$ ruby name_abbrev.rb --dra
["--draft", true]

Вы можете отключить сокращения, используя метод require_exact.

require 'optparse'
parser = OptionParser.new
parser.on('-n', '--dry-run',) do |value|
  p ['--dry-run', value]
end
parser.on('-d', '--draft',) do |value|
  p ['--draft', value]
end
parser.require_exact = true
parser.parse!

Выполнения:

$ ruby no_abbreviation.rb --dry-ru
no_abbreviation.rb:10:in `<main>': invalid option: --dry-ru (OptionParser::InvalidOption)
$ ruby no_abbreviation.rb --dry-run
["--dry-run", true]

Аргументы параметров

Параметр может не принимать аргумент, принимать обязательный аргумент или необязательный аргумент.

Параметр без аргумента

Все примеры выше определяют параметры без аргумента.

Параметр с обязательным аргументом

Укажите обязательный аргумент для параметра, добавив слово-заглушку к его определению имени.

File required_argument.rb определяет два параметра; каждый из них имеет обязательный аргумент, потому что определение имени имеет последующее слово-заглушку.

require 'optparse'
parser = OptionParser.new
parser.on('-x XXX', '--xxx', 'Required argument via short name') do |value|
  p ['--xxx', value]
end
parser.on('-y', '--y YYY', 'Required argument via long name') do |value|
  p ['--yyy', value]
end
parser.parse!

Когда параметр найден, сгенерированный аргумент передается.

Выполнения:

$ ruby required_argument.rb --help
Usage: required_argument [options]
    -x, --xxx XXX                    Required argument via short name
    -y, --y YYY                      Required argument via long name
$ ruby required_argument.rb -x AAA
["--xxx", "AAA"]
$ ruby required_argument.rb -y BBB
["--yyy", "BBB"]

Пропуск обязательного аргумента вызывает ошибку:

$ ruby required_argument.rb -x
required_argument.rb:9:in `<main>': missing argument: -x (OptionParser::MissingArgument)

Параметр с необязательным аргументом

Укажите необязательный аргумент для параметра, добавив слово-заглушку в квадратных скобках к его определению имени.

File optional_argument.rb определяет два параметра; каждый из них имеет необязательный аргумент, потому что определение имени имеет последующее слово-заглушку в квадратных скобках.

require 'optparse'
parser = OptionParser.new
parser.on('-x [XXX]', '--xxx', 'Optional argument via short  name') do |value|
  p ['--xxx', value]
end
parser.on('-y', '--yyy [YYY]', 'Optional argument via long name') do |value|
  p ['--yyy', value]
end
parser.parse!

Когда параметр с аргументом найден, указанный аргумент передается.

Выполнения:

$ ruby optional_argument.rb --help
Usage: optional_argument [options]
    -x, --xxx [XXX]                  Optional argument via short  name
    -y, --yyy [YYY]                  Optional argument via long name
$ ruby optional_argument.rb -x AAA
["--xxx", "AAA"]
$ ruby optional_argument.rb -y BBB
["--yyy", "BBB"]

Пропуск необязательного аргумента не вызывает ошибку.

Значения аргументов

Допустимые значения аргументов могут быть ограничены, либо указав явные значения, либо предоставив шаблон, которому должно соответствовать данное значение.

Явные значения аргументов

Вы можете указать значения аргументов двумя способами:

Укажите значения в массиве строк.
Укажите значения в хэше.

Явные значения в `Array`

Вы можете указать явные значения аргумента в массиве строк. Значение аргумента должно быть одной из этих строк или недвусмысленным сокращением.

File explicit_array_values.rb определяет параметры с явными значениями аргументов.

require 'optparse'
parser = OptionParser.new
parser.on('-xXXX', ['foo', 'bar'], 'Values for required argument' ) do |value|
  p ['-x', value]
end
parser.on('-y [YYY]', ['baz', 'bat'], 'Values for optional argument') do |value|
  p ['-y', value]
end
parser.parse!

Выполнения:

$ ruby explicit_array_values.rb --help
Usage: explicit_array_values [options]
    -xXXX                            Values for required argument
    -y [YYY]                         Values for optional argument
$ ruby explicit_array_values.rb -x
explicit_array_values.rb:9:in `<main>': missing argument: -x (OptionParser::MissingArgument)
$ ruby explicit_array_values.rb -x foo
["-x", "foo"]
$ ruby explicit_array_values.rb -x f
["-x", "foo"]
$ ruby explicit_array_values.rb -x bar
["-x", "bar"]
$ ruby explicit_array_values.rb -y ba
explicit_array_values.rb:9:in `<main>': ambiguous argument: -y ba (OptionParser::AmbiguousArgument)
$ ruby explicit_array_values.rb -x baz
explicit_array_values.rb:9:in `<main>': invalid argument: -x baz (OptionParser::InvalidArgument)

Явные значения в `Hash`

Вы можете указать явные значения аргументов в хэше со строковыми ключами. Переданное значение должно быть одним из этих ключей или недвусмысленным сокращением; возвращаемое значение будет значением для этого ключа.

File explicit_hash_values.rb определяет параметры с явными значениями аргументов.

require 'optparse'
parser = OptionParser.new
parser.on('-xXXX', {foo: 0, bar: 1}, 'Values for required argument' ) do |value|
  p ['-x', value]
end
parser.on('-y [YYY]', {baz: 2, bat: 3}, 'Values for optional argument') do |value|
  p ['-y', value]
end
parser.parse!

Выполнения:

$ ruby explicit_hash_values.rb --help
Usage: explicit_hash_values [options]
    -xXXX                            Values for required argument
    -y [YYY]                         Values for optional argument
$ ruby explicit_hash_values.rb -x
explicit_hash_values.rb:9:in `<main>': missing argument: -x (OptionParser::MissingArgument)
$ ruby explicit_hash_values.rb -x foo
["-x", 0]
$ ruby explicit_hash_values.rb -x f
["-x", 0]
$ ruby explicit_hash_values.rb -x bar
["-x", 1]
$ ruby explicit_hash_values.rb -x baz
explicit_hash_values.rb:9:in `<main>': invalid argument: -x baz (OptionParser::InvalidArgument)
$ ruby explicit_hash_values.rb -y
["-y", nil]
$ ruby explicit_hash_values.rb -y baz
["-y", 2]
$ ruby explicit_hash_values.rb -y bat
["-y", 3]
$ ruby explicit_hash_values.rb -y ba
explicit_hash_values.rb:9:in `<main>': ambiguous argument: -y ba (OptionParser::AmbiguousArgument)
$ ruby explicit_hash_values.rb -y bam
["-y", nil]

Шаблоны значений аргументов

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

File matched_values.rb определяет параметры с соответствующими значениями аргументов.

require 'optparse'
parser = OptionParser.new
parser.on('--xxx XXX', /foo/i, 'Matched values') do |value|
  p ['--xxx', value]
end
parser.parse!

Выполнения:

$ ruby matched_values.rb --help
Usage: matched_values [options]
        --xxx XXX                    Matched values
$ ruby matched_values.rb --xxx foo
["--xxx", "foo"]
$ ruby matched_values.rb --xxx FOO
["--xxx", "FOO"]
$ ruby matched_values.rb --xxx bar
matched_values.rb:6:in `<main>': invalid argument: --xxx bar (OptionParser::InvalidArgument)

Ключевой аргумент `into`

При разборе параметров вы можете добавить ключевой параметр into с аргументом в формате хэша; каждый проанализированный параметр будет добавлен как пара имя/значение.

Это полезно для:

Сбор опций.
Проверка на отсутствие опций.
Установление значений по умолчанию для опций.

Сбор опций

Используйте ключевой аргумент into для сбора опций.

require 'optparse'
parser = OptionParser.new
parser.on('-x', '--xxx', 'Short and long, no argument')
parser.on('-yYYY', '--yyy', 'Short and long, required argument')
parser.on('-z [ZZZ]', '--zzz', 'Short and long, optional argument')
options = {}
parser.parse!(into: options)
p options

Выполнения:

$ ruby collected_options.rb --help
Usage: into [options]
    -x, --xxx                        Short and long, no argument
    -y, --yyyYYY                     Short and long, required argument
    -z, --zzz [ZZZ]                  Short and long, optional argument
$ ruby collected_options.rb --xxx
{:xxx=>true}
$ ruby collected_options.rb --xxx --yyy FOO
{:xxx=>true, :yyy=>"FOO"}
$ ruby collected_options.rb --xxx --yyy FOO --zzz Bar
{:xxx=>true, :yyy=>"FOO", :zzz=>"Bar"}
$ ruby collected_options.rb --xxx --yyy FOO --yyy BAR
{:xxx=>true, :yyy=>"BAR"}

Обратите внимание в последнем выполнении, что значение аргумента для опции --yyy было перезаписано.

Проверка на отсутствие опций

Используйте собранные опции для проверки на отсутствие опций.

require 'optparse'
parser = OptionParser.new
parser.on('-x', '--xxx', 'Short and long, no argument')
parser.on('-yYYY', '--yyy', 'Short and long, required argument')
parser.on('-z [ZZZ]', '--zzz', 'Short and long, optional argument')
options = {}
parser.parse!(into: options)
required_options = [:xxx, :zzz]
missing_options = required_options - options.keys
unless missing_options.empty?
  fail "Missing required options: #{missing_options}"
end

Выполнения:

$ ruby missing_options.rb --help
Usage: missing_options [options]
    -x, --xxx                        Short and long, no argument
    -y, --yyyYYY                     Short and long, required argument
    -z, --zzz [ZZZ]                  Short and long, optional argument
$ ruby missing_options.rb --yyy FOO
missing_options.rb:11:in `<main>': Missing required options: [:xxx, :zzz] (RuntimeError)

Значения по умолчанию для опций

Инициализируйте аргумент into для определения значений по умолчанию для опций.

require 'optparse'
parser = OptionParser.new
parser.on('-x', '--xxx', 'Short and long, no argument')
parser.on('-yYYY', '--yyy', 'Short and long, required argument')
parser.on('-z [ZZZ]', '--zzz', 'Short and long, optional argument')
options = {yyy: 'AAA', zzz: 'BBB'}
parser.parse!(into: options)
p options

Выполнения:

$ ruby default_values.rb --help
Usage: default_values [options]
    -x, --xxx                        Short and long, no argument
    -y, --yyyYYY                     Short and long, required argument
    -z, --zzz [ZZZ]                  Short and long, optional argument
$ ruby default_values.rb --yyy FOO
{:yyy=>"FOO", :zzz=>"BBB"}

Конвертеры аргументов

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

Пример: File date.rb определяет опцию, аргумент которой должен быть преобразован в объект Date. Аргумент преобразуется методом Date#parse.

require 'optparse/date'
parser = OptionParser.new
parser.on('--date=DATE', Date) do |value|
  p [value, value.class]
end
parser.parse!

Выполнения:

$ ruby date.rb --date 2001-02-03
[#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date]
$ ruby date.rb --date 20010203
[#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date]
$ ruby date.rb --date "3rd Feb 2001"
[#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date]

Вы также можете определить пользовательские конвертеры. См. Конвертеры аргументов для встроенных и пользовательских конвертеров.

Справка

OptionParser предоставляет автоматически сгенерированный текст справки.

Текст справки состоит из:

Баннера, отображающего использование.
Короткого и длинного имен опций.
Имен аргументов опций (фиктивных).
Описаний опций.

Пример кода:

require 'optparse'
parser = OptionParser.new
parser.on(
  '-x', '--xxx',
  'Adipiscing elit. Aenean commodo ligula eget.',
  'Aenean massa. Cum sociis natoque penatibus',
  )
parser.on(
  '-y', '--yyy YYY',
  'Lorem ipsum dolor sit amet, consectetuer.'
)
parser.on(
  '-z', '--zzz [ZZZ]',
  'Et magnis dis parturient montes, nascetur',
  'ridiculus mus. Donec quam felis, ultricies',
  'nec, pellentesque eu, pretium quis, sem.',
  )
parser.parse!

Имена опций и фиктивные имена аргументов определены, как описано выше.

Описание опции состоит из строк, которые не являются сами по себе именами опций; опция может иметь более одной строки описания. Выполнение:

Usage: help [options]
    -x, --xxx                        Adipiscing elit. Aenean commodo ligula eget.
                                     Aenean massa. Cum sociis natoque penatibus
    -y, --yyy YYY                    Lorem ipsum dolor sit amet, consectetuer.
    -z, --zzz [ZZZ]                  Et magnis dis parturient montes, nascetur
                                     ridiculus mus. Donec quam felis, ultricies
                                     nec, pellentesque eu, pretium quis, sem.

Имя программы включено в стандартный баннер: Usage: #{program_name} [options]; вы можете изменить имя программы.

require 'optparse'
parser = OptionParser.new
parser.program_name = 'help_program_name.rb'
parser.parse!

Выполнение:

$ ruby help_program_name.rb --help
Usage: help_program_name.rb [options]

Вы также можете изменить весь баннер.

require 'optparse'
parser = OptionParser.new
parser.banner = "Usage: ruby help_banner.rb"
parser.parse!

Выполнение:

$ ruby help_banner.rb --help
Usage: ruby help_banner.rb

По умолчанию, имена опций отступлены на 4 пробела, а ширина поля имен опций составляет 32 пробела.

Вы можете изменить эти значения, а также баннер, передав параметры в OptionParser.new.

require 'optparse'
parser = OptionParser.new(
  'ruby help_format.rb [options]', # Banner
  20,                               # Width of options field
  ' ' * 2                               # Indentation
)
parser.on(
  '-x', '--xxx',
  'Adipiscing elit. Aenean commodo ligula eget.',
  'Aenean massa. Cum sociis natoque penatibus',
  )
parser.on(
  '-y', '--yyy YYY',
  'Lorem ipsum dolor sit amet, consectetuer.'
)
parser.on(
  '-z', '--zzz [ZZZ]',
  'Et magnis dis parturient montes, nascetur',
  'ridiculus mus. Donec quam felis, ultricies',
  'nec, pellentesque eu, pretium quis, sem.',
  )
parser.parse!

Выполнение:

$ ruby help_format.rb --help
ruby help_format.rb [options]
  -x, --xxx            Adipiscing elit. Aenean commodo ligula eget.
                       Aenean massa. Cum sociis natoque penatibus
  -y, --yyy YYY        Lorem ipsum dolor sit amet, consectetuer.
  -z, --zzz [ZZZ]      Et magnis dis parturient montes, nascetur
                       ridiculus mus. Donec quam felis, ultricies
                       nec, pellentesque eu, pretium quis, sem.

Список верхнего и базового уровней

Объект OptionParser хранит стек объектов OptionParser::List, каждый из которых содержит набор из нуля или более опций. Вероятно, вам не придётся добавлять или удалять из этого стека.

В стек входят:

Список верхнего уровня, задаваемый OptionParser#top.
Список базового уровня, задаваемый OptionParser#base.

Когда OptionParser строит текст справки, опции в списке верхнего уровня предшествуют опциям в списке базового уровня.

Определение опций

Методы определения опций позволяют вам создать опцию и также добавить/вставить её в список верхнего уровня или добавить её в список базового уровня.

Каждый из следующих трёх методов принимает последовательность аргументов параметров и блок, создаёт объект опции с помощью метода Option#make_switch (см. ниже) и возвращает созданную опцию:

Метод OptionParser#define добавляет созданную опцию в список верхнего уровня.
Метод OptionParser#define_head вставляет созданную опцию в начало списка верхнего уровня.
Метод OptionParser#define_tail добавляет созданную опцию в список базового уровня.

Эти следующие три метода идентичны трём вышеуказанным, за исключением их возвращаемых значений:

Метод OptionParser#on идентичен методу OptionParser#define, за исключением того, что он возвращает объект анализатора self.
Метод OptionParser#on_head идентичен методу OptionParser#define_head, за исключением того, что он возвращает объект анализатора self.
Метод OptionParser#on_tail идентичен методу OptionParser#define_tail, за исключением того, что он возвращает объект анализатора self.

Хотя вам, возможно, никогда не придётся вызывать его напрямую, вот основной метод для определения опции:

Метод OptionParser#make_switch принимает массив параметров и блок. См. Параметры новых опций. Этот метод отличается от других тем, что:
- Принимает массив параметров; другие принимают последовательность аргументов параметров.
- Возвращает массив, содержащий созданный объект опции, имена опций и другие значения; другие возвращают либо созданный объект опции, либо объект анализатора self.

Парсинг

OptionParser имеет шесть методов экземпляра для парсинга.

Три имеют имена, оканчивающиеся на «bang» (!):

parse!
order!
permute!

Каждый из этих методов:

Принимает необязательный массив строковых аргументов argv; если не указан, argv по умолчанию принимает значение OptionParser#default_argv, начальное значение которого – ARGV.
Принимает необязательный ключевой аргумент into (см. Ключевой аргумент в).
Возвращает argv, возможно, с некоторыми удалёнными элементами.

Три других метода имеют имена, не оканчивающиеся на «bang»:

parse
order
permute

Каждый из этих методов:

Принимает массив строковых аргументов или ноль или более строковых аргументов.
Принимает необязательный ключевой аргумент into и его значение в. (см. Ключевой аргумент в).
Возвращает argv, возможно, с некоторыми удалёнными элементами.

Метод parse!

Метод parse!:

Принимает необязательный массив строковых аргументов argv; если не указан, argv по умолчанию принимает значение OptionParser#default_argv, начальное значение которого – ARGV.
Принимает необязательный ключевой аргумент into (см. Ключевой аргумент в).
Возвращает argv, возможно, с некоторыми удалёнными элементами.

Метод обрабатывает элементы в argv начиная с argv[0], и заканчивая, по умолчанию, в конце.

В противном случае обработка завершается, и метод возвращается, когда:

Найден аргумент-терминатор --; аргумент-терминатор удаляется перед возвратом.
Переменная среды POSIXLY_CORRECT определена, и найден неаргумент-опции; неаргумент-опции не удаляется. Обратите внимание, что значение этой переменной не имеет значения, так как проверяется только её существование.

File parse_bang.rb:

require 'optparse'
parser = OptionParser.new
parser.on('--xxx') do |value|
  p ['--xxx', value]
end
parser.on('--yyy YYY') do |value|
  p ['--yyy', value]
end
parser.on('--zzz [ZZZ]') do |value|
  p ['--zzz', value]
end
ret = parser.parse!
puts "Returned: #{ret} (#{ret.class})"

Справка:

$ ruby parse_bang.rb --help
Usage: parse_bang [options]
        --xxx
        --yyy YYY
        --zzz [ZZZ]

Поведение по умолчанию:

$ ruby parse_bang.rb input_file.txt output_file.txt --xxx --yyy FOO --zzz BAR
["--xxx", true]
["--yyy", "FOO"]
["--zzz", "BAR"]
Returned: ["input_file.txt", "output_file.txt"] (Array)

Обработка завершена аргументом-терминатором:

$ ruby parse_bang.rb input_file.txt output_file.txt --xxx --yyy FOO -- --zzz BAR
["--xxx", true]
["--yyy", "FOO"]
Returned: ["input_file.txt", "output_file.txt", "--zzz", "BAR"] (Array)

Обработка завершена неаргументом-опцией при определении POSIXLY_CORRECT:

$ POSIXLY_CORRECT=true ruby parse_bang.rb --xxx input_file.txt output_file.txt -yyy FOO
["--xxx", true]
Returned: ["input_file.txt", "output_file.txt", "-yyy", "FOO"] (Array)

Метод parse

Метод parse:

Принимает массив строковых аргументов или ноль или более строковых аргументов.
Принимает необязательный ключевой аргумент into и его значение в. (см. Ключевой аргумент в).
Возвращает argv, возможно, с некоторыми удалёнными элементами.

Если задан массив ary, метод формирует массив argv как ary.dup. Если заданы ноль или более строковых аргументов, эти аргументы образуют массив argv.

Метод вызывает

parse!(argv, into: into)

Обратите внимание, что переменная среды POSIXLY_CORRECT и аргумент-терминатор -- учитываются.

File parse.rb:

require 'optparse'
parser = OptionParser.new
parser.on('--xxx') do |value|
  p ['--xxx', value]
end
parser.on('--yyy YYY') do |value|
  p ['--yyy', value]
end
parser.on('--zzz [ZZZ]') do |value|
  p ['--zzz', value]
end
ret = parser.parse(ARGV)
puts "Returned: #{ret} (#{ret.class})"

Справка:

$ ruby parse.rb --help
Usage: parse [options]
        --xxx
        --yyy YYY
        --zzz [ZZZ]

Поведение по умолчанию:

$ ruby parse.rb input_file.txt output_file.txt --xxx --yyy FOO --zzz BAR
["--xxx", true]
["--yyy", "FOO"]
["--zzz", "BAR"]
Returned: ["input_file.txt", "output_file.txt"] (Array)

Обработка завершена аргументом-терминатором:

$ ruby parse.rb input_file.txt output_file.txt --xxx --yyy FOO -- --zzz BAR
["--xxx", true]
["--yyy", "FOO"]
Returned: ["input_file.txt", "output_file.txt", "--zzz", "BAR"] (Array)

Обработка завершена неаргументом-опцией при определении POSIXLY_CORRECT:

$ POSIXLY_CORRECT=true ruby parse.rb --xxx input_file.txt output_file.txt -yyy FOO
["--xxx", true]
Returned: ["input_file.txt", "output_file.txt", "-yyy", "FOO"] (Array)

Метод order!

Вызов метода OptionParser#order! даёт точно такой же результат, как вызов метода OptionParser#parse! с определённой переменной среды POSIXLY_CORRECT.

Метод order

Вызов метода OptionParser#order даёт точно такой же результат, как вызов метода OptionParser#parse с определённой переменной среды POSIXLY_CORRECT.

Метод permute!

Вызов метода OptionParser#permute! даёт точно такой же результат, как вызов метода OptionParser#parse! с неопределённой переменной среды POSIXLY_CORRECT.

Метод permute

Вызов метода OptionParser#permute даёт точно такой же результат, как вызов метода OptionParser#parse с неопределённой переменной среды POSIXLY_CORRECT.

Ruby Core © 1993–2022 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.

Руководство

Зачем OptionParser?

Содержание

Начать с

Определение параметров

Имена параметров

Короткие имена параметров

Длинные имена параметров

Смешивание имён параметров

Сокращения имён параметров

Аргументы параметров

Параметр без аргумента

Параметр с обязательным аргументом

Параметр с необязательным аргументом

Значения аргументов

Явные значения аргументов

Явные значения в Array

Явные значения в Hash

Шаблоны значений аргументов

Ключевой аргумент into

Сбор опций

Проверка на отсутствие опций

Значения по умолчанию для опций

Конвертеры аргументов

Справка

Список верхнего и базового уровней

Определение опций

Парсинг

Метод parse!

Метод parse

Метод order!

Метод order

Метод permute!

Метод permute

Явные значения в `Array`

Явные значения в `Hash`

Ключевой аргумент `into`