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) click to toggle source
# File lib/rubygems/command.rb, line 63
def self.add_common_option(*args, &handler)
  Gem::Command.common_options << [args, handler]
end
add_specific_extra_args(cmd,args) click to toggle source

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

# File lib/rubygems/command.rb, line 92
def self.add_specific_extra_args(cmd,args)
  args = args.split(/\s+/) if args.kind_of? String
  specific_extra_args_hash[cmd] = args
end
build_args() click to toggle source

Arguments used when building gems

# File lib/rubygems/command.rb, line 51
def self.build_args
  @build_args ||= []
end
build_args=(value) click to toggle source
# File lib/rubygems/command.rb, line 55
def self.build_args=(value)
  @build_args = value
end
common_options() click to toggle source
# File lib/rubygems/command.rb, line 59
def self.common_options
  @common_options ||= []
end
extra_args() click to toggle source
# File lib/rubygems/command.rb, line 67
def self.extra_args
  @extra_args ||= []
end
extra_args=(value) click to toggle source
# File lib/rubygems/command.rb, line 71
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={}) click to toggle source

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

# File lib/rubygems/command.rb, line 118
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] = [] }
  @parser = nil
  @when_invoked = nil
end
specific_extra_args(cmd) click to toggle source

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

# File lib/rubygems/command.rb, line 84
def self.specific_extra_args(cmd)
  specific_extra_args_hash[cmd]
end
specific_extra_args_hash() click to toggle source

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

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

Public Instance Methods

add_extra_args(args) click to toggle source

Adds extra args from ~/.gemrc

# File lib/rubygems/command.rb, line 403
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 extra.first.to_s =~ /^[^-]/
    result << ex if handles?(ex)
  end

  result.flatten!
  result.concat(args)
  result
end
add_option(*opts) { |value, options| ... } click to toggle source

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

See 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.

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

  @option_groups[group_name] << [opts, handler]
end
arguments() click to toggle source

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
# File lib/rubygems/command.rb, line 253
def arguments
  ""
end
begins?(long, short) click to toggle source

True if long begins with the characters from short.

# File lib/rubygems/command.rb, line 132
def begins?(long, short)
  return false if short.nil?
  long[0, short.length] == short
end
defaults_str() click to toggle source

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
# File lib/rubygems/command.rb, line 267
def defaults_str
  ""
end
description() click to toggle source

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

# File lib/rubygems/command.rb, line 274
def description
  nil
end
execute() click to toggle source

Override to provide command handling.

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

See also: get_all_gem_names, get_one_gem_name, get_one_optional_argument

# File lib/rubygems/command.rb, line 146
def execute
  raise Gem::Exception, "generic command has no actions"
end
get_all_gem_names() click to toggle source

Get all gem names from the command line.

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

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

  args.select { |arg| arg !~ /^-/ }
end
get_all_gem_names_and_versions() click to toggle source

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.

# File lib/rubygems/command.rb, line 200
def get_all_gem_names_and_versions
  get_all_gem_names.map do |name|
    if /\A(.*):(#{Gem::Requirement::PATTERN_RAW})\z/ =~ name
      [$1, $2]
    else
      [name]
    end
  end
end
get_one_gem_name() click to toggle source

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.

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

  if args.nil? or 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_one_optional_argument() click to toggle source

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.

# File lib/rubygems/command.rb, line 234
def get_one_optional_argument
  args = options[:args] || []
  args.first
end
handle_options(args) click to toggle source

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

# File lib/rubygems/command.rb, line 393
def handle_options(args)
  args = add_extra_args(args)
  @options = Marshal.load Marshal.dump @defaults # deep copy
  parser.parse!(args)
  @options[:args] = args
end
handles?(args) click to toggle source

True if the command handles the given argument list.

# File lib/rubygems/command.rb, line 380
def handles?(args)
  begin
    parser.parse!(args.dup)
    return true
  rescue
    return false
  end
end
invoke(*args) click to toggle source

Invoke the command with the given list of arguments.

# File lib/rubygems/command.rb, line 298
def invoke(*args)
  invoke_with_build_args args, nil
end
invoke_with_build_args(args, build_args) click to toggle source

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

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

  options[:build_args] = build_args

  if options[:silent]
    old_ui = self.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) click to toggle source

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

# File lib/rubygems/command.rb, line 372
def merge_options(new_options)
  @options = @defaults.clone
  new_options.each do |k,v| @options[k] = v end
end
remove_option(name) click to toggle source

Remove previously defined command-line argument name.

# File lib/rubygems/command.rb, line 362
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
show_help() click to toggle source

Display the help message for the command.

# File lib/rubygems/command.rb, line 290
def show_help
  parser.program_name = usage
  say parser
end
show_lookup_failure(gem_name, version, errors, domain, required_by = nil) click to toggle source

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

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

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

  alert_error msg

  unless domain == :local  # HACK
    suggestions = Gem::SpecFetcher.fetcher.suggest_gems_from_name gem_name

    unless suggestions.empty?
      alert_error "Possible alternatives: #{suggestions.join(", ")}"
    end
  end
end
usage() click to toggle source

Override to display the usage for an individual gem command.

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

# File lib/rubygems/command.rb, line 283
def usage
  program_name
end
when_invoked(&block) click to toggle source

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.

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

Private Instance Methods

add_parser_run_info(title, content) click to toggle source

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

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

    @parser.separator nil
    @parser.separator "  #{title}:"
    content.split(/\n/).each do |line|
      @parser.separator "    #{line}"
    end
  end

  def add_parser_summary # :nodoc:
    return unless @summary

    @parser.separator nil
    @parser.separator "  Summary:"
    wrap(@summary, 80 - 4).split("\n").each do |line|
      @parser.separator "    #{line.strip}"
    end
  end

  ##
  # Create on demand parser.

  def parser
    create_option_parser if @parser.nil?
    @parser
  end

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

  def create_option_parser
    @parser = 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

  def configure_options(header, option_list)
    return if option_list.nil? or 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

  ##
  # Wraps +text+ to +width+

  def wrap(text, width) # :doc:
    text.gsub(/(.{1,#{width}})( +|$\n?)|(.{1,#{width}})/, "\\1\\3\n")
  end

  # ----------------------------------------------------------------
  # Add the options common to all commands.

  add_common_option('-h', '--help',
                    'Get help on this command') do |value, options|
    options[:help] = true
  end

  add_common_option('-V', '--[no-]verbose',
                    'Set the verbose level of output') do |value, options|
    # Set us to "really verbose" so the progress meter works
    if Gem.configuration.verbose and value
      Gem.configuration.verbose = 1
    else
      Gem.configuration.verbose = value
    end
  end

  add_common_option('-q', '--quiet', 'Silence command progress meter') do |value, options|
    Gem.configuration.verbose = false
  end

  add_common_option("--silent",
                    "Silence RubyGems output") do |value, options|
    options[:silent] = true
  end

  # Backtrace and config-file are added so they show up in the help
  # commands.  Both options are actually handled before the other
  # options get parsed.

  add_common_option('--config-file FILE',
                    'Use this config file instead of default') do
  end

  add_common_option('--backtrace',
                    'Show stack backtrace on errors') do
  end

  add_common_option('--debug',
                    'Turn on Ruby debugging') do
  end

  add_common_option('--norc',
                    'Avoid loading any .gemrc file') do
  end


  # :stopdoc:

  HELP = <<-HELP.freeze
RubyGems is a sophisticated package manager for Ruby.  This is a
basic help message containing pointers to more information.

  Usage:
    gem -h/--help
    gem -v/--version
    gem command [arguments...] [options...]

  Examples:
    gem install rake
    gem list --local
    gem build package.gemspec
    gem help install

  Further help:
    gem help commands            list all 'gem' commands
    gem help examples            show some examples of usage
    gem help gem_dependencies    gem dependencies file guide
    gem help platforms           gem platforms guide
    gem help <COMMAND>           show help on COMMAND
                                   (e.g. 'gem help install')
    gem server                   present a web page at
                                 http://localhost:8808/
                                 with info about installed gems
  Further information:
    http://guides.rubygems.org
  HELP

  # :startdoc:

end

##
# \Commands will be placed in this namespace

module Gem
configure_options(header, option_list) click to toggle source
# File lib/rubygems/command.rb, line 500
  def configure_options(header, option_list)
    return if option_list.nil? or 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

  ##
  # Wraps +text+ to +width+

  def wrap(text, width) # :doc:
    text.gsub(/(.{1,#{width}})( +|$\n?)|(.{1,#{width}})/, "\\1\\3\n")
  end

  # ----------------------------------------------------------------
  # Add the options common to all commands.

  add_common_option('-h', '--help',
                    'Get help on this command') do |value, options|
    options[:help] = true
  end

  add_common_option('-V', '--[no-]verbose',
                    'Set the verbose level of output') do |value, options|
    # Set us to "really verbose" so the progress meter works
    if Gem.configuration.verbose and value
      Gem.configuration.verbose = 1
    else
      Gem.configuration.verbose = value
    end
  end

  add_common_option('-q', '--quiet', 'Silence command progress meter') do |value, options|
    Gem.configuration.verbose = false
  end

  add_common_option("--silent",
                    "Silence RubyGems output") do |value, options|
    options[:silent] = true
  end

  # Backtrace and config-file are added so they show up in the help
  # commands.  Both options are actually handled before the other
  # options get parsed.

  add_common_option('--config-file FILE',
                    'Use this config file instead of default') do
  end

  add_common_option('--backtrace',
                    'Show stack backtrace on errors') do
  end

  add_common_option('--debug',
                    'Turn on Ruby debugging') do
  end

  add_common_option('--norc',
                    'Avoid loading any .gemrc file') do
  end


  # :stopdoc:

  HELP = <<-HELP.freeze
RubyGems is a sophisticated package manager for Ruby.  This is a
basic help message containing pointers to more information.

  Usage:
    gem -h/--help
    gem -v/--version
    gem command [arguments...] [options...]

  Examples:
    gem install rake
    gem list --local
    gem build package.gemspec
    gem help install

  Further help:
    gem help commands            list all 'gem' commands
    gem help examples            show some examples of usage
    gem help gem_dependencies    gem dependencies file guide
    gem help platforms           gem platforms guide
    gem help <COMMAND>           show help on COMMAND
                                   (e.g. 'gem help install')
    gem server                   present a web page at
                                 http://localhost:8808/
                                 with info about installed gems
  Further information:
    http://guides.rubygems.org
  HELP

  # :startdoc:

end
create_option_parser() click to toggle source

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

# File lib/rubygems/command.rb, line 486
def create_option_parser
  @parser = 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
parser() click to toggle source

Create on demand parser.

# File lib/rubygems/command.rb, line 477
def parser
  create_option_parser if @parser.nil?
  @parser
end
wrap(text, width) click to toggle source

Wraps text to width

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