In Files

  • rubygems/command.rb
  • rubygems/command_manager.rb
  • rubygems/commands/help_command.rb

Class/Module Index [+]

Quicksearch

Gem::Command

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

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 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) 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 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() click to toggle source

Arguments used when building gems

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

Public Instance Methods

add_extra_args(args) click to toggle source

Adds extra args from ~/.gemrc

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

True if long begins with the characters from short.

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

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

 
               # File rubygems/command.rb, line 238
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 rubygems/command.rb, line 144
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 rubygems/command.rb, line 163
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

  gem_names = args.select { |arg| arg !~ /^-/ }
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 rubygems/command.rb, line 178
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() 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 rubygems/command.rb, line 198
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 rubygems/command.rb, line 337
def handle_options(args)
  args = add_extra_args(args)
  @options = @defaults.clone
  parser.parse!(args)
  @options[:args] = args
end
            
handles?(args) click to toggle source

True if the command handles the given argument list.

 
               # File rubygems/command.rb, line 324
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 rubygems/command.rb, line 262
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) click to toggle source

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

 
               # File rubygems/command.rb, line 316
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 rubygems/command.rb, line 306
def remove_option(name)
  @option_groups.each do |_, option_list|
    option_list.reject! { |args, _| args.any? { |x| x =~ /^#{name}/ } }
  end
end
            
show_help() click to toggle source

Display the help message for the command.

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

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

 
               # File rubygems/command.rb, line 151
def show_lookup_failure(gem_name, version, errors=nil)
  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
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 rubygems/command.rb, line 247
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 rubygems/command.rb, line 282
def when_invoked(&block)
  @when_invoked = block
end
            

Private Instance Methods

wrap(text, width) click to toggle source

Wraps text to width

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

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.

blog comments powered by Disqus