irb 1.4.2 → 1.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25f63261bbf06e8b1605b8a680e538dd90641ad2492c0bfb0f8e127f673e2793
-  data.tar.gz: 9f113f6c97887e83f9d476dba5e4c0a5656d76cc554e1e818c94e8828b4051fa
+  metadata.gz: 2f4318c00db4c9aaf6b89c57e116935705e2bdf7f576c16c3ee8862102468d64
+  data.tar.gz: a685194eca805c046ffa7084273da09a6b40eb0a4b711f80e2e3da49df03b585
 SHA512:
-  metadata.gz: 024d8e4dc13978bbae5ed3404e3ecff763da3fcc01e26c43d3e7e54822121bbc708de49c5a9c951a15c0ceee05a60cf282cbbd6ae6ec42960e9a8943a9217417
-  data.tar.gz: 146edac46f0d81a01e120493e56eefa8d8b51143851718876617673bcbddf19b54e246d55541833101926e17186ce55b6484e2fb20e6f57735ee49ddfe0b6890
+  metadata.gz: fa16a155b6554feeb1876849e57032e25fbf6a6e5e094c96ae3602e82ef1c26f69c2ab169fb0a670178c3f0097912fbdb092e24285e0c41f0af0b7f381ea362f
+  data.tar.gz: acc20573c8b1291a87dba4fd244f7d408ba004c242c07f1d3afa9cde4e101c696e797059bbdbd310da96dec79213abcd68074f2fe76b0b9ce2368e049acd1db7

data/Gemfile

@@ -11,4 +11,5 @@ group :development do
   gem "stackprof" if is_unix && !is_truffleruby
   gem "test-unit"
   gem "reline", github: "ruby/reline" if ENV["WITH_LATEST_RELINE"] == "true"
+  gem "debug", github: "ruby/debug"
 end

data/README.md

@@ -40,6 +40,60 @@ irb(main):006:1> end
 
 The Readline extension module can be used with irb. Use of Readline is default if it's installed.
 
+## Commands
+
+The following commands are available on IRB. You can get the same output from the `show_cmds` command.
+
+
+```
+IRB
+  cwws           Show the current workspace.
+  chws           Change the current workspace to an object.
+  workspaces     Show workspaces.
+  pushws         Push an object to the workspace stack.
+  popws          Pop a workspace from the workspace stack.
+  irb_load       Load a Ruby file.
+  irb_require    Require a Ruby file.
+  source         Loads a given file in the current session.
+  irb            Start a child IRB.
+  jobs           List of current sessions.
+  fg             Switches to the session of the given number.
+  kill           Kills the session with the given number.
+  irb_info       Show information about IRB.
+  show_cmds      List all available commands and their description.
+
+Debugging
+  debug          Start the debugger of debug.gem.
+  break          Start the debugger of debug.gem and run its `break` command.
+  catch          Start the debugger of debug.gem and run its `catch` command.
+  next           Start the debugger of debug.gem and run its `next` command.
+  delete         Start the debugger of debug.gem and run its `delete` command.
+  step           Start the debugger of debug.gem and run its `step` command.
+  continue       Start the debugger of debug.gem and run its `continue` command.
+  finish         Start the debugger of debug.gem and run its `finish` command.
+  backtrace      Start the debugger of debug.gem and run its `backtrace` command.
+  info           Start the debugger of debug.gem and run its `info` command.
+
+Misc
+  edit           Open a file with the editor command defined with `ENV["EDITOR"]`.
+  measure        `measure` enables the mode to measure processing time. `measure :off` disables it.
+
+Context
+  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.
+  show_source    Show the source code of a given method or constant.
+  whereami       Show the source code around binding.irb again.
+```
+
+## Configuration
+
+### Environment Variables
+
+- `NO_COLOR`: Assigning a value to it disables IRB's colorization.
+- `IRB_USE_AUTOCOMPLETE`: Setting it to `false` disables IRB's autocompletion.
+- `EDITOR`: Its value would be used to open files by the `edit` command.
+- `IRBRC`: The file specified would be evaluated as IRB's rc-file.
+
 ## Documentation
 
 https://docs.ruby-lang.org/en/master/IRB.html
@@ -54,6 +108,13 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/ruby/irb.
 
+## Releasing
+
+```
+rake release
+gh release create vX.Y.Z --generate-notes
+```
+
 ## License
 
 The gem is available as open source under the terms of the [2-Clause BSD License](https://opensource.org/licenses/BSD-2-Clause).

data/Rakefile

@@ -8,6 +8,31 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList["test/irb/test_*.rb"]
 end
 
+# To make sure they have been correctly setup for Ruby CI.
+desc "Run each irb test file in isolation."
+task :test_in_isolation do
+  failed = false
+
+  FileList["test/irb/test_*.rb"].each do |test_file|
+    ENV["TEST"] = test_file
+    begin
+      Rake::Task["test"].execute
+    rescue => e
+      failed = true
+      msg = "Test '#{test_file}' failed when being executed in isolation. Please make sure 'rake test TEST=#{test_file}' passes."
+      separation_line = '=' * msg.length
+
+      puts <<~MSG
+        #{separation_line}
+        #{msg}
+        #{separation_line}
+      MSG
+    end
+  end
+
+  fail "Some tests failed when being executed in isolation" if failed
+end
+
 Rake::TestTask.new(:test_yamatanooroti) do |t|
   t.libs << 'test' << "test/lib"
   t.libs << 'lib'

data/irb.gemspec

@@ -34,7 +34,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.5")
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.6")
 
   spec.add_dependency "reline", ">= 0.3.0"
 end

data/lib/irb/cmd/backtrace.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "debug"
+
+module IRB
+  # :stopdoc:
+
+  module ExtendCommand
+    class Backtrace < DebugCommand
+      def self.transform_args(args)
+        args&.dump
+      end
+
+      def execute(*args)
+        super(pre_cmds: ["backtrace", *args].join(" "))
+      end
+    end
+  end
+
+  # :startdoc:
+end

data/lib/irb/cmd/break.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "debug"
+
+module IRB
+  # :stopdoc:
+
+  module ExtendCommand
+    class Break < DebugCommand
+      def self.transform_args(args)
+        args&.dump
+      end
+
+      def execute(args = nil)
+        super(pre_cmds: "break #{args}")
+      end
+    end
+  end
+
+  # :startdoc:
+end

data/lib/irb/cmd/catch.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "debug"
+
+module IRB
+  # :stopdoc:
+
+  module ExtendCommand
+    class Catch < DebugCommand
+      def self.transform_args(args)
+        args&.dump
+      end
+
+      def execute(*args)
+        super(pre_cmds: ["catch", *args].join(" "))
+      end
+    end
+  end
+
+  # :startdoc:
+end

data/lib/irb/cmd/chws.rb

@@ -19,12 +19,18 @@ module IRB
   module ExtendCommand
 
     class CurrentWorkingWorkspace < Nop
+      category "IRB"
+      description "Show the current workspace."
+
       def execute(*obj)
         irb_context.main
       end
     end
 
     class ChangeWorkspace < Nop
+      category "IRB"
+      description "Change the current workspace to an object."
+
       def execute(*obj)
         irb_context.change_workspace(*obj)
         irb_context.main

data/lib/irb/cmd/continue.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "debug"
+
+module IRB
+  # :stopdoc:
+
+  module ExtendCommand
+    class Continue < DebugCommand
+      def execute(*args)
+        super(do_cmds: ["continue", *args].join(" "))
+      end
+    end
+  end
+
+  # :startdoc:
+end

data/lib/irb/cmd/debug.rb

@@ -0,0 +1,136 @@
+require_relative "nop"
+
+module IRB
+  # :stopdoc:
+
+  module ExtendCommand
+    class Debug < Nop
+      category "Debugging"
+      description "Start the debugger of debug.gem."
+
+      BINDING_IRB_FRAME_REGEXPS = [
+        '<internal:prelude>',
+        binding.method(:irb).source_location.first,
+      ].map { |file| /\A#{Regexp.escape(file)}:\d+:in `irb'\z/ }
+      IRB_DIR = File.expand_path('..', __dir__)
+
+      def execute(pre_cmds: nil, do_cmds: nil)
+        unless binding_irb?
+          puts "`debug` command is only available when IRB is started with binding.irb"
+          return
+        end
+
+        unless setup_debugger
+          puts <<~MSG
+            You need to install the debug gem before using this command.
+            If you use `bundle exec`, please add `gem "debug"` into your Gemfile.
+          MSG
+          return
+        end
+
+        options = { oneshot: true, hook_call: false }
+        if pre_cmds || do_cmds
+          options[:command] = ['irb', pre_cmds, do_cmds]
+        end
+        if DEBUGGER__::LineBreakpoint.instance_method(:initialize).parameters.include?([:key, :skip_src])
+          options[:skip_src] = true
+        end
+
+        # To make debugger commands like `next` or `continue` work without asking
+        # the user to quit IRB after that, we need to exit IRB first and then hit
+        # a TracePoint on #debug_break.
+        file, lineno = IRB::Irb.instance_method(:debug_break).source_location
+        DEBUGGER__::SESSION.add_line_breakpoint(file, lineno + 1, **options)
+        # exit current Irb#run call
+        throw :IRB_EXIT
+      end
+
+      private
+
+      def binding_irb?
+        caller.any? do |frame|
+          BINDING_IRB_FRAME_REGEXPS.any? do |regexp|
+            frame.match?(regexp)
+          end
+        end
+      end
+
+      module SkipPathHelperForIRB
+        def skip_internal_path?(path)
+          # The latter can be removed once https://github.com/ruby/debug/issues/866 is resolved
+          super || path.match?(IRB_DIR) || path.match?('<internal:prelude>')
+        end
+      end
+
+      def setup_debugger
+        unless defined?(DEBUGGER__::SESSION)
+          begin
+            require "debug/session"
+          rescue LoadError # debug.gem is not written in Gemfile
+            return false unless load_bundled_debug_gem
+          end
+          DEBUGGER__.start(nonstop: true)
+        end
+
+        unless DEBUGGER__.respond_to?(:capture_frames_without_irb)
+          DEBUGGER__.singleton_class.send(:alias_method, :capture_frames_without_irb, :capture_frames)
+
+          def DEBUGGER__.capture_frames(*args)
+            frames = capture_frames_without_irb(*args)
+            frames.reject! do |frame|
+              frame.realpath&.start_with?(IRB_DIR) || frame.path == "<internal:prelude>"
+            end
+            frames
+          end
+
+          DEBUGGER__::ThreadClient.prepend(SkipPathHelperForIRB)
+        end
+
+        true
+      end
+
+      # This is used when debug.gem is not written in Gemfile. Even if it's not
+      # installed by `bundle install`, debug.gem is installed by default because
+      # it's a bundled gem. This method tries to activate and load that.
+      def load_bundled_debug_gem
+        # Discover latest debug.gem under GEM_PATH
+        debug_gem = Gem.paths.path.flat_map { |path| Dir.glob("#{path}/gems/debug-*") }.select do |path|
+          File.basename(path).match?(/\Adebug-\d+\.\d+\.\d+(\w+)?\z/)
+        end.sort_by do |path|
+          Gem::Version.new(File.basename(path).delete_prefix('debug-'))
+        end.last
+        return false unless debug_gem
+
+        # Discover debug/debug.so under extensions for Ruby 3.2+
+        ext_name = "/debug/debug.#{RbConfig::CONFIG['DLEXT']}"
+        ext_path = Gem.paths.path.flat_map do |path|
+          Dir.glob("#{path}/extensions/**/#{File.basename(debug_gem)}#{ext_name}")
+        end.first
+
+        # Attempt to forcibly load the bundled gem
+        if ext_path
+          $LOAD_PATH << ext_path.delete_suffix(ext_name)
+        end
+        $LOAD_PATH << "#{debug_gem}/lib"
+        begin
+          require "debug/session"
+          puts "Loaded #{File.basename(debug_gem)}"
+          true
+        rescue LoadError
+          false
+        end
+      end
+    end
+
+    class DebugCommand < Debug
+      def self.category
+        "Debugging"
+      end
+
+      def self.description
+        command_name = self.name.split("::").last.downcase
+        "Start the debugger of debug.gem and run its `#{command_name}` command."
+      end
+    end
+  end
+end

data/lib/irb/cmd/delete.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "debug"
+
+module IRB
+  # :stopdoc:
+
+  module ExtendCommand
+    class Delete < DebugCommand
+      def execute(*args)
+        super(pre_cmds: ["delete", *args].join(" "))
+      end
+    end
+  end
+
+  # :startdoc:
+end

data/lib/irb/cmd/edit.rb

@@ -0,0 +1,61 @@
+require 'shellwords'
+require_relative "nop"
+
+module IRB
+  # :stopdoc:
+
+  module ExtendCommand
+    class Edit < Nop
+      category "Misc"
+      description 'Open a file with the editor command defined with `ENV["EDITOR"]`.'
+
+      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
+
+        if path.nil? && (irb_path = @irb_context.irb_path)
+          path = irb_path
+        end
+
+        if !File.exist?(path)
+          require_relative "show_source"
+
+          source =
+            begin
+              ShowSource.find_source(path, @irb_context)
+            rescue NameError
+              # if user enters a path that doesn't exist, it'll cause NameError when passed here because find_source would try to evaluate it as well
+              # in this case, we should just ignore the error
+            end
+
+          if source && File.exist?(source.file)
+            path = source.file
+          else
+            puts "Can not find file: #{path}"
+            return
+          end
+        end
+
+        if editor = ENV['EDITOR']
+          puts "command: '#{editor}'"
+          puts "   path: #{path}"
+          system(*Shellwords.split(editor), path)
+        else
+          puts "Can not find editor setting: ENV['EDITOR']"
+        end
+      end
+    end
+  end
+
+  # :startdoc:
+end

data/lib/irb/cmd/finish.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "debug"
+
+module IRB
+  # :stopdoc:
+
+  module ExtendCommand
+    class Finish < DebugCommand
+      def execute(*args)
+        super(do_cmds: ["finish", *args].join(" "))
+      end
+    end
+  end
+
+  # :startdoc:
+end

data/lib/irb/cmd/help.rb

@@ -16,6 +16,20 @@ module IRB
 
   module ExtendCommand
     class Help < Nop
+      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
+
+      category "Context"
+      description "Enter the mode to look up RI documents."
+
       def execute(*names)
         require 'rdoc/ri/driver'
         opts = RDoc::RI::Driver.process_args([])

data/lib/irb/cmd/info.rb

@@ -1,31 +1,18 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 
-require_relative "nop"
+require_relative "debug"
 
 module IRB
   # :stopdoc:
 
   module ExtendCommand
-    class Info < Nop
-      def execute
-        Class.new {
-          def inspect
-            str  = "Ruby version: #{RUBY_VERSION}\n"
-            str += "IRB version: #{IRB.version}\n"
-            str += "InputMethod: #{IRB.CurrentContext.io.inspect}\n"
-            str += ".irbrc path: #{IRB.rc_file}\n" if File.exist?(IRB.rc_file)
-            str += "RUBY_PLATFORM: #{RUBY_PLATFORM}\n"
-            str += "LANG env: #{ENV["LANG"]}\n" if ENV["LANG"] && !ENV["LANG"].empty?
-            str += "LC_ALL env: #{ENV["LC_ALL"]}\n" if ENV["LC_ALL"] && !ENV["LC_ALL"].empty?
-            str += "East Asian Ambiguous Width: #{Reline.ambiguous_width.inspect}\n"
-            if RbConfig::CONFIG['host_os'] =~ /mswin|msys|mingw|cygwin|bccwin|wince|emc/
-              codepage = `chcp`.b.sub(/.*: (\d+)\n/, '\1')
-              str += "Code page: #{codepage}\n"
-            end
-            str
-          end
-          alias_method :to_s, :inspect
-        }.new
+    class Info < DebugCommand
+      def self.transform_args(args)
+        args&.dump
+      end
+
+      def execute(*args)
+        super(pre_cmds: ["info", *args].join(" "))
       end
     end
   end

data/lib/irb/cmd/irb_info.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: false
+
+require_relative "nop"
+
+module IRB
+  # :stopdoc:
+
+  module ExtendCommand
+    class IrbInfo < Nop
+      category "IRB"
+      description "Show information about IRB."
+
+      def execute
+        Class.new {
+          def inspect
+            str  = "Ruby version: #{RUBY_VERSION}\n"
+            str += "IRB version: #{IRB.version}\n"
+            str += "InputMethod: #{IRB.CurrentContext.io.inspect}\n"
+            str += ".irbrc path: #{IRB.rc_file}\n" if File.exist?(IRB.rc_file)
+            str += "RUBY_PLATFORM: #{RUBY_PLATFORM}\n"
+            str += "LANG env: #{ENV["LANG"]}\n" if ENV["LANG"] && !ENV["LANG"].empty?
+            str += "LC_ALL env: #{ENV["LC_ALL"]}\n" if ENV["LC_ALL"] && !ENV["LC_ALL"].empty?
+            str += "East Asian Ambiguous Width: #{Reline.ambiguous_width.inspect}\n"
+            if RbConfig::CONFIG['host_os'] =~ /mswin|msys|mingw|cygwin|bccwin|wince|emc/
+              codepage = `chcp`.b.sub(/.*: (\d+)\n/, '\1')
+              str += "Code page: #{codepage}\n"
+            end
+            str
+          end
+          alias_method :to_s, :inspect
+        }.new
+      end
+    end
+  end
+
+  # :startdoc:
+end

data/lib/irb/cmd/load.rb

@@ -17,18 +17,29 @@ module IRB
   # :stopdoc:
 
   module ExtendCommand
-    class Load < Nop
+    class LoaderCommand < Nop
       include IrbLoader
 
-      def execute(file_name, priv = nil)
-        return irb_load(file_name, priv)
+      def raise_cmd_argument_error
+        raise CommandArgumentError.new("Please specify the file name.")
       end
     end
 
-    class Require < Nop
-      include IrbLoader
+    class Load < LoaderCommand
+      category "IRB"
+      description "Load a Ruby file."
+
+      def execute(file_name = nil, priv = nil)
+        raise_cmd_argument_error unless file_name
+        irb_load(file_name, priv)
+      end
+    end
 
-      def execute(file_name)
+    class Require < LoaderCommand
+      category "IRB"
+      description "Require a Ruby file."
+      def execute(file_name = nil)
+        raise_cmd_argument_error unless file_name
 
         rex = Regexp.new("#{Regexp.quote(file_name)}(\.o|\.rb)?")
         return false if $".find{|f| f =~ rex}
@@ -56,13 +67,16 @@ module IRB
       end
     end
 
-    class Source < Nop
-      include IrbLoader
-      def execute(file_name)
+    class Source < LoaderCommand
+      category "IRB"
+      description "Loads a given file in the current session."
+
+      def execute(file_name = nil)
+        raise_cmd_argument_error unless file_name
+
         source_file(file_name)
       end
     end
   end
-
   # :startdoc:
 end

data/lib/irb/cmd/ls.rb

@@ -9,6 +9,18 @@ module IRB
 
   module ExtendCommand
     class Ls < Nop
+      category "Context"
+      description "Show methods, constants, and variables. `-g [query]` or `-G [query]` allows you to filter out the output."
+
+      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]}/"
+        else
+          args
+        end
+      end
+
       def execute(*arg, grep: nil)
         o = Output.new(grep: grep)
 
@@ -21,6 +33,7 @@ module IRB
         o.dump("instance variables", obj.instance_variables)
         o.dump("class variables", klass.class_variables)
         o.dump("locals", locals)
+        nil
       end
 
       def dump_methods(o, klass, obj)

data/lib/irb/cmd/measure.rb

@@ -5,6 +5,9 @@ module IRB
 
   module ExtendCommand
     class Measure < Nop
+      category "Misc"
+      description "`measure` enables the mode to measure processing time. `measure :off` disables it."
+
       def initialize(*args)
         super(*args)
       end