Class: Gem::Command

Inherits:
Object
  • Object
show all
Includes:
UserInteraction
Defined in:
lib/rubygems/command.rb

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from UserInteraction

#alert, #alert_error, #alert_warning, #ask, #ask_for_password, #ask_yes_no, #choose_from_list, #say, #terminate_interaction, #verbose

Methods included from DefaultUserInteraction

ui, #ui, ui=, #ui=, use_ui, #use_ui

Methods included from Text

#clean_text, #format_text, #levenshtein_distance, #min3, #truncate_text

Constructor Details

#initialize(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].



120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/rubygems/command.rb', line 120

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] = [] }
  @deprecated_options = { command => {} }
  @parser = nil
  @when_invoked = nil
end

Instance Attribute Details

#command ⇒ Object (readonly)

The name of the command.



28
29
30
 
# File 'lib/rubygems/command.rb', line 28

def command
  @command
end

#defaults ⇒ Object

The default options for the command.



38
39
40
 
# File 'lib/rubygems/command.rb', line 38

def defaults
  @defaults
end

#options ⇒ Object (readonly)

The options for the command.



33
34
35
 
# File 'lib/rubygems/command.rb', line 33

def options
  @options
end

#program_name ⇒ Object

The name of the command for command-line invocation.



43
44
45
 
# File 'lib/rubygems/command.rb', line 43

def program_name
  @program_name
end

#summary ⇒ Object

A short description of the command.



48
49
50
 
# File 'lib/rubygems/command.rb', line 48

def summary
  @summary
end

Class Method Details

.add_common_option(*args, &handler) ⇒ Object 



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

def self.add_common_option(*args, &handler)
  Gem::Command.common_options << [args, handler]
end

.add_specific_extra_args(cmd, args) ⇒ Object

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



94
95
96
97
 
# File 'lib/rubygems/command.rb', line 94

def self.add_specific_extra_args(cmd,args)
  args = args.split(/\s+/) if args.is_a? String
  specific_extra_args_hash[cmd] = args
end

.build_args ⇒ Object

Arguments used when building gems



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

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

.build_args=(value) ⇒ Object 



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

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

.common_options ⇒ Object 



61
62
63
 
# File 'lib/rubygems/command.rb', line 61

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

.extra_args ⇒ Object 



69
70
71
 
# File 'lib/rubygems/command.rb', line 69

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

.extra_args=(value) ⇒ Object 



73
74
75
76
77
78
79
80
 
# File 'lib/rubygems/command.rb', line 73

def self.extra_args=(value)
  case value
  when Array
    @extra_args = value
  when String
    @extra_args = value.split(" ")
  end
end

.specific_extra_args(cmd) ⇒ Object

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



86
87
88
 
# File 'lib/rubygems/command.rb', line 86

def self.specific_extra_args(cmd)
  specific_extra_args_hash[cmd]
end

.specific_extra_args_hash ⇒ Object

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



102
103
104
105
106
 
# File 'lib/rubygems/command.rb', line 102

def self.specific_extra_args_hash
  @specific_extra_args_hash ||= Hash.new do |h,k|
    h[k] = Array.new
  end
end

Instance Method Details

#add_extra_args(args) ⇒ Object

Adds extra args from ~/.gemrc



451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
 
# File 'lib/rubygems/command.rb', line 451

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 /^[^-]/.match?(extra.first.to_s)
    result << ex if handles?(ex)
  end

  result.flatten!
  result.concat(args)
  result
end

#add_option(*opts, &handler) ⇒ Object

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

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



358
359
360
361
362
363
364
 
# File 'lib/rubygems/command.rb', line 358

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

  raise "Do not pass an empty string in opts" if opts.include?("")

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

#arguments ⇒ Object

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



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

def arguments
  ""
end

#begins?(long, short) ⇒ Boolean

True if long begins with the characters from short.

Returns:

  • (Boolean) 


135
136
137
138
 
# File 'lib/rubygems/command.rb', line 135

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

#check_deprecated_options(options) ⇒ Object 



397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
 
# File 'lib/rubygems/command.rb', line 397

def check_deprecated_options(options)
  options.each do |option|
    next unless option_is_deprecated?(option)
    deprecation = @deprecated_options[command][option]
    version_to_expire = deprecation["rg_version_to_expire"]

    deprecate_option_msg = if version_to_expire
      "The \"#{option}\" option has been deprecated and will be removed in Rubygems #{version_to_expire}."
    else
      "The \"#{option}\" option has been deprecated and will be removed in future versions of Rubygems."
    end

    extra_msg = deprecation["extra_msg"]

    deprecate_option_msg += " #{extra_msg}" if extra_msg

    alert_warning(deprecate_option_msg)
  end
end

#defaults_str ⇒ Object

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



272
273
274
 
# File 'lib/rubygems/command.rb', line 272

def defaults_str
  ""
end

#deprecate_option(name, version: nil, extra_msg: nil) ⇒ Object

Mark a command-line option as deprecated, and optionally specify a deprecation horizon.

Note that with the current implementation, every version of the option needs to be explicitly deprecated, so to deprecate an option defined as

add_option('-t', '--[no-]test', 'Set test mode') do |value, options|
  # ... stuff ...
end

you would need to explicitly add a call to ‘deprecate_option` for every version of the option you want to deprecate, like

deprecate_option('-t')
deprecate_option('--test')
deprecate_option('--no-test')



393
394
395
 
# File 'lib/rubygems/command.rb', line 393

def deprecate_option(name, version: nil, extra_msg: nil)
  @deprecated_options[command].merge!({ name => { "rg_version_to_expire" => version, "extra_msg" => extra_msg } })
end

#deprecated? ⇒ Boolean

Returns:

  • (Boolean) 


469
470
471
 
# File 'lib/rubygems/command.rb', line 469

def deprecated?
  false
end

#description ⇒ Object

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



279
280
281
 
# File 'lib/rubygems/command.rb', line 279

def description
  nil
end

#execute ⇒ Object

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:



149
150
151
 
# File 'lib/rubygems/command.rb', line 149

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

#extract_gem_name_and_version(name) ⇒ Object

:nodoc:



207
208
209
210
211
212
213
 
# File 'lib/rubygems/command.rb', line 207

def extract_gem_name_and_version(name) # :nodoc:
  if /\A(.*):(#{Gem::Requirement::PATTERN_RAW})\z/ =~ name
    [$1, $2]
  else
    [name]
  end
end

#get_all_gem_names ⇒ Object

Get all gem names from the command line.



185
186
187
188
189
190
191
192
193
194
 
# File 'lib/rubygems/command.rb', line 185

def get_all_gem_names
  args = options[:args]

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

  args.reject {|arg| arg.start_with?("-") }
end

#get_all_gem_names_and_versions ⇒ Object

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.



201
202
203
204
205
 
# File 'lib/rubygems/command.rb', line 201

def get_all_gem_names_and_versions
  get_all_gem_names.map do |name|
    extract_gem_name_and_version(name)
  end
end

#get_one_gem_name ⇒ Object

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.



219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
 
# File 'lib/rubygems/command.rb', line 219

def get_one_gem_name
  args = options[:args]

  if args.nil? || 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 ⇒ Object

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.



239
240
241
242
 
# File 'lib/rubygems/command.rb', line 239

def get_one_optional_argument
  args = options[:args] || []
  args.first
end

#handle_options(args) ⇒ Object

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



440
441
442
443
444
445
446
 
# File 'lib/rubygems/command.rb', line 440

def handle_options(args)
  args = add_extra_args(args)
  check_deprecated_options(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.

Returns:

  • (Boolean) 


429
430
431
432
433
434
 
# File 'lib/rubygems/command.rb', line 429

def handles?(args)
  parser.parse!(args.dup)
  true
rescue StandardError
  false
end

#invoke(*args) ⇒ Object

Invoke the command with the given list of arguments.



303
304
305
 
# File 'lib/rubygems/command.rb', line 303

def invoke(*args)
  invoke_with_build_args args, nil
end

#invoke_with_build_args(args, build_args) ⇒ Object

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



311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
 
# File 'lib/rubygems/command.rb', line 311

def invoke_with_build_args(args, build_args)
  handle_options args

  options[:build_args] = build_args

  if options[:silent]
    old_ui = 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) ⇒ Object

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



421
422
423
424
 
# File 'lib/rubygems/command.rb', line 421

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

#remove_option(name) ⇒ Object

Remove previously defined command-line argument name.



369
370
371
372
373
 
# File 'lib/rubygems/command.rb', line 369

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 ⇒ Object

Display the help message for the command.



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

def show_help
  parser.program_name = usage
  say parser
end

#show_lookup_failure(gem_name, version, errors, suppress_suggestions = false, required_by = nil) ⇒ Object

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



157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
 
# File 'lib/rubygems/command.rb', line 157

def show_lookup_failure(gem_name, version, errors, suppress_suggestions = false, required_by = nil)
  gem = "'#{gem_name}' (#{version})"
  msg = String.new "Could not find a valid gem #{gem}"

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

  alert_error msg

  unless suppress_suggestions
    suggestions = Gem::SpecFetcher.fetcher.suggest_gems_from_name(gem_name, :latest, 10)
    unless suggestions.empty?
      alert_error "Possible alternatives: #{suggestions.join(", ")}"
    end
  end
end

#usage ⇒ Object

Override to display the usage for an individual gem command.

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



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

def usage
  program_name
end

#when_invoked(&block) ⇒ Object

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.



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

def when_invoked(&block)
  @when_invoked = block
end