Object
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
# 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.
# 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
# File lib/rubygems/command.rb, line 49 49: def self.build_args 50: @build_args ||= [] 51: end
# File lib/rubygems/command.rb, line 53 53: def self.build_args=(value) 54: @build_args = value 55: end
# File lib/rubygems/command.rb, line 57 57: def self.common_options 58: @common_options ||= [] 59: end
# File lib/rubygems/command.rb, line 65 65: def self.extra_args 66: @extra_args ||= [] 67: end
# 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 #, 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
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
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 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
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
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
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
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
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 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 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 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
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 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 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 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
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
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
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
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
# 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
# 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
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.