summaryrefslogtreecommitdiff
path: root/lib/rubygems/command.rb
diff options
context:
space:
mode:
authordrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2009-06-09 21:38:59 +0000
committerdrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2009-06-09 21:38:59 +0000
commit31c94ffeb5f09d09ac2c86fc9e6614e38251a43d (patch)
tree10e44506238c7af3d7c9d822111996731726e38d /lib/rubygems/command.rb
parenta6afbaeb3be396c0fdea3b9077d9256c59edcfca (diff)
Update to RubyGems 1.3.4 r2223
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@23659 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'lib/rubygems/command.rb')
-rw-r--r--lib/rubygems/command.rb743
1 files changed, 424 insertions, 319 deletions
diff --git a/lib/rubygems/command.rb b/lib/rubygems/command.rb
index 860764e..3a1e2ac 100644
--- a/lib/rubygems/command.rb
+++ b/lib/rubygems/command.rb
@@ -5,402 +5,507 @@
#++
require 'optparse'
-
require 'rubygems/user_interaction'
-module Gem
+##
+# Base class for all Gem commands. When creating a new gem command, define
+# #new, #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
- # Base class for all Gem commands. When creating a new gem command, define
- # #arguments, #defaults_str, #description and #usage (as appropriate).
- class Command
+class Gem::Command
- include UserInteraction
+ include Gem::UserInteraction
- # The name of the command.
- attr_reader :command
+ ##
+ # The name of the command.
- # The options for the command.
- attr_reader :options
+ attr_reader :command
- # The default options for the command.
- attr_accessor :defaults
+ ##
+ # The options for the command.
- # The name of the command for command-line invocation.
- attr_accessor :program_name
+ attr_reader :options
- # A short description of the command.
- attr_accessor :summary
+ ##
+ # The default options for the 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.
- #
- # Use add_option to add command-line switches.
- 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
+ attr_accessor :defaults
- # True if +long+ begins with the characters from +short+.
- def begins?(long, short)
- return false if short.nil?
- long[0, short.length] == short
- end
+ ##
+ # The name of the command for command-line invocation.
- # Override to provide command handling.
- def execute
- fail "Generic command has no actions"
- end
+ attr_accessor :program_name
- # Get all gem names from the command line.
- def get_all_gem_names
- args = options[:args]
+ ##
+ # A short description of the command.
- if args.nil? or args.empty? then
- raise Gem::CommandLineError,
- "Please specify at least one gem name (e.g. gem build GEMNAME)"
- end
+ attr_accessor :summary
- gem_names = args.select { |arg| arg !~ /^-/ }
- end
+ ##
+ # Arguments used when building gems
- # Get the single gem name from the command line. Fail if there is no gem
- # name or if there is more than one gem name given.
- def get_one_gem_name
- args = options[:args]
+ def self.build_args
+ @build_args ||= []
+ end
+
+ def self.build_args=(value)
+ @build_args = value
+ end
- 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
+ def self.common_options
+ @common_options ||= []
+ end
- if args.size > 1 then
- raise Gem::CommandLineError,
- "Too many gem names (#{args.join(', ')}); please specify only one"
- end
+ def self.add_common_option(*args, &handler)
+ Gem::Command.common_options << [args, handler]
+ end
- args.first
- end
+ def self.extra_args
+ @extra_args ||= []
+ 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.
- def get_one_optional_argument
- args = options[:args] || []
- args.first
+ def self.extra_args=(value)
+ case value
+ when Array
+ @extra_args = value
+ when String
+ @extra_args = value.split
end
+ end
- # Override to provide details of the arguments a command takes.
- # It should return a left-justified string, one argument per line.
- def arguments
- ""
- end
+ ##
+ # Return an array of extra arguments for the command. The extra arguments
+ # come from the gem configuration file read at program startup.
- # Override to display the default values of the command
- # options. (similar to +arguments+, but displays the default
- # values).
- def defaults_str
- ""
- end
+ def self.specific_extra_args(cmd)
+ specific_extra_args_hash[cmd]
+ end
- # Override to display a longer description of what this command does.
- def description
- nil
- 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.
- # Override to display the usage for an individual gem command.
- def usage
- program_name
- end
+ def self.add_specific_extra_args(cmd,args)
+ args = args.split(/\s+/) if args.kind_of? String
+ specific_extra_args_hash[cmd] = args
+ end
- # Display the help message for the command.
- def show_help
- parser.program_name = usage
- say parser
- end
+ ##
+ # Accessor for the specific extra args hash (self initializing).
- # Invoke the command with the given list of arguments.
- def invoke(*args)
- handle_options(args)
- if options[:help]
- show_help
- elsif @when_invoked
- @when_invoked.call(options)
- else
- execute
- end
+ def self.specific_extra_args_hash
+ @specific_extra_args_hash ||= Hash.new do |h,k|
+ h[k] = Array.new
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.
- def when_invoked(&block)
- @when_invoked = block
+ 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
+ # <tt>options[:args]</tt>.
+
+ 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
+
+ ##
+ # True if +long+ begins with the characters from +short+.
+
+ def begins?(long, short)
+ return false if short.nil?
+ long[0, short.length] == short
+ end
+
+ ##
+ # Override to provide command handling.
+ #
+ # #options will be filled in with your parsed options, unparsed options will
+ # be left in <tt>options[:args]</tt>.
+ #
+ # See also: #get_all_gem_names, #get_one_gem_name,
+ # #get_one_optional_argument
+
+ def execute
+ raise Gem::Exception, "generic command has no actions"
+ end
+
+ ##
+ # Get all gem names from the command line.
+
+ 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
- # 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.
- def add_option(*opts, &handler) # :yields: value, options
- group_name = Symbol === opts.first ? opts.shift : :options
+ gem_names = args.select { |arg| arg !~ /^-/ }
+ end
- @option_groups[group_name] << [opts, handler]
- end
+ ##
+ # Get the single gem name from the command line. Fail if there is no gem
+ # name or if there is more than one gem name given.
- # Remove previously defined command-line argument +name+.
- def remove_option(name)
- @option_groups.each do |_, option_list|
- option_list.reject! { |args, _| args.any? { |x| x =~ /^#{name}/ } }
- end
- end
+ def get_one_gem_name
+ args = options[:args]
- # Merge a set of command options with the set of default options
- # (without modifying the default option hash).
- def merge_options(new_options)
- @options = @defaults.clone
- new_options.each do |k,v| @options[k] = v end
+ 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
- # True if the command handles the given argument list.
- def handles?(args)
- begin
- parser.parse!(args.dup)
- return true
- rescue
- return false
- end
+ if args.size > 1 then
+ raise Gem::CommandLineError,
+ "Too many gem names (#{args.join(', ')}); please specify only one"
end
- # Handle the given list of arguments by parsing them and recording
- # the results.
- def handle_options(args)
- args = add_extra_args(args)
- @options = @defaults.clone
- parser.parse!(args)
- @options[:args] = 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.
+
+ def get_one_optional_argument
+ args = options[:args] || []
+ args.first
+ 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
+
+ def arguments
+ ""
+ 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
+
+ def defaults_str
+ ""
+ end
+
+ ##
+ # Override to display a longer description of what this command does.
+
+ def description
+ nil
+ end
+
+ ##
+ # Override to display the usage for an individual gem command.
+ #
+ # The text "[options]" is automatically appended to the usage text.
+
+ def usage
+ program_name
+ end
+
+ ##
+ # Display the help message for the command.
+
+ def show_help
+ parser.program_name = usage
+ say parser
+ end
+
+ ##
+ # Invoke the command with the given list of arguments.
+
+ def invoke(*args)
+ handle_options(args)
+ if options[:help]
+ show_help
+ elsif @when_invoked
+ @when_invoked.call(options)
+ else
+ execute
end
-
- def add_extra_args(args)
- result = []
- s_extra = Command.specific_extra_args(@command)
- extra = Command.extra_args + s_extra
- while ! extra.empty?
- 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
+
+ ##
+ # 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.
+
+ def when_invoked(&block)
+ @when_invoked = block
+ 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.
+
+ def add_option(*opts, &handler) # :yields: value, options
+ group_name = Symbol === opts.first ? opts.shift : :options
+
+ @option_groups[group_name] << [opts, handler]
+ end
+
+ ##
+ # Remove previously defined command-line argument +name+.
+
+ def remove_option(name)
+ @option_groups.each do |_, option_list|
+ option_list.reject! { |args, _| args.any? { |x| x =~ /^#{name}/ } }
end
-
- private
-
- # Create on demand parser.
- def parser
- create_option_parser if @parser.nil?
- @parser
+ end
+
+ ##
+ # Merge a set of command options with the set of default options (without
+ # modifying the default option hash).
+
+ def merge_options(new_options)
+ @options = @defaults.clone
+ new_options.each do |k,v| @options[k] = v end
+ end
+
+ ##
+ # True if the command handles the given argument list.
+
+ def handles?(args)
+ begin
+ parser.parse!(args.dup)
+ return true
+ rescue
+ return false
end
+ end
- def create_option_parser
- @parser = OptionParser.new
-
- @parser.separator("")
- regular_options = @option_groups.delete :options
-
- configure_options "", regular_options
-
- @option_groups.sort_by { |n,_| n.to_s }.each do |group_name, option_list|
- configure_options group_name, option_list
- end
-
- configure_options "Common", Command.common_options
+ ##
+ # Handle the given list of arguments by parsing them and recording the
+ # results.
- @parser.separator("")
- unless arguments.empty?
- @parser.separator(" Arguments:")
- arguments.split(/\n/).each do |arg_desc|
- @parser.separator(" #{arg_desc}")
- end
- @parser.separator("")
- end
+ def handle_options(args)
+ args = add_extra_args(args)
+ @options = @defaults.clone
+ parser.parse!(args)
+ @options[:args] = args
+ end
- @parser.separator(" Summary:")
- wrap(@summary, 80 - 4).split("\n").each do |line|
- @parser.separator(" #{line.strip}")
- end
+ ##
+ # Adds extra args from ~/.gemrc
- if description then
- formatted = description.split("\n\n").map do |chunk|
- wrap(chunk, 80 - 4)
- end.join("\n")
+ def add_extra_args(args)
+ result = []
- @parser.separator ""
- @parser.separator " Description:"
- formatted.split("\n").each do |line|
- @parser.separator " #{line.rstrip}"
- end
- end
+ s_extra = Gem::Command.specific_extra_args(@command)
+ extra = Gem::Command.extra_args + s_extra
- unless defaults_str.empty?
- @parser.separator("")
- @parser.separator(" Defaults:")
- defaults_str.split(/\n/).each do |line|
- @parser.separator(" #{line}")
- end
- end
+ until extra.empty? do
+ ex = []
+ ex << extra.shift
+ ex << extra.shift if extra.first.to_s =~ /^[^-]/
+ result << ex if handles?(ex)
end
- def configure_options(header, option_list)
- return if option_list.nil? or option_list.empty?
+ result.flatten!
+ result.concat(args)
+ result
+ end
- header = header.to_s.empty? ? '' : "#{header} "
- @parser.separator " #{header}Options:"
+ private
- option_list.each do |args, handler|
- dashes = args.select { |arg| arg =~ /^-/ }
- @parser.on(*args) do |value|
- handler.call(value, @options)
- end
- end
+ ##
+ # Create on demand parser.
- @parser.separator ''
- end
+ def parser
+ create_option_parser if @parser.nil?
+ @parser
+ end
- # Wraps +text+ to +width+
- def wrap(text, width)
- text.gsub(/(.{1,#{width}})( +|$\n?)|(.{1,#{width}})/, "\\1\\3\n")
- end
-
- ##################################################################
- # Class methods for Command.
- class << self
- def common_options
- @common_options ||= []
- end
+ def create_option_parser
+ @parser = OptionParser.new
- def add_common_option(*args, &handler)
- Gem::Command.common_options << [args, handler]
- end
+ @parser.separator("")
+ regular_options = @option_groups.delete :options
- def extra_args
- @extra_args ||= []
- end
-
- def extra_args=(value)
- case value
- when Array
- @extra_args = value
- when String
- @extra_args = value.split
- end
- end
+ configure_options "", regular_options
- # Return an array of extra arguments for the command. The extra
- # arguments come from the gem configuration file read at program
- # startup.
- def specific_extra_args(cmd)
- specific_extra_args_hash[cmd]
- end
+ @option_groups.sort_by { |n,_| n.to_s }.each do |group_name, option_list|
+ configure_options group_name, option_list
+ 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.
- def add_specific_extra_args(cmd,args)
- args = args.split(/\s+/) if args.kind_of? String
- specific_extra_args_hash[cmd] = args
- end
+ configure_options "Common", Gem::Command.common_options
- # Accessor for the specific extra args hash (self initializing).
- def specific_extra_args_hash
- @specific_extra_args_hash ||= Hash.new do |h,k|
- h[k] = Array.new
- end
+ @parser.separator("")
+ unless arguments.empty?
+ @parser.separator(" Arguments:")
+ arguments.split(/\n/).each do |arg_desc|
+ @parser.separator(" #{arg_desc}")
end
+ @parser.separator("")
end
- # ----------------------------------------------------------------
- # Add the options common to all commands.
-
- add_common_option('-h', '--help',
- 'Get help on this command') do
- |value, options|
- options[:help] = true
+ @parser.separator(" Summary:")
+ wrap(@summary, 80 - 4).split("\n").each do |line|
+ @parser.separator(" #{line.strip}")
end
- add_common_option('-V', '--[no-]verbose',
- 'Set the verbose level of output') do |value, options|
- # Set us to "really verbose" so the progress meter works
- if Gem.configuration.verbose and value then
- Gem.configuration.verbose = 1
- else
- Gem.configuration.verbose = value
+ if description then
+ formatted = description.split("\n\n").map do |chunk|
+ wrap(chunk, 80 - 4)
+ end.join("\n")
+
+ @parser.separator ""
+ @parser.separator " Description:"
+ formatted.split("\n").each do |line|
+ @parser.separator " #{line.rstrip}"
end
end
- add_common_option('-q', '--quiet', 'Silence commands') do |value, options|
- Gem.configuration.verbose = false
+ unless defaults_str.empty?
+ @parser.separator("")
+ @parser.separator(" Defaults:")
+ defaults_str.split(/\n/).each do |line|
+ @parser.separator(" #{line}")
+ end
end
+ end
- # Backtrace and config-file are added so they show up in the help
- # commands. Both options are actually handled before the other
- # options get parsed.
+ def configure_options(header, option_list)
+ return if option_list.nil? or option_list.empty?
- add_common_option('--config-file FILE',
- "Use this config file instead of default") do
- end
+ header = header.to_s.empty? ? '' : "#{header} "
+ @parser.separator " #{header}Options:"
- add_common_option('--backtrace',
- 'Show stack backtrace on errors') do
+ option_list.each do |args, handler|
+ dashes = args.select { |arg| arg =~ /^-/ }
+ @parser.on(*args) do |value|
+ handler.call(value, @options)
+ end
end
- add_common_option('--debug',
- 'Turn on Ruby debugging') do
- end
+ @parser.separator ''
+ end
- # :stopdoc:
- HELP = %{
- RubyGems is a sophisticated package manager for Ruby. This is a
- basic help message containing pointers to more information.
+ ##
+ # Wraps +text+ to +width+
- Usage:
- gem -h/--help
- gem -v/--version
- gem command [arguments...] [options...]
+ def wrap(text, width) # :doc:
+ text.gsub(/(.{1,#{width}})( +|$\n?)|(.{1,#{width}})/, "\\1\\3\n")
+ end
- Examples:
- gem install rake
- gem list --local
- gem build package.gemspec
- gem help install
+ # ----------------------------------------------------------------
+ # Add the options common to all commands.
- Further help:
- gem help commands list all 'gem' commands
- gem help examples show some examples of usage
- gem help platforms show information about platforms
- gem help <COMMAND> show help on COMMAND
- (e.g. 'gem help install')
- Further information:
- http://rubygems.rubyforge.org
- }.gsub(/^ /, "")
+ add_common_option('-h', '--help',
+ 'Get help on this command') do |value, options|
+ options[:help] = true
+ end
- # :startdoc:
+ add_common_option('-V', '--[no-]verbose',
+ 'Set the verbose level of output') do |value, options|
+ # Set us to "really verbose" so the progress meter works
+ if Gem.configuration.verbose and value then
+ Gem.configuration.verbose = 1
+ else
+ Gem.configuration.verbose = value
+ end
+ end
+
+ add_common_option('-q', '--quiet', 'Silence commands') do |value, options|
+ Gem.configuration.verbose = false
+ end
+
+ # Backtrace and config-file are added so they show up in the help
+ # commands. Both options are actually handled before the other
+ # options get parsed.
+
+ add_common_option('--config-file FILE',
+ 'Use this config file instead of default') do
+ end
+
+ add_common_option('--backtrace',
+ 'Show stack backtrace on errors') do
+ end
+
+ add_common_option('--debug',
+ 'Turn on Ruby debugging') do
+ end
+
+ # :stopdoc:
+
+ 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 platforms show information about platforms
+ 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://rubygems.rubyforge.org
+ }.gsub(/^ /, '')
+
+ # :startdoc:
- end # class
+end
- # This is where Commands will be placed in the namespace
- module Commands; end
+##
+# This is where Commands will be placed in the namespace
+module Gem::Commands
end
+