Support command extension APIs

[Stan Lo]

Description

Since version 1.6, IRB's built-in commands now have category and description attributes and can be listed in the show_cmds command's output. This greatly improved feature discovery and made IRB easier to use.

However, because IRB doesn't have official APIs for custom commands, they are currently defined as context methods. This means those commands won't be listed in the show_cmds output.

We should start thinking about command extension APIs to increase custom commands' discoverability as well.

Details

I want the command definition and related APIs to be similar to Pry's, as I believe its design is intuitive and this could help Pry extension authors get familiar with this new spec more easily.

Command Definition

module IRB
  module Command
    class MyCommand < Command::Base
      category "my_category"
      description "This is my command for xyz"
      aliases ["foo", "bar"]

      def execute(arg_string)
      end
    end
  end
end

Some notes:

• IRB::Command should be a better namespace than IRB::ExtendCommand
• Similarly, IRB::Command::Base should be better than IRB::ExtendCommand::Nop
• To simplify command handling on IRB part, I prefer directly passing the arg string to the command and let command author do the rest.
• Command name will be inferred from the class's name. In this case, it'll be my_command.

Command Registration

IRB::ExtendedCommandBundle.add_command(IRB::Command::MyCommand)

• Letting users register with the command class is way easier than asking them to figure out how to load the command lazily. It also simplifies IRB's implementation.
• If we register the command this way, we can also just let users define aliases in the command class.
• While I do worry a bit about loading commands eagerly would slow down IRB boot time, I don't have any actual data for it. Perhaps it's not a valid concern after all.

Command Invocation

• my_command arg1 arg2 will call MyCommand#execute with arg_string = "arg1 arg2"
  • foo arg1 arg2 and bar arg1 arg2 will work this way too
• my_command(arg1, arg2) will call the my_command method on the current object.
  • Commands can't be used as methods

Possible First Adopters

• Rails
  • Current commands (they should be considered helpers so #588 should be a better option)
  • We can also port rails routes and rails middlewares using the new APIs
• irbtools
  • It actually already extends commands with "unofficial" ways in order to utilize the new command attributes.

[HASUMI Hitoshi]

This is just an idea:
It'd be good if the authors of a command can easily define a short-hand alias for a command including options.
eg) measure_off for measure :off (it's hardly shortened, lol, but I believe you get what I mean.

Defining an alias by an IRB user is also worth discussing, I think :)