Gem::Command

Base class for all Gem commands. When creating a new gem command, define #, #, #, #, # and # (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.

options[R]

The options for the command.

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.

Public Class Methods

add_common_option(*args, &handler) click to toggle source

    # File lib/rubygems/command.rb, line 61
61:   def self.add_common_option(*args, &handler)
62:     Gem::Command.common_options << [args, handler]
63:   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 lib/rubygems/command.rb, line 90
90:   def self.add_specific_extra_args(cmd,args)
91:     args = args.split(/\s+/) if args.kind_of? String
92:     specific_extra_args_hash[cmd] = args
93:   end

build_args() click to toggle source

Arguments used when building gems

    # File lib/rubygems/command.rb, line 49
49:   def self.build_args
50:     @build_args ||= []
51:   end

build_args=(value) click to toggle source

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

common_options() click to toggle source

    # File lib/rubygems/command.rb, line 57
57:   def self.common_options
58:     @common_options ||= []
59:   end

extra_args() click to toggle source

    # File lib/rubygems/command.rb, line 65
65:   def self.extra_args
66:     @extra_args ||= []
67:   end

extra_args=(value) click to toggle source

    # File lib/rubygems/command.rb, line 69
69:   def self.extra_args=(value)
70:     case value
71:     when Array
72:       @extra_args = value
73:     when String
74:       @extra_args = value.split
75:     end
76:   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 #, 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 lib/rubygems/command.rb, line 116
116:   def initialize(command, summary=nil, defaults={})
117:     @command = command
118:     @summary = summary
119:     @program_name = "gem #{command}"
120:     @defaults = defaults
121:     @options = defaults.dup
122:     @option_groups = Hash.new { |h,k| h[k] = [] }
123:     @parser = nil
124:     @when_invoked = nil
125:   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 lib/rubygems/command.rb, line 82
82:   def self.specific_extra_args(cmd)
83:     specific_extra_args_hash[cmd]
84:   end

specific_extra_args_hash() click to toggle source

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

     # File lib/rubygems/command.rb, line 98
 98:   def self.specific_extra_args_hash
 99:     @specific_extra_args_hash ||= Hash.new do |h,k|
100:       h[k] = Array.new
101:     end
102:   end

Public Instance Methods

add_extra_args(args) click to toggle source

Adds extra args from ~/.gemrc

     # File lib/rubygems/command.rb, line 355
355:   def add_extra_args(args)
356:     result = []
357: 
358:     s_extra = Gem::Command.specific_extra_args(@command)
359:     extra = Gem::Command.extra_args + s_extra
360: 
361:     until extra.empty? do
362:       ex = []
363:       ex << extra.shift
364:       ex << extra.shift if extra.first.to_s =~ /^[^-]/
365:       result << ex if handles?(ex)
366:     end
367: 
368:     result.flatten!
369:     result.concat(args)
370:     result
371:   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 lib/rubygems/command.rb, line 305
305:   def add_option(*opts, &handler) # :yields: value, options
306:     group_name = Symbol === opts.first ? opts.shift : :options
307: 
308:     @option_groups[group_name] << [opts, handler]
309:   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 lib/rubygems/command.rb, line 225
225:   def arguments
226:     ""
227:   end

begins?(long, short) click to toggle source

True if long begins with the characters from short.

     # File lib/rubygems/command.rb, line 130
130:   def begins?(long, short)
131:     return false if short.nil?
132:     long[0, short.length] == short
133:   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 lib/rubygems/command.rb, line 239
239:   def defaults_str
240:     ""
241:   end

description() click to toggle source

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

     # File lib/rubygems/command.rb, line 246
246:   def description
247:     nil
248:   end

execute() click to toggle source

Override to provide command handling.

# will be filled in with your parsed options, unparsed options will be left in options[:args].

See also: #, #, #

     # File lib/rubygems/command.rb, line 144
144:   def execute
145:     raise Gem::Exception, "generic command has no actions"
146:   end

get_all_gem_names() click to toggle source

Get all gem names from the command line.

     # File lib/rubygems/command.rb, line 171
171:   def get_all_gem_names
172:     args = options[:args]
173: 
174:     if args.nil? or args.empty? then
175:       raise Gem::CommandLineError,
176:             "Please specify at least one gem name (e.g. gem build GEMNAME)"
177:     end
178: 
179:     args.select { |arg| arg !~ /^-/ }
180:   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 lib/rubygems/command.rb, line 186
186:   def get_one_gem_name
187:     args = options[:args]
188: 
189:     if args.nil? or args.empty? then
190:       raise Gem::CommandLineError,
191:             "Please specify a gem name on the command line (e.g. gem build GEMNAME)"
192:     end
193: 
194:     if args.size > 1 then
195:       raise Gem::CommandLineError,
196:             "Too many gem names (#{args.join(', ')}); please specify only one"
197:     end
198: 
199:     args.first
200:   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 lib/rubygems/command.rb, line 206
206:   def get_one_optional_argument
207:     args = options[:args] || []
208:     args.first
209:   end

handle_options(args) click to toggle source

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

     # File lib/rubygems/command.rb, line 345
345:   def handle_options(args)
346:     args = add_extra_args(args)
347:     @options = @defaults.clone
348:     parser.parse!(args)
349:     @options[:args] = args
350:   end

handles?(args) click to toggle source

True if the command handles the given argument list.

     # File lib/rubygems/command.rb, line 332
332:   def handles?(args)
333:     begin
334:       parser.parse!(args.dup)
335:       return true
336:     rescue
337:       return false
338:     end
339:   end

invoke(*args) click to toggle source

Invoke the command with the given list of arguments.

     # File lib/rubygems/command.rb, line 270
270:   def invoke(*args)
271:     handle_options args
272: 
273:     if options[:help] then
274:       show_help
275:     elsif @when_invoked then
276:       @when_invoked.call options
277:     else
278:       execute
279:     end
280:   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 lib/rubygems/command.rb, line 324
324:   def merge_options(new_options)
325:     @options = @defaults.clone
326:     new_options.each do |k,v| @options[k] = v end
327:   end

remove_option(name) click to toggle source

Remove previously defined command-line argument name.

     # File lib/rubygems/command.rb, line 314
314:   def remove_option(name)
315:     @option_groups.each do |_, option_list|
316:       option_list.reject! { |args, _| args.any? { |x| x =~ /^#{name}/ } }
317:     end
318:   end

show_help() click to toggle source

Display the help message for the command.

     # File lib/rubygems/command.rb, line 262
262:   def show_help
263:     parser.program_name = usage
264:     say parser
265:   end

show_lookup_failure(gem_name, version, errors, domain) click to toggle source

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

     # File lib/rubygems/command.rb, line 151
151:   def show_lookup_failure(gem_name, version, errors, domain)
152:     if errors and !errors.empty?
153:       alert_error "Could not find a valid gem '#{gem_name}' (#{version}), here is why:"
154:       errors.each { |x| say "          #{x.wordy}" }
155:     else
156:       alert_error "Could not find a valid gem '#{gem_name}' (#{version}) in any repository"
157:     end
158: 
159:     unless domain == :local then # HACK
160:       suggestions = Gem::SpecFetcher.fetcher.suggest_gems_from_name gem_name
161: 
162:       unless suggestions.empty?
163:         alert_error "Possible alternatives: #{suggestions.join(", ")}"
164:       end
165:     end
166:   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 lib/rubygems/command.rb, line 255
255:   def usage
256:     program_name
257:   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 lib/rubygems/command.rb, line 290
290:   def when_invoked(&block)
291:     @when_invoked = block
292:   end

Private Instance Methods

configure_options(header, option_list) click to toggle source

     # File lib/rubygems/command.rb, line 436
436:   def configure_options(header, option_list)
437:     return if option_list.nil? or option_list.empty?
438: 
439:     header = header.to_s.empty? ? '' : "#{header} "
440:     @parser.separator "  #{header}Options:"
441: 
442:     option_list.each do |args, handler|
443:       args.select { |arg| arg =~ /^-/ }
444:       @parser.on(*args) do |value|
445:         handler.call(value, @options)
446:       end
447:     end
448: 
449:     @parser.separator ''
450:   end

create_option_parser() click to toggle source

     # File lib/rubygems/command.rb, line 383
383:   def create_option_parser
384:     @parser = OptionParser.new
385: 
386:     @parser.separator nil
387:     regular_options = @option_groups.delete :options
388: 
389:     configure_options "", regular_options
390: 
391:     @option_groups.sort_by { |n,_| n.to_s }.each do |group_name, option_list|
392:       @parser.separator nil
393:       configure_options group_name, option_list
394:     end
395: 
396:     @parser.separator nil
397:     configure_options "Common", Gem::Command.common_options
398: 
399:     unless arguments.empty?
400:       @parser.separator nil
401:       @parser.separator "  Arguments:"
402:       arguments.split(/\n/).each do |arg_desc|
403:         @parser.separator "    #{arg_desc}"
404:       end
405:     end
406: 
407:     if @summary then
408:       @parser.separator nil
409:       @parser.separator "  Summary:"
410:       wrap(@summary, 80 - 4).split("\n").each do |line|
411:         @parser.separator "    #{line.strip}"
412:       end
413:     end
414: 
415:     if description then
416:       formatted = description.split("\n\n").map do |chunk|
417:         wrap chunk, 80 - 4
418:       end.join "\n"
419: 
420:       @parser.separator nil
421:       @parser.separator "  Description:"
422:       formatted.split("\n").each do |line|
423:         @parser.separator "    #{line.rstrip}"
424:       end
425:     end
426: 
427:     unless defaults_str.empty?
428:       @parser.separator nil
429:       @parser.separator "  Defaults:"
430:       defaults_str.split(/\n/).each do |line|
431:         @parser.separator "    #{line}"
432:       end
433:     end
434:   end

parser() click to toggle source

Create on demand parser.

     # File lib/rubygems/command.rb, line 378
378:   def parser
379:     create_option_parser if @parser.nil?
380:     @parser
381:   end

wrap(text, width) click to toggle source

Wraps text to width

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

Home Classes Methods

In Files

Parent

Methods

Included Modules

Files

Class Index

Gem::Command

Attributes

Public Class Methods

Public Instance Methods

Private Instance Methods