lib/ruby-1.9.1-rc1/lib/rubygems/commands/help_command.rb

   1 require 'rubygems/command'
   2
   3 class Gem::Commands::HelpCommand < Gem::Command
   4
   5   # :stopdoc:
   6   EXAMPLES = <<-EOF
   7 Some examples of 'gem' usage.
   8
   9 * Install 'rake', either from local directory or remote server:
  10
  11     gem install rake
  12
  13 * Install 'rake', only from remote server:
  14
  15     gem install rake --remote
  16
  17 * Install 'rake' from remote server, and run unit tests,
  18   and generate RDocs:
  19
  20     gem install --remote rake --test --rdoc --ri
  21
  22 * Install 'rake', but only version 0.3.1, even if dependencies
  23   are not met, and into a user-specific directory:
  24
  25     gem install rake --version 0.3.1 --force --user-install
  26
  27 * List local gems whose name begins with 'D':
  28
  29     gem list D
  30
  31 * List local and remote gems whose name contains 'log':
  32
  33     gem search log --both
  34
  35 * List only remote gems whose name contains 'log':
  36
  37     gem search log --remote
  38
  39 * Uninstall 'rake':
  40
  41     gem uninstall rake
  42
  43 * Create a gem:
  44
  45     See http://rubygems.rubyforge.org/wiki/wiki.pl?CreateAGemInTenMinutes
  46
  47 * See information about RubyGems:
  48
  49     gem environment
  50
  51 * Update all gems on your system:
  52
  53     gem update
  54   EOF
  55
  56   PLATFORMS = <<-'EOF'
  57 RubyGems platforms are composed of three parts, a CPU, an OS, and a
  58 version.  These values are taken from values in rbconfig.rb.  You can view
  59 your current platform by running `gem environment`.
  60
  61 RubyGems matches platforms as follows:
  62
  63   * The CPU must match exactly, unless one of the platforms has
  64     "universal" as the CPU.
  65   * The OS must match exactly.
  66   * The versions must match exactly unless one of the versions is nil.
  67
  68 For commands that install, uninstall and list gems, you can override what
  69 RubyGems thinks your platform is with the --platform option.  The platform
  70 you pass must match "#{cpu}-#{os}" or "#{cpu}-#{os}-#{version}".  On mswin
  71 platforms, the version is the compiler version, not the OS version.  (Ruby
  72 compiled with VC6 uses "60" as the compiler version, VC8 uses "80".)
  73
  74 Example platforms:
  75
  76   x86-freebsd        # Any FreeBSD version on an x86 CPU
  77   universal-darwin-8 # Darwin 8 only gems that run on any CPU
  78   x86-mswin32-80     # Windows gems compiled with VC8
  79
  80 When building platform gems, set the platform in the gem specification to
  81 Gem::Platform::CURRENT.  This will correctly mark the gem with your ruby's
  82 platform.
  83   EOF
  84   # :startdoc:
  85
  86   def initialize
  87     super 'help', "Provide help on the 'gem' command"
  88   end
  89
  90   def arguments # :nodoc:
  91     args = <<-EOF
  92       commands      List all 'gem' commands
  93       examples      Show examples of 'gem' usage
  94       <command>     Show specific help for <command>
  95     EOF
  96     return args.gsub(/^\s+/, '')
  97   end
  98
  99   def usage # :nodoc:
 100     "#{program_name} ARGUMENT"
 101   end
 102
 103   def execute
 104     command_manager = Gem::CommandManager.instance
 105     arg = options[:args][0]
 106
 107     if begins? "commands", arg then
 108       out = []
 109       out << "GEM commands are:"
 110       out << nil
 111
 112       margin_width = 4
 113
 114       desc_width = command_manager.command_names.map { |n| n.size }.max + 4
 115
 116       summary_width = 80 - margin_width - desc_width
 117       wrap_indent = ' ' * (margin_width + desc_width)
 118       format = "#{' ' * margin_width}%-#{desc_width}s%s"
 119
 120       command_manager.command_names.each do |cmd_name|
 121         summary = command_manager[cmd_name].summary
 122         summary = wrap(summary, summary_width).split "\n"
 123         out << sprintf(format, cmd_name, summary.shift)
 124         until summary.empty? do
 125           out << "#{wrap_indent}#{summary.shift}"
 126         end
 127       end
 128
 129       out << nil
 130       out << "For help on a particular command, use 'gem help COMMAND'."
 131       out << nil
 132       out << "Commands may be abbreviated, so long as they are unambiguous."
 133       out << "e.g. 'gem i rake' is short for 'gem install rake'."
 134
 135       say out.join("\n")
 136
 137     elsif begins? "options", arg then
 138       say Gem::Command::HELP
 139
 140     elsif begins? "examples", arg then
 141       say EXAMPLES
 142
 143     elsif begins? "platforms", arg then
 144       say PLATFORMS
 145
 146     elsif options[:help] then
 147       command = command_manager[options[:help]]
 148       if command
 149         # help with provided command
 150         command.invoke("--help")
 151       else
 152         alert_error "Unknown command #{options[:help]}.  Try 'gem help commands'"
 153       end
 154
 155     elsif arg then
 156       possibilities = command_manager.find_command_possibilities(arg.downcase)
 157       if possibilities.size == 1
 158         command = command_manager[possibilities.first]
 159         command.invoke("--help")
 160       elsif possibilities.size > 1
 161         alert_warning "Ambiguous command #{arg} (#{possibilities.join(', ')})"
 162       else
 163         alert_warning "Unknown command #{arg}. Try gem help commands"
 164       end
 165
 166     else
 167       say Gem::Command::HELP
 168     end
 169   end
 170
 171 end
 172