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

Методы создания опций в 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, для отображения определенных опций.

Содержание:

• Имена опций

  • Короткое имя

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Описание

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

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

  • Обработчики Proc

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

Имена опций

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

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

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

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

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

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’, ‘Одно длинное имя’) do |value|

  p ['--xxx', value]
  

  end parser.on(‘–y1%’, ‘–z2#’, ‘Два длинных имени (алиасы)’) 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 [опции]

  -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, которому должно соответствовать данное значение аргумента.

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)

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

Опция может указывать, что ее аргумент должен быть преобразован из стандартного 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]

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

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

• Блок (это наиболее часто встречающийся случай).

• Объект Proc.

• Метод.

Блоки Обработчиков

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

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

Обработчики (Методы)

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

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