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-2.5.9/lib/rubygems/command.rb, line 63
def self.add_common_option(*args, &handler)
Gem::Command.common_options << [args, handler]
end
# File tmp/rubies/ruby-2.5.9/lib/rubygems/command.rb, line 92
def self.add_specific_extra_args(cmd,args)
args = args.split(/\s+/) if args.kind_of? 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-2.5.9/lib/rubygems/command.rb, line 51
def self.build_args
@build_args ||= []
end
Arguments used when building gems
# File tmp/rubies/ruby-2.5.9/lib/rubygems/command.rb, line 55
def self.build_args=(value)
@build_args = value
end
# File tmp/rubies/ruby-2.5.9/lib/rubygems/command.rb, line 59
def self.common_options
@common_options ||= []
end
# File tmp/rubies/ruby-2.5.9/lib/rubygems/command.rb, line 67
def self.extra_args
@extra_args ||= []
end
# File tmp/rubies/ruby-2.5.9/lib/rubygems/command.rb, line 71
def self.extra_args=(value)
case value
when Array
@extra_args = value
when String
@extra_args = value.split
end
end
# File tmp/rubies/ruby-2.5.9/lib/rubygems/command.rb, line 118
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] = [] }
@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-2.5.9/lib/rubygems/command.rb, line 84
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-2.5.9/lib/rubygems/command.rb, line 100
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-2.5.9/lib/rubygems/command.rb, line 395
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 =~ /^[^-]/
result << ex if handles?(ex)
end
result.flatten!
result.concat(args)
result
end
Adds extra args from ~/.gemrc
# File tmp/rubies/ruby-2.5.9/lib/rubygems/command.rb, line 345
def add_option(*opts, &handler) # :yields: value, options
group_name = Symbol === opts.first ? opts.shift : :options
@option_groups[group_name] << [opts, handler]
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 tmp/rubies/ruby-2.5.9/lib/rubygems/command.rb, line 446
def add_parser_run_info title, content
return if content.empty?
@parser.separator nil
@parser.separator " #{title}:"
content.split(/\n/).each do |line|
@parser.separator " #{line}"
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-2.5.9/lib/rubygems/command.rb, line 245
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-2.5.9/lib/rubygems/command.rb, line 132
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-2.5.9/lib/rubygems/command.rb, line 492
def configure_options(header, option_list)
return if option_list.nil? or option_list.empty?
header = header.to_s.empty? ? '' : "#{header} "
@parser.separator " #{header}Options:"
option_list.each do |args, handler|
args.select { |arg| arg =~ /^-/ }
@parser.on(*args) do |value|
handler.call(value, @options)
end
end
@parser.separator ''
end
# File tmp/rubies/ruby-2.5.9/lib/rubygems/command.rb, line 478
def create_option_parser
@parser = 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-2.5.9/lib/rubygems/command.rb, line 259
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-2.5.9/lib/rubygems/command.rb, line 266
def description
nil
end
Override to display a longer description of what this command does.
# File tmp/rubies/ruby-2.5.9/lib/rubygems/command.rb, line 146
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-2.5.9/lib/rubygems/command.rb, line 176
def get_all_gem_names
args = options[:args]
if args.nil? or args.empty? then
raise Gem::CommandLineError,
"Please specify at least one gem name (e.g. gem build GEMNAME)"
end
args.select { |arg| arg !~ /^-/ }
end
Get all gem names from the command line.
# File tmp/rubies/ruby-2.5.9/lib/rubygems/command.rb, line 192
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 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-2.5.9/lib/rubygems/command.rb, line 206
def get_one_gem_name
args = options[:args]
if args.nil? or args.empty? then
raise Gem::CommandLineError,
"Please specify a gem name on the command line (e.g. gem build GEMNAME)"
end
if args.size > 1 then
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-2.5.9/lib/rubygems/command.rb, line 226
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-2.5.9/lib/rubygems/command.rb, line 385
def handle_options(args)
args = add_extra_args(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-2.5.9/lib/rubygems/command.rb, line 372
def handles?(args)
begin
parser.parse!(args.dup)
return true
rescue
return false
end
end
True if the command handles the given argument list.
# File tmp/rubies/ruby-2.5.9/lib/rubygems/command.rb, line 290
def invoke(*args)
invoke_with_build_args args, nil
end
Invoke the command with the given list of arguments.
# File tmp/rubies/ruby-2.5.9/lib/rubygems/command.rb, line 298
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] then
show_help
elsif @when_invoked then
@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-2.5.9/lib/rubygems/command.rb, line 364
def merge_options(new_options)
@options = @defaults.clone
new_options.each do |k,v| @options[k] = v end
end
Merge a set of command options with the set of default options (without modifying the default option hash).
# File tmp/rubies/ruby-2.5.9/lib/rubygems/command.rb, line 469
def parser
create_option_parser if @parser.nil?
@parser
end
Create on demand parser.
# File tmp/rubies/ruby-2.5.9/lib/rubygems/command.rb, line 354
def remove_option(name)
@option_groups.each do |_, option_list|
option_list.reject! { |args, _| args.any? { |x| x =~ /^#{name}/ } }
end
end
Remove previously defined command-line argument name.
# File tmp/rubies/ruby-2.5.9/lib/rubygems/command.rb, line 282
def show_help
parser.program_name = usage
say parser
end
Display the help message for the command.
# File tmp/rubies/ruby-2.5.9/lib/rubygems/command.rb, line 155
def show_lookup_failure(gem_name, version, errors, domain)
if errors and !errors.empty?
msg = "Could not find a valid gem '#{gem_name}' (#{version}), here is why:\n".dup
errors.each { |x| msg << " #{x.wordy}\n" }
alert_error msg
else
alert_error "Could not find a valid gem '#{gem_name}' (#{version}) in any repository"
end
unless domain == :local then # HACK
suggestions = Gem::SpecFetcher.fetcher.suggest_gems_from_name gem_name
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-2.5.9/lib/rubygems/command.rb, line 275
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-2.5.9/lib/rubygems/command.rb, line 330
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-2.5.9/lib/rubygems/command.rb, line 511
def wrap(text, width) # :doc:
text.gsub(/(.{1,#{width}})( +|$\n?)|(.{1,#{width}})/, "\\1\\3\n")
end
Wraps text to width