irb 1.6.4 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db51125adbe98b16228e314bff627b1cec953b92f32c774c4b9a820dc3bfc40b
-  data.tar.gz: ead3ebf30f5a4369d8cc2767691397d766bab8532031f8f505c2d0b3f251e071
+  metadata.gz: 485bdcb4daa6d3f0e0a70fc6ff6e93289d9d8b46c4a32094ab85fd7ad1ad6994
+  data.tar.gz: d57ae530ec9c2db847b0f15ab10f01f23e4ae62cd9542770ddbbee83fe446195
 SHA512:
-  metadata.gz: d2f749ce66ed43433fbbc7ec8682a0c3f0180ac8fb676739e5c3cbf0eb2f8bbb89a7896af11120bdeedd730e57edddaeabf932ae22ac55ad33c99f8408ffc832
-  data.tar.gz: 55621e3a5f9926c3f1b44426c23b9b08543920075fa0d32eeda8b7db35ded09aba6c311011e7f8397a6a5089bbb63d2b2e2603c1d7e254b77a16b93ca35b76f3
+  metadata.gz: e8d8f8a7444b8c6bb13d7ba2e4baf38df9ee4126be78188ddb15d5c97160908e43789b54df09d534badb8eb3a69a4f771687f46038033361fdccf0e1ffe3fa66
+  data.tar.gz: 2658667bb3f923447d311f9c866b3fbcefd0f7451e8cdc61c9593b5c9e05d443558e87e7da7e706fdb998cc86fe601e1ec87d4ed21e32ea05552e66906dabca3

data/Gemfile

@@ -15,4 +15,5 @@ gem "stackprof" if is_unix && !is_truffleruby
 gem "reline", github: "ruby/reline" if ENV["WITH_LATEST_RELINE"] == "true"
 gem "rake"
 gem "test-unit"
+gem "test-unit-ruby-core"
 gem "debug", github: "ruby/debug"

data/README.md

@@ -1,12 +1,29 @@
 # IRB
 
-[![Gem Version](https://badge.fury.io/rb/irb.svg)](https://badge.fury.io/rb/irb) 
+[![Gem Version](https://badge.fury.io/rb/irb.svg)](https://badge.fury.io/rb/irb)
 [![build](https://github.com/ruby/irb/actions/workflows/test.yml/badge.svg)](https://github.com/ruby/irb/actions/workflows/test.yml)
 
 IRB stands for "interactive Ruby" and is a tool to interactively execute Ruby expressions read from the standard input.
 
 The `irb` command from your shell will start the interpreter.
 
+- [Installation](#installation)
+- [Usage](#usage)
+  - [The `irb` Executable](#the-irb-executable)
+  - [The `binding.irb` Breakpoint](#the-bindingirb-breakpoint)
+- [Commands](#commands)
+- [Debugging with IRB](#debugging-with-irb)
+  - [More about `debug.gem`](#more-about-debuggem)
+  - [Advantages Over `debug.gem`'s Console](#advantages-over-debuggems-console)
+- [Configuration](#configuration)
+  - [Environment Variables](#environment-variables)
+- [Documentation](#documentation)
+- [Extending IRB](#extending-irb)
+- [Development](#development)
+- [Contributing](#contributing)
+- [Releasing](#releasing)
+- [License](#license)
+
 ## Installation
 
 > **Note**
@@ -43,15 +60,15 @@ In the session, you can evaluate Ruby expressions or even prototype a small Ruby
 
 ```shell
 $ irb
-irb(main):001:0> 1 + 2
+irb(main):001> 1 + 2
 => 3
-irb(main):002:1* class Foo
-irb(main):003:2*   def foo
-irb(main):004:2*     puts 1
-irb(main):005:1*   end
-irb(main):006:0> end
+irb(main):002* class Foo
+irb(main):003*   def foo
+irb(main):004*     puts 1
+irb(main):005*   end
+irb(main):006> end
 => :foo
-irb(main):007:0> Foo.new.foo
+irb(main):007> Foo.new.foo
 1
 => nil
 ```
@@ -84,23 +101,26 @@ Hello World
 
 The following commands are available on IRB. You can get the same output from the `show_cmds` command.
 
-
 ```
-IRB
+Workspace
   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
   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.
+
+Multi-irb (DEPRECATED)
   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.
@@ -115,29 +135,130 @@ 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["EDITOR"]`.
+  edit           Open a file with the editor command defined with `ENV["VISUAL"]` or `ENV["EDITOR"]`.
   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.
   show_source    Show the source code of a given method or constant.
   whereami       Show the source code around binding.irb again.
 ```
 
+## Debugging with IRB
+
+Starting from version 1.8.0, IRB boasts a powerful integration with `debug.gem`, providing a debugging experience akin to `pry-byebug`.
+
+After hitting a `binding.irb` breakpoint, you can activate the debugger with the `debug` command.
+
+```shell
+From: test.rb @ line 3 :
+
+    1:
+    2: def greet(word)
+ => 3:   binding.irb
+    4:   puts "Hello #{word}"
+    5: end
+    6:
+    7: greet("World")
+
+irb(main):001> debug
+irb:rdbg(main):002>
+```
+
+Once activated, the prompt's header changes from `irb` to `irb:rdbg`, enabling you to use any of `debug.gem`'s [commands](https://github.com/ruby/debug#debug-command-on-the-debug-console):
+
+```shell
+irb:rdbg(main):002> info # use info command to see available variables
+%self = main
+_ = nil
+word = "World"
+irb:rdbg(main):003> next # use next command to move to the next line
+[1, 7] in test.rb
+     1|
+     2| def greet(word)
+     3|   binding.irb
+=>   4|   puts "Hello #{word}"
+     5| end
+     6|
+     7| greet("World")
+=>#0    Object#greet(word="World") at test.rb:4
+  #1    <main> at test.rb:7
+irb:rdbg(main):004>
+```
+
+Simultaneously, you maintain access to IRB's commands, such as `show_source`:
+
+```shell
+irb:rdbg(main):004> show_source greet
+
+From: test.rb:2
+
+def greet(word)
+  binding.irb
+  puts "Hello #{word}"
+end
+```
+
+### More about `debug.gem`
+
+`debug.gem` offers many advanced debugging features that simple REPLs can't provide, including:
+
+- Step-debugging
+- Frame navigation
+- Setting breakpoints with commands
+- Thread control
+- ...and many more
+
+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`.
+
+### Advantages Over `debug.gem`'s Console
+
+This integration offers several benefits over `debug.gem`'s native console:
+
+1. Access to handy IRB commands like `show_source` or `show_doc`.
+2. Support for multi-line input.
+3. Symbol shortcuts such as `@` (`whereami`) and `$` (`show_source`).
+4. Autocompletion.
+5. Customizable prompt.
+
+However, there are also some limitations to be aware of:
+
+1. `binding.irb` doesn't support `pre` and `do` arguments like [`binding.break`](https://github.com/ruby/debug#bindingbreak-method).
+2. As IRB [doesn't currently support remote-connection](https://github.com/ruby/irb/issues/672), it can't be used with `debug.gem`'s remote debugging feature.
+3. Access to the previous return value via the underscore `_` is not supported.
+
 ## 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.
+- `VISUAL`: Its value would be used to open files by the `edit` command.
+- `EDITOR`: Its value would be used to open files by the `edit` command if `VISUAL` is unset.
 - `IRBRC`: The file specified would be evaluated as IRB's rc-file.
 
 ## Documentation
 
 https://docs.ruby-lang.org/en/master/IRB.html
 
+## 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.
+
+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!
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/Rakefile

@@ -41,11 +41,4 @@ Rake::TestTask.new(:test_yamatanooroti) do |t|
   t.pattern = 'test/irb/yamatanooroti/test_*.rb'
 end
 
-task :sync_tool do
-  require 'fileutils'
-  FileUtils.cp "../ruby/tool/lib/core_assertions.rb", "./test/lib"
-  FileUtils.cp "../ruby/tool/lib/envutil.rb", "./test/lib"
-  FileUtils.cp "../ruby/tool/lib/find_executable.rb", "./test/lib"
-end
-
 task :default => :test

data/doc/irb/irb.rd.ja

@@ -125,7 +125,6 @@ irb起動時に``~/.irbrc''を読み込みます. もし存在しない場合は
 
    IRB.conf[:PROMPT][:MY_PROMPT] = { # プロンプトモードの名前
      :PROMPT_I => nil,		  # 通常のプロンプト
-     :PROMPT_N => nil,		  # 継続行のプロンプト
      :PROMPT_S => nil,		  # 文字列などの継続行のプロンプト
      :PROMPT_C => nil,		  # 式が継続している時のプロンプト
      :RETURN => "    ==>%s\n"	  # リターン時のプロンプト
@@ -140,7 +139,7 @@ OKです.
 
   IRB.conf[:PROMPT_MODE] = :MY_PROMPT
 
-PROMPT_I, PROMPT_N, PROMPT_S, PROMPT_Cは, フォーマットを指定します.
+PROMPT_I, PROMPT_S, PROMPT_Cは, フォーマットを指定します.
 
   %N	起動しているコマンド名が出力される.
   %m	mainオブジェクト(self)がto_sで出力される.
@@ -155,7 +154,6 @@ PROMPT_I, PROMPT_N, PROMPT_S, PROMPT_Cは, フォーマットを指定します.
 
   IRB.conf[:PROMPT][:DEFAULT] = {
       :PROMPT_I => "%N(%m):%03n:%i> ",
-      :PROMPT_N => "%N(%m):%03n:%i> ",
       :PROMPT_S => "%N(%m):%03n:%i%l ",
       :PROMPT_C => "%N(%m):%03n:%i* ",
       :RETURN => "=> %s\n"

data/irb.gemspec

@@ -41,5 +41,6 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = Gem::Requirement.new(">= 2.7")
 
-  spec.add_dependency "reline", ">= 0.3.0"
+  spec.add_dependency "reline", ">= 0.3.6"
+  spec.add_dependency "rdoc", "~> 6.5"
 end

data/lib/irb/cmd/chws.rb

@@ -13,7 +13,7 @@ module IRB
   module ExtendCommand
 
     class CurrentWorkingWorkspace < Nop
-      category "IRB"
+      category "Workspace"
       description "Show the current workspace."
 
       def execute(*obj)
@@ -22,7 +22,7 @@ module IRB
     end
 
     class ChangeWorkspace < Nop
-      category "IRB"
+      category "Workspace"
       description "Change the current workspace to an object."
 
       def execute(*obj)

data/lib/irb/cmd/debug.rb

@@ -1,4 +1,5 @@
 require_relative "nop"
+require_relative "../debug"
 
 module IRB
   # :stopdoc:
@@ -12,37 +13,46 @@ module IRB
         '<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
+        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
+            throw :IRB_EXIT, cmd
+          else
+            puts "IRB is already running with a debug session."
+            return
+          end
+        else
+          # If IRB is not running with a debug session yet, then:
+          # 1. Check if the debugging command is run from a `binding.irb` call.
+          # 2. If so, try setting up the debug gem.
+          # 3. Insert a debug breakpoint at `Irb#debug_break` with the intended command.
+          # 4. Exit the current Irb#run call via `throw :IRB_EXIT`.
+          # 5. `Irb#debug_break` will be called and trigger the breakpoint, which will run the intended command.
+          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
+          if IRB.respond_to?(:JobManager)
+            warn "Can't start the debugger when IRB is running in a multi-IRB session."
+            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
+          unless IRB::Debug.setup(irb_context.irb)
+            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
 
-        # 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
+          IRB::Debug.insert_debug_break(pre_cmds: pre_cmds, do_cmds: do_cmds)
+
+          # exit current Irb#run call
+          throw :IRB_EXIT
+        end
       end
 
       private
@@ -54,72 +64,6 @@ module IRB
           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

data/lib/irb/cmd/edit.rb

@@ -1,5 +1,6 @@
 require 'shellwords'
 require_relative "nop"
+require_relative "../source_finder"
 
 module IRB
   # :stopdoc:
@@ -7,7 +8,7 @@ module IRB
   module ExtendCommand
     class Edit < Nop
       category "Misc"
-      description 'Open a file with the editor command defined with `ENV["EDITOR"]`.'
+      description 'Open a file with the editor command defined with `ENV["VISUAL"]` or `ENV["EDITOR"]`.'
 
       class << self
         def transform_args(args)
@@ -28,17 +29,15 @@ module IRB
         end
 
         if !File.exist?(path)
-          require_relative "show_source"
-
           source =
             begin
-              ShowSource.find_source(path, @irb_context)
+              SourceFinder.new(@irb_context).find_source(path)
             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)
+          if source
             path = source.file
           else
             puts "Can not find file: #{path}"
@@ -46,12 +45,12 @@ module IRB
           end
         end
 
-        if editor = ENV['EDITOR']
+        if editor = (ENV['VISUAL'] || ENV['EDITOR'])
           puts "command: '#{editor}'"
           puts "   path: #{path}"
           system(*Shellwords.split(editor), path)
         else
-          puts "Can not find editor setting: ENV['EDITOR']"
+          puts "Can not find editor setting: ENV['VISUAL'] or ENV['EDITOR']"
         end
       end
     end

data/lib/irb/cmd/help.rb

@@ -1,57 +1,23 @@
-# frozen_string_literal: false
-#
-#   help.rb - helper using ri
-#
+# frozen_string_literal: true
 
-require_relative "nop"
+require_relative "show_doc"
 
 module IRB
-  # :stopdoc:
-
   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
-
+    class Help < ShowDoc
       category "Context"
-      description "Enter the mode to look up RI documents."
+      description "[DEPRECATED] Enter the mode to look up RI documents."
+
+      DEPRECATION_MESSAGE = <<~MSG
+        [Deprecation] The `help` command will be repurposed to display command help in the future.
+        For RI document lookup, please use the `show_doc` command instead.
+        For command help, please use `show_cmds` for now.
+      MSG
 
       def execute(*names)
-        require 'rdoc/ri/driver'
-        opts = RDoc::RI::Driver.process_args([])
-        IRB::ExtendCommand::Help.const_set(:Ri, RDoc::RI::Driver.new(opts))
-      rescue LoadError, SystemExit
-        IRB::ExtendCommand::Help.remove_method(:execute)
-        # raise NoMethodError in ensure
-      else
-        def execute(*names)
-          if names.empty?
-            Ri.interactive
-            return
-          end
-          names.each do |name|
-            begin
-              Ri.display_name(name.to_s)
-            rescue RDoc::RI::Error
-              puts $!.message
-            end
-          end
-          nil
-        end
-        nil
-      ensure
-        execute(*names)
+        warn DEPRECATION_MESSAGE
+        super
       end
     end
   end
-
-  # :startdoc:
 end

data/lib/irb/cmd/irb_info.rb

@@ -11,24 +11,20 @@ module 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
+        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
+        puts str
+        nil
       end
     end
   end