diff options
Diffstat (limited to 'lib/rubygems/command.rb')
| -rw-r--r-- | lib/rubygems/command.rb | 743 |
1 files changed, 424 insertions, 319 deletions
diff --git a/lib/rubygems/command.rb b/lib/rubygems/command.rb index 860764e6d5..3a1e2ac872 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 + |