Class: Gem::Command
Overview
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 Commands::ContentsCommand
Constant Summary
-
HELP =
Internal use only
# File 'lib/rubygems/command.rb', line 565<<-HELP RubyGems is a sophisticated package manager for Ruby. This is a basic help message containing pointers to more information. Usage: gem -h/--help gem -v/--version gem command [arguments...] [options...] Examples: gem install rake gem list --local gem build package.gemspec gem help install Further help: gem help commands list all 'gem' commands gem help examples show some examples of usage gem help gem_dependencies gem dependencies file guide gem help platforms gem platforms guide gem help <COMMAND> show help on COMMAND (e.g. 'gem help install') gem server present a web page at http://localhost:8808/ with info about installed gems Further information: http://guides.rubygems.org HELP
Class Attribute Summary
-
.build_args
rw
Arguments used when building gems.
- .build_args=(value) rw
- .extra_args rw
- .extra_args=(value) rw
Class Method Summary
- .add_common_option(*args, &handler)
-
.add_specific_extra_args(cmd, args)
Add a list of extra arguments for the given command.
- .common_options
-
.new(command, summary = nil, defaults = {}) ⇒ Command
constructor
Initializes a generic gem command named #command.
-
.specific_extra_args(cmd)
Return an array of extra arguments for the command.
-
.specific_extra_args_hash
Accessor for the specific extra args hash (self initializing).
Instance Attribute Summary
-
#command
readonly
The name of the command.
-
#defaults
rw
The default options for the command.
-
#options
readonly
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.
DefaultUserInteraction - Included
Instance Method Summary
-
#add_extra_args(args)
Adds extra args from ~/.gemrc.
-
#add_option(*opts, &handler)
Add a command-line option and handler to the command.
-
#arguments
Override to provide details of the arguments a command takes.
-
#begins?(long, short) ⇒ Boolean
True if
long
begins with the characters fromshort
. -
#defaults_str
Override to display the default values of the command options.
-
#description
Override to display a longer description of what this command does.
-
#execute
Override to provide command handling.
-
#get_all_gem_names
Get all gem names from the command line.
-
#get_all_gem_names_and_versions
Get all [gem, version] from the command line.
-
#get_one_gem_name
Get a single gem name from the command line.
-
#get_one_optional_argument
Get a single optional argument from the command line.
-
#handle_options(args)
Handle the given list of arguments by parsing them and recording the results.
-
#handles?(args) ⇒ Boolean
True if the command handles the given argument list.
-
#invoke(*args)
Invoke the command with the given list of arguments.
-
#invoke_with_build_args(args, build_args)
Invoke the command with the given list of normal arguments and additional build arguments.
-
#merge_options(new_options)
Merge a set of command options with the set of default options (without modifying the default option hash).
-
#remove_option(name)
Remove previously defined command-line argument
name
. -
#show_help
Display the help message for the command.
-
#show_lookup_failure(gem_name, version, errors, domain)
Display to the user that a gem couldn't be found and reasons why.
-
#usage
Override to display the usage for an individual gem command.
-
#when_invoked(&block)
Call the given block when invoked.
-
#add_parser_run_info(title, content)
private
Adds a section with
title
andcontent
to the parser help view. - #configure_options(header, option_list) private
-
#create_option_parser
private
Creates an option parser and fills it in with the help info for the command.
-
#parser
private
Create on demand parser.
-
#wrap(text, width)
private
Wraps
text
towidth
- #add_parser_description private Internal use only
- #add_parser_options private Internal use only
- #add_parser_summary private Internal use only
UserInteraction - Included
#alert | Displays an alert |
#alert_error | Displays an error |
#alert_warning | Displays a warning |
#ask | Asks a |
#ask_for_password | Asks for a password with a |
#ask_yes_no | Asks a yes or no |
#choose_from_list | Asks the user to answer |
#say | Displays the given |
#terminate_interaction | Terminates the RubyGems process with the given |
#verbose | Calls |
DefaultUserInteraction - Included
Text - Included
#clean_text | Remove any non-printable characters and make the text suitable for printing. |
#format_text | Wraps |
#levenshtein_distance | This code is based directly on the Text gem implementation Returns a value representing the “cost” of transforming str1 into str2. |
#truncate_text, #min3 |
Constructor Details
.new(command, summary = nil, defaults = {}) ⇒ 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.
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]
.
Class Attribute Details
.build_args (rw)
Arguments used when building gems
# File 'lib/rubygems/command.rb', line 51
def self.build_args @build_args ||= [] end
.build_args=(value) (rw)
[ GitHub ]# File 'lib/rubygems/command.rb', line 55
def self.build_args=(value) @build_args = value end
.extra_args (rw)
[ GitHub ]# File 'lib/rubygems/command.rb', line 67
def self.extra_args @extra_args ||= [] end
.extra_args=(value) (rw)
[ GitHub ]# File '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
Class Method Details
.add_common_option(*args, &handler)
[ GitHub ]# File 'lib/rubygems/command.rb', line 63
def self.add_common_option(*args, &handler) Gem::Command. << [args, handler] end
.add_specific_extra_args(cmd, args)
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 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
.common_options
[ GitHub ]# File 'lib/rubygems/command.rb', line 59
def self. @common_options ||= [] end
.specific_extra_args(cmd)
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 84
def self.specific_extra_args(cmd) specific_extra_args_hash[cmd] end
.specific_extra_args_hash
Accessor for the specific extra args hash (self initializing).
Instance Attribute Details
#command (readonly)
The name of the command.
# File 'lib/rubygems/command.rb', line 26
attr_reader :command
#defaults (rw)
The default options for the command.
# File 'lib/rubygems/command.rb', line 36
attr_accessor :defaults
#options (readonly)
The options for the command.
# File 'lib/rubygems/command.rb', line 31
attr_reader :
#program_name (rw)
The name of the command for command-line invocation.
# File 'lib/rubygems/command.rb', line 41
attr_accessor :program_name
#summary (rw)
A short description of the command.
# File 'lib/rubygems/command.rb', line 46
attr_accessor :summary
Instance Method Details
#add_extra_args(args)
Adds extra args from ~/.gemrc
# File '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
#add_option(*opts, &handler)
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 345
def add_option(*opts, &handler) # :yields: value, options group_name = Symbol === opts.first ? opts.shift : : @option_groups[group_name] << [opts, handler] end
#add_parser_description (private)
# File 'lib/rubygems/command.rb', line 415
def add_parser_description # :nodoc: return unless description formatted = description.split("\n\n").map do |chunk| wrap chunk, 80 - 4 end.join "\n" @parser.separator nil @parser.separator " Description:" formatted.split("\n").each do |line| @parser.separator " #{line.rstrip}" end end
#add_parser_options (private)
# File 'lib/rubygems/command.rb', line 429
def # :nodoc: @parser.separator nil = @option_groups.delete : "", @option_groups.sort_by { |n,_| n.to_s }.each do |group_name, option_list| @parser.separator nil group_name, option_list end end
#add_parser_run_info(title, content) (private)
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 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
#add_parser_summary (private)
# File 'lib/rubygems/command.rb', line 456
def add_parser_summary # :nodoc: return unless @summary @parser.separator nil @parser.separator " Summary:" wrap(@summary, 80 - 4).split("\n").each do |line| @parser.separator " #{line.strip}" end end
#arguments
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 245
def arguments "" end
#begins?(long, short) ⇒ Boolean
True if long
begins with the characters from short
.
# File 'lib/rubygems/command.rb', line 132
def begins?(long, short) return false if short.nil? long[0, short.length] == short end
#configure_options(header, option_list) (private)
[ GitHub ]# File 'lib/rubygems/command.rb', line 492
def (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
#create_option_parser (private)
Creates an option parser and fills it in with the help info for the command.
# File 'lib/rubygems/command.rb', line 478
def create_option_parser @parser = OptionParser.new @parser.separator nil "Common", Gem::Command. add_parser_run_info "Arguments", arguments add_parser_summary add_parser_description add_parser_run_info "Defaults", defaults_str end
#defaults_str
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 259
def defaults_str "" end
#description
Override to display a longer description of what this command does.
# File 'lib/rubygems/command.rb', line 266
def description nil end
#execute
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
#get_all_gem_names
Get all gem names from the command line.
# File 'lib/rubygems/command.rb', line 176
def get_all_gem_names args = [: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_and_versions
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 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_one_gem_name
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 206
def get_one_gem_name args = [: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_one_optional_argument
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 226
def get_one_optional_argument args = [:args] || [] args.first end
#handle_options(args)
Handle the given list of arguments by parsing them and recording the results.
# File 'lib/rubygems/command.rb', line 385
def (args) args = add_extra_args(args) @options = Marshal.load Marshal.dump @defaults # deep copy parser.parse!(args) @options[:args] = args end
#handles?(args) ⇒ Boolean
True if the command handles the given argument list.
# File 'lib/rubygems/command.rb', line 372
def handles?(args) begin parser.parse!(args.dup) return true rescue return false end end
#invoke(*args)
Invoke the command with the given list of arguments.
# File 'lib/rubygems/command.rb', line 290
def invoke(*args) invoke_with_build_args args, nil end
#invoke_with_build_args(args, build_args)
Invoke the command with the given list of normal arguments and additional build arguments.
# File 'lib/rubygems/command.rb', line 298
def invoke_with_build_args(args, build_args) args [:build_args] = build_args if [:silent] old_ui = self.ui self.ui = ui = Gem::SilentUI.new end if [:help] then show_help elsif @when_invoked then @when_invoked.call else execute end ensure if ui self.ui = old_ui ui.close end end
#merge_options(new_options)
Merge a set of command options with the set of default options (without modifying the default option hash).
# File 'lib/rubygems/command.rb', line 364
def ( ) @options = @defaults.clone .each do |k,v| @options[k] = v end end
#parser (private)
Create on demand parser.
# File 'lib/rubygems/command.rb', line 469
def parser create_option_parser if @parser.nil? @parser end
#remove_option(name)
Remove previously defined command-line argument name
.
# File '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
#show_help
Display the help message for the command.
# File 'lib/rubygems/command.rb', line 282
def show_help parser.program_name = usage say parser end
#show_lookup_failure(gem_name, version, errors, domain)
Display to the user that a gem couldn't be found and reasons why
# File '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
#usage
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 275
def usage program_name end
#when_invoked(&block)
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 330
def when_invoked(&block) @when_invoked = block end
#wrap(text, width) (private)
Wraps text
to width
# File 'lib/rubygems/command.rb', line 511
def wrap(text, width) # :doc: text.gsub(/(.{1,#{width}})( +|$\n?)|(.{1,#{width}})/, "\\1\\3\n") end