irb 1.12.0 → 1.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ef257bd1b4917c3af8f4e1c372cb7c489cd16844df518e352c0bff74c77b4fc
-  data.tar.gz: e9cd328330de9c415b93f680228ff79c3a798c481fe657bc48f7d7305470462c
+  metadata.gz: e4425b668e9f62b7535ef0db6b790b8e15a0ca62d4b81461d758c645c6043496
+  data.tar.gz: 36977d4a243c9acbc057729ff7bd6ea2432f8cfdb4013e7e4f2c05bebef26c70
 SHA512:
-  metadata.gz: 78b5b33588812cda49274b45e7b905cec8cb9e6b0ed71be66a644680db5ac96a19e276952425ec54a05d2ce3e8cf99b69eb7964e310770e155ced4f51501b088
-  data.tar.gz: 68ae7b61704a3356a14d526bdf058306c9ef158d8442030779b9256a59bee2929e1bab1fdf394f39bda09479b47430ca1de94c57c7b23017affec1400975e03a
+  metadata.gz: 804b6fa04f60f7ecc3bf98a9aa818fd8a0e177528c455ac46e853683463176b3eb651eb81e079b70870d2c4f55ab99d4292f10563f42b4c50d697e8e9684b810
+  data.tar.gz: 0f554e6950eda72508cf3af5eb4c446fc0584eec20c843cbf7ae653698b233add55251028dcf7a4991df5dfdfb90956589b728d727d4deb9e64cfe524349aab5

data/README.md

@@ -351,21 +351,13 @@ irb(main):002> a.first. # Completes Integer methods
 
 ## Documentation
 
-https://docs.ruby-lang.org/en/master/IRB.html
+https://ruby.github.io/irb/
 
 ## Extending IRB
 
-IRB is currently going through some refactoring to bring in some cool improvements and make things more flexible for developers.
-We know that in the past, due to a lack of public APIs and documentation, many of you have had to use IRB's private APIs
-and components to extend it. We also know that changes can be a bit annoying and might mess with your current setup.
+IRB `v1.13.0` and later versions allows users/libraries to extend its functionality through official APIs.
 
-We're sorry if this causes a bit of a scramble. We're working hard to make IRB better and your input is super important to us.
-If you've been using private APIs or components in your projects, we'd love to hear about your use cases. Please feel free to file a new issue. Your feedback will be a massive help in guiding us on how to design and prioritize the development of official APIs in the future.
-
-Right now, we've got command extension APIs on the drawing board, as you can see in [#513](https://github.com/ruby/irb/issues/513).
-We've also got a prototype for helper method extension APIs in the works, as shown in [#588](https://github.com/ruby/irb/issues/588).
-
-We really appreciate your understanding and patience during this transition. We're pretty excited about the improvements these changes will bring to the IRB ecosystem and we hope you are too!
+For more information, please visit [EXTEND_IRB.md](./EXTEND_IRB.md).
 
 ## Development
 

data/Rakefile

@@ -1,5 +1,6 @@
 require "bundler/gem_tasks"
 require "rake/testtask"
+require "rdoc/task"
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test" << "test/lib"
@@ -42,3 +43,12 @@ Rake::TestTask.new(:test_yamatanooroti) do |t|
 end
 
 task :default => :test
+
+RDoc::Task.new do |rdoc|
+  rdoc.title = "IRB"
+  rdoc.rdoc_files.include("*.md", "lib/**/*.rb")
+  rdoc.rdoc_files.exclude("lib/irb/xmp.rb")
+  rdoc.rdoc_dir = "docs"
+  rdoc.main = "README.md"
+  rdoc.options.push("--copy-files", "LICENSE.txt")
+end

data/irb.gemspec

@@ -42,5 +42,5 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = Gem::Requirement.new(">= 2.7")
 
   spec.add_dependency "reline", ">= 0.4.2"
-  spec.add_dependency "rdoc"
+  spec.add_dependency "rdoc", ">= 4.0.0"
 end

data/lib/irb/cmd/nop.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 
 # This file is just a placeholder for backward-compatibility.
-# Please require 'irb' and inheirt your command from `IRB::Command::Base` instead.
+# Please require 'irb' and inherit your command from `IRB::Command::Base` instead.

data/lib/irb/color.rb

@@ -79,12 +79,12 @@ module IRB # :nodoc:
 
     class << self
       def colorable?
-        supported = $stdout.tty? && (/mswin|mingw/ =~ RUBY_PLATFORM || (ENV.key?('TERM') && ENV['TERM'] != 'dumb'))
+        supported = $stdout.tty? && (/mswin|mingw/.match?(RUBY_PLATFORM) || (ENV.key?('TERM') && ENV['TERM'] != 'dumb'))
 
         # because ruby/debug also uses irb's color module selectively,
         # irb won't be activated in that case.
         if IRB.respond_to?(:conf)
-          supported && IRB.conf.fetch(:USE_COLORIZE, true)
+          supported && !!IRB.conf.fetch(:USE_COLORIZE, true)
         else
           supported
         end

data/lib/irb/command/backtrace.rb

@@ -7,12 +7,8 @@ module IRB
 
   module Command
     class Backtrace < DebugCommand
-      def self.transform_args(args)
-        args&.dump
-      end
-
-      def execute(*args)
-        super(pre_cmds: ["backtrace", *args].join(" "))
+      def execute(arg)
+        execute_debug_command(pre_cmds: "backtrace #{arg}")
       end
     end
   end

data/lib/irb/command/base.rb

@@ -10,6 +10,10 @@ module IRB
   module Command
     class CommandArgumentError < StandardError; end
 
+    def self.extract_ruby_args(*args, **kwargs)
+      throw :EXTRACT_RUBY_ARGS, [args, kwargs]
+    end
+
     class Base
       class << self
         def category(category = nil)
@@ -29,19 +33,13 @@ module IRB
 
         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)
-        command = new(irb_context)
-        command.execute(*opts, **kwargs, &block)
+      def self.execute(irb_context, arg)
+        new(irb_context).execute(arg)
       rescue CommandArgumentError => e
         puts e.message
       end
@@ -52,7 +50,7 @@ module IRB
 
       attr_reader :irb_context
 
-      def execute(*opts)
+      def execute(arg)
         #nop
       end
     end

data/lib/irb/command/break.rb

@@ -7,12 +7,8 @@ module IRB
 
   module Command
     class Break < DebugCommand
-      def self.transform_args(args)
-        args&.dump
-      end
-
-      def execute(args = nil)
-        super(pre_cmds: "break #{args}")
+      def execute(arg)
+        execute_debug_command(pre_cmds: "break #{arg}")
       end
     end
   end

data/lib/irb/command/catch.rb

@@ -7,12 +7,8 @@ module IRB
 
   module Command
     class Catch < DebugCommand
-      def self.transform_args(args)
-        args&.dump
-      end
-
-      def execute(*args)
-        super(pre_cmds: ["catch", *args].join(" "))
+      def execute(arg)
+        execute_debug_command(pre_cmds: "catch #{arg}")
       end
     end
   end

data/lib/irb/command/chws.rb

@@ -14,8 +14,8 @@ module IRB
       category "Workspace"
       description "Show the current workspace."
 
-      def execute(*obj)
-        irb_context.main
+      def execute(_arg)
+        puts "Current workspace: #{irb_context.main}"
       end
     end
 
@@ -23,9 +23,15 @@ module IRB
       category "Workspace"
       description "Change the current workspace to an object."
 
-      def execute(*obj)
-        irb_context.change_workspace(*obj)
-        irb_context.main
+      def execute(arg)
+        if arg.empty?
+          irb_context.change_workspace
+        else
+          obj = eval(arg, irb_context.workspace.binding)
+          irb_context.change_workspace(obj)
+        end
+
+        puts "Current workspace: #{irb_context.main}"
       end
     end
   end

data/lib/irb/command/context.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module IRB
+  module Command
+    class Context < Base
+      category "IRB"
+      description "Displays current configuration."
+
+      def execute(_arg)
+        # This command just displays the configuration.
+        # Modifying the configuration is achieved by sending a message to IRB.conf.
+        Pager.page_content(IRB.CurrentContext.inspect)
+      end
+    end
+  end
+end

data/lib/irb/command/continue.rb

@@ -7,8 +7,8 @@ module IRB
 
   module Command
     class Continue < DebugCommand
-      def execute(*args)
-        super(do_cmds: ["continue", *args].join(" "))
+      def execute(arg)
+        execute_debug_command(do_cmds: "continue #{arg}")
       end
     end
   end

data/lib/irb/command/debug.rb

@@ -13,7 +13,14 @@ module IRB
         binding.method(:irb).source_location.first,
       ].map { |file| /\A#{Regexp.escape(file)}:\d+:in (`|'Binding#)irb'\z/ }
 
-      def execute(pre_cmds: nil, do_cmds: nil)
+      def execute(_arg)
+        execute_debug_command
+      end
+
+      def execute_debug_command(pre_cmds: nil, do_cmds: nil)
+        pre_cmds = pre_cmds&.rstrip
+        do_cmds = do_cmds&.rstrip
+
         if irb_context.with_debugger
           # If IRB is already running with a debug session, throw the command and IRB.debug_readline will pass it to the debugger.
           if cmd = pre_cmds || do_cmds

data/lib/irb/command/delete.rb

@@ -7,8 +7,8 @@ module IRB
 
   module Command
     class Delete < DebugCommand
-      def execute(*args)
-        super(pre_cmds: ["delete", *args].join(" "))
+      def execute(arg)
+        execute_debug_command(pre_cmds: "delete #{arg}")
       end
     end
   end

data/lib/irb/command/disable_irb.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module IRB
+  # :stopdoc:
+
+  module Command
+    class DisableIrb < Base
+      category "IRB"
+      description "Disable binding.irb."
+
+      def execute(*)
+        ::Binding.define_method(:irb) {}
+        IRB.irb_exit
+      end
+    end
+  end
+
+  # :startdoc:
+end

data/lib/irb/command/edit.rb

@@ -1,5 +1,6 @@
 require 'shellwords'
 
+require_relative "../color"
 require_relative "../source_finder"
 
 module IRB
@@ -7,6 +8,8 @@ module IRB
 
   module Command
     class Edit < Base
+      include RubyArgsExtractor
+
       category "Misc"
       description 'Open a file or source location.'
       help_message <<~HELP_MESSAGE
@@ -26,19 +29,9 @@ module IRB
           edit Foo#bar
       HELP_MESSAGE
 
-      class << self
-        def transform_args(args)
-          # Return a string literal as is for backward compatibility
-          if args.nil? || args.empty? || string_literal?(args)
-            args
-          else # Otherwise, consider the input as a String for convenience
-            args.strip.dump
-          end
-        end
-      end
-
-      def execute(*args)
-        path = args.first
+      def execute(arg)
+        # Accept string literal for backward compatibility
+        path = unwrap_string_literal(arg)
 
         if path.nil?
           path = @irb_context.irb_path

data/lib/irb/command/exit.rb

@@ -8,10 +8,8 @@ module IRB
       category "IRB"
       description "Exit the current irb session."
 
-      def execute(*)
+      def execute(_arg)
         IRB.irb_exit
-      rescue UncaughtThrowError
-        Kernel.exit
       end
     end
   end

data/lib/irb/command/finish.rb

@@ -7,8 +7,8 @@ module IRB
 
   module Command
     class Finish < DebugCommand
-      def execute(*args)
-        super(do_cmds: ["finish", *args].join(" "))
+      def execute(arg)
+        execute_debug_command(do_cmds: "finish #{arg}")
       end
     end
   end

data/lib/irb/command/force_exit.rb

@@ -8,10 +8,8 @@ module IRB
       category "IRB"
       description "Exit the current process."
 
-      def execute(*)
+      def execute(_arg)
         throw :IRB_EXIT, true
-      rescue UncaughtThrowError
-        Kernel.exit!
       end
     end
   end

data/lib/irb/command/help.rb

@@ -6,27 +6,16 @@ module IRB
       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)
+      def execute(command_name)
         content =
-          if command_name
-            if command_class = ExtendCommandBundle.load_command(command_name)
+          if command_name.empty?
+            help_message
+          else
+            if command_class = Command.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
@@ -34,8 +23,10 @@ module IRB
       private
 
       def help_message
-        commands_info = IRB::ExtendCommandBundle.all_commands_info
+        commands_info = IRB::Command.all_commands_info
+        helper_methods_info = IRB::HelperMethod.all_helper_methods_info
         commands_grouped_by_categories = commands_info.group_by { |cmd| cmd[:category] }
+        commands_grouped_by_categories["Helper methods"] = helper_methods_info
 
         user_aliases = irb_context.instance_variable_get(:@user_aliases)
 

data/lib/irb/command/history.rb

@@ -12,14 +12,12 @@ module IRB
       category "IRB"
       description "Shows the input history. `-g [query]` or `-G [query]` allows you to filter the output."
 
-      def self.transform_args(args)
-        match = args&.match(/(-g|-G)\s+(?<grep>.+)\s*\n\z/)
-        return unless match
+      def execute(arg)
 
-        "grep: #{Regexp.new(match[:grep]).inspect}"
-      end
+        if (match = arg&.match(/(-g|-G)\s+(?<grep>.+)\s*\n\z/))
+          grep = Regexp.new(match[:grep])
+        end
 
-      def execute(grep: nil)
         formatted_inputs = irb_context.io.class::HISTORY.each_with_index.reverse_each.filter_map do |input, index|
           next if grep && !input.match?(grep)
 

data/lib/irb/command/info.rb

@@ -7,12 +7,8 @@ module IRB
 
   module Command
     class Info < DebugCommand
-      def self.transform_args(args)
-        args&.dump
-      end
-
-      def execute(*args)
-        super(pre_cmds: ["info", *args].join(" "))
+      def execute(arg)
+        execute_debug_command(pre_cmds: "info #{arg}")
       end
     end
   end

data/lib/irb/command/internal_helpers.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module IRB
+  module Command
+    # Internal use only, for default command's backward compatibility.
+    module RubyArgsExtractor # :nodoc:
+      def unwrap_string_literal(str)
+        return if str.empty?
+
+        sexp = Ripper.sexp(str)
+        if sexp && sexp.size == 2 && sexp.last&.first&.first == :string_literal
+          @irb_context.workspace.binding.eval(str).to_s
+        else
+          str
+        end
+      end
+
+      def ruby_args(arg)
+        # Use throw and catch to handle arg that includes `;`
+        # For example: "1, kw: (2; 3); 4" will be parsed to [[1], { kw: 3 }]
+        catch(:EXTRACT_RUBY_ARGS) do
+          @irb_context.workspace.binding.eval "IRB::Command.extract_ruby_args #{arg}"
+        end || [[], {}]
+      end
+    end
+  end
+end

data/lib/irb/command/irb_info.rb

@@ -8,12 +8,12 @@ module IRB
       category "IRB"
       description "Show information about IRB."
 
-      def execute
+      def execute(_arg)
         str  = "Ruby version: #{RUBY_VERSION}\n"
         str += "IRB version: #{IRB.version}\n"
         str += "InputMethod: #{IRB.CurrentContext.io.inspect}\n"
         str += "Completion: #{IRB.CurrentContext.io.respond_to?(:completion_info) ? IRB.CurrentContext.io.completion_info : 'off'}\n"
-        rc_files = IRB.rc_files.select { |rc| File.exist?(rc) }
+        rc_files = IRB.irbrc_files
         str += ".irbrc paths: #{rc_files.join(", ")}\n" if rc_files.any?
         str += "RUBY_PLATFORM: #{RUBY_PLATFORM}\n"
         str += "LANG env: #{ENV["LANG"]}\n" if ENV["LANG"] && !ENV["LANG"].empty?

data/lib/irb/command/load.rb

@@ -10,6 +10,7 @@ module IRB
 
   module Command
     class LoaderCommand < Base
+      include RubyArgsExtractor
       include IrbLoader
 
       def raise_cmd_argument_error
@@ -21,7 +22,12 @@ module IRB
       category "IRB"
       description "Load a Ruby file."
 
-      def execute(file_name = nil, priv = nil)
+      def execute(arg)
+        args, kwargs = ruby_args(arg)
+        execute_internal(*args, **kwargs)
+      end
+
+      def execute_internal(file_name = nil, priv = nil)
         raise_cmd_argument_error unless file_name
         irb_load(file_name, priv)
       end
@@ -30,7 +36,13 @@ module IRB
     class Require < LoaderCommand
       category "IRB"
       description "Require a Ruby file."
-      def execute(file_name = nil)
+
+      def execute(arg)
+        args, kwargs = ruby_args(arg)
+        execute_internal(*args, **kwargs)
+      end
+
+      def execute_internal(file_name = nil)
         raise_cmd_argument_error unless file_name
 
         rex = Regexp.new("#{Regexp.quote(file_name)}(\.o|\.rb)?")
@@ -63,7 +75,12 @@ module IRB
       category "IRB"
       description "Loads a given file in the current session."
 
-      def execute(file_name = nil)
+      def execute(arg)
+        args, kwargs = ruby_args(arg)
+        execute_internal(*args, **kwargs)
+      end
+
+      def execute_internal(file_name = nil)
         raise_cmd_argument_error unless file_name
 
         source_file(file_name)

data/lib/irb/command/ls.rb

@@ -11,6 +11,8 @@ module IRB
 
   module Command
     class Ls < Base
+      include RubyArgsExtractor
+
       category "Context"
       description "Show methods, constants, and variables."
 
@@ -20,27 +22,35 @@ module IRB
           -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/)
-          args = match[:args]
-          "#{args}#{',' unless args.chomp.empty?} grep: /#{match[:grep]}/"
+      def execute(arg)
+        if match = arg.match(/\A(?<target>.+\s|)(-g|-G)\s+(?<grep>.+)$/)
+          if match[:target].empty?
+            use_main = true
+          else
+            obj = @irb_context.workspace.binding.eval(match[:target])
+          end
+          grep = Regexp.new(match[:grep])
         else
-          args
+          args, kwargs = ruby_args(arg)
+          use_main = args.empty?
+          obj = args.first
+          grep = kwargs[:grep]
+        end
+
+        if use_main
+          obj = irb_context.workspace.main
+          locals = irb_context.workspace.binding.local_variables
         end
-      end
 
-      def execute(*arg, grep: nil)
         o = Output.new(grep: grep)
 
-        obj    = arg.empty? ? irb_context.workspace.main : arg.first
-        locals = arg.empty? ? irb_context.workspace.binding.local_variables : []
         klass  = (obj.class == Class || obj.class == Module ? obj : obj.class)
 
         o.dump("constants", obj.constants) if obj.respond_to?(:constants)
         dump_methods(o, klass, obj)
         o.dump("instance variables", obj.instance_variables)
         o.dump("class variables", klass.class_variables)
-        o.dump("locals", locals)
+        o.dump("locals", locals) if locals
         o.print_result
       end
 

data/lib/irb/command/measure.rb

@@ -3,6 +3,8 @@ module IRB
 
   module Command
     class Measure < Base
+      include RubyArgsExtractor
+
       category "Misc"
       description "`measure` enables the mode to measure processing time. `measure :off` disables it."
 
@@ -10,15 +12,19 @@ module IRB
         super(*args)
       end
 
-      def execute(type = nil, arg = nil)
-        # Please check IRB.init_config in lib/irb/init.rb that sets
-        # IRB.conf[:MEASURE_PROC] to register default "measure" methods,
-        # "measure :time" (abbreviated as "measure") and "measure :stackprof".
-
-        if block_given?
+      def execute(arg)
+        if arg&.match?(/^do$|^do[^\w]|^\{/)
           warn 'Configure IRB.conf[:MEASURE_PROC] to add custom measure methods.'
           return
         end
+        args, kwargs = ruby_args(arg)
+        execute_internal(*args, **kwargs)
+      end
+
+      def execute_internal(type = nil, arg = nil)
+        # Please check IRB.init_config in lib/irb/init.rb that sets
+        # IRB.conf[:MEASURE_PROC] to register default "measure" methods,
+        # "measure :time" (abbreviated as "measure") and "measure :stackprof".
 
         case type
         when :off

data/lib/irb/command/next.rb

@@ -7,8 +7,8 @@ module IRB
 
   module Command
     class Next < DebugCommand
-      def execute(*args)
-        super(do_cmds: ["next", *args].join(" "))
+      def execute(arg)
+        execute_debug_command(do_cmds: "next #{arg}")
       end
     end
   end