irb 1.7.4 → 1.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea4ae752c3ffee02c55d78d1da5032244d6c9574fc8a7e64bcd4d0798e89b619
-  data.tar.gz: 24eb6d55d8c1fdead9230a92d3f70016936ccbe99a69bdef60de9d68108e0336
+  metadata.gz: 0b6bfef2fbb8e5e7d7587a567055e2b7f019678d2355f6ae52f7a7d8161df0c0
+  data.tar.gz: 653be685d9f249341c3e165cb4303baa05563c5556cc2bf2584243c39ec0cb92
 SHA512:
-  metadata.gz: 3aec5c7c99c1dc58ed3f427cd6ef397c1310b1b43f42923999d6dc7b12b6d9334af6660c7cc1cd2b0d1b8b3b5a6411d5e85bad84513a8230688924850f48819c
-  data.tar.gz: e54020f1e5c7a777905d0218fcf1a1634acfe89fe9a64a27199154bbda4557b3af0b43444d2e36d5d124021783092ffe089df3ead84da45c053879cc7a5d5a1d
+  metadata.gz: 215ce7d8130e1a43382706858c487d7835971e326e93eb1c2ccb559b7dec5f1ecd216b451ad535beaba5e908419ec3e1c13bcc8dea8a0e6d2d7c45fed4639fdb
+  data.tar.gz: c950ff10929df5ac8365ec0b86fcafe1ac85685ef955b6d12ec7febaf2a9bc85be8b325a58b60583c2a7567889cc6fbe9c6c6eb9b16a10f35409b7da21c7cd32

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.6"
+  spec.add_dependency "reline", ">= 0.3.8"
+  spec.add_dependency "rdoc"
 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/ls.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 require "reline"
+require "stringio"
 require_relative "nop"
+require_relative "../pager"
 require_relative "../color"
 
 module IRB
@@ -33,7 +35,7 @@ module IRB
         o.dump("instance variables", obj.instance_variables)
         o.dump("class variables", klass.class_variables)
         o.dump("locals", locals)
-        nil
+        o.print_result
       end
 
       def dump_methods(o, klass, obj)
@@ -77,6 +79,11 @@ module IRB
         def initialize(grep: nil)
           @grep = grep
           @line_width = screen_width - MARGIN.length # right padding
+          @io = StringIO.new
+        end
+
+        def print_result
+          Pager.page_content(@io.string)
         end
 
         def dump(name, strs)
@@ -85,12 +92,12 @@ module IRB
           return if strs.empty?
 
           # Attempt a single line
-          print "#{Color.colorize(name, [:BOLD, :BLUE])}: "
+          @io.print "#{Color.colorize(name, [:BOLD, :BLUE])}: "
           if fits_on_line?(strs, cols: strs.size, offset: "#{name}: ".length)
-            puts strs.join(MARGIN)
+            @io.puts strs.join(MARGIN)
             return
           end
-          puts
+          @io.puts
 
           # Dump with the largest # of columns that fits on a line
           cols = strs.size
@@ -99,7 +106,7 @@ module IRB
           end
           widths = col_widths(strs, cols: cols)
           strs.each_slice(cols) do |ss|
-            puts ss.map.with_index { |s, i| "#{MARGIN}%-#{widths[i]}s" % s }.join
+            @io.puts ss.map.with_index { |s, i| "#{MARGIN}%-#{widths[i]}s" % s }.join
           end
         end
 

data/lib/irb/cmd/pushws.rb

@@ -12,7 +12,7 @@ module IRB
 
   module ExtendCommand
     class Workspaces < Nop
-      category "IRB"
+      category "Workspace"
       description "Show workspaces."
 
       def execute(*obj)
@@ -21,7 +21,7 @@ module IRB
     end
 
     class PushWorkspace < Workspaces
-      category "IRB"
+      category "Workspace"
       description "Push an object to the workspace stack."
 
       def execute(*obj)
@@ -31,7 +31,7 @@ module IRB
     end
 
     class PopWorkspace < Workspaces
-      category "IRB"
+      category "Workspace"
       description "Pop a workspace from the workspace stack."
 
       def execute(*obj)

data/lib/irb/cmd/show_cmds.rb

@@ -2,6 +2,7 @@
 
 require "stringio"
 require_relative "nop"
+require_relative "../pager"
 
 module IRB
   # :stopdoc:
@@ -14,6 +15,16 @@ module IRB
       def execute(*args)
         commands_info = IRB::ExtendCommandBundle.all_commands_info
         commands_grouped_by_categories = commands_info.group_by { |cmd| cmd[:category] }
+
+        if irb_context.with_debugger
+          # Remove the original "Debugging" category
+          commands_grouped_by_categories.delete("Debugging")
+          # Remove the `help` command as it's delegated to the debugger
+          commands_grouped_by_categories["Context"].delete_if { |cmd| cmd[:display_name] == :help }
+          # 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
@@ -28,9 +39,12 @@ module IRB
           output.puts
         end
 
-        puts output.string
+        # Append the debugger help at the end
+        if irb_context.with_debugger
+          output.puts DEBUGGER__.help
+        end
 
-        nil
+        Pager.page_content(output.string)
       end
     end
   end