Spec-Zone.ru › Ruby 4.0

Учебник

Зачем нужен OptionParser?

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

p ARGV

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

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

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

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

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

  • Код, определяющий параметр, и код, обрабатывающий его, находились в одном месте.

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

  • Аргумент мог автоматически преобразовываться в указанный класс.

  • Допустимые формы аргумента можно было ограничить.

  • Допустимые значения аргумента можно было ограничить.

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

Содержание

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

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

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

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

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

    • Комбинирование имен параметров

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

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

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

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

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

    • Сокращения аргументов

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

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

      • Явно заданные значения в массиве

      • Явно заданные значения в хеше

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

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

    • Сбор параметров

    • Проверка отсутствующих параметров

    • Значения параметров по умолчанию

  • Преобразователи аргументов

  • Справка

  • Верхний и базовый списки

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

  • Разбор

    • Метод parse!

    • Метод parse

    • Метод order!

    • Метод order

    • Метод permute!

    • Метод permute

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

Чтобы использовать OptionParser:

  1. Подключите код OptionParser.

  2. Создайте объект OptionParser.

  3. Определите один или несколько параметров.

  4. Разберите командную строку.

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.on('--yyy YYY', Integer, 'Check by range', 1..3) do |value|
  p ['--yyy', value]
end
parser.on('--zzz ZZZ', Integer, 'Check by list', [1, 3, 4]) do |value|
  p ['--zzz', 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:

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

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API