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

Методы создания параметров в 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"]

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

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)

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]

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)

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]

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

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

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