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
The name of the command.
The options for the command.
The default options for the command.
The name of the command for command-line invocation.
A short description of the command.
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 65
def self.add_common_option(*args, &handler)
Gem::Command.common_options << [args, handler]
end
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 94
def self.add_specific_extra_args(cmd,args)
args = args.split(/\s+/) if args.is_a? String
specific_extra_args_hash[cmd] = args
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 tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 53
def self.build_args
@build_args ||= []
end
Arguments used when building gems
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 57
def self.build_args=(value)
@build_args = value
end
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 61
def self.common_options
@common_options ||= []
end
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 69
def self.extra_args
@extra_args ||= []
end
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 73
def self.extra_args=(value)
case value
when Array
@extra_args = value
when String
@extra_args = value.split(" ")
end
end
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 120
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
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 tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 86
def self.specific_extra_args(cmd)
specific_extra_args_hash[cmd]
end
Return an array of extra arguments for the command. The extra arguments come from the gem configuration file read at program startup.
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 102
def self.specific_extra_args_hash
@specific_extra_args_hash ||= Hash.new do |h,k|
h[k] = Array.new
end
end
Accessor for the specific extra args hash (self initializing).
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 451
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 /^[^-]/.match?(extra.first.to_s)
result << ex if handles?(ex)
end
result.flatten!
result.concat(args)
result
end
Adds extra args from ~/.gemrc
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 358
def add_option(*opts, &handler) # :yields: value, options
group_name = Symbol === opts.first ? opts.shift : :options
raise "Do not pass an empty string in opts" if opts.include?("")
@option_groups[group_name] << [opts, handler]
end
Add a command-line option and handler to the command.
See Gem::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 tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 510
def add_parser_run_info(title, content)
return if content.empty?
@parser.separator nil
@parser.separator " #{title}:"
content.each_line do |line|
@parser.separator " #{line.rstrip}"
end
end
Adds a section with title and content to the parser help view. Used for adding command arguments and default arguments.
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 258
def arguments
""
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 tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 135
def begins?(long, short)
return false if short.nil?
long[0, short.length] == short
end
True if long begins with the characters from short.
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 397
def check_deprecated_options(options)
options.each do |option|
next unless 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
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 556
def configure_options(header, option_list)
return if option_list.nil? || option_list.empty?
header = header.to_s.empty? ? "" : "#{header} "
@parser.separator " #{header}Options:"
option_list.each do |args, handler|
@parser.on(*args) do |value|
handler.call(value, @options)
end
end
@parser.separator ""
end
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 542
def create_option_parser
@parser = Gem::OptionParser.new
add_parser_options
@parser.separator nil
configure_options "Common", Gem::Command.common_options
add_parser_run_info "Arguments", arguments
add_parser_summary
add_parser_description
add_parser_run_info "Defaults", defaults_str
end
Creates an option parser and fills it in with the help info for the command.
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 272
def defaults_str
""
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 tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 393
def deprecate_option(name, version: nil, extra_msg: nil)
@deprecated_options[command].merge!({ name => { "rg_version_to_expire" => version, "extra_msg" => extra_msg } })
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 tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 469
def deprecated?
false
end
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 279
def description
nil
end
Override to display a longer description of what this command does.
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 149
def execute
raise Gem::Exception, "generic command has no actions"
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 tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 185
def get_all_gem_names
args = options[:args]
if args.nil? || args.empty?
raise Gem::CommandLineError,
"Please specify at least one gem name (e.g. gem build GEMNAME)"
end
args.reject {|arg| arg.start_with?("-") }
end
Get all gem names from the command line.
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 201
def get_all_gem_names_and_versions
get_all_gem_names.map do |name|
extract_gem_name_and_version(name)
end
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 tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 219
def get_one_gem_name
args = options[:args]
if args.nil? || 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 gem name from the command line. Fail if there is no gem name or if there is more than one gem name given.
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 239
def get_one_optional_argument
args = options[:args] || []
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 tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 440
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
Handle the given list of arguments by parsing them and recording the results.
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 429
def handles?(args)
parser.parse!(args.dup)
true
rescue StandardError
false
end
True if the command handles the given argument list.
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 303
def invoke(*args)
invoke_with_build_args args, nil
end
Invoke the command with the given list of arguments.
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 311
def invoke_with_build_args(args, build_args)
handle_options args
options[:build_args] = build_args
if options[:silent]
old_ui = 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
Invoke the command with the given list of normal arguments and additional build arguments.
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 421
def merge_options(new_options)
@options = @defaults.clone
new_options.each {|k,v| @options[k] = v }
end
Merge a set of command options with the set of default options (without modifying the default option hash).
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 475
def option_is_deprecated?(option)
@deprecated_options[command].key?(option)
end
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 533
def parser
create_option_parser if @parser.nil?
@parser
end
Create on demand parser.
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 369
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
Remove previously defined command-line argument name.
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 295
def show_help
parser.program_name = usage
say parser
end
Display the help message for the command.
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 157
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 && !errors.empty?
msg << ", here is why:\n"
errors.each {|x| msg << " #{x.wordy}\n" }
else
if required_by && 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
Display to the user that a gem couldn’t be found and reasons why
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 288
def usage
program_name
end
Override to display the usage for an individual gem command.
The text “[options]” is automatically appended to the usage text.
# File tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 343
def when_invoked(&block)
@when_invoked = block
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 tmp/rubies/ruby-3.4.0-preview1/lib/rubygems/command.rb, line 574
def wrap(text, width) # :doc:
text.gsub(/(.{1,#{width}})( +|$\n?)|(.{1,#{width}})/, "\\1\\3\n")
end
Wraps text to width