Spec-Zone.ru › Ruby 3.4

класс OptionParser

Родитель:
Объект

OptionParser

Новичок в OptionParser?

См. Учебник.

Введение

OptionParser — это класс для анализа командно-строчных параметров. Он значительно более продвинутый, но также и более простой в использовании, чем GetoptLong, и представляет собой более ориентированное на Ruby решение.

Функциональные возможности

  1. Спецификация аргументов и код для их обработки размещены в одном месте.

  2. Он может выводить сводку параметров; вам не нужно поддерживать эту строку отдельно.

  3. Необязательные и обязательные аргументы определяются очень удобно.

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

  5. Аргументы могут быть ограничены определённым набором.

Все эти возможности продемонстрированы в примерах ниже. См. make_switch для полной документации.

Минимальный пример

require 'optparse'

options = {}
OptionParser.new do |parser|
  parser.banner = "Usage: example.rb [options]"

  parser.on("-v", "--[no-]verbose", "Run verbosely") do |v|
    options[:verbose] = v
  end
end.parse!

p options
p ARGV

Генерация справки

OptionParser можно использовать для автоматической генерации справки для написанных вами команд:

require 'optparse'

Options = Struct.new(:name)

class Parser
  def self.parse(options)
    args = Options.new("world")

    opt_parser = OptionParser.new do |parser|
      parser.banner = "Usage: example.rb [options]"

      parser.on("-nNAME", "--name=NAME", "Name to say hello to") do |n|
        args.name = n
      end

      parser.on("-h", "--help", "Prints this help") do
        puts parser
        exit
      end
    end

    opt_parser.parse!(options)
    return args
  end
end
options = Parser.parse %w[--help]

#=>
   # Usage: example.rb [options]
   #     -n, --name=NAME                  Name to say hello to
   #     -h, --help                       Prints this help

Обязательные аргументы

Для параметров, требующих аргумент, строки спецификации параметров могут содержать имя параметра в верхнем регистре. Если параметр используется без обязательного аргумента, будет возбуждено исключение.

require 'optparse'

options = {}
OptionParser.new do |parser|
  parser.on("-r", "--require LIBRARY",
            "Require the LIBRARY before executing your script") do |lib|
    puts "You required #{lib}!"
  end
end.parse!

Используется:

$ ruby optparse-test.rb -r
optparse-test.rb:9:in `<main>': missing argument: -r (OptionParser::MissingArgument)
$ ruby optparse-test.rb -r my-library
You required my-library!

Преобразование типов

OptionParser поддерживает возможность приведения командно-строчных аргументов к объектам.

OptionParser поставляется с несколькими готовыми типами преобразований. Они:

  • Date — Всё, что принимается Date.parse (необходимо подключить optparse/date)

  • DateTime — Всё, что принимается DateTime.parse (необходимо подключить optparse/date)

  • Time — Всё, что принимается Time.httpdate или Time.parse (необходимо подключить optparse/time)

  • URI — Всё, что принимается URI.parse (необходимо подключить optparse/uri)

  • Shellwords — Всё, что принимается Shellwords.shellwords (необходимо подключить optparse/shellwords)

  • String — Любая непустая строка

  • Integer — Любое целое число. Будет преобразовывать восьмеричные числа. (например, 124, -3, 040)

  • Float — Любое вещественное число. (например, 10, 3.14, -100E+13)

  • Numeric — Любое целое число, вещественное число или рациональное число (1, 3.4, 1/3)

  • DecimalInteger — Как Integer, но без восьмеричного формата.

  • OctalInteger — Как Integer, но без десятичного формата.

  • DecimalNumeric — Десятичное целое число или вещественное число.

  • TrueClass — Принимает ‘+, yes, true, -, no, false’ и по умолчанию true

  • FalseClass — То же, что и TrueClass, но по умолчанию false

  • Array — Строки, разделенные запятыми (например, 1,2,3)

  • Regexp — Регулярные выражения. Также включает параметры.

Мы также можем добавить собственные преобразования, о чём мы поговорим ниже.

Использование встроенных преобразований

В качестве примера используется встроенное преобразование Time. Другие встроенные преобразования ведут себя аналогично. OptionParser попытается распарсить аргумент как Time. Если это удается, данное время будет передано в обработчик блока. В противном случае будет возбуждено исключение.

require 'optparse'
require 'optparse/time'
OptionParser.new do |parser|
  parser.on("-t", "--time [TIME]", Time, "Begin execution at given time") do |time|
    p time
  end
end.parse!

Используется:

$ ruby optparse-test.rb  -t nonsense
... invalid argument: -t nonsense (OptionParser::InvalidArgument)
$ ruby optparse-test.rb  -t 10-11-12
2010-11-12 00:00:00 -0500
$ ruby optparse-test.rb  -t 9:30
2014-08-13 09:30:00 -0400

Создание пользовательских преобразований

Метод accept в OptionParser может использоваться для создания преобразователей. Он определяет, какой блок преобразования вызывать всякий раз, когда указывается класс. В примере ниже используется получение объекта User перед тем, как обработчик on получит его.

require 'optparse'

User = Struct.new(:id, :name)

def find_user id
  not_found = ->{ raise "No User Found for id #{id}" }
  [ User.new(1, "Sam"),
    User.new(2, "Gandalf") ].find(not_found) do |u|
    u.id == id
  end
end

op = OptionParser.new
op.accept(User) do |user_id|
  find_user user_id.to_i
end

op.on("--user ID", User) do |user|
  puts user
end

op.parse!

Используется:

$ ruby optparse-test.rb --user 1
#<struct User id=1, name="Sam">
$ ruby optparse-test.rb --user 2
#<struct User id=2, name="Gandalf">
$ ruby optparse-test.rb --user 3
optparse-test.rb:15:in `block in find_user': No User Found for id 3 (RuntimeError)

Сохранение параметров в Hash

Параметр into методов order, parse и т. д. сохраняет командно-строчные параметры в Hash.

require 'optparse'

options = {}
OptionParser.new do |parser|
  parser.on('-a')
  parser.on('-b NUM', Integer)
  parser.on('-v', '--verbose')
end.parse!(into: options)

p options

Используется:

$ ruby optparse-test.rb -a
{:a=>true}
$ ruby optparse-test.rb -a -v
{:a=>true, :verbose=>true}
$ ruby optparse-test.rb -a -b 100
{:a=>true, :b=>100}

Полный пример

Следующий пример — полная программа Ruby. Вы можете запустить её и увидеть эффект задания различных параметров. Это, вероятно, лучший способ узнать функциональные возможности optparse.

require 'optparse'
require 'optparse/time'
require 'ostruct'
require 'pp'

class OptparseExample
  Version = '1.0.0'

  CODES = %w[iso-2022-jp shift_jis euc-jp utf8 binary]
  CODE_ALIASES = { "jis" => "iso-2022-jp", "sjis" => "shift_jis" }

  class ScriptOptions
    attr_accessor :library, :inplace, :encoding, :transfer_type,
                  :verbose, :extension, :delay, :time, :record_separator,
                  :list

    def initialize
      self.library = []
      self.inplace = false
      self.encoding = "utf8"
      self.transfer_type = :auto
      self.verbose = false
    end

    def define_options(parser)
      parser.banner = "Usage: example.rb [options]"
      parser.separator ""
      parser.separator "Specific options:"

      # add additional options
      perform_inplace_option(parser)
      delay_execution_option(parser)
      execute_at_time_option(parser)
      specify_record_separator_option(parser)
      list_example_option(parser)
      specify_encoding_option(parser)
      optional_option_argument_with_keyword_completion_option(parser)
      boolean_verbose_option(parser)

      parser.separator ""
      parser.separator "Common options:"
      # No argument, shows at tail.  This will print an options summary.
      # Try it and see!
      parser.on_tail("-h", "--help", "Show this message") do
        puts parser
        exit
      end
      # Another typical switch to print the version.
      parser.on_tail("--version", "Show version") do
        puts Version
        exit
      end
    end

    def perform_inplace_option(parser)
      # Specifies an optional option argument
      parser.on("-i", "--inplace [EXTENSION]",
                "Edit ARGV files in place",
                "(make backup if EXTENSION supplied)") do |ext|
        self.inplace = true
        self.extension = ext || ''
        self.extension.sub!(/\A\.?(?=.)/, ".")  # Ensure extension begins with dot.
      end
    end

    def delay_execution_option(parser)
      # Cast 'delay' argument to a Float.
      parser.on("--delay N", Float, "Delay N seconds before executing") do |n|
        self.delay = n
      end
    end

    def execute_at_time_option(parser)
      # Cast 'time' argument to a Time object.
      parser.on("-t", "--time [TIME]", Time, "Begin execution at given time") do |time|
        self.time = time
      end
    end

    def specify_record_separator_option(parser)
      # Cast to octal integer.
      parser.on("-F", "--irs [OCTAL]", OptionParser::OctalInteger,
                "Specify record separator (default \\0)") do |rs|
        self.record_separator = rs
      end
    end

    def list_example_option(parser)
      # List of arguments.
      parser.on("--list x,y,z", Array, "Example 'list' of arguments") do |list|
        self.list = list
      end
    end

    def specify_encoding_option(parser)
      # Keyword completion.  We are specifying a specific set of arguments (CODES
      # and CODE_ALIASES - notice the latter is a Hash), and the user may provide
      # the shortest unambiguous text.
      code_list = (CODE_ALIASES.keys + CODES).join(', ')
      parser.on("--code CODE", CODES, CODE_ALIASES, "Select encoding",
                "(#{code_list})") do |encoding|
        self.encoding = encoding
      end
    end

    def optional_option_argument_with_keyword_completion_option(parser)
      # Optional '--type' option argument with keyword completion.
      parser.on("--type [TYPE]", [:text, :binary, :auto],
                "Select transfer type (text, binary, auto)") do |t|
        self.transfer_type = t
      end
    end

    def boolean_verbose_option(parser)
      # Boolean switch.
      parser.on("-v", "--[no-]verbose", "Run verbosely") do |v|
        self.verbose = v
      end
    end
  end

  #
  # Return a structure describing the options.
  #
  def parse(args)
    # The options specified on the command line will be collected in
    # *options*.

    @options = ScriptOptions.new
    @args = OptionParser.new do |parser|
      @options.define_options(parser)
      parser.parse!(args)
    end
    @options
  end

  attr_reader :parser, :options
end  # class OptparseExample

example = OptparseExample.new
options = example.parse(ARGV)
pp options # example.options
pp ARGV

Модуль завершения для оболочки Completion

Для современных оболочек (например, bash, zsh и т. д.) можно использовать завершение команд для командно-строчных параметров.

Дополнительная документация

Приведенных выше примеров, а также сопровождающего Учебника, должно быть достаточно, чтобы понять, как использовать этот класс. Если у вас есть вопросы, создайте тикет на bugs.ruby-lang.org.

Константы

DecimalInteger

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

DecimalNumeric

Формат десятичного целого/вещественного числа, который должен быть преобразован в Integer для целого формата и Float для формата с плавающей запятой.

OctalInteger

Формат целого числа в восьмеричной/шестнадцатеричной/двоичной системе (подобно Ruby/C), который должен быть преобразован в Integer.

Version

Строка версии

Атрибуты

banner [W]

Заголовок-баннер, предшествующий описанию.

default_argv [RW]

Строки, подлежащие парсингу по умолчанию.

program_name [W]

Имя программы, которое будет выведено в сообщениях об ошибках и баннере по умолчанию, по умолчанию — $0.

raise_unknown [RW]

Вызывать исключение при неизвестном параметре.

release [W]

Код выпуска

require_exact [RW]

Требовать точное совпадение параметров (запрещает использование сокращенных длинных параметров в качестве коротких).

set_banner [W]

Заголовок-баннер, предшествующий описанию.

set_program_name [W]

Имя программы, которое будет выведено в сообщениях об ошибках и баннере по умолчанию, по умолчанию — $0.

set_summary_indent [RW]

Отступ для сводки. Должен быть String (или иметь метод + String).

set_summary_width [RW]

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

summary_indent [RW]

Отступ для сводки. Должен быть String (или иметь метод + String).

summary_width [RW]

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

version [W]

Version

END_OF_DOCUMENT_MARKER

Методы публичного класса

accept (*args, &blk)
Исходный код
# File lib/optparse.rb, line 1233
def self.accept(*args, &blk) top.accept(*args, &blk) end

См. accept.

getopts (*args, symbolize_names: false)
Исходный код
# File lib/optparse.rb, line 1913
def self.getopts(*args, symbolize_names: false)
  new.getopts(*args, symbolize_names: symbolize_names)
end

См. getopts.

inc (arg, default = nil)
Исходный код
# File lib/optparse.rb, line 1155
def self.inc(arg, default = nil)
  case arg
  when Integer
    arg.nonzero?
  when nil
    default.to_i + 1
  end
end

Возвращает увеличенное значение default согласно arg.

new (banner = nil, width = 32, indent = ' ' * 4) { |self| ... }
Исходный код
# File lib/optparse.rb, line 1178
def initialize(banner = nil, width = 32, indent = ' ' * 4)
  @stack = [DefaultList, List.new, List.new]
  @program_name = nil
  @banner = banner
  @summary_width = width
  @summary_indent = indent
  @default_argv = ARGV
  @require_exact = false
  @raise_unknown = true
  add_officious
  yield self if block_given?
end

Инициализирует экземпляр и возвращает его, если вызывается с блоком.

banner

Сообщение баннера.

width

Ширина резюме.

indent

Отступ резюме.

reject (*args, &blk)
Исходный код
# File lib/optparse.rb, line 1246
def self.reject(*args, &blk) top.reject(*args, &blk) end

См. reject.

show_version (*pkgs)
Исходный код
# File lib/optparse/version.rb, line 10
def show_version(*pkgs)
  progname = ARGV.options.program_name
  result = false
  show = proc do |klass, cname, version|
    str = "#{progname}"
    unless klass == ::Object and cname == :VERSION
      version = version.join(".") if Array === version
      str << ": #{klass}" unless klass == Object
      str << " version #{version}"
    end
    [:Release, :RELEASE].find do |rel|
      if klass.const_defined?(rel)
        str << " (#{klass.const_get(rel)})"
      end
    end
    puts str
    result = true
  end
  if pkgs.size == 1 and pkgs[0] == "all"
    self.search_const(::Object, /\AV(?:ERSION|ersion)\z/) do |klass, cname, version|
      unless cname[1] == ?e and klass.const_defined?(:Version)
        show.call(klass, cname.intern, version)
      end
    end
  else
    pkgs.each do |pkg|
      begin
        pkg = pkg.split(/::|\//).inject(::Object) {|m, c| m.const_get(c)}
        v = case
            when pkg.const_defined?(:Version)
              pkg.const_get(n = :Version)
            when pkg.const_defined?(:VERSION)
              pkg.const_get(n = :VERSION)
            else
              n = nil
              "unknown"
            end
        show.call(pkg, n, v)
      rescue NameError
      end
    end
  end
  result
end

Отображает строку версии в пакетах, если Version определена.

pkgs

список пакетов

terminate (arg = nil)
Исходный код
# File lib/optparse.rb, line 1208
def self.terminate(arg = nil)
  throw :terminate, arg
end

См. terminate.

top ()
Исходный код
# File lib/optparse.rb, line 1218
def self.top() DefaultList end

Возвращает глобальный верхний список опций.

Не используйте напрямую.

with (*args, &block)
Исходный код
# File lib/optparse.rb, line 1146
def self.with(*args, &block)
  opts = new(*args)
  opts.instance_eval(&block)
  opts
end

Инициализирует новый экземпляр и вычисляет необязательный блок в контексте экземпляра. Аргументы args передаются в new, см. описание параметров там.

Этот метод устарел, его поведение соответствует более старому методу new.

Методы публичного экземпляра

abort (mesg = $!)
Исходный код
# File lib/optparse.rb, line 1348
def abort(mesg = $!)
  super("#{program_name}: #{mesg}")
end

Выводит сообщение с именем программы, затем завершает работу.

mesg

Сообщение, по умолчанию +$!+.

См. Kernel#abort.

Вызывает метод суперкласса Kernel#abort
accept (*args, &blk)
Исходный код
# File lib/optparse.rb, line 1229
def accept(*args, &blk) top.accept(*args, &blk) end

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

t

Указатель класса аргумента, любой объект, включая Class.

pat

Шаблон для аргумента, по умолчанию t если он отвечает на match.

accept(t, pat, &block)
additional_message (typ, opt)
Исходный код
# File lib/optparse.rb, line 1964
def additional_message(typ, opt)
  return unless typ and opt and defined?(DidYouMean::SpellChecker)
  all_candidates = []
  visit(:get_candidates, typ) do |candidates|
    all_candidates.concat(candidates)
  end
  all_candidates.select! {|cand| cand.is_a?(String) }
  checker = DidYouMean::SpellChecker.new(dictionary: all_candidates)
  DidYouMean.formatter.message_for(all_candidates & checker.correct(opt))
end

Возвращает дополнительную информацию.

banner ()
Исходный код
# File lib/optparse.rb, line 1278
def banner
  unless @banner
    @banner = +"Usage: #{program_name} [options]"
    visit(:add_banner, @banner)
  end
  @banner
end

Заголовок баннера, предваряющий сводку.

base ()
Исходный код
# File lib/optparse.rb, line 1362
def base
  @stack[1]
end

Предмет on_tail.

candidate (word)
Исходный код
# File lib/optparse.rb, line 1978
def candidate(word)
  list = []
  case word
  when '-'
    long = short = true
  when /\A--/
    word, arg = word.split(/=/, 2)
    argpat = Completion.regexp(arg, false) if arg and !arg.empty?
    long = true
  when /\A-/
    short = true
  end
  pat = Completion.regexp(word, long)
  visit(:each_option) do |opt|
    next unless Switch === opt
    opts = (long ? opt.long : []) + (short ? opt.short : [])
    opts = Completion.candidate(word, true, pat, &opts.method(:each)).map(&:first) if pat
    if /\A=/ =~ opt.arg
      opts.map! {|sw| sw + "="}
      if arg and CompletingHash === opt.pattern
        if opts = opt.pattern.candidate(arg, false, argpat)
          opts.map!(&:last)
        end
      end
    end
    list.concat(opts)
  end
  list
end

Возвращает кандидатов для word.

def_head_option
Псевдоним для: define_head
def_option
Псевдоним для: define
def_tail_option
Псевдоним для: define_tail
define(*params, &block)
Исходный код
# File lib/optparse.rb, line 1606
def define(*opts, &block)
  top.append(*(sw = make_switch(opts, block)))
  sw[0]
end

Создает параметр из указанных параметров params. См. Параметры новых параметров.

Блок, если он предоставлен, является обработчиком созданного параметра. Когда параметр встречается во время анализа командной строки, блок вызывается с аргументом, заданным для параметра, если таковой имеется. См. Обработчики параметров.

Также алиасировано как: def_option
define_by_keywords(options, method, **params)
Исходный код
# File lib/optparse/kwargs.rb, line 15
def define_by_keywords(options, method, **params)
  method.parameters.each do |type, name|
    case type
    when :key, :keyreq
      op, cl = *(type == :key ? %w"[ ]" : ["", ""])
      define("--#{name}=#{op}#{name.upcase}#{cl}", *params[name]) do |o|
        options[name] = o
      end
    end
  end
  options
end

Создает параметр из указанных параметров params. См. Параметры новых параметров.

Блок, если он предоставлен, является обработчиком созданного параметра. Когда параметр встречается во время анализа командной строки, блок вызывается с аргументом, заданным для параметра, если таковой имеется. См. Обработчики параметров.

Определяет параметры, которые устанавливаются в options для параметров ключевых слов method.

Параметры для каждого ключевого слова задаются как элементы params.

define_head(*params, &block)
Исходный код
# File lib/optparse.rb, line 1627
def define_head(*opts, &block)
  top.prepend(*(sw = make_switch(opts, block)))
  sw[0]
end

Создает параметр из указанных параметров params. См. Параметры новых параметров.

Блок, если он предоставлен, является обработчиком созданного параметра. Когда параметр встречается во время анализа командной строки, блок вызывается с аргументом, заданным для параметра, если таковой имеется. См. Обработчики параметров.

Также алиасировано как: def_head_option
define_tail(*params, &block)
Исходный код
# File lib/optparse.rb, line 1650
def define_tail(*opts, &block)
  base.append(*(sw = make_switch(opts, block)))
  sw[0]
end

Создает параметр из указанных параметров params. См. Параметры новых параметров.

Блок, если он предоставлен, является обработчиком созданного параметра. Когда параметр встречается во время анализа командной строки, блок вызывается с аргументом, заданным для параметра, если таковой имеется. См. Обработчики параметров.

Также алиасировано как: def_tail_option
environment (env = File.basename($0, '.*'), **keywords)
Исходный код
# File lib/optparse.rb, line 2051
def environment(env = File.basename($0, '.*'), **keywords)
  env = ENV[env] || ENV[env.upcase] or return
  require 'shellwords'
  parse(*Shellwords.shellwords(env), **keywords)
end

Парсит переменную окружения env или ее заглавную версию со split-ом как в оболочке.

env по умолчанию равно имени файла программы.

getopts (*args, symbolize_names: false, **keywords)
Исходный код
# File lib/optparse.rb, line 1878
def getopts(*args, symbolize_names: false, **keywords)
  argv = Array === args.first ? args.shift : default_argv
  single_options, *long_options = *args

  result = {}

  single_options.scan(/(.)(:)?/) do |opt, val|
    if val
      result[opt] = nil
      define("-#{opt} VAL")
    else
      result[opt] = false
      define("-#{opt}")
    end
  end if single_options

  long_options.each do |arg|
    arg, desc = arg.split(';', 2)
    opt, val = arg.split(':', 2)
    if val
      result[opt] = val.empty? ? nil : val
      define("--#{opt}=#{result[opt] || "VAL"}", *[desc].compact)
    else
      result[opt] = false
      define("--#{opt}", *[desc].compact)
    end
  end

  parse_in_order(argv, result.method(:[]=), **keywords)
  symbolize_names ? result.transform_keys(&:to_sym) : result
end

Метод-обёртка для getopts.rb.

params = ARGV.getopts("ab:", "foo", "bar:", "zot:Z;zot option")
# params["a"] = true   # -a
# params["b"] = "1"    # -b1
# params["foo"] = "1"  # --foo
# params["bar"] = "x"  # --bar x
# params["zot"] = "z"  # --zot Z

Параметр symbolize_names (булево) указывает, должны ли возвращаемые ключи Hash быть Символами; по умолчанию false (используются Строки).

params = ARGV.getopts("ab:", "foo", "bar:", "zot:Z;zot option", symbolize_names: true)
# params[:a] = true   # -a
# params[:b] = "1"    # -b1
# params[:foo] = "1"  # --foo
# params[:bar] = "x"  # --bar x
# params[:zot] = "z"  # --zot Z
help ()
Исходный код
# File lib/optparse.rb, line 1407
def help; summarize("#{banner}".sub(/\n?\z/, "\n")) end

Возвращает строку с кратким описанием параметров.

Также известен как: to_s
inc (*args)
Исходный код
# File lib/optparse.rb, line 1167
def inc(*args)
  self.class.inc(*args)
end

См. self.inc

load (filename = nil, **keywords)
Исходный код
# File lib/optparse.rb, line 2019
def load(filename = nil, **keywords)
  unless filename
    basename = File.basename($0, '.*')
    return true if load(File.expand_path(basename, '~/.options'), **keywords) rescue nil
    basename << ".options"
    return [
      # XDG
      ENV['XDG_CONFIG_HOME'],
      '~/.config',
      *ENV['XDG_CONFIG_DIRS']&.split(File::PATH_SEPARATOR),

      # Haiku
      '~/config/settings',
    ].any? {|dir|
      next if !dir or dir.empty?
      load(File.expand_path(basename, dir), **keywords) rescue nil
    }
  end
  begin
    parse(*File.readlines(filename, chomp: true), **keywords)
    true
  rescue Errno::ENOENT, Errno::ENOTDIR
    false
  end
end

Загружает параметры из файлов имен как filename. Ничего не делает, если файл отсутствует. Возвращает, была ли загрузка успешной.

filename по умолчанию — это имя базового файла программы без суффикса в каталоге ~/.options, затем имя базового файла с суффиксом ‘.options’ в стандартных местах XDG и Haiku.

Необязательный аргумент ключевого слова into работает точно так же, как и принимаемый в методе parse.

make_switch(params, block = nil)
Исходный код
# File lib/optparse.rb, line 1462
def make_switch(opts, block = nil)
  short, long, nolong, style, pattern, conv, not_pattern, not_conv, not_style = [], [], []
  ldesc, sdesc, desc, arg = [], [], []
  default_style = Switch::NoArgument
  default_pattern = nil
  klass = nil
  q, a = nil
  has_arg = false

  opts.each do |o|
    # argument class
    next if search(:atype, o) do |pat, c|
      klass = notwice(o, klass, 'type')
      if not_style and not_style != Switch::NoArgument
        not_pattern, not_conv = pat, c
      else
        default_pattern, conv = pat, c
      end
    end

    # directly specified pattern(any object possible to match)
    if (!(String === o || Symbol === o)) and o.respond_to?(:match)
      pattern = notwice(o, pattern, 'pattern')
      if pattern.respond_to?(:convert)
        conv = pattern.method(:convert).to_proc
      else
        conv = SPLAT_PROC
      end
      next
    end

    # anything others
    case o
    when Proc, Method
      block = notwice(o, block, 'block')
    when Array, Hash
      case pattern
      when CompletingHash
      when nil
        pattern = CompletingHash.new
        conv = pattern.method(:convert).to_proc if pattern.respond_to?(:convert)
      else
        raise ArgumentError, "argument pattern given twice"
      end
      o.each {|pat, *v| pattern[pat] = v.fetch(0) {pat}}
    when Module
      raise ArgumentError, "unsupported argument type: #{o}", ParseError.filter_backtrace(caller(4))
    when *ArgumentStyle.keys
      style = notwice(ArgumentStyle[o], style, 'style')
    when /^--no-([^\[\]=\s]*)(.+)?/
      q, a = $1, $2
      o = notwice(a ? Object : TrueClass, klass, 'type')
      not_pattern, not_conv = search(:atype, o) unless not_style
      not_style = (not_style || default_style).guess(arg = a) if a
      default_style = Switch::NoArgument
      default_pattern, conv = search(:atype, FalseClass) unless default_pattern
      ldesc << "--no-#{q}"
      (q = q.downcase).tr!('_', '-')
      long << "no-#{q}"
      nolong << q
    when /^--\[no-\]([^\[\]=\s]*)(.+)?/
      q, a = $1, $2
      o = notwice(a ? Object : TrueClass, klass, 'type')
      if a
        default_style = default_style.guess(arg = a)
        default_pattern, conv = search(:atype, o) unless default_pattern
      end
      ldesc << "--[no-]#{q}"
      (o = q.downcase).tr!('_', '-')
      long << o
      not_pattern, not_conv = search(:atype, FalseClass) unless not_style
      not_style = Switch::NoArgument
      nolong << "no-#{o}"
    when /^--([^\[\]=\s]*)(.+)?/
      q, a = $1, $2
      if a
        o = notwice(NilClass, klass, 'type')
        default_style = default_style.guess(arg = a)
        default_pattern, conv = search(:atype, o) unless default_pattern
      end
      ldesc << "--#{q}"
      (o = q.downcase).tr!('_', '-')
      long << o
    when /^-(\[\^?\]?(?:[^\\\]]|\\.)*\])(.+)?/
      q, a = $1, $2
      o = notwice(Object, klass, 'type')
      if a
        default_style = default_style.guess(arg = a)
        default_pattern, conv = search(:atype, o) unless default_pattern
      else
        has_arg = true
      end
      sdesc << "-#{q}"
      short << Regexp.new(q)
    when /^-(.)(.+)?/
      q, a = $1, $2
      if a
        o = notwice(NilClass, klass, 'type')
        default_style = default_style.guess(arg = a)
        default_pattern, conv = search(:atype, o) unless default_pattern
      end
      sdesc << "-#{q}"
      short << q
    when /^=/
      style = notwice(default_style.guess(arg = o), style, 'style')
      default_pattern, conv = search(:atype, Object) unless default_pattern
    else
      desc.push(o) if o && !o.empty?
    end
  end

  default_pattern, conv = search(:atype, default_style.pattern) unless default_pattern
  if !(short.empty? and long.empty?)
    if has_arg and default_style == Switch::NoArgument
      default_style = Switch::RequiredArgument
    end
    s = (style || default_style).new(pattern || default_pattern,
                                     conv, sdesc, ldesc, arg, desc, block)
  elsif !block
    if style or pattern
      raise ArgumentError, "no switch given", ParseError.filter_backtrace(caller)
    end
    s = desc
  else
    short << pattern
    s = (style || default_style).new(pattern,
                                     conv, nil, nil, arg, desc, block)
  end
  return s, short, long,
    (not_style.new(not_pattern, not_conv, sdesc, ldesc, nil, desc, block) if not_style),
    nolong
end

Создает параметр из заданных параметров params. См. Параметры для новых параметров.

Блок, если задан, является обработчиком для созданного параметра. Когда параметр встречается во время анализа командной строки, блок вызывается с аргументом, заданным для параметра, если таковой имеется. См. Обработчики параметров.

new () { |self| ... }
Исходный код
# File lib/optparse.rb, line 1372
def new
  @stack.push(List.new)
  if block_given?
    yield self
  else
    self
  end
end

Добавляет новый List.

Если задан блок, передает self и возвращает результат блока, иначе возвращает self.

on(*params, &block)
Исходный код
# File lib/optparse.rb, line 1616
def on(*opts, &block)
  define(*opts, &block)
  self
end

Создает параметр из заданных параметров params. См. Параметры для новых параметров.

Блок, если задан, является обработчиком для созданного параметра. Когда параметр встречается во время анализа командной строки, блок вызывается с аргументом, заданным для параметра, если таковой имеется. См. Обработчики параметров.

on_head(*params, &block)
Исходный код
# File lib/optparse.rb, line 1639
def on_head(*opts, &block)
  define_head(*opts, &block)
  self
end

Создает параметр из заданных параметров params. См. Параметры для новых параметров.

Блок, если задан, является обработчиком для созданного параметра. Когда параметр встречается во время анализа командной строки, блок вызывается с аргументом, заданным для параметра, если таковой имеется. См. Обработчики параметров.

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

on_tail(*params, &block)
Исходный код
# File lib/optparse.rb, line 1663
def on_tail(*opts, &block)
  define_tail(*opts, &block)
  self
end

Создает параметр из заданных параметров params. См. Параметры для новых параметров.

Блок, если задан, является обработчиком для созданного параметра. Когда параметр встречается во время анализа командной строки, блок вызывается с аргументом, заданным для параметра, если таковой имеется. См. Обработчики параметров.

Новый параметр добавляется в конец сводки.

order (*argv, **keywords, &nonopt)
Исходный код
# File lib/optparse.rb, line 1692
def order(*argv, **keywords, &nonopt)
  argv = argv[0].dup if argv.size == 1 and Array === argv[0]
  order!(argv, **keywords, &nonopt)
end

Разбирает аргументы командной строки argv по порядку. Когда задан блок, каждый аргумент без параметра передается ему. Когда предоставлен необязательный аргумент ключевого слова into, значения разобранных параметров сохраняются там с помощью метода []= (поэтому это может быть Hash или OpenStruct или другой подобный объект).

Возвращает оставшиеся argv без анализа.

order! (argv = default_argv, into: nil, **keywords, &nonopt)
Исходный код
# File lib/optparse.rb, line 1701
def order!(argv = default_argv, into: nil, **keywords, &nonopt)
  setter = ->(name, val) {into[name.to_sym] = val} if into
  parse_in_order(argv, setter, **keywords, &nonopt)
end

То же, что и order, но удаляет переключатели деструктивно. Аргументы без параметров остаются в argv.

parse (*argv, **keywords)
Исходный код
# File lib/optparse.rb, line 1842
def parse(*argv, **keywords)
  argv = argv[0].dup if argv.size == 1 and Array === argv[0]
  parse!(argv, **keywords)
end

Разбирает аргументы командной строки argv по порядку, когда установлена переменная среды POSIXLY_CORRECT, и в режиме перестановки в противном случае. Когда предоставлен необязательный аргумент ключевого слова into, значения разобранных параметров сохраняются там с помощью метода []= (поэтому это может быть Hash или OpenStruct или другой подобный объект).

parse! (argv = default_argv, **keywords)
Исходный код
# File lib/optparse.rb, line 1851
def parse!(argv = default_argv, **keywords)
  if ENV.include?('POSIXLY_CORRECT')
    order!(argv, **keywords)
  else
    permute!(argv, **keywords)
  end
end

То же, что и parse, но удаляет переключатели деструктивно. Аргументы без параметров остаются в argv.

permute (*argv, **keywords)
Исходный код
# File lib/optparse.rb, line 1819
def permute(*argv, **keywords)
  argv = argv[0].dup if argv.size == 1 and Array === argv[0]
  permute!(argv, **keywords)
end

Разбирает аргументы командной строки argv в режиме перестановки и возвращает список аргументов без параметров. Когда предоставлен необязательный аргумент ключевого слова into, значения разобранных параметров сохраняются там с помощью метода []= (поэтому это может быть Hash или OpenStruct или другой подобный объект).

permute! (argv = default_argv, **keywords)
Исходный код
# File lib/optparse.rb, line 1828
def permute!(argv = default_argv, **keywords)
  nonopts = []
  order!(argv, **keywords, &nonopts.method(:<<))
  argv[0, 0] = nonopts
  argv
end

То же, что и permute, но удаляет переключатели деструктивно. Аргументы, не являющиеся опциями, остаются в argv.

program_name ()
Исходный код
# File lib/optparse.rb, line 1290
def program_name
  @program_name || File.basename($0, '.*')
end

Имя программы, которое будет выведено в сообщении об ошибке и в стандартном баннере, по умолчанию равно $0.

reject (*args, &blk)
Исходный код
# File lib/optparse.rb, line 1242
def reject(*args, &blk) top.reject(*args, &blk) end

Направляет отказ от указанного аргумента класса.

type

Указатель класса аргумента, любой объект, включая Class.

reject(type)
release ()
Исходный код
# File lib/optparse.rb, line 1315
def release
  (defined?(@release) && @release) || (defined?(::Release) && ::Release) || (defined?(::RELEASE) && ::RELEASE)
end

Код выпуска

remove ()
Исходный код
# File lib/optparse.rb, line 1384
def remove
  @stack.pop
end

Удаляет последний List.

separator (string)
Исходный код
# File lib/optparse.rb, line 1672
def separator(string)
  top.append(string, nil, nil)
end

Добавить разделитель в сводку.

summarize (to = [], width = @summary_width, max = width - 1, indent = @summary_indent, &blk)
Исходный код
# File lib/optparse.rb, line 1397
def summarize(to = [], width = @summary_width, max = width - 1, indent = @summary_indent, &blk)
  nl = "\n"
  blk ||= proc {|l| to << (l.index(nl, -1) ? l : l + nl)}
  visit(:summarize, {}, {}, width, max, indent, &blk)
  to
end

Помещает сводку опций в to и возвращает to. Выдает каждую строку, если задан блок.

to

Место назначения вывода, которое должно иметь метод <<. По умолчанию равно [].

width

Ширина левой стороны, по умолчанию равна @summary_width.

max

Максимальная длина, разрешенная для левой стороны, по умолчанию равна width - 1.

indent

Отступ, по умолчанию равен @summary_indent.

terminate (arg = nil)
Исходный код
# File lib/optparse.rb, line 1202
def terminate(arg = nil)
  self.class.terminate(arg)
end

Прерывает разбор опций. Необязательный параметр arg — это строка, возвращенная назад, которая будет первым аргументом, не являющимся опцией.

to_a ()
Исходный код
# File lib/optparse.rb, line 1436
def to_a; summarize("#{banner}".split(/^/)) end

Возвращает список сводки опций.

to_s ()
Псевдоним для: help
top ()
Исходный код
# File lib/optparse.rb, line 1355
def top
  @stack[-1]
end

Объект on / on_head, accept / reject

ver ()
Исходный код
# File lib/optparse.rb, line 1322
def ver
  if v = version
    str = +"#{program_name} #{[v].join('.')}"
    str << " (#{v})" if v = release
    str
  end
end

Возвращает строку версии из program_name, версии и выпуска.

version ()
Исходный код
# File lib/optparse.rb, line 1308
def version
  (defined?(@version) && @version) || (defined?(::Version) && ::Version)
end

Version

warn (mesg = $!)
Исходный код
# File lib/optparse.rb, line 1337
def warn(mesg = $!)
  super("#{program_name}: #{mesg}")
end

Отображает сообщение об ошибке с именем программы

mesg

Сообщение, по умолчанию равно +$!+.

См. Kernel#warn.

Вызывает метод суперкласса Kernel#warn

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

Spec-Zone.ru

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