Tutorial — Ruby 3.4 | 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, отображающий автоматически сгенерированный текст справки.

Содержание

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

Начало работы

Чтобы использовать 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

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

Метод 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 или Hash.

require 'optparse'
parser = OptionParser.new
parser.on('-x', '--xxx=VALUE', %w[ABC def], 'Argument abbreviations') do |value|
  p ['--xxx', value]
end
parser.on('-y', '--yyy=VALUE', {"abc"=>"XYZ", def: "FOO"}, 'Argument abbreviations') do |value|
  p ['--yyy', value]
end
parser.parse!

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

Запуск:

$ ruby argument_abbreviation.rb --help
Usage: argument_abbreviation [options]
Usage: argument_abbreviation [options]
    -x, --xxx=VALUE                  Argument abbreviations
    -y, --yyy=VALUE                  Argument abbreviations
$ ruby argument_abbreviation.rb --xxx A
["--xxx", "ABC"]
$ ruby argument_abbreviation.rb --xxx c
argument_abbreviation.rb:9:in `<main>': invalid argument: --xxx c (OptionParser::InvalidArgument)
$ ruby argument_abbreviation.rb --yyy a --yyy d
["--yyy", "XYZ"]
["--yyy", "FOO"]

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

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

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

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

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

Явно заданные значения в `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 есть шесть методов экземпляра для разбора.

Три из них оканчиваются на «восклицательный знак» (!):

parse!
order!
permute!

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

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

Названия трех остальных методов не оканчиваются на «восклицательный знак»:

parse
order
permute

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

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

Метод `parse!`

Метод parse!:

Принимает необязательный массив строковых аргументов argv; если он не указан, argv по умолчанию получает значение OptionParser#default_argv, начальным значением которого является ARGV.
Принимает необязательный ключевой аргумент into (см. раздел Ключевой аргумент 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 и значение для него into (см. раздел Ключевой аргумент 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–2025 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`