class Gem::Command

Base class for all Gem commands. When creating a new gem command, define initialize, execute, arguments, defaults_str, description and usage (as appropriate). See the above mentioned methods for details.

A very good example to look at is Gem::Commands::ContentsCommand

Attributes

command [R]

The name of the command.

defaults [RW]

The default options for the command.

options [R]

The options for the command.

program_name [RW]

The name of the command for command-line invocation.

summary [RW]

A short description of the command.

Public Class Methods

add_common_option (*args, &handler)

Source

# 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)

Source

# 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

Add a list of extra arguments for the given command. args may be an array or a string to be split on white space.

build_args ()

Source

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

Arguments used when building gems

build_args= (value)

Source

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

common_options ()

Source

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

extra_args ()

Source

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

extra_args= (value)

Source

# 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={})

Source

# 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

Initializes a generic gem command named command. summary is a short description displayed in ‘gem help commands`. defaults are the default options. Defaults should be mirrored in defaults_str, unless there are none.

When defining a new command subclass, use add_option to add command-line switches.

Unhandled arguments (gem names, files, etc.) are left in options[:args].

specific_extra_args (cmd)

Source

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

Return an array of extra arguments for the command. The extra arguments come from the gem configuration file read at program startup.

specific_extra_args_hash ()

Source

# 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

Accessor for the specific extra args hash (self initializing).

Public Instance Methods

add_extra_args (args)

Source

# 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

Adds extra args from ~/.gemrc

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

Source

# 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

Add a command-line option and handler to the command.

See Gem::OptionParser#make_switch for an explanation of opts.

handler will be called with two values, the value of the argument and the options hash.

If the first argument of add_option is a Symbol, it’s used to group options in output. See ‘gem help list` for an example.

arguments ()

Source

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

Override to provide details of the arguments a command takes. It should return a left-justified string, one argument per line.

For example:

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

def arguments
  "FILE          name of file to find"
end

begins? (long, short)

Source

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

True if long begins with the characters from short.

check_deprecated_options (options)

Source

# 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 ()

Source

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

Override to display the default values of the command options. (similar to arguments, but displays the default values).

For example:

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

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

Source

# 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

Mark a command-line option as deprecated, and optionally specify a deprecation horizon.

Note that with the current implementation, every version of the option needs to be explicitly deprecated, so to deprecate an option defined as

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

you would need to explicitly add a call to ‘deprecate_option` for every version of the option you want to deprecate, like

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

deprecated? ()

Source

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

description ()

Source

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

Override to display a longer description of what this command does.

execute ()

Source

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

Override to provide command handling.

options will be filled in with your parsed options, unparsed options will be left in options[:args].

get_all_gem_names ()

Source

# 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

Get all gem names from the command line.

get_all_gem_names_and_versions ()

Source

# 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

Get all [gem, version] from the command line.

An argument in the form gem:ver is pull apart into the gen name and version, respectively.

get_one_gem_name ()

Source

# 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

Get a single gem name from the command line. Fail if there is no gem name or if there is more than one gem name given.

get_one_optional_argument ()

Source

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

Get a single optional argument from the command line. If more than one argument is given, return only the first. Return nil if none are given.

handle_options (args)

Source

# 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

Handle the given list of arguments by parsing them and recording the results.

handles? (args)

Source

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

True if the command handles the given argument list.

invoke (*args)

Source

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

Invoke the command with the given list of arguments.

invoke_with_build_args (args, build_args)

Source

# 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

Invoke the command with the given list of normal arguments and additional build arguments.

merge_options (new_options)

Source

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

Merge a set of command options with the set of default options (without modifying the default option hash).

remove_option (name)

Source

# 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

Remove previously defined command-line argument name.

show_help ()

Source

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

Display the help message for the command.

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

Source

# 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

Display to the user that a gem couldn’t be found and reasons why

usage ()

Source

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

Override to display the usage for an individual gem command.

The text “[options]” is automatically appended to the usage text.

when_invoked (&block)

Source

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

Call the given block when invoked.

Normal command invocations just executes the execute method of the command. Specifying an invocation block allows the test methods to override the normal action of a command to determine that it has been invoked correctly.

Private Instance Methods

add_parser_run_info (title, content)

Source

# 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

Adds a section with title and content to the parser help view. Used for adding command arguments and default arguments.

configure_options (header, option_list)

Source

# 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 ()

Source

# 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

Creates an option parser and fills it in with the help info for the command.

option_is_deprecated? (option)

Source

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

parser ()

Source

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

Create on demand parser.

wrap (text, width)

Source

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

Wraps text to width