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

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

Methods included from DefaultUserInteraction

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

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



116
117
118
119
120
121
122
123
124
125
 
# 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

Instance Attribute Details

#command ⇒ Object (readonly)

The name of the command.



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

def command
  @command
end

#defaults ⇒ Object

The default options for the command.



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

def defaults
  @defaults
end

#options ⇒ Object (readonly)

The options for the command.



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

def options
  @options
end

#program_name ⇒ Object

The name of the command for command-line invocation.



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

def program_name
  @program_name
end

#summary ⇒ Object

A short description of the command.



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

def summary
  @summary
end

Class Method Details

.add_common_option(*args, &handler) ⇒ Object 



61
62
63
 
# 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) ⇒ 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.



90
91
92
93
 
# 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 ⇒ Object

Arguments used when building gems



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

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

.build_args=(value) ⇒ Object 



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

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

.common_options ⇒ Object 



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

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

.extra_args ⇒ Object 



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

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

.extra_args=(value) ⇒ Object 



69
70
71
72
73
74
75
76
 
# 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

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



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

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



98
99
100
101
102
 
# 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 Method Details

#add_extra_args(args) ⇒ Object

Adds extra args from ~/.gemrc



355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
 
# 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, &handler) ⇒ Object

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.



305
306
307
308
309
 
# 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 ⇒ 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



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

def arguments
  ""
end

#begins?(long, short) ⇒ Boolean

True if long begins with the characters from short.

Returns:

  • (Boolean) 


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

def begins?(long, short)
  return false if short.nil?
  long[0, short.length] == short
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



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

def defaults_str
  ""
end

#description ⇒ Object

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



246
247
248
 
# File 'lib/rubygems/command.rb', line 246

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:



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

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

#get_all_gem_names ⇒ Object

Get all gem names from the command line.



171
172
173
174
175
176
177
178
179
180
 
# 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 ⇒ 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.



186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
 
# 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 ⇒ 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.



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

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.



345
346
347
348
349
350
 
# 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) ⇒ Boolean

True if the command handles the given argument list.

Returns:

  • (Boolean) 


332
333
334
335
336
337
338
339
 
# File 'lib/rubygems/command.rb', line 332

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

#invoke(*args) ⇒ Object

Invoke the command with the given list of arguments.



270
271
272
273
274
275
276
277
278
279
280
 
# 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) ⇒ Object

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



324
325
326
327
 
# 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) ⇒ Object

Remove previously defined command-line argument name.



314
315
316
317
318
 
# 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 ⇒ Object

Display the help message for the command.



262
263
264
265
 
# 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) ⇒ Object

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



151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
 
# 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 ⇒ Object

Override to display the usage for an individual gem command.

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



255
256
257
 
# File 'lib/rubygems/command.rb', line 255

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.



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

def when_invoked(&block)
  @when_invoked = block
end