Class Gem::Command
In: lib/rubygems/command.rb
Parent: Object

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

Methods

Included Modules

Gem::UserInteraction

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

[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 a list of extra arguments for the given command. args may be an array or a string to be split on white space.

[Source]

    # 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

Arguments used when building gems

[Source]

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

[Source]

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

[Source]

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

[Source]

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

[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

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

[Source]

     # 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

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

[Source]

    # File lib/rubygems/command.rb, line 82
82:   def self.specific_extra_args(cmd)
83:     specific_extra_args_hash[cmd]
84:   end

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

[Source]

     # 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

Adds extra args from ~/.gemrc

[Source]

     # File lib/rubygems/command.rb, line 334
334:   def add_extra_args(args)
335:     result = []
336: 
337:     s_extra = Gem::Command.specific_extra_args(@command)
338:     extra = Gem::Command.extra_args + s_extra
339: 
340:     until extra.empty? do
341:       ex = []
342:       ex << extra.shift
343:       ex << extra.shift if extra.first.to_s =~ /^[^-]/
344:       result << ex if handles?(ex)
345:     end
346: 
347:     result.flatten!
348:     result.concat(args)
349:     result
350:   end

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.

[Source]

     # File lib/rubygems/command.rb, line 284
284:   def add_option(*opts, &handler) # :yields: value, options
285:     group_name = Symbol === opts.first ? opts.shift : :options
286: 
287:     @option_groups[group_name] << [opts, handler]
288:   end

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

[Source]

     # File lib/rubygems/command.rb, line 205
205:   def arguments
206:     ""
207:   end

True if long begins with the characters from short.

[Source]

     # 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

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

[Source]

     # File lib/rubygems/command.rb, line 219
219:   def defaults_str
220:     ""
221:   end

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

[Source]

     # File lib/rubygems/command.rb, line 226
226:   def description
227:     nil
228:   end

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

[Source]

     # 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 from the command line.

[Source]

     # File lib/rubygems/command.rb, line 151
151:   def get_all_gem_names
152:     args = options[:args]
153: 
154:     if args.nil? or args.empty? then
155:       raise Gem::CommandLineError,
156:             "Please specify at least one gem name (e.g. gem build GEMNAME)"
157:     end
158: 
159:     gem_names = args.select { |arg| arg !~ /^-/ }
160:   end

Get the single gem name from the command line. Fail if there is no gem name or if there is more than one gem name given.

[Source]

     # File lib/rubygems/command.rb, line 166
166:   def get_one_gem_name
167:     args = options[:args]
168: 
169:     if args.nil? or args.empty? then
170:       raise Gem::CommandLineError,
171:             "Please specify a gem name on the command line (e.g. gem build GEMNAME)"
172:     end
173: 
174:     if args.size > 1 then
175:       raise Gem::CommandLineError,
176:             "Too many gem names (#{args.join(', ')}); please specify only one"
177:     end
178: 
179:     args.first
180:   end

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.

[Source]

     # File lib/rubygems/command.rb, line 186
186:   def get_one_optional_argument
187:     args = options[:args] || []
188:     args.first
189:   end

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

[Source]

     # File lib/rubygems/command.rb, line 324
324:   def handle_options(args)
325:     args = add_extra_args(args)
326:     @options = @defaults.clone
327:     parser.parse!(args)
328:     @options[:args] = args
329:   end

True if the command handles the given argument list.

[Source]

     # File lib/rubygems/command.rb, line 311
311:   def handles?(args)
312:     begin
313:       parser.parse!(args.dup)
314:       return true
315:     rescue
316:       return false
317:     end
318:   end

Invoke the command with the given list of arguments.

[Source]

     # File lib/rubygems/command.rb, line 250
250:   def invoke(*args)
251:     handle_options(args)
252:     if options[:help]
253:       show_help
254:     elsif @when_invoked
255:       @when_invoked.call(options)
256:     else
257:       execute
258:     end
259:   end

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

[Source]

     # File lib/rubygems/command.rb, line 303
303:   def merge_options(new_options)
304:     @options = @defaults.clone
305:     new_options.each do |k,v| @options[k] = v end
306:   end

Remove previously defined command-line argument name.

[Source]

     # File lib/rubygems/command.rb, line 293
293:   def remove_option(name)
294:     @option_groups.each do |_, option_list|
295:       option_list.reject! { |args, _| args.any? { |x| x =~ /^#{name}/ } }
296:     end
297:   end

Display the help message for the command.

[Source]

     # File lib/rubygems/command.rb, line 242
242:   def show_help
243:     parser.program_name = usage
244:     say parser
245:   end

Override to display the usage for an individual gem command.

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

[Source]

     # File lib/rubygems/command.rb, line 235
235:   def usage
236:     program_name
237:   end

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.

[Source]

     # File lib/rubygems/command.rb, line 269
269:   def when_invoked(&block)
270:     @when_invoked = block
271:   end

Private Instance methods

Wraps text to width

[Source]

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

[Validate]