Параметры новых опций

Методы создания опций в OptionParser принимают аргументы, определяющие поведение новой опции:

• OptionParser#on

• OptionParser#on_head

• OptionParser#on_tail

• OptionParser#define

• OptionParser#define_head

• OptionParser#define_tail

• OptionParser#make_switch

В примерах кода на этой странице используются:

• OptionParser#on для определения опций.

• OptionParser#parse! для разбора командной строки.

• Встроенная опция --help для отображения определённых опций.

Содержание:

• Имена опций

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

    • Простые короткие имена

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

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

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

  • Длинные имена

    • Простые длинные имена

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

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

    • Длинные имена с отрицанием

  • Смешанные имена

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

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

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

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

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

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

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

• Описания

• Обработчики опций

  • Блоки-обработчики

  • Процедуры-обработчики

  • Методы-обработчики

Имена опций

Существует два вида имён опций:

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

• Длинное имя опции, состоящее из двух дефисов и одного или нескольких символов.

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

Простые короткие имена

File short_simple.rb определяет две опции:

• Одну с коротким именем -x.

• Другую — с двумя короткими именами, то есть псевдонимами: -1 и -%.

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

Выполнение:

$ ruby short_simple.rb --help
Usage: short_simple [options]
    -x                               One short name
    -1, -%                           Two short names (aliases)
$ ruby short_simple.rb -x
["-x", true]
$ ruby short_simple.rb -1 -x -%
["-1 or -%", true]
["-x", true]
["-1 or -%", true]

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

Короткое имя, за которым (без пробела) следует условное слово, определяет опцию, требующую аргумент.

File short_required.rb определяет опцию -x, требующую аргумент.

require 'optparse'
parser = OptionParser.new
parser.on('-xXXX', 'Short name with required argument') do |value|
  p ['-x', value]
end
parser.parse!

Выполнение:

$ ruby short_required.rb --help
Usage: short_required [options]
    -xXXX                            Short name with required argument
$ ruby short_required.rb -x
short_required.rb:6:in '<main>': missing argument: -x (OptionParser::MissingArgument)
$ ruby short_required.rb -x FOO
["-x", "FOO"]

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

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

File short_optional.rb определяет опцию -x с необязательным аргументом.

require 'optparse'
parser = OptionParser.new
parser.on('-x [XXX]', 'Short name with optional argument') do |value|
  p ['-x', value]
end
parser.parse!

Выполнение:

$ ruby short_optional.rb --help
Usage: short_optional [options]
    -x [XXX]                         Short name with optional argument
$ ruby short_optional.rb -x
["-x", nil]
$ ruby short_optional.rb -x FOO
["-x", "FOO"]

Короткие имена из Range

Можно определить опцию с несколькими короткими именами, взятыми из диапазона символов. Парсер возвращает как указанный символ, так и значение.

File short_range.rb определяет опцию с короткими именами для всех печатных символов от ! до ~:

require 'optparse'
parser = OptionParser.new
parser.on('-[!-~]', 'Short names in (very large) range') do |name, value|
  p ['!-~', name, value]
end
parser.parse!

Выполнение:

$ ruby short_range.rb --help
Usage: short_range [options]
    -[!-~]                           Short names in (very large) range
$ ruby short_range.rb -!
["!-~", "!", nil]
$ ruby short_range.rb -!
["!-~", "!", nil]
$ ruby short_range.rb -A
["!-~", "A", nil]
$ ruby short_range.rb -z
["!-~", "z", nil]

Длинные имена

Простые длинные имена

File long_simple.rb определяет две опции:

• Одну с длинным именем -xxx.

• Другую — с двумя длинными именами, то есть псевдонимами: --y1% и --z2#.

  require ‘optparse’ parser = OptionParser.new parser.on(‘–xxx’, ‘One long name’) do |value|

  p ['--xxx', value]
  

  end parser.on(‘–y1%’, ‘–z2#’, ‘Two long names (aliases)’) do |value|

  p ['--y1% or --z2#', value]
  

  end parser.parse!

Выполнение:

$ ruby long_simple.rb --help
Usage: long_simple [options]
        --xxx                        One long name
        --y1%, --z2#                 Two long names (aliases)
$ ruby long_simple.rb --xxx
["--xxx", true]
$ ruby long_simple.rb --y1% --xxx --z2#
["--y1% or --z2#", true]
["--xxx", true]
["--y1% or --z2#", true]

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

Длинное имя, за которым (через пробел) следует условное слово, определяет опцию, требующую аргумент.

File long_required.rb определяет опцию --xxx, требующую аргумент.

require 'optparse'
parser = OptionParser.new
parser.on('--xxx XXX', 'Long name with required argument') do |value|
  p ['--xxx', value]
end
parser.parse!

Выполнение:

$ ruby long_required.rb --help
Usage: long_required [options]
        --xxx XXX                    Long name with required argument
$ ruby long_required.rb --xxx
long_required.rb:6:in '<main>': missing argument: --xxx (OptionParser::MissingArgument)
$ ruby long_required.rb --xxx FOO
["--xxx", "FOO"]

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

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

File long_optional.rb определяет опцию --xxx с необязательным аргументом.

require 'optparse'
parser = OptionParser.new
parser.on('--xxx [XXX]', 'Long name with optional argument') do |value|
  p ['--xxx', value]
end
parser.parse!

Выполнение:

$ ruby long_optional.rb --help
Usage: long_optional [options]
        --xxx [XXX]                  Long name with optional argument
$ ruby long_optional.rb --xxx
["--xxx", nil]
$ ruby long_optional.rb --xxx FOO
["--xxx", "FOO"]

Длинные имена с отрицанием

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

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

Использование: 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"]

Ключевые слова аргументов

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

Вместо этого можно использовать отдельный символ-ключевое слово: одно из :NONE (значение по умолчанию), :REQUIRED или :OPTIONAL.

File argument_keywords.rb определяет опцию с обязательным аргументом.

require 'optparse'
parser = OptionParser.new
parser.on('-x', '--xxx', :REQUIRED, 'Required argument') do |value|
  p ['--xxx', value]
end
parser.parse!

Выполнение:

$ ruby argument_keywords.rb --help
Usage: argument_keywords [options]
    -x, --xxx                        Required argument
$ ruby argument_styles.rb --xxx
argument_styles.rb:6:in '<main>': missing argument: --xxx (OptionParser::MissingArgument)
$ ruby argument_styles.rb --xxx FOO
["--xxx", "FOO"]

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

Ещё один способ указать обязательный аргумент — определить его в строке, отдельной от строки имени.

File argument_strings.rb определяет опцию с обязательным аргументом.

require 'optparse'
parser = OptionParser.new
parser.on('-x', '--xxx', '=XXX', 'Required argument') do |value|
  p ['--xxx', value]
end
parser.parse!

Выполнение:

$ ruby argument_strings.rb --help
Usage: argument_strings [options]
    -x, --xxx=XXX                    Required argument
$ ruby argument_strings.rb --xxx
argument_strings.rb:9:in '<main>': missing argument: --xxx (OptionParser::MissingArgument)
$ ruby argument_strings.rb --xxx FOO
["--xxx", "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, которому должен соответствовать аргумент, либо Range или Array, в который должно входить преобразованное значение.

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
        --yyy YYY                    Check by range
        --zzz ZZZ                    Check by list
$ 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:12:in '<main>': invalid argument: --xxx bar (OptionParser::InvalidArgument)
$ ruby matched_values.rb --yyy 1
["--yyy", 1]
$ ruby matched_values.rb --yyy 4
matched_values.rb:12:in '<main>': invalid argument: --yyy 4 (OptionParser::InvalidArgument)
$ ruby matched_values.rb --zzz 1
["--zzz", 1]
$ ruby matched_values.rb --zzz 2
matched_values.rb:12:in '<main>': invalid argument: --zzz 2 (OptionParser::InvalidArgument)

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

Для аргумента опции можно задать преобразование из типа по умолчанию — String — в экземпляр другого класса.

Доступно несколько встроенных преобразователей. Также можно создавать собственные преобразователи.

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

Описания

Параметр описания — это любая строка, которая не распознаётся как имя опции или терминатор; иными словами, она не начинается с дефиса.

Можно указать любое количество параметров описания; каждый из них становится отдельной строкой в тексте, создаваемом опцией --help.

File descriptions.rb содержит шесть строк в массиве descriptions. Все они передаются как параметры в OptionParser#on, так что каждая строка становится отдельной строкой описания опции.

require 'optparse'
parser = OptionParser.new
description = <<-EOT
Lorem ipsum dolor sit amet, consectetuer
adipiscing elit. Aenean commodo ligula eget.
Aenean massa. Cum sociis natoque penatibus
et magnis dis parturient montes, nascetur
ridiculus mus. Donec quam felis, ultricies
nec, pellentesque eu, pretium quis, sem.
EOT
descriptions = description.split($/)
parser.on('--xxx', *descriptions) do |value|
  p ['--xxx', value]
end
parser.parse!

Выполнение:

$ ruby descriptions.rb --help
Usage: descriptions [options]
        --xxx                        Lorem ipsum dolor sit amet, consectetuer
                                     adipiscing elit. Aenean commodo ligula eget.
                                     Aenean massa. Cum sociis natoque penatibus
                                     et magnis dis parturient montes, nascetur
                                     ridiculus mus. Donec quam felis, ultricies
                                     nec, pellentesque eu, pretium quis, sem.
$ ruby descriptions.rb --xxx
["--xxx", true]

Обработчики опций

Обработчик опции — это исполняемый объект, который вызывается при обнаружении опции. Обработчиком может быть:

• Блок (чаще всего используются именно блоки).

• Процедура.

• Метод.

Блоки-обработчики

Обработчиком опции может быть блок.

File block.rb определяет опцию с блоком-обработчиком.

require 'optparse'
parser = OptionParser.new
parser.on('--xxx', 'Option with no argument') do |value|
  p ['Handler block for -xxx called with value:', value]
end
parser.on('--yyy YYY', 'Option with required argument') do |value|
  p ['Handler block for -yyy called with value:', value]
end
parser.parse!

Выполнение:

$ ruby block.rb --help
Usage: block [options]
        --xxx                        Option with no argument
        --yyy YYY                    Option with required argument
$ ruby block.rb --xxx
["Handler block for -xxx called with value:", true]
$ ruby block.rb --yyy FOO
["Handler block for -yyy called with value:", "FOO"]

Процедуры-обработчики

Обработчиком опции может быть Proc.

File proc.rb определяет опцию с процедурой-обработчиком.

require 'optparse'
parser = OptionParser.new
parser.on(
  '--xxx',
  'Option with no argument',
  ->(value) {p ['Handler proc for -xxx called with value:', value]}
)
parser.on(
  '--yyy YYY',
  'Option with required argument',
  ->(value) {p ['Handler proc for -yyy called with value:', value]}
)
parser.parse!

Выполнение:

$ ruby proc.rb --help
Usage: proc [options]
        --xxx                        Option with no argument
        --yyy YYY                    Option with required argument
$ ruby proc.rb --xxx
["Handler proc for -xxx called with value:", true]
$ ruby proc.rb --yyy FOO
["Handler proc for -yyy called with value:", "FOO"]

Методы-обработчики

Обработчиком опции может быть метод.

File proc.rb определяет опцию с методом-обработчиком.

require 'optparse'
parser = OptionParser.new
def xxx_handler(value)
  p ['Handler method for -xxx called with value:', value]
end
parser.on('--xxx', 'Option with no argument', method(:xxx_handler))
def yyy_handler(value)
  p ['Handler method for -yyy called with value:', value]
end
parser.on('--yyy YYY', 'Option with required argument', method(:yyy_handler))
parser.parse!

Выполнение:

$ ruby method.rb --help
Usage: method [options]
        --xxx                        Option with no argument
        --yyy YYY                    Option with required argument
$ ruby method.rb --xxx
["Handler method for -xxx called with value:", true]
$ ruby method.rb --yyy FOO
["Handler method for -yyy called with value:", "FOO"]