Revamp help command

COMPARED_WITH_PRY.md

@@ -9,7 +9,7 @@ Feel free to chip in and update this table - we appreciate your help!
 | Supported Rubies          | `>= 2.0`                                                                                                             | `>= 2.7`                                                                       |                                                                                                              |
 | Source code browsing      | `show-source`                                                                                                        | `show_source`                                                                  | IRB's `show_source` can't display C source. See [#664](https://github.com/ruby/irb/issues/664)               |
 | Document browsing         | `ri`                                                                                                                 | `show_doc`                                                                     |                                                                                                              |
-| Live help system          | `help` or `command_name --help`                                                                                      | `show_cmds`                                                                    | IRB doesn't support detailed descriptions for individual commands yet                                        |
+| Live help system          | `help` or `command_name --help`                                                                                      | `help`                                                                         | IRB doesn't support detailed descriptions for individual commands yet                                        |
 | Open methods in editors   | `edit`                                                                                                               | `edit`                                                                         |                                                                                                              |
 | Syntax highlighting       | Yes                                                                                                                  | Yes                                                                            |                                                                                                              |
 | Command shell integration | Yes                                                                                                                  | No                                                                             | Currently, there's no plan to support such features in IRB                                                   |

README.md

@@ -107,17 +107,19 @@ Hello World
 
 ## Commands
 
-The following commands are available on IRB. You can get the same output from the `show_cmds` command.
+The following commands are available on IRB. You can get the same output from the `help` command.
 
 ```txt
+Help
+  help           List all available commands. Use `help <command>` to get information about a specific command.
+
 IRB
   exit           Exit the current irb session.
   exit!          Exit the current process.
   irb_load       Load a Ruby file.
   irb_require    Require a Ruby file.
   source         Loads a given file in the current session.
   irb_info       Show information about IRB.
-  show_cmds      List all available commands and their description.
   history        Shows the input history. `-g [query]` or `-G [query]` allows you to filter the output.
 
 Workspace
@@ -146,13 +148,12 @@ Debugging
   info           Start the debugger of debug.gem and run its `info` command.
 
 Misc
-  edit           Open a file with the editor command defined with `ENV["VISUAL"]` or `ENV["EDITOR"]`.
+  edit           Open a file or source location.
   measure        `measure` enables the mode to measure processing time. `measure :off` disables it.
 
 Context
-  help           [DEPRECATED] Enter the mode to look up RI documents.
   show_doc       Enter the mode to look up RI documents.
-  ls             Show methods, constants, and variables. `-g [query]` or `-G [query]` allows you to filter out the output.
+  ls             Show methods, constants, and variables.
   show_source    Show the source code of a given method or constant.
   whereami       Show the source code around binding.irb again.
 
@@ -228,7 +229,7 @@ end
 
 To learn about these features, please refer to `debug.gem`'s [commands list](https://github.com/ruby/debug#debug-command-on-the-debug-console).
 
-In the `irb:rdbg` session, the `show_cmds` command will also display all commands from `debug.gem`.
+In the `irb:rdbg` session, the `help` command will also display all commands from `debug.gem`.
 
 ### Advantages Over `debug.gem`'s Console
 

lib/irb.rb

@@ -811,7 +811,7 @@
 #
 # === Commands
 #
-# Please use the `show_cmds` command to see the list of available commands.
+# Please use the `help` command to see the list of available commands.
 #
 # === IRB Sessions
 #

lib/irb/command.rb

@@ -162,6 +162,7 @@ def irb_context
       [
         :irb_help, :Help, "command/help",
         [:help, NO_OVERRIDE],
+        [:show_cmds, NO_OVERRIDE],
       ],
 
       [
@@ -187,16 +188,10 @@ def irb_context
         :irb_show_source, :ShowSource, "command/show_source",
         [:show_source, NO_OVERRIDE],
       ],
-
       [
         :irb_whereami, :Whereami, "command/whereami",
         [:whereami, NO_OVERRIDE],
       ],
-      [
-        :irb_show_cmds, :ShowCmds, "command/show_cmds",
-        [:show_cmds, NO_OVERRIDE],
-      ],
-
       [
         :irb_history, :History, "command/history",
         [:history, NO_OVERRIDE],

lib/irb/command/base.rb

@@ -22,12 +22,21 @@ def description(description = nil)
           @description
         end
 
+        def help_message(help_message = nil)
+          @help_message = help_message if help_message
+          @help_message
+        end
+
         private
 
         def string_literal?(args)
           sexp = Ripper.sexp(args)
           sexp && sexp.size == 2 && sexp.last&.first&.first == :string_literal
         end
+
+        def highlight(text)
+          Color.colorize(text, [:BOLD, :BLUE])
+        end
       end
 
       def self.execute(irb_context, *opts, **kwargs, &block)

lib/irb/command/edit.rb

@@ -8,7 +8,23 @@ module IRB
   module Command
     class Edit < Base
       category "Misc"
-      description 'Open a file with the editor command defined with `ENV["VISUAL"]` or `ENV["EDITOR"]`.'
+      description 'Open a file or source location.'
+      help_message <<~HELP_MESSAGE
+        Usage: edit [FILE or constant or method signature]
+
+        Open a file in the editor specified in #{highlight('ENV["VISUAL"]')} or #{highlight('ENV["EDITOR"]')}
+
+        - If no arguments are provided, IRB will attempt to open the file the current context was defined in.
+        - If FILE is provided, IRB will open the file.
+        - If a constant or method signature is provided, IRB will attempt to locate the source file and open it.
+
+        Examples:
+
+          edit
+          edit foo.rb
+          edit Foo
+          edit Foo#bar
+      HELP_MESSAGE
 
       class << self
         def transform_args(args)

lib/irb/command/help.rb

@@ -1,12 +1,84 @@
 # frozen_string_literal: true
 
-require_relative "show_cmds"
-
 module IRB
   module Command
-    class Help < ShowCmds
-      category "IRB"
-      description "List all available commands and their description."
+    class Help < Base
+      category "Help"
+      description "List all available commands. Use `help <command>` to get information about a specific command."
+
+      class << self
+        def transform_args(args)
+          # Return a string literal as is for backward compatibility
+          if args.empty? || string_literal?(args)
+            args
+          else # Otherwise, consider the input as a String for convenience
+            args.strip.dump
+          end
+        end
+      end
+
+      def execute(command_name = nil)
+        content =
+          if command_name
+            if command_class = ExtendCommandBundle.load_command(command_name)
+              command_class.help_message || command_class.description
+            else
+              "Can't find command `#{command_name}`. Please check the command name and try again.\n\n"
+            end
+          else
+            help_message
+          end
+        Pager.page_content(content)
+      end
+
+      private
+
+      def help_message
+        commands_info = IRB::ExtendCommandBundle.all_commands_info
+        commands_grouped_by_categories = commands_info.group_by { |cmd| cmd[:category] }
+
+        user_aliases = irb_context.instance_variable_get(:@user_aliases)
+
+        commands_grouped_by_categories["Aliases"] = user_aliases.map do |alias_name, target|
+          { display_name: alias_name, description: "Alias for `#{target}`" }
+        end
+
+        if irb_context.with_debugger
+          # Remove the original "Debugging" category
+          commands_grouped_by_categories.delete("Debugging")
+          # Add an empty "Debugging (from debug.gem)" category at the end
+          commands_grouped_by_categories["Debugging (from debug.gem)"] = []
+        end
+
+        longest_cmd_name_length = commands_info.map { |c| c[:display_name].length }.max
+
+        output = StringIO.new
+
+        help_cmds = commands_grouped_by_categories.delete("Help")
+
+        add_category_to_output("Help", help_cmds, output, longest_cmd_name_length)
+
+        commands_grouped_by_categories.each do |category, cmds|
+          add_category_to_output(category, cmds, output, longest_cmd_name_length)
+        end
+
+        # Append the debugger help at the end
+        if irb_context.with_debugger
+          output.puts DEBUGGER__.help
+        end
+
+        output.string
+      end
+
+      def add_category_to_output(category, cmds, output, longest_cmd_name_length)
+        output.puts Color.colorize(category, [:BOLD])
+
+        cmds.each do |cmd|
+          output.puts "  #{cmd[:display_name].to_s.ljust(longest_cmd_name_length)}    #{cmd[:description]}"
+        end
+
+        output.puts
+      end
     end
   end
 end

lib/irb/command/ls.rb

@@ -12,7 +12,13 @@ module IRB
   module Command
     class Ls < Base
       category "Context"
-      description "Show methods, constants, and variables. `-g [query]` or `-G [query]` allows you to filter out the output."
+      description "Show methods, constants, and variables."
+
+      help_message <<~HELP_MESSAGE
+        Usage: ls [obj] [-g [query]]
+
+          -g [query]  Filter the output with a query.
+      HELP_MESSAGE
 
       def self.transform_args(args)
         if match = args&.match(/\A(?<args>.+\s|)(-g|-G)\s+(?<grep>[^\s]+)\s*\n\z/)

lib/irb/statement.rb

@@ -83,9 +83,8 @@ def suppresses_echo?
       end
 
       def should_be_handled_by_debugger?
-        require_relative 'command/help'
         require_relative 'command/debug'
-        IRB::Command::DebugCommand > @command_class || IRB::Command::Help == @command_class
+        IRB::Command::DebugCommand > @command_class
       end
 
       def evaluable_code

test/irb/command/test_help.rb

@@ -0,0 +1,66 @@
+require "tempfile"
+require_relative "../helper"
+
+module TestIRB
+  class HelpTest < IntegrationTestCase
+    def setup
+      super
+
+      write_rc <<~'RUBY'
+        IRB.conf[:USE_PAGER] = false
+      RUBY
+
+      write_ruby <<~'RUBY'
+        binding.irb
+      RUBY
+    end
+
+    def test_help
+      out = run_ruby_file do
+        type "help"
+        type "exit"
+      end
+
+      assert_match(/List all available commands/, out)
+      assert_match(/Start the debugger of debug\.gem/, out)
+    end
+
+    def test_command_help
+      out = run_ruby_file do
+        type "help ls"
+        type "exit"
+      end
+
+      assert_match(/Usage: ls \[obj\]/, out)
+    end
+
+    def test_command_help_not_found
+      out = run_ruby_file do
+        type "help foo"
+        type "exit"
+      end
+
+      assert_match(/Can't find command `foo`\. Please check the command name and try again\./, out)
+    end
+
+    def test_show_cmds
+      out = run_ruby_file do
+        type "help"
+        type "exit"
+      end
+
+      assert_match(/List all available commands/, out)
+      assert_match(/Start the debugger of debug\.gem/, out)
+    end
+
+    def test_help_lists_user_aliases
+      out = run_ruby_file do
+        type "help"
+        type "exit"
+      end
+
+      assert_match(/\$\s+Alias for `show_source`/, out)
+      assert_match(/@\s+Alias for `whereami`/, out)
+    end
+  end
+end