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

Source: show | on GitHub 

# File ../ruby/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. args may be an array or a string to be split on white space.

Source: show | on GitHub 

# File ../ruby/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

Source: show | on GitHub 

# File ../ruby/lib/rubygems/command.rb, line 49
def self.build_args
  @build_args ||= []
end
build_args=(value)

Source: show | on GitHub 

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

Source: show | on GitHub 

# File ../ruby/lib/rubygems/command.rb, line 57
def self.common_options
  @common_options ||= []
end
extra_args()

Source: show | on GitHub 

# File ../ruby/lib/rubygems/command.rb, line 65
def self.extra_args
  @extra_args ||= []
end
extra_args=(value)

Source: show | on GitHub 

# File ../ruby/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. 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].

Source: show | on GitHub 

# File ../ruby/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.

Source: show | on GitHub 

# File ../ruby/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).

Source: show | on GitHub 

# File ../ruby/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

Source: show | on GitHub 

# File ../ruby/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.

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.

Source: show | on GitHub 

# File ../ruby/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

Source: show | on GitHub 

# File ../ruby/lib/rubygems/command.rb, line 225
def arguments
  ""
end
begins?(long, short)

True if long begins with the characters from short.

Source: show | on GitHub 

# File ../ruby/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

Source: show | on GitHub 

# File ../ruby/lib/rubygems/command.rb, line 239
def defaults_str
  ""
end
description()

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

Source: show | on GitHub 

# File ../ruby/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

Source: show | on GitHub 

# File ../ruby/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.

Source: show | on GitHub 

# File ../ruby/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.

Source: show | on GitHub 

# File ../ruby/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.

Source: show | on GitHub 

# File ../ruby/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.

Source: show | on GitHub 

# File ../ruby/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.

Source: show | on GitHub 

# File ../ruby/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.

Source: show | on GitHub 

# File ../ruby/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).

Source: show | on GitHub 

# File ../ruby/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.

Source: show | on GitHub 

# File ../ruby/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.

Source: show | on GitHub 

# File ../ruby/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

Source: show | on GitHub 

# File ../ruby/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.

Source: show | on GitHub 

# File ../ruby/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 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.

Source: show | on GitHub 

# File ../ruby/lib/rubygems/command.rb, line 290
def when_invoked(&block)
  @when_invoked = block
end
Instance Private methods
configure_options(header, option_list)

Source: show | on GitHub 

# File ../ruby/lib/rubygems/command.rb, line 436
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|
    args.select { |arg| arg =~ /^-/ }
    @parser.on(*args) do |value|
      handler.call(value, @options)
    end
  end

  @parser.separator ''
end
create_option_parser()

Source: show | on GitHub 

# File ../ruby/lib/rubygems/command.rb, line 383
def create_option_parser
  @parser = OptionParser.new

  @parser.separator nil
  regular_options = @option_groups.delete :options

  configure_options "", regular_options

  @option_groups.sort_by { |n,_| n.to_s }.each do |group_name, option_list|
    @parser.separator nil
    configure_options group_name, option_list
  end

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

  unless arguments.empty?
    @parser.separator nil
    @parser.separator "  Arguments:"
    arguments.split(/\n/).each do |arg_desc|
      @parser.separator "    #{arg_desc}"
    end
  end

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

  if description then
    formatted = description.split("\n\n").map do |chunk|
      wrap chunk, 80 - 4
    end.join "\n"

    @parser.separator nil
    @parser.separator "  Description:"
    formatted.split("\n").each do |line|
      @parser.separator "    #{line.rstrip}"
    end
  end

  unless defaults_str.empty?
    @parser.separator nil
    @parser.separator "  Defaults:"
    defaults_str.split(/\n/).each do |line|
      @parser.separator "    #{line}"
    end
  end
end
parser()

Create on demand parser.

Source: show | on GitHub 

# File ../ruby/lib/rubygems/command.rb, line 378
def parser
  create_option_parser if @parser.nil?
  @parser
end
wrap(text, width)

Wraps text to width

Source: show | on GitHub 

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