Tutorial — Ruby 3.3 | 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 описания для опции.

Имена опций

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

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

Короткие имена опций

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

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

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

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

Пример: 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 строит свой текст справки, параметры в списке сверху предшествуют параметрам в списке снизу.

Методы для определения параметров

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

Каждый из следующих трёх методов принимает последовательность аргументов параметров и блок, создаёт объект параметра с помощью метода OptionParser#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=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

Почему `OptionParser`?

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

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

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

Метод `parse!`

Метод `parse`

Метод `order!`

Метод `order`

Метод `permute!`

Метод `permute`