Class | Gem::Command |
In: |
lib/rubygems/command.rb
|
Parent: | Object |
Base class for all Gem commands. When creating a new gem command, define arguments, defaults_str, description and usage (as appropriate).
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. |
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.
Use add_option to add command-line switches.
# File lib/rubygems/command.rb, line 40 40: def initialize(command, summary=nil, defaults={}) 41: @command = command 42: @summary = summary 43: @program_name = "gem #{command}" 44: @defaults = defaults 45: @options = defaults.dup 46: @option_groups = Hash.new { |h,k| h[k] = [] } 47: @parser = nil 48: @when_invoked = nil 49: end
# File lib/rubygems/command.rb, line 195 195: def add_extra_args(args) 196: result = [] 197: s_extra = Command.specific_extra_args(@command) 198: extra = Command.extra_args + s_extra 199: while ! extra.empty? 200: ex = [] 201: ex << extra.shift 202: ex << extra.shift if extra.first.to_s =~ /^[^-]/ 203: result << ex if handles?(ex) 204: end 205: result.flatten! 206: result.concat(args) 207: result 208: 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.
# File lib/rubygems/command.rb, line 156 156: def add_option(*opts, &handler) # :yields: value, options 157: group_name = Symbol === opts.first ? opts.shift : :options 158: 159: @option_groups[group_name] << [opts, handler] 160: end
True if long begins with the characters from short.
# File lib/rubygems/command.rb, line 52 52: def begins?(long, short) 53: return false if short.nil? 54: long[0, short.length] == short 55: end
Override to display a longer description of what this command does.
# File lib/rubygems/command.rb, line 113 113: def description 114: nil 115: end
Override to provide command handling.
# File lib/rubygems/command.rb, line 58 58: def execute 59: fail "Generic command has no actions" 60: end
Get all gem names from the command line.
# File lib/rubygems/command.rb, line 63 63: def get_all_gem_names 64: args = options[:args] 65: 66: if args.nil? or args.empty? then 67: raise Gem::CommandLineError, 68: "Please specify at least one gem name (e.g. gem build GEMNAME)" 69: end 70: 71: gem_names = args.select { |arg| arg !~ /^-/ } 72: 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 76 76: def get_one_gem_name 77: args = options[:args] 78: 79: if args.nil? or args.empty? then 80: raise Gem::CommandLineError, 81: "Please specify a gem name on the command line (e.g. gem build GEMNAME)" 82: end 83: 84: if args.size > 1 then 85: raise Gem::CommandLineError, 86: "Too many gem names (#{args.join(', ')}); please specify only one" 87: end 88: 89: args.first 90: 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 94 94: def get_one_optional_argument 95: args = options[:args] || [] 96: args.first 97: end
True if the command handles the given argument list.
# File lib/rubygems/command.rb, line 177 177: def handles?(args) 178: begin 179: parser.parse!(args.dup) 180: return true 181: rescue 182: return false 183: end 184: 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 171 171: def merge_options(new_options) 172: @options = @defaults.clone 173: new_options.each do |k,v| @options[k] = v end 174: end
Remove previously defined command-line argument name.
# File lib/rubygems/command.rb, line 163 163: def remove_option(name) 164: @option_groups.each do |_, option_list| 165: option_list.reject! { |args, _| args.any? { |x| x =~ /^#{name}/ } } 166: end 167: end
Display the help message for the command.
# File lib/rubygems/command.rb, line 123 123: def show_help 124: parser.program_name = usage 125: say parser 126: 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 146 146: def when_invoked(&block) 147: @when_invoked = block 148: end