class Gem::Command

所有 Gem 命令的基类。当创建一个新的 gem 命令时，定义 initialize、execute、arguments、defaults_str、description 和 usage （如适用）。有关详细信息，请参阅上述方法。

一个很好的例子是 Gem::Commands::ContentsCommand

属性

command [R]

命令的名称。

defaults [RW]

命令的默认选项。

options [R]

命令的选项。

program_name [RW]

用于命令行调用的命令名称。

summary [RW]

命令的简短描述。

公共类方法

add_common_option (*args, &handler)

源代码

# File lib/rubygems/command.rb, line 65
def self.add_common_option(*args, &handler)
  Gem::Command.common_options << [args, handler]
end

add_specific_extra_args (cmd,args)

源代码

# File lib/rubygems/command.rb, line 94
def self.add_specific_extra_args(cmd,args)
  args = args.split(/\s+/) if args.is_a? String
  specific_extra_args_hash[cmd] = args
end

为给定命令添加额外的参数列表。args 可以是一个数组或一个以空格分隔的字符串。

build_args ()

源代码

# File lib/rubygems/command.rb, line 53
def self.build_args
  @build_args ||= []
end

构建 gem 时使用的参数

build_args= (value)

源代码

# File lib/rubygems/command.rb, line 57
def self.build_args=(value)
  @build_args = value
end

common_options ()

源代码

# File lib/rubygems/command.rb, line 61
def self.common_options
  @common_options ||= []
end

extra_args ()

源代码

# File lib/rubygems/command.rb, line 69
def self.extra_args
  @extra_args ||= []
end

extra_args= (value)

源代码

# File lib/rubygems/command.rb, line 73
def self.extra_args=(value)
  case value
  when Array
    @extra_args = value
  when String
    @extra_args = value.split(" ")
  end
end

new (command, summary=nil, defaults={})

源代码

# File lib/rubygems/command.rb, line 120
def initialize(command, summary=nil, defaults={})
  @command = command
  @summary = summary
  @program_name = "gem #{command}"
  @defaults = defaults
  @options = defaults.dup
  @option_groups = Hash.new {|h,k| h[k] = [] }
  @deprecated_options = { command => {} }
  @parser = nil
  @when_invoked = nil
end

初始化一个名为 command 的通用 gem 命令。summary 是一个在 ‘gem help commands’ 中显示的简短描述。defaults 是默认选项。默认值应在 defaults_str 中反映，除非没有默认值。

当定义一个新的命令子类时，使用 add_option 添加命令行开关。

未处理的参数（gem 名称、文件等）保留在 options[:args] 中。

specific_extra_args (cmd)

源代码

# File lib/rubygems/command.rb, line 86
def self.specific_extra_args(cmd)
  specific_extra_args_hash[cmd]
end

返回命令的额外参数数组。额外参数来自程序启动时读取的 gem 配置文件。

specific_extra_args_hash ()

源代码

# File lib/rubygems/command.rb, line 102
def self.specific_extra_args_hash
  @specific_extra_args_hash ||= Hash.new do |h,k|
    h[k] = Array.new
  end
end

特定额外参数哈希的访问器（自我初始化）。

公共实例方法

add_extra_args (args)

源代码

# File lib/rubygems/command.rb, line 451
def add_extra_args(args)
  result = []

  s_extra = Gem::Command.specific_extra_args(@command)
  extra = Gem::Command.extra_args + s_extra

  until extra.empty? do
    ex = []
    ex << extra.shift
    ex << extra.shift if /^[^-]/.match?(extra.first.to_s)
    result << ex if handles?(ex)
  end

  result.flatten!
  result.concat(args)
  result
end

从 ~/.gemrc 添加额外参数

add_option (*opts) { |value, options| ... }

源代码

# File lib/rubygems/command.rb, line 358
def add_option(*opts, &handler) # :yields: value, options
  group_name = Symbol === opts.first ? opts.shift : :options

  raise "Do not pass an empty string in opts" if opts.include?("")

  @option_groups[group_name] << [opts, handler]
end

向命令添加命令行选项和处理程序。

有关 opts 的解释，请参阅 Gem::OptionParser#make_switch。

将使用两个值调用 handler，即参数的值和选项哈希。

如果 add_option 的第一个参数是一个 Symbol，则它用于在输出中对选项进行分组。有关示例，请参阅 ‘gem help list’。

arguments ()

源代码

# File lib/rubygems/command.rb, line 258
def arguments
  ""
end

重写以提供命令接受的参数的详细信息。它应该返回一个左对齐的字符串，每行一个参数。

例如

def usage
  "#{program_name} FILE [FILE ...]"
end

def arguments
  "FILE          name of file to find"
end

begins? (long, short)

源代码

# File lib/rubygems/command.rb, line 135
def begins?(long, short)
  return false if short.nil?
  long[0, short.length] == short
end

如果 long 以 short 中的字符开头，则为 True。

check_deprecated_options (options)

源代码

# File lib/rubygems/command.rb, line 397
def check_deprecated_options(options)
  options.each do |option|
    next unless option_is_deprecated?(option)
    deprecation = @deprecated_options[command][option]
    version_to_expire = deprecation["rg_version_to_expire"]

    deprecate_option_msg = if version_to_expire
      "The \"#{option}\" option has been deprecated and will be removed in Rubygems #{version_to_expire}."
    else
      "The \"#{option}\" option has been deprecated and will be removed in future versions of Rubygems."
    end

    extra_msg = deprecation["extra_msg"]

    deprecate_option_msg += " #{extra_msg}" if extra_msg

    alert_warning(deprecate_option_msg)
  end
end

defaults_str ()

源代码

# File lib/rubygems/command.rb, line 272
def defaults_str
  ""
end

重写以显示命令选项的默认值。（类似于 arguments，但显示默认值）。

例如

def defaults_str
  --no-gems-first --no-all
end

deprecate_option (name, version: nil, extra_msg: nil)

源代码

# File lib/rubygems/command.rb, line 393
def deprecate_option(name, version: nil, extra_msg: nil)
  @deprecated_options[command].merge!({ name => { "rg_version_to_expire" => version, "extra_msg" => extra_msg } })
end

将命令行选项标记为已弃用，并可选择指定弃用时间。

请注意，在当前的实现中，选项的每个版本都需要显式弃用，因此要弃用定义为的选项

add_option('-t', '--[no-]test', 'Set test mode') do |value, options|
  # ... stuff ...
end

您需要为要弃用的选项的每个版本显式添加对 ‘deprecate_option’ 的调用，例如

deprecate_option('-t')
deprecate_option('--test')
deprecate_option('--no-test')

deprecated? ()

源代码

# File lib/rubygems/command.rb, line 469
def deprecated?
  false
end

description ()

源代码

# File lib/rubygems/command.rb, line 279
def description
  nil
end

重写以显示此命令的作用的更长描述。

execute ()

源代码

# File lib/rubygems/command.rb, line 149
def execute
  raise Gem::Exception, "generic command has no actions"
end

重写以提供命令处理。

options 将填充已解析的选项，未解析的选项将保留在 options[:args] 中。

另请参阅：get_all_gem_names、get_one_gem_name、get_one_optional_argument

get_all_gem_names ()

源代码

# File lib/rubygems/command.rb, line 185
def get_all_gem_names
  args = options[:args]

  if args.nil? || args.empty?
    raise Gem::CommandLineError,
          "Please specify at least one gem name (e.g. gem build GEMNAME)"
  end

  args.reject {|arg| arg.start_with?("-") }
end

从命令行获取所有 gem 名称。

get_all_gem_names_and_versions ()

源代码

# File lib/rubygems/command.rb, line 201
def get_all_gem_names_and_versions
  get_all_gem_names.map do |name|
    extract_gem_name_and_version(name)
  end
end

从命令行获取所有 [gem, version]。

形如 gem:ver 的参数分别分解为 gem 名称和版本。

get_one_gem_name ()

源代码

# File lib/rubygems/command.rb, line 219
def get_one_gem_name
  args = options[:args]

  if args.nil? || args.empty?
    raise Gem::CommandLineError,
          "Please specify a gem name on the command line (e.g. gem build GEMNAME)"
  end

  if args.size > 1
    raise Gem::CommandLineError,
          "Too many gem names (#{args.join(", ")}); please specify only one"
  end

  args.first
end

从命令行获取单个 gem 名称。如果没有 gem 名称，或者给出的 gem 名称多于一个，则失败。

get_one_optional_argument ()

源代码

# File lib/rubygems/command.rb, line 239
def get_one_optional_argument
  args = options[:args] || []
  args.first
end

从命令行获取单个可选参数。如果给出的参数多于一个，则仅返回第一个。如果没有给出任何参数，则返回 nil。

handle_options (args)

源代码

# File lib/rubygems/command.rb, line 440
def handle_options(args)
  args = add_extra_args(args)
  check_deprecated_options(args)
  @options = Marshal.load Marshal.dump @defaults # deep copy
  parser.parse!(args)
  @options[:args] = args
end

通过解析给定的参数列表并记录结果来处理它们。

handles? (args)

源代码

# File lib/rubygems/command.rb, line 429
def handles?(args)
  parser.parse!(args.dup)
  true
rescue StandardError
  false
end

如果命令处理给定的参数列表，则为 True。

invoke (*args)

源代码

# File lib/rubygems/command.rb, line 303
def invoke(*args)
  invoke_with_build_args args, nil
end

使用给定的参数列表调用命令。

invoke_with_build_args (args, build_args)

源代码

# File lib/rubygems/command.rb, line 311
def invoke_with_build_args(args, build_args)
  handle_options args

  options[:build_args] = build_args

  if options[:silent]
    old_ui = ui
    self.ui = ui = Gem::SilentUI.new
  end

  if options[:help]
    show_help
  elsif @when_invoked
    @when_invoked.call options
  else
    execute
  end
ensure
  if ui
    self.ui = old_ui
    ui.close
  end
end

使用给定的常规参数列表和额外的构建参数调用命令。

merge_options (new_options)

源代码

# File lib/rubygems/command.rb, line 421
def merge_options(new_options)
  @options = @defaults.clone
  new_options.each {|k,v| @options[k] = v }
end

将一组命令选项与一组默认选项合并（不修改默认选项哈希）。

remove_option (name)

源代码

# File lib/rubygems/command.rb, line 369
def remove_option(name)
  @option_groups.each do |_, option_list|
    option_list.reject! {|args, _| args.any? {|x| x.is_a?(String) && x =~ /^#{name}/ } }
  end
end

删除先前定义的命令行参数 name。

show_help ()

源代码

# File lib/rubygems/command.rb, line 295
def show_help
  parser.program_name = usage
  say parser
end

显示命令的帮助消息。

show_lookup_failure (gem_name, version, errors, suppress_suggestions = false, required_by = nil)

源代码

# File lib/rubygems/command.rb, line 157
def show_lookup_failure(gem_name, version, errors, suppress_suggestions = false, required_by = nil)
  gem = "'#{gem_name}' (#{version})"
  msg = String.new "Could not find a valid gem #{gem}"

  if errors && !errors.empty?
    msg << ", here is why:\n"
    errors.each {|x| msg << "          #{x.wordy}\n" }
  else
    if required_by && gem != required_by
      msg << " (required by #{required_by}) in any repository"
    else
      msg << " in any repository"
    end
  end

  alert_error msg

  unless suppress_suggestions
    suggestions = Gem::SpecFetcher.fetcher.suggest_gems_from_name(gem_name, :latest, 10)
    unless suggestions.empty?
      alert_error "Possible alternatives: #{suggestions.join(", ")}"
    end
  end
end

向用户显示找不到 gem 以及原因

usage ()

源代码

# File lib/rubygems/command.rb, line 288
def usage
  program_name
end

重写以显示单个 gem 命令的用法。

文本“[options]”会自动附加到用法文本。

when_invoked (&block)

源代码

# File lib/rubygems/command.rb, line 343
def when_invoked(&block)
  @when_invoked = block
end

在调用时调用给定的块。

正常的命令调用只会执行命令的 execute 方法。指定调用块允许测试方法覆盖命令的正常操作，以确定它已被正确调用。

私有实例方法

add_parser_run_info (title, content)

源代码

# File lib/rubygems/command.rb, line 510
def add_parser_run_info(title, content)
  return if content.empty?

  @parser.separator nil
  @parser.separator "  #{title}:"
  content.each_line do |line|
    @parser.separator "    #{line.rstrip}"
  end
end

向解析器帮助视图添加一个带有 title 和 content 的部分。用于添加命令参数和默认参数。

configure_options (header, option_list)

源代码

# File lib/rubygems/command.rb, line 556
def configure_options(header, option_list)
  return if option_list.nil? || option_list.empty?

  header = header.to_s.empty? ? "" : "#{header} "
  @parser.separator "  #{header}Options:"

  option_list.each do |args, handler|
    @parser.on(*args) do |value|
      handler.call(value, @options)
    end
  end

  @parser.separator ""
end

create_option_parser ()

源代码

# File lib/rubygems/command.rb, line 542
def create_option_parser
  @parser = Gem::OptionParser.new

  add_parser_options

  @parser.separator nil
  configure_options "Common", Gem::Command.common_options

  add_parser_run_info "Arguments", arguments
  add_parser_summary
  add_parser_description
  add_parser_run_info "Defaults", defaults_str
end

创建一个选项解析器，并用命令的帮助信息填充它。

option_is_deprecated? (option)

源代码

# File lib/rubygems/command.rb, line 475
def option_is_deprecated?(option)
  @deprecated_options[command].key?(option)
end

parser ()

源代码

# File lib/rubygems/command.rb, line 533
def parser
  create_option_parser if @parser.nil?
  @parser
end

按需创建解析器。

wrap (text, width)

源代码

# File lib/rubygems/command.rb, line 574
def wrap(text, width) # :doc:
  text.gsub(/(.{1,#{width}})( +|$\n?)|(.{1,#{width}})/, "\\1\\3\n")
end

将 text 包装到 width