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