Base class for all Gem commands. When creating a new gem command, define initialize, 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
# File rubygems/command.rb, line 66 def self.add_common_option(*args, &handler) Gem::Command.common_options << [args, handler] 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 rubygems/command.rb, line 95 def self.add_specific_extra_args(cmd,args) args = args.split(/\s+/) if args.kind_of? String specific_extra_args_hash[cmd] = args end
Arguments used when building gems
# File rubygems/command.rb, line 54 def self.build_args @build_args ||= [] end
# File rubygems/command.rb, line 58 def self.build_args=(value) @build_args = value end
# File rubygems/command.rb, line 62 def self.common_options @common_options ||= [] end
# File rubygems/command.rb, line 70 def self.extra_args @extra_args ||= [] end
# File rubygems/command.rb, line 74 def self.extra_args=(value) case value when Array @extra_args = value when String @extra_args = value.split(' ') end 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 rubygems/command.rb, line 121 def initialize(command, summary=nil, defaults={}) @command = command @summary = summary @program_name = "gem #{command}" @defaults = defaults @options = defaults.dup @option_groups = Hash.new {|h,k| h[k] = [] } @deprecated_options = { command => {} } @parser = nil @when_invoked = nil end
Return an array of extra arguments for the command. The extra arguments come from the gem configuration file read at program startup.
# File rubygems/command.rb, line 87 def self.specific_extra_args(cmd) specific_extra_args_hash[cmd] end
Adds extra args from ~/.gemrc
# File rubygems/command.rb, line 449 def add_extra_args(args) result = [] s_extra = Gem::Command.specific_extra_args(@command) extra = Gem::Command.extra_args + s_extra until extra.empty? do ex = [] ex << extra.shift ex << extra.shift if extra.first.to_s =~ /^[^-]/ # rubocop:disable Performance/StartWith result << ex if handles?(ex) end result.flatten! result.concat(args) result 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 rubygems/command.rb, line 355 def add_option(*opts, &handler) # :yields: value, options group_name = Symbol === opts.first ? opts.shift : :options @option_groups[group_name] << [opts, handler] 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 rubygems/command.rb, line 255 def arguments "" end
True if long
begins with the characters from short
.
# File rubygems/command.rb, line 136 def begins?(long, short) return false if short.nil? long[0, short.length] == short end
# File rubygems/command.rb, line 392 def check_deprecated_options(options) options.each do |option| if option_is_deprecated?(option) deprecation = @deprecated_options[command][option] version_to_expire = deprecation["rg_version_to_expire"] deprecate_option_msg = if version_to_expire "The \"#{option}\" option has been deprecated and will be removed in Rubygems #{version_to_expire}." else "The \"#{option}\" option has been deprecated and will be removed in future versions of Rubygems." end extra_msg = deprecation["extra_msg"] deprecate_option_msg += " #{extra_msg}" if extra_msg alert_warning(deprecate_option_msg) end end 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 rubygems/command.rb, line 269 def defaults_str "" end
Mark a command-line option as deprecated, and optionally specify a deprecation horizon.
Note that with the current implementation, every version of the option needs to be explicitly deprecated, so to deprecate an option defined as
add_option('-t', '--[no-]test', 'Set test mode') do |value, options| # ... stuff ... end
you would need to explicitly add a call to `deprecate_option` for every version of the option you want to deprecate, like
deprecate_option('-t') deprecate_option('--test') deprecate_option('--no-test')
# File rubygems/command.rb, line 388 def deprecate_option(name, version: nil, extra_msg: nil) @deprecated_options[command].merge!({ name => { "rg_version_to_expire" => version, "extra_msg" => extra_msg } }) end
Override to display a longer description of what this command does.
# File rubygems/command.rb, line 276 def description nil 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 rubygems/command.rb, line 150 def execute raise Gem::Exception, "generic command has no actions" end
Get all gem names from the command line.
# File rubygems/command.rb, line 186 def get_all_gem_names args = options[:args] if args.nil? or args.empty? raise Gem::CommandLineError, "Please specify at least one gem name (e.g. gem build GEMNAME)" end args.select {|arg| arg !~ /^-/ } end
Get all [gem, version] from the command line.
An argument in the form gem:ver is pull apart into the gen name and version, respectively.
# File rubygems/command.rb, line 202 def get_all_gem_names_and_versions get_all_gem_names.map do |name| if /\A(.*):(#{Gem::Requirement::PATTERN_RAW})\z/ =~ name [$1, $2] else [name] end end 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 rubygems/command.rb, line 216 def get_one_gem_name args = options[:args] if args.nil? or args.empty? raise Gem::CommandLineError, "Please specify a gem name on the command line (e.g. gem build GEMNAME)" end if args.size > 1 raise Gem::CommandLineError, "Too many gem names (#{args.join(', ')}); please specify only one" end args.first 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 rubygems/command.rb, line 236 def get_one_optional_argument args = options[:args] || [] args.first end
Handle the given list of arguments by parsing them and recording the results.
# File rubygems/command.rb, line 438 def handle_options(args) args = add_extra_args(args) check_deprecated_options(args) @options = Marshal.load Marshal.dump @defaults # deep copy parser.parse!(args) @options[:args] = args end
True if the command handles the given argument list.
# File rubygems/command.rb, line 425 def handles?(args) begin parser.parse!(args.dup) return true rescue return false end end
Invoke the command with the given list of arguments.
# File rubygems/command.rb, line 300 def invoke(*args) invoke_with_build_args args, nil end
Invoke the command with the given list of normal arguments and additional build arguments.
# File rubygems/command.rb, line 308 def invoke_with_build_args(args, build_args) handle_options args options[:build_args] = build_args if options[:silent] old_ui = self.ui self.ui = ui = Gem::SilentUI.new end if options[:help] show_help elsif @when_invoked @when_invoked.call options else execute end ensure if ui self.ui = old_ui ui.close end end
Merge a set of command options with the set of default options (without modifying the default option hash).
# File rubygems/command.rb, line 417 def merge_options(new_options) @options = @defaults.clone new_options.each {|k,v| @options[k] = v } end
Remove previously defined command-line argument name
.
# File rubygems/command.rb, line 364 def remove_option(name) @option_groups.each do |_, option_list| option_list.reject! {|args, _| args.any? {|x| x.is_a?(String) && x =~ /^#{name}/ } } end end
Display the help message for the command.
# File rubygems/command.rb, line 292 def show_help parser.program_name = usage say parser end
Display to the user that a gem couldn't be found and reasons why
# File rubygems/command.rb, line 158 def show_lookup_failure(gem_name, version, errors, suppress_suggestions = false, required_by = nil) gem = "'#{gem_name}' (#{version})" msg = String.new "Could not find a valid gem #{gem}" if errors and !errors.empty? msg << ", here is why:\n" errors.each {|x| msg << " #{x.wordy}\n" } else if required_by and gem != required_by msg << " (required by #{required_by}) in any repository" else msg << " in any repository" end end alert_error msg unless suppress_suggestions suggestions = Gem::SpecFetcher.fetcher.suggest_gems_from_name(gem_name, :latest, 10) unless suggestions.empty? alert_error "Possible alternatives: #{suggestions.join(", ")}" end end end
Override to display the usage for an individual gem command.
The text “[options]” is automatically appended to the usage text.
# File rubygems/command.rb, line 285 def usage program_name 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 rubygems/command.rb, line 340 def when_invoked(&block) @when_invoked = block end