irb 1.8.3 → 1.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 332023cd842d367c49ca245616a926f8f8df1f724c16b22d18447f1456710290
-  data.tar.gz: c6b7ab4d628a6fb766bed6f93b124490b1c364ba79b7ce8c1e4e21d67df64545
+  metadata.gz: b57e45ef4cb7d58489abeda8131ed81a1625b05fd139e00082bf3011fc0c2fdc
+  data.tar.gz: 411b92eee70de798e94c0c9c30801467cdf240a43eff4da9e46230374fa8504f
 SHA512:
-  metadata.gz: 8962b3e7359c4292bb09c75f3a5f1548b5dd53c3053a4a736a0a295c83126b065eca7578a185a0bf218468053399a3f029e47a06860ac69713756fb346945d08
-  data.tar.gz: '0109b52f17e50b944d5fb3e9e40b432a3a3bafbf45ed9b0dd5725de43527e5ca3926db65b44bf39c646f76c38c4dee07cd2eb8fcb33690dc071dcd4a66b99b87'
+  metadata.gz: '0919ac233b97abb80a9d34cad9be792e85bce261cc4c29c36eac8d7ba81bd99c4592b5b8c1bdbdc7e96d778ccf20b5374987eef0224e9fb6583639633e3c2bb0'
+  data.tar.gz: 89dad0bbdebdee60a3f08ca2cf918293bffac4db7b183a45ab93f6cc4906ca7a62437286a08291ba76fae8e2bba31f3b6a28be3cd13a141f451a5c4e1b09041d

data/.document

@@ -1,4 +1,4 @@
 LICENSE.txt
 README.md
-doc
+doc/irb/indexes.md
 lib/**/*.rb

data/Gemfile

@@ -16,4 +16,12 @@ 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"
+
+gem "rubocop"
+
+gem "tracer" if !is_truffleruby
+gem "debug", github: "ruby/debug", platforms: [:mri, :mswin]
+
+if RUBY_VERSION >= "3.0.0" && !is_truffleruby
+  gem "repl_type_completor"
+end

data/README.md

@@ -15,6 +15,10 @@ The `irb` command from your shell will start the interpreter.
 - [Debugging with IRB](#debugging-with-irb)
   - [More about `debug.gem`](#more-about-debuggem)
   - [Advantages Over `debug.gem`'s Console](#advantages-over-debuggems-console)
+- [Type Based Completion](#type-based-completion)
+  - [How to Enable IRB::TypeCompletor](#how-to-enable-irbtypecompletor)
+  - [Advantage over Default IRB::RegexpCompletor](#advantage-over-default-irbregexpcompletor)
+  - [Difference between Steep's Completion](#difference-between-steeps-completion)
 - [Configuration](#configuration)
   - [Environment Variables](#environment-variables)
 - [Documentation](#documentation)
@@ -26,7 +30,7 @@ The `irb` command from your shell will start the interpreter.
 
 ## Installation
 
-> **Note**
+> [!Note]
 >
 > IRB is a default gem of Ruby so you shouldn't need to install it separately.
 >
@@ -52,6 +56,10 @@ $ gem install irb
 
 ## Usage
 
+> [!Note]
+>
+> We're working hard to match Pry's variety of powerful features in IRB, and you can track our progress or find contribution ideas in [this document](https://github.com/ruby/irb/blob/master/COMPARED_WITH_PRY.md).
+
 ### The `irb` Executable
 
 You can start a fresh IRB session by typing `irb` in your terminal.
@@ -99,22 +107,27 @@ Hello World
 
 ## Commands
 
-The following commands are available on IRB. You can get the same output from the `show_cmds` command.
+The following commands are available on IRB. You can get the same output from the `help` command.
 
-```
-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.
+```txt
+Help
+  help           List all available commands. Use `help <command>` to get information about a specific command.
 
 IRB
+  exit           Exit the current irb session.
+  exit!          Exit the current process.
   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.
+  history        Shows the input history. `-g [query]` or `-G [query]` allows you to filter the output.
+
+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.
 
 Multi-irb (DEPRECATED)
   irb            Start a child IRB.
@@ -135,15 +148,18 @@ 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["VISUAL"]` or `ENV["EDITOR"]`.
+  edit           Open a file or source location.
   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.
+  ls             Show methods, constants, and variables.
   show_source    Show the source code of a given method or constant.
   whereami       Show the source code around binding.irb again.
+
+Aliases
+  $              Alias for `show_source`
+  @              Alias for `whereami`
 ```
 
 ## Debugging with IRB
@@ -213,7 +229,7 @@ end
 
 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`.
+In the `irb:rdbg` session, the `help` command will also display all commands from `debug.gem`.
 
 ### Advantages Over `debug.gem`'s Console
 
@@ -231,33 +247,117 @@ However, there are also some limitations to be aware of:
 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.
 
+## Type Based Completion
+
+IRB's default completion `IRB::RegexpCompletor` uses Regexp. IRB has another experimental completion `IRB::TypeCompletor` that uses type analysis.
+
+### How to Enable IRB::TypeCompletor
+
+Install [ruby/repl_type_completor](https://github.com/ruby/repl_type_completor/) with:
+```
+$ gem install repl_type_completor
+```
+Or add these lines to your project's Gemfile.
+```ruby
+gem 'irb'
+gem 'repl_type_completor', group: [:development, :test]
+```
+
+Now you can use type based completion by:
+
+Running IRB with the `--type-completor` option
+```
+$ irb --type-completor
+```
+
+Or writing this line to IRB's rc-file (e.g. `~/.irbrc`)
+```ruby
+IRB.conf[:COMPLETOR] = :type # default is :regexp
+```
+
+Or setting the environment variable `IRB_COMPLETOR`
+```ruby
+ENV['IRB_COMPLETOR'] = 'type'
+IRB.start
+```
+
+To check if it's enabled, type `irb_info` into IRB and see the `Completion` section.
+```
+irb(main):001> irb_info
+...
+# Enabled
+Completion: Autocomplete, ReplTypeCompletor: 0.1.0, Prism: 0.18.0, RBS: 3.3.0
+# Not enabled
+Completion: Autocomplete, RegexpCompletor
+...
+```
+If you have `sig/` directory or `rbs_collection.lock.yaml` in current directory, IRB will load it.
+
+### Advantage over Default IRB::RegexpCompletor
+
+IRB::TypeCompletor can autocomplete chained methods, block parameters and more if type information is available.
+These are some examples IRB::RegexpCompletor cannot complete.
+
+```ruby
+irb(main):001> 'Ruby'.upcase.chars.s # Array methods (sample, select, shift, size)
+```
+
+```ruby
+irb(main):001> 10.times.map(&:to_s).each do |s|
+irb(main):002>   s.up # String methods (upcase, upcase!, upto)
+```
+
+```ruby
+irb(main):001> class User < ApplicationRecord
+irb(main):002>   def foo
+irb(main):003>     sa # save, save!
+```
+
+As a trade-off, completion calculation takes more time than IRB::RegexpCompletor.
+
+### Difference between Steep's Completion
+
+Compared with Steep, IRB::TypeCompletor has some difference and limitations.
+```ruby
+[0, 'a'].sample.
+# Steep completes intersection of Integer methods and String methods
+# IRB::TypeCompletor completes both Integer and String methods
+```
+
+Some features like type narrowing is not implemented.
+```ruby
+def f(arg = [0, 'a'].sample)
+  if arg.is_a?(String)
+    arg. # Completes both Integer and String methods
+```
+
+Unlike other static type checker, IRB::TypeCompletor uses runtime information to provide better completion.
+```ruby
+irb(main):001> a = [1]
+=> [1]
+irb(main):002> a.first. # Completes Integer methods
+```
+
 ## 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.
+- `IRB_COMPLETOR`: Configures IRB's auto-completion behavior, allowing settings for either `regexp` or `type`.
 - `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
+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.
-
-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.
+IRB `v1.13.0` and later versions allows users/libraries to extend its functionality through official APIs.
 
-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
 
@@ -269,6 +369,30 @@ 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.
 
+### Set up the environment
+
+1. Fork the project to your GithHub account
+2. Clone the fork with `git clone git@github.com:[your_username]/irb.git`
+3. Run `bundle install`
+4. Run `bundle exec rake` to make sure tests pass locally
+
+### Run integration tests
+
+If your changes affect component rendering, such as the autocompletion's dialog/dropdown, you may need to run IRB's integration tests, known as `yamatanooroti`.
+
+Before running these tests, ensure that you have `libvterm` installed. If you're using Homebrew, you can install it by running:
+
+```bash
+brew install libvterm
+```
+
+After installing `libvterm`, you can run the integration tests using the following commands:
+
+```bash
+WITH_VTERM=1 bundle install
+WITH_VTERM=1 bundle exec rake test test_yamatanooroti
+```
+
 ## Releasing
 
 ```

data/Rakefile

@@ -1,11 +1,12 @@
 require "bundler/gem_tasks"
 require "rake/testtask"
+require "rdoc/task"
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test" << "test/lib"
   t.libs << "lib"
   t.ruby_opts << "-rhelper"
-  t.test_files = FileList["test/irb/test_*.rb"]
+  t.test_files = FileList["test/irb/**/test_*.rb"]
 end
 
 # To make sure they have been correctly setup for Ruby CI.
@@ -13,11 +14,11 @@ desc "Run each irb test file in isolation."
 task :test_in_isolation do
   failed = false
 
-  FileList["test/irb/test_*.rb"].each do |test_file|
+  FileList["test/irb/**/test_*.rb"].each do |test_file|
     ENV["TEST"] = test_file
     begin
       Rake::Task["test"].execute
-    rescue => e
+    rescue
       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
@@ -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

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

data/lib/irb/cmd/nop.rb

@@ -1,53 +1,4 @@
-# frozen_string_literal: false
-#
-#   nop.rb -
-#   	by Keiju ISHITSUKA(keiju@ruby-lang.org)
-#
+# frozen_string_literal: true
 
-module IRB
-  # :stopdoc:
-
-  module ExtendCommand
-    class CommandArgumentError < StandardError; end
-
-    class Nop
-      class << self
-        def category(category = nil)
-          @category = category if category
-          @category
-        end
-
-        def description(description = nil)
-          @description = description if description
-          @description
-        end
-
-        private
-
-        def string_literal?(args)
-          sexp = Ripper.sexp(args)
-          sexp && sexp.size == 2 && sexp.last&.first&.first == :string_literal
-        end
-      end
-
-      def self.execute(irb_context, *opts, **kwargs, &block)
-        command = new(irb_context)
-        command.execute(*opts, **kwargs, &block)
-      rescue CommandArgumentError => e
-        puts e.message
-      end
-
-      def initialize(irb_context)
-        @irb_context = irb_context
-      end
-
-      attr_reader :irb_context
-
-      def execute(*opts)
-        #nop
-      end
-    end
-  end
-
-  # :startdoc:
-end
+# This file is just a placeholder for backward-compatibility.
+# 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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "debug"
+
+module IRB
+  # :stopdoc:
+
+  module Command
+    class Backtrace < DebugCommand
+      def execute(arg)
+        execute_debug_command(pre_cmds: "backtrace #{arg}")
+      end
+    end
+  end
+
+  # :startdoc:
+end

data/lib/irb/command/base.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+#
+#   nop.rb -
+#   	by Keiju ISHITSUKA(keiju@ruby-lang.org)
+#
+
+module IRB
+  # :stopdoc:
+
+  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)
+          @category = category if category
+          @category || "No category"
+        end
+
+        def description(description = nil)
+          @description = description if description
+          @description || "No description provided."
+        end
+
+        def help_message(help_message = nil)
+          @help_message = help_message if help_message
+          @help_message
+        end
+
+        private
+
+        def highlight(text)
+          Color.colorize(text, [:BOLD, :BLUE])
+        end
+      end
+
+      def self.execute(irb_context, arg)
+        new(irb_context).execute(arg)
+      rescue CommandArgumentError => e
+        puts e.message
+      end
+
+      def initialize(irb_context)
+        @irb_context = irb_context
+      end
+
+      attr_reader :irb_context
+
+      def execute(arg)
+        #nop
+      end
+    end
+
+    Nop = Base
+  end
+
+  # :startdoc:
+end

data/lib/irb/command/break.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "debug"
+
+module IRB
+  # :stopdoc:
+
+  module Command
+    class Break < DebugCommand
+      def execute(arg)
+        execute_debug_command(pre_cmds: "break #{arg}")
+      end
+    end
+  end
+
+  # :startdoc:
+end

data/lib/irb/command/catch.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "debug"
+
+module IRB
+  # :stopdoc:
+
+  module Command
+    class Catch < DebugCommand
+      def execute(arg)
+        execute_debug_command(pre_cmds: "catch #{arg}")
+      end
+    end
+  end
+
+  # :startdoc:
+end

data/lib/irb/command/chws.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+#
+#   change-ws.rb -
+#   	by Keiju ISHITSUKA(keiju@ruby-lang.org)
+#
+require_relative "../ext/change-ws"
+
+module IRB
+  # :stopdoc:
+
+  module Command
+
+    class CurrentWorkingWorkspace < Base
+      category "Workspace"
+      description "Show the current workspace."
+
+      def execute(_arg)
+        puts "Current workspace: #{irb_context.main}"
+      end
+    end
+
+    class ChangeWorkspace < Base
+      category "Workspace"
+      description "Change the current workspace to an object."
+
+      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
+
+  # :startdoc:
+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/{cmd → command}/continue.rb

@@ -5,10 +5,10 @@ require_relative "debug"
 module IRB
   # :stopdoc:
 
-  module ExtendCommand
+  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/{cmd → command}/debug.rb

@@ -1,20 +1,21 @@
-require_relative "nop"
 require_relative "../debug"
 
 module IRB
   # :stopdoc:
 
-  module ExtendCommand
-    class Debug < Nop
+  module Command
+    class Debug < Base
       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/ }
+      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
 
-      def execute(pre_cmds: nil, do_cmds: nil)
         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
@@ -30,8 +31,8 @@ module IRB
           # 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"
+          unless irb_context.from_binding?
+            puts "Debugging commands are only available when IRB is started with binding.irb"
             return
           end
 
@@ -54,16 +55,6 @@ module IRB
           throw :IRB_EXIT
         end
       end
-
-      private
-
-      def binding_irb?
-        caller.any? do |frame|
-          BINDING_IRB_FRAME_REGEXPS.any? do |regexp|
-            frame.match?(regexp)
-          end
-        end
-      end
     end
 
     class DebugCommand < Debug

data/lib/irb/{cmd → command}/delete.rb

@@ -5,10 +5,10 @@ require_relative "debug"
 module IRB
   # :stopdoc:
 
-  module ExtendCommand
+  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