Parameters for New Options — Ruby 3.3

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

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

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

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’, ‘Одно длинное имя’) 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 [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, которому должен соответствовать данный аргумент.

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

Обработчики (Procs)

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

File proc.rb определяет параметр, имеющий обработчик proc.

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

Ruby Core © 1993–2022 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.

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

Имена опций

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Явные значения в Array

Явные значения в Hash

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

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

Описания

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

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

Обработчики (Procs)

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

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

Явные значения в `Array`

Явные значения в `Hash`