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
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. |
# 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 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].
# 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
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
Adds extra args from ~/.gemrc
# 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.
# 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
# File lib/rubygems/command.rb, line 205 205: def arguments 206: "" 207: 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 a longer description of what this command does.
# 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
# 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.
# 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.
# 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.
# File lib/rubygems/command.rb, line 186 186: def get_one_optional_argument 187: args = options[:args] || [] 188: args.first 189: end
True if the command handles the given argument list.
# 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
Merge a set of command options with the set of default options (without modifying the default option hash).
# 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.
# 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.
# File lib/rubygems/command.rb, line 242 242: def show_help 243: parser.program_name = usage 244: say parser 245: 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 269 269: def when_invoked(&block) 270: @when_invoked = block 271: end