Base class for all Gem commands. When creating a new gem command, define new, 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

Methods
A
B
C
D
E
G
H
I
M
N
R
S
U
W
Included Modules
Attributes
[R] command

The name of the command.

[RW] defaults

The default options for the command.

[R] options

The options for the command.

[RW] program_name

The name of the command for command-line invocation.

[RW] summary

A short description of the command.

Class Public methods
add_common_option(*args, &handler)
# File lib/rubygems/command.rb, line 61
def self.add_common_option(*args, &handler)
  Gem::Command.common_options << [args, handler]
end
add_specific_extra_args(cmd,args)

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

# File lib/rubygems/command.rb, line 90
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()

Arguments used when building gems

# File lib/rubygems/command.rb, line 49
def self.build_args
  @build_args ||= []
end
build_args=(value)
# File lib/rubygems/command.rb, line 53
def self.build_args=(value)
  @build_args = value
end
common_options()
# File lib/rubygems/command.rb, line 57
def self.common_options
  @common_options ||= []
end
extra_args()
# File lib/rubygems/command.rb, line 65
def self.extra_args
  @extra_args ||= []
end
extra_args=(value)
# File lib/rubygems/command.rb, line 69
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={})

Initializes a generic gem command named command. summaryis a short description displayed in `gem help commands`. defaultsare 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 116
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)

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 82
def self.specific_extra_args(cmd)
  specific_extra_args_hash[cmd]
end
specific_extra_args_hash()

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

# File lib/rubygems/command.rb, line 98
def self.specific_extra_args_hash
  @specific_extra_args_hash ||= Hash.new do |h,k|
    h[k] = Array.new
  end
end
Instance Public methods
add_extra_args(args)

Adds extra args from ~/.gemrc

# File lib/rubygems/command.rb, line 355
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)

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

See OptionParser#make_switch for an explanation of opts.

handlerwill 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 305
def add_option(*opts, &handler) # :yields: value, options
  group_name = Symbol === opts.first ? opts.shift : :options

  @option_groups[group_name] << [opts, handler]
end
arguments()

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 225
def arguments
  ""
end
begins?(long, short)

True if longbegins with the characters from short.

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

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 239
def defaults_str
  ""
end
description()

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

# File lib/rubygems/command.rb, line 246
def description
  nil
end
execute()

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 144
def execute
  raise Gem::Exception, "generic command has no actions"
end
get_all_gem_names()

Get all gem names from the command line.

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

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

  args.select { |arg| arg !~ /^-/ }
end
get_one_gem_name()

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 186
def get_one_gem_name
  args = options[:args]

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

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

  args.first
end
get_one_optional_argument()

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 206
def get_one_optional_argument
  args = options[:args] || []
  args.first
end
handle_options(args)

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

# File lib/rubygems/command.rb, line 345
def handle_options(args)
  args = add_extra_args(args)
  @options = @defaults.clone
  parser.parse!(args)
  @options[:args] = args
end
handles?(args)

True if the command handles the given argument list.

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

Invoke the command with the given list of arguments.

# File lib/rubygems/command.rb, line 270
def invoke(*args)
  handle_options args

  if options[:help] then
    show_help
  elsif @when_invoked then
    @when_invoked.call options
  else
    execute
  end
end
merge_options(new_options)

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

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

Remove previously defined command-line argument name.

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

Display the help message for the command.

# File lib/rubygems/command.rb, line 262
def show_help
  parser.program_name = usage
  say parser
end
show_lookup_failure(gem_name, version, errors, domain)

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

# File lib/rubygems/command.rb, line 151
def show_lookup_failure(gem_name, version, errors, domain)
  if errors and !errors.empty?
    alert_error "Could not find a valid gem '#{gem_name}' (#{version}), here is why:"
    errors.each { |x| say "          #{x.wordy}" }
  else
    alert_error "Could not find a valid gem '#{gem_name}' (#{version}) in any repository"
  end

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

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

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 255
def usage
  program_name
end
when_invoked(&block)

Call the given block when invoked.

Normal command invocations just executes the executemethod 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 290
def when_invoked(&block)
  @when_invoked = block
end
Instance Private methods
wrap(text, width)

Wraps textto width

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