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

Содержание

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

Начать

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

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

parse!
order!
permute!

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

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

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

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 определена:

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

END_OF_DOCUMENT_MARKER

Метод `permute!`

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

Метод `permute`

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

Ruby Core © 1993–2024 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`