123456789_123456789_123456789_123456789_123456789_

Class: Gem::Command

Overview

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 Commands::ContentsCommand

Class Attribute Summary

Class Method Summary

Instance Attribute Summary

  • #defaults rw

    The default options for the command.

  • #program_name rw

    The name of the command for command-line invocation.

  • #summary rw

    A short description of the command.

  • #command readonly

    The name of the command.

  • #options readonly

    The options for the command.

DefaultUserInteraction - Included

#ui

See DefaultUserInteraction.ui
#ui=

See DefaultUserInteraction.ui=

Instance Method Summary

UserInteraction - Included

#alert

Displays an alert statement.
#alert_error

Displays an error statement to the error output location.
#alert_warning

Displays a warning statement to the warning output location.
#ask

Asks a question and returns the answer.
#ask_for_password

Asks for a password with a prompt
#ask_yes_no

Asks a yes or no question.
#choose_from_list

Asks the user to answer question with an answer from the given list.
#say

Displays the given statement on the standard output (or equivalent).
#terminate_interaction

Terminates the RubyGems process with the given exit_code
#verbose

Calls say with msg or the results of the block if really_verbose is true.

DefaultUserInteraction - Included

#use_ui

See DefaultUserInteraction.use_ui

Constructor Details

.new(command, summary = nil, defaults = {}) ⇒ Command

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

[ GitHub ] 

  


# 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


  







Class Attribute Details



  

    .build_args   (rw)
  



  

    

Arguments used when building gems


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 51



def self.build_args
  @build_args ||= []
end


  








  

    .build_args=(value)   (rw)
  

  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 55



def self.build_args=(value)
  @build_args = value
end


  








  

    .extra_args   (rw)
  

  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 67



def self.extra_args
  @extra_args ||= []
end


  








  

    .extra_args=(value)   (rw)
  

  [ GitHub ]


  

  


# 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


  







Class Method Details



  

    .add_common_option(*args, &handler)  
  

  [ GitHub ]


  

  


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



  

    

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


  



  [ GitHub ]


  

  


# 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


  








  

    .common_options  
  

  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 59



def self.common_options
  @common_options ||= []
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.


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 84



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


  



  [ GitHub ]


  

  


# 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


  







Instance Attribute Details



  

    #command   (readonly)
  



  

    

The name of the command.


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 26



attr_reader :command


  








  

    #defaults   (rw)
  



  

    

The default options for the command.


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 36



attr_accessor :defaults


  








  

    #options   (readonly)
  



  

    

The options for the command.


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 31



attr_reader :options


  








  

    #program_name   (rw)
  



  

    

The name of the command for command-line invocation.


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 41



attr_accessor :program_name


  








  

    #summary   (rw)
  



  

    

A short description of the command.


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 46



attr_accessor :summary


  







Instance Method Details



  

    #add_extra_args(args)  
  



  

    

Adds extra args from ~/.gemrc


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 385



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, &handler)  
  



  

    

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.


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 335



def add_option(*opts, &handler) # :yields: value, options
  group_name = Symbol === opts.first ? opts.shift : :options

  @option_groups[group_name] << [opts, handler]
end


  








  

    #add_parser_run_info(title, content)   (private)
  



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 436



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


  








  

    #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


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 245



def arguments
  ""
end


  








  

    #begins?(long, short)  ⇒ Boolean 
  



  

    

True if long begins with the characters from short.


  





  


  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 132



def begins?(long, short)
  return false if short.nil?
  long[0, short.length] == short
end


  








  

    #configure_options(header, option_list)   (private)
  

  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 482



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



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 468



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


  








  

    #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


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 259



def defaults_str
  ""
end


  








  

    #description  
  



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 266



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


  





  
Raises:





  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 146



def execute
  raise Gem::Exception, "generic command has no actions"
end


  








  

    #get_all_gem_names  
  



  

    

Get all gem names from the command line.


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 176



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_all_gem_names_and_versions  
  



  

    

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.


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 192



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  
  



  

    

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.


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 206



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.


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 226



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.


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 375



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)  ⇒ Boolean 
  



  

    

True if the command handles the given argument list.


  





  


  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 362



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.


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 290



def invoke(*args)
  invoke_with_build_args args, nil
end


  








  

    #invoke_with_build_args(args, build_args)  
  



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 298



def invoke_with_build_args(args, build_args)
  handle_options args

  options[:build_args] = build_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).


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 354



def merge_options(new_options)
  @options = @defaults.clone
  new_options.each do |k,v| @options[k] = v end
end


  








  

    #parser   (private)
  



  

    

Create on demand parser.


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 459



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


  








  

    #remove_option(name)  
  



  

    

Remove previously defined command-line argument name.


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 344



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.


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 282



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


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 155



def show_lookup_failure(gem_name, version, errors, domain)
  if errors and !errors.empty?
    msg = "Could not find a valid gem '#{gem_name}' (#{version}), here is why:\n".dup
    errors.each { |x| msg << "          #{x.wordy}\n" }
    alert_error msg
  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.


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 275



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.


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 320



def when_invoked(&block)
  @when_invoked = block
end


  








  

    #wrap(text, width)   (private)
  



  

    

Wraps text to width


  



  [ GitHub ]


  

  


# File 'lib/rubygems/command.rb', line 501



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