class Gem::Command
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
Attributes
The name of the command.
The default options for the command.
The options for the command.
The name of the command for command-line invocation.
A short description of the command.
Public Class Methods
# File lib/rubygems/command.rb, line 62 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 lib/rubygems/command.rb, line 91 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 lib/rubygems/command.rb, line 50 def self.build_args @build_args ||= [] end
# File lib/rubygems/command.rb, line 54 def self.build_args=(value) @build_args = value end
# File lib/rubygems/command.rb, line 58 def self.common_options @common_options ||= [] end
# File lib/rubygems/command.rb, line 66 def self.extra_args @extra_args ||= [] end
# File lib/rubygems/command.rb, line 70 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 lib/rubygems/command.rb, line 117 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
Return an array of extra arguments for the command. The extra arguments come from the gem configuration file read at program startup.
# File lib/rubygems/command.rb, line 83 def self.specific_extra_args(cmd) specific_extra_args_hash[cmd] end
Accessor for the specific extra args hash (self initializing).
# File lib/rubygems/command.rb, line 99 def self.specific_extra_args_hash @specific_extra_args_hash ||= Hash.new do |h,k| h[k] = Array.new end end
Public Instance Methods
Adds extra args from ~/.gemrc
# File lib/rubygems/command.rb, line 382 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
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 332 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 lib/rubygems/command.rb, line 242 def arguments "" end
True if long
begins with the characters from
short
.
# File lib/rubygems/command.rb, line 131 def begins?(long, short) return false if short.nil? long[0, short.length] == short 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 lib/rubygems/command.rb, line 256 def defaults_str "" end
Override to display a longer description of what this command does.
# File lib/rubygems/command.rb, line 263 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 lib/rubygems/command.rb, line 145 def execute raise Gem::Exception, "generic command has no actions" end
Get all gem names from the command line.
# File lib/rubygems/command.rb, line 173 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, version] from the command line.
An argument in the form gem:ver is pull apart into the gen name and version, respectively.
# File lib/rubygems/command.rb, line 189 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 lib/rubygems/command.rb, line 203 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 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 223 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 lib/rubygems/command.rb, line 372 def handle_options(args) args = add_extra_args(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 lib/rubygems/command.rb, line 359 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 lib/rubygems/command.rb, line 287 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 lib/rubygems/command.rb, line 295 def invoke_with_build_args(args, build_args) handle_options args options[:build_args] = build_args if options[:help] then show_help elsif @when_invoked then @when_invoked.call options else execute end 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 351 def merge_options(new_options) @options = @defaults.clone new_options.each do |k,v| @options[k] = v end end
Remove previously defined command-line argument name
.
# File lib/rubygems/command.rb, line 341 def remove_option(name) @option_groups.each do |_, option_list| option_list.reject! { |args, _| args.any? { |x| x =~ /^#{name}/ } } end end
Display the help message for the command.
# File lib/rubygems/command.rb, line 279 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 lib/rubygems/command.rb, line 152 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" 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
Override to display the usage for an individual gem command.
The text “[options]” is automatically appended to the usage text.
# File lib/rubygems/command.rb, line 272 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 lib/rubygems/command.rb, line 317 def when_invoked(&block) @when_invoked = block end
Private Instance Methods
Adds a section with title
and content
to the
parser help view. Used for adding command arguments and default arguments.
# File lib/rubygems/command.rb, line 433 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
# File lib/rubygems/command.rb, line 479 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
Creates an option parser and fills it in with the help info for the command.
# File lib/rubygems/command.rb, line 465 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
Create on demand parser.
# File lib/rubygems/command.rb, line 456 def parser create_option_parser if @parser.nil? @parser end
Wraps text
to width
# File lib/rubygems/command.rb, line 498 def wrap(text, width) # :doc: text.gsub(/(.{1,#{width}})( +|$\n?)|(.{1,#{width}})/, "\\1\\3\n") end