irb 1.7.1 → 1.13.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8dc3e14a57010a1ece61f5ca0111e98742f29daea5ab1ad1bdc48e0de6e55b2
-  data.tar.gz: 7da9b8c9e3e3c68384c0f65eb030d7874c8f0d07c20ce651ab7b54f5bfdfb9bd
+  metadata.gz: 243737997cdd6abe7e129eb7e7945dca379f1af38ed4254dfe094f2a611918cc
+  data.tar.gz: 5a1cbbdf5ab88a61278afe32a5497f38efa1342e123734ae3ede6135aae9b91f
 SHA512:
-  metadata.gz: 73173c7af8ffa50bfa26a49ad1c2b7a2db12a89b006980b2b0d649bc6a03b776359ce03d20a9a7dde493c3c64e70e85864809436b546b571f23e77774748f35e
-  data.tar.gz: 371777b42d560af3196092e98555a46d9c93c4efa592e8f38365dd0f5be6863ea4a50d6160baedf7d7d7c6914087394cde33e0fd57e17bec68a63f64f8265a89
+  metadata.gz: 0b4e5d658e1eba4a0503ffd3776c3baffabb0782eb43a993aac593b6dc4383e9e209ca3c1f077c78225f612a1ac7607f951bc11a2ff8fd78a93e12029fbf1954
+  data.tar.gz: c9e978f318f22d322934b77b8c431830e67a9cb7cf365923041f77123ee5e7d39ffa814a4e7bdd9af759f4671d0b24bd2ae68a9d20beb54b4a0e4248e32ee85f

data/.document

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

data/Gemfile

@@ -15,4 +15,13 @@ gem "stackprof" if is_unix && !is_truffleruby
 gem "reline", github: "ruby/reline" if ENV["WITH_LATEST_RELINE"] == "true"
 gem "rake"
 gem "test-unit"
-gem "debug", github: "ruby/debug"
+gem "test-unit-ruby-core"
+
+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

@@ -1,15 +1,36 @@
 # 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)
+- [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)
+- [Extending IRB](#extending-irb)
+- [Development](#development)
+- [Contributing](#contributing)
+- [Releasing](#releasing)
+- [License](#license)
+
 ## Installation
 
-> **Note**
+> [!Note]
 >
 > IRB is a default gem of Ruby so you shouldn't need to install it separately.
 >
@@ -35,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.
@@ -43,15 +68,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
 ```
@@ -82,25 +107,33 @@ 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.
 
+```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.
+  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.
-  irb_load       Load a Ruby file.
-  irb_require    Require a Ruby file.
-  source         Loads a given file in the current session.
+
+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,14 +148,194 @@ 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 or source location.
   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.
+  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
+
+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. Alternatively, if the `debug` method happens to already be defined in the current scope, you can call `irb_debug`.
+
+```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 `help` 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.
+
+## 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
@@ -131,12 +344,20 @@ Context
 
 - `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.
+- `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 `v1.13.0` and later versions allows users/libraries to extend its functionality through official APIs.
+
+For more information, please visit [EXTEND_IRB.md](./EXTEND_IRB.md).
 
 ## Development
 
@@ -148,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
@@ -41,11 +42,13 @@ 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
+
+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/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.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

@@ -9,12 +9,14 @@ module IRB # :nodoc:
     BOLD      = 1
     UNDERLINE = 4
     REVERSE   = 7
+    BLACK     = 30
     RED       = 31
     GREEN     = 32
     YELLOW    = 33
     BLUE      = 34
     MAGENTA   = 35
     CYAN      = 36
+    WHITE     = 37
 
     TOKEN_KEYWORDS = {
       on_kw: ['nil', 'self', 'true', 'false', '__FILE__', '__LINE__', '__ENCODING__'],
@@ -77,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