irb 1.4.2 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25f63261bbf06e8b1605b8a680e538dd90641ad2492c0bfb0f8e127f673e2793
-  data.tar.gz: 9f113f6c97887e83f9d476dba5e4c0a5656d76cc554e1e818c94e8828b4051fa
+  metadata.gz: 33ff0b70fb3730f087bc24a7a8b63253ba1a4ad0416a0ffcd1e5395f26e5d0b2
+  data.tar.gz: 9cd418e90733c4cb4658368b2a899b50490ad9dbd7352a1c1df0070c10d9669d
 SHA512:
-  metadata.gz: 024d8e4dc13978bbae5ed3404e3ecff763da3fcc01e26c43d3e7e54822121bbc708de49c5a9c951a15c0ceee05a60cf282cbbd6ae6ec42960e9a8943a9217417
-  data.tar.gz: 146edac46f0d81a01e120493e56eefa8d8b51143851718876617673bcbddf19b54e246d55541833101926e17186ce55b6484e2fb20e6f57735ee49ddfe0b6890
+  metadata.gz: ec6102a41d55404aa8e5585243cbe74fcdbe1e1d5bcd88ddae4240adff4281d14200b99c621324515a4e226eff5964644a7e8456d707af2ca7dcf8e5211a0b4b
+  data.tar.gz: 0ed81d78ce49803706b36f36e173acb1e27f3e217bd3c6e00e46d4875b6be3c7958a2cb3db146703c3cbf7198094561a562e0fd244f6a61501f9ae5196df343a

data/README.md

@@ -40,6 +40,57 @@ 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.
+
+* `cwws`
+  * Show the current workspace.
+* `cb`, `cws`, `chws`
+  * Change the current workspace to an object.
+* `bindings`, `workspaces`
+  * Show workspaces.
+* `edit`
+  * Open a file with the editor command defined with `ENV["EDITOR"]`
+    * `edit` - opens the file the current context belongs to (if applicable)
+    * `edit foo.rb` - opens `foo.rb`
+    * `edit Foo` - opens the location of `Foo`
+    * `edit Foo.bar` - opens the location of `Foo.bar`
+    * `edit Foo#bar` - opens the location of `Foo#bar`
+* `pushb`, `pushws`
+  * Push an object to the workspace stack.
+* `popb`, `popws`
+  * Pop a workspace from the workspace stack.
+* `load`
+  * Load a Ruby file.
+* `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.
+* `help`
+  * Enter the mode to look up RI documents.
+* `irb_info`
+  * Show information about IRB.
+* `ls`
+  * Show methods, constants, and variables.
+    `-g [query]` or `-G [query]` allows you to filter out the output.
+* `measure`
+  * `measure` enables the mode to measure processing time. `measure :off` disables it.
+* `$`, `show_source`
+  * Show the source code of a given method or constant.
+* `@`, `whereami`
+  * Show the source code around binding.irb again.
+* `debug`
+  * Start the debugger of debug.gem.
+
 ## Documentation
 
 https://docs.ruby-lang.org/en/master/IRB.html

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/debug.rb

@@ -0,0 +1,96 @@
+require_relative "nop"
+
+module IRB
+  # :stopdoc:
+
+  module ExtendCommand
+    class Debug < Nop
+      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(*args)
+        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
+
+        # 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, oneshot: true, hook_call: false)
+        # 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
+
+      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
+        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.map { |path| Dir.glob("#{path}/gems/debug-*") }.flatten.select do |path|
+          File.basename(path).match?(/\Adebug-\d+\.\d+\.\d+\z/)
+        end.sort_by do |path|
+          Gem::Version.new(File.basename(path).delete_prefix('debug-'))
+        end.last
+        return false unless debug_gem
+
+        # Attempt to forcibly load the bundled gem
+        $LOAD_PATH << "#{debug_gem}/lib"
+        begin
+          require "debug/session"
+          puts "Loaded #{File.basename(debug_gem)}"
+          true
+        rescue LoadError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/irb/cmd/edit.rb

@@ -0,0 +1,65 @@
+require 'shellwords'
+require_relative "nop"
+
+module IRB
+  # :stopdoc:
+
+  module ExtendCommand
+    class Edit < Nop
+      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
+
+        private
+
+        def string_literal?(args)
+          sexp = Ripper.sexp(args)
+          sexp && sexp.size == 2 && sexp.last&.first&.first == :string_literal
+        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/ls.rb

@@ -9,6 +9,15 @@ module IRB
 
   module ExtendCommand
     class Ls < Nop
+      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)
 

data/lib/irb/cmd/show_source.rb

@@ -9,12 +9,73 @@ module IRB
 
   module ExtendCommand
     class ShowSource < 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
+
+        def find_source(str, irb_context)
+          case str
+          when /\A[A-Z]\w*(::[A-Z]\w*)*\z/ # Const::Name
+            eval(str, irb_context.workspace.binding) # trigger autoload
+            base = irb_context.workspace.binding.receiver.yield_self { |r| r.is_a?(Module) ? r : Object }
+            file, line = base.const_source_location(str) if base.respond_to?(:const_source_location) # Ruby 2.7+
+          when /\A(?<owner>[A-Z]\w*(::[A-Z]\w*)*)#(?<method>[^ :.]+)\z/ # Class#method
+            owner = eval(Regexp.last_match[:owner], irb_context.workspace.binding)
+            method = Regexp.last_match[:method]
+            if owner.respond_to?(:instance_method) && owner.instance_methods.include?(method.to_sym)
+              file, line = owner.instance_method(method).source_location
+            end
+          when /\A((?<receiver>.+)(\.|::))?(?<method>[^ :.]+)\z/ # method, receiver.method, receiver::method
+            receiver = eval(Regexp.last_match[:receiver] || 'self', irb_context.workspace.binding)
+            method = Regexp.last_match[:method]
+            file, line = receiver.method(method).source_location if receiver.respond_to?(method)
+          end
+          if file && line
+            Source.new(file: file, first_line: line, last_line: find_end(file, line))
+          end
+        end
+
+        private
+
+        def find_end(file, first_line)
+          return first_line unless File.exist?(file)
+          lex = RubyLex.new
+          lines = File.read(file).lines[(first_line - 1)..-1]
+          tokens = RubyLex.ripper_lex_without_warning(lines.join)
+          prev_tokens = []
+
+          # chunk with line number
+          tokens.chunk { |tok| tok.pos[0] }.each do |lnum, chunk|
+            code = lines[0..lnum].join
+            prev_tokens.concat chunk
+            continue = lex.process_continue(prev_tokens)
+            code_block_open = lex.check_code_block(code, prev_tokens)
+            if !continue && !code_block_open
+              return first_line + lnum
+            end
+          end
+          first_line
+        end
+
+        def string_literal?(args)
+          sexp = Ripper.sexp(args)
+          sexp && sexp.size == 2 && sexp.last&.first&.first == :string_literal
+        end
+      end
+
       def execute(str = nil)
         unless str.is_a?(String)
           puts "Error: Expected a string but got #{str.inspect}"
           return
         end
-        source = find_source(str)
+
+        source = self.class.find_source(str, @irb_context)
         if source && File.exist?(source.file)
           show_source(source)
         else
@@ -35,48 +96,6 @@ module IRB
         puts
       end
 
-      def find_source(str)
-        case str
-        when /\A[A-Z]\w*(::[A-Z]\w*)*\z/ # Const::Name
-          eval(str, irb_context.workspace.binding) # trigger autoload
-          base = irb_context.workspace.binding.receiver.yield_self { |r| r.is_a?(Module) ? r : Object }
-          file, line = base.const_source_location(str) if base.respond_to?(:const_source_location) # Ruby 2.7+
-        when /\A(?<owner>[A-Z]\w*(::[A-Z]\w*)*)#(?<method>[^ :.]+)\z/ # Class#method
-          owner = eval(Regexp.last_match[:owner], irb_context.workspace.binding)
-          method = Regexp.last_match[:method]
-          if owner.respond_to?(:instance_method) && owner.instance_methods.include?(method.to_sym)
-            file, line = owner.instance_method(method).source_location
-          end
-        when /\A((?<receiver>.+)(\.|::))?(?<method>[^ :.]+)\z/ # method, receiver.method, receiver::method
-          receiver = eval(Regexp.last_match[:receiver] || 'self', irb_context.workspace.binding)
-          method = Regexp.last_match[:method]
-          file, line = receiver.method(method).source_location if receiver.respond_to?(method)
-        end
-        if file && line
-          Source.new(file: file, first_line: line, last_line: find_end(file, line))
-        end
-      end
-
-      def find_end(file, first_line)
-        return first_line unless File.exist?(file)
-        lex = RubyLex.new
-        lines = File.read(file).lines[(first_line - 1)..-1]
-        tokens = RubyLex.ripper_lex_without_warning(lines.join)
-        prev_tokens = []
-
-        # chunk with line number
-        tokens.chunk { |tok| tok.pos[0] }.each do |lnum, chunk|
-          code = lines[0..lnum].join
-          prev_tokens.concat chunk
-          continue = lex.process_continue(prev_tokens)
-          code_block_open = lex.check_code_block(code, prev_tokens)
-          if !continue && !code_block_open
-            return first_line + lnum
-          end
-        end
-        first_line
-      end
-
       def bold(str)
         Color.colorize(str, [:BOLD])
       end

data/lib/irb/color.rb

@@ -123,13 +123,15 @@ module IRB # :nodoc:
       # If `complete` is false (code is incomplete), this does not warn compile_error.
       # This option is needed to avoid warning a user when the compile_error is happening
       # because the input is not wrong but just incomplete.
-      def colorize_code(code, complete: true, ignore_error: false, colorable: colorable?)
+      def colorize_code(code, complete: true, ignore_error: false, colorable: colorable?, local_variables: [])
         return code unless colorable
 
         symbol_state = SymbolState.new
         colored = +''
+        lvars_code = RubyLex.generate_local_variables_assign_code(local_variables)
+        code_with_lvars = lvars_code ? "#{lvars_code}\n#{code}" : code
 
-        scan(code, allow_last_error: !complete) do |token, str, expr|
+        scan(code_with_lvars, allow_last_error: !complete) do |token, str, expr|
           # handle uncolorable code
           if token.nil?
             colored << Reline::Unicode.escape_for_print(str)
@@ -152,6 +154,11 @@ module IRB # :nodoc:
             end
           end
         end
+
+        if lvars_code
+          raise "#{lvars_code.dump} should have no \\n" if lvars_code.include?("\n")
+          colored.sub!(/\A.+\n/, '') # delete_prefix lvars_code with colors
+        end
         colored
       end
 

data/lib/irb/completion.rb

@@ -64,25 +64,27 @@ module IRB
       if File.respond_to?(:absolute_path?)
         File.absolute_path?(p)
       else
-        if File.absolute_path(p) == p
-          true
-        else
-          false
-        end
+        File.absolute_path(p) == p
       end
     end
 
+    GEM_PATHS =
+      if defined?(Gem::Specification)
+        Gem::Specification.latest_specs(true).map { |s|
+          s.require_paths.map { |p|
+            if absolute_path?(p)
+              p
+            else
+              File.join(s.full_gem_path, p)
+            end
+          }
+        }.flatten
+      else
+        []
+      end.freeze
+
     def self.retrieve_gem_and_system_load_path
-      gem_paths = Gem::Specification.latest_specs(true).map { |s|
-        s.require_paths.map { |p|
-          if absolute_path?(p)
-            p
-          else
-            File.join(s.full_gem_path, p)
-          end
-        }
-      }.flatten if defined?(Gem::Specification)
-      candidates = (gem_paths.to_a | $LOAD_PATH)
+      candidates = (GEM_PATHS | $LOAD_PATH)
       candidates.map do |p|
         if p.respond_to?(:to_path)
           p.to_path
@@ -171,10 +173,10 @@ module IRB
         receiver = $1
         message = $3
 
-        candidates = String.instance_methods.collect{|m| m.to_s}
         if doc_namespace
           "String.#{message}"
         else
+          candidates = String.instance_methods.collect{|m| m.to_s}
           select_message(receiver, message, candidates)
         end
 
@@ -183,10 +185,10 @@ module IRB
         receiver = $1
         message = $2
 
-        candidates = Regexp.instance_methods.collect{|m| m.to_s}
         if doc_namespace
           "Regexp.#{message}"
         else
+          candidates = Regexp.instance_methods.collect{|m| m.to_s}
           select_message(receiver, message, candidates)
         end
 
@@ -195,10 +197,10 @@ module IRB
         receiver = $1
         message = $2
 
-        candidates = Array.instance_methods.collect{|m| m.to_s}
         if doc_namespace
           "Array.#{message}"
         else
+          candidates = Array.instance_methods.collect{|m| m.to_s}
           select_message(receiver, message, candidates)
         end
 
@@ -207,29 +209,33 @@ module IRB
         receiver = $1
         message = $2
 
-        proc_candidates = Proc.instance_methods.collect{|m| m.to_s}
-        hash_candidates = Hash.instance_methods.collect{|m| m.to_s}
         if doc_namespace
           ["Proc.#{message}", "Hash.#{message}"]
         else
+          proc_candidates = Proc.instance_methods.collect{|m| m.to_s}
+          hash_candidates = Hash.instance_methods.collect{|m| m.to_s}
           select_message(receiver, message, proc_candidates | hash_candidates)
         end
 
       when /^(:[^:.]*)$/
         # Symbol
-        return nil if doc_namespace
-        sym = $1
-        candidates = Symbol.all_symbols.collect do |s|
-          ":" + s.id2name.encode(Encoding.default_external)
-        rescue EncodingError
-          # ignore
+        if doc_namespace
+          nil
+        else
+          sym = $1
+          candidates = Symbol.all_symbols.collect do |s|
+            ":" + s.id2name.encode(Encoding.default_external)
+          rescue EncodingError
+            # ignore
+          end
+          candidates.grep(/^#{Regexp.quote(sym)}/)
         end
-        candidates.grep(/^#{Regexp.quote(sym)}/)
-
       when /^::([A-Z][^:\.\(\)]*)$/
         # Absolute Constant or class methods
         receiver = $1
+
         candidates = Object.constants.collect{|m| m.to_s}
+
         if doc_namespace
           candidates.find { |i| i == receiver }
         else
@@ -240,16 +246,18 @@ module IRB
         # Constant or class methods
         receiver = $1
         message = $2
-        begin
-          candidates = eval("#{receiver}.constants.collect{|m| m.to_s}", bind)
-          candidates |= eval("#{receiver}.methods.collect{|m| m.to_s}", bind)
-        rescue Exception
-          candidates = []
-        end
+
         if doc_namespace
           "#{receiver}::#{message}"
         else
-          select_message(receiver, message, candidates, "::")
+          begin
+            candidates = eval("#{receiver}.constants.collect{|m| m.to_s}", bind)
+            candidates |= eval("#{receiver}.methods.collect{|m| m.to_s}", bind)
+          rescue Exception
+            candidates = []
+          end
+
+          select_message(receiver, message, candidates.sort, "::")
         end
 
       when /^(:[^:.]+)(\.|::)([^.]*)$/
@@ -258,10 +266,10 @@ module IRB
         sep = $2
         message = $3
 
-        candidates = Symbol.instance_methods.collect{|m| m.to_s}
         if doc_namespace
           "Symbol.#{message}"
         else
+          candidates = Symbol.instance_methods.collect{|m| m.to_s}
           select_message(receiver, message, candidates, sep)
         end
 
@@ -273,6 +281,7 @@ module IRB
 
         begin
           instance = eval(receiver, bind)
+
           if doc_namespace
             "#{instance.class.name}.#{message}"
           else
@@ -283,7 +292,7 @@ module IRB
           if doc_namespace
             nil
           else
-            candidates = []
+            []
           end
         end
 
@@ -305,7 +314,7 @@ module IRB
           if doc_namespace
             nil
           else
-            candidates = []
+            []
           end
         end
 
@@ -313,6 +322,7 @@ module IRB
         # global var
         gvar = $1
         all_gvars = global_variables.collect{|m| m.to_s}
+
         if doc_namespace
           all_gvars.find{ |i| i == gvar }
         else
@@ -351,11 +361,13 @@ module IRB
           to_ignore = ignored_modules
           ObjectSpace.each_object(Module){|m|
             next if (to_ignore.include?(m) rescue true)
+            next unless m.respond_to?(:instance_methods) # JRuby has modules that represent java packages. They don't include many common ruby methods
             candidates.concat m.instance_methods(false).collect{|x| x.to_s}
           }
           candidates.sort!
           candidates.uniq!
         end
+
         if doc_namespace
           rec_class = rec.is_a?(Module) ? rec : rec.class
           "#{rec_class.name}#{sep}#{candidates.find{ |i| i == message }}"
@@ -370,10 +382,11 @@ module IRB
         message = $1
 
         candidates = String.instance_methods(true).collect{|m| m.to_s}
+
         if doc_namespace
           "String.#{candidates.find{ |i| i == message }}"
         else
-          select_message(receiver, message, candidates)
+          select_message(receiver, message, candidates.sort)
         end
 
       else
@@ -390,7 +403,7 @@ module IRB
         else
           candidates = (bind.eval_methods | bind.eval_private_methods | bind.local_variables | bind.eval_instance_variables | bind.eval_class_constants).collect{|m| m.to_s}
           candidates |= ReservedWords
-          candidates.grep(/^#{Regexp.quote(input)}/)
+          candidates.grep(/^#{Regexp.quote(input)}/).sort
         end
       end
     end

data/lib/irb/context.rb

@@ -49,12 +49,15 @@ module IRB
       if IRB.conf.has_key?(:USE_MULTILINE)
         @use_multiline = IRB.conf[:USE_MULTILINE]
       elsif IRB.conf.has_key?(:USE_RELINE) # backward compatibility
+        warn <<~MSG.strip
+          USE_RELINE is deprecated, please use USE_MULTILINE instead.
+        MSG
         @use_multiline = IRB.conf[:USE_RELINE]
       elsif IRB.conf.has_key?(:USE_REIDLINE)
         warn <<~MSG.strip
-          USE_REIDLINE is deprecated, please use USE_RELINE instead.
+          USE_REIDLINE is deprecated, please use USE_MULTILINE instead.
         MSG
-        @use_multiline = IRB.conf[:USE_RELINE]
+        @use_multiline = IRB.conf[:USE_REIDLINE]
       else
         @use_multiline = nil
       end
@@ -149,6 +152,8 @@ module IRB
       if @newline_before_multiline_output.nil?
         @newline_before_multiline_output = true
       end
+
+      @command_aliases = IRB.conf[:COMMAND_ALIASES]
     end
 
     # The top-level workspace, see WorkSpace#main
@@ -326,6 +331,9 @@ module IRB
     # See IRB@Command+line+options for more command line options.
     attr_accessor :back_trace_limit
 
+    # User-defined IRB command aliases
+    attr_accessor :command_aliases
+
     # Alias for #use_multiline
     alias use_multiline? use_multiline
     # Alias for #use_singleline
@@ -477,6 +485,20 @@ module IRB
         line = "begin ::Kernel.raise _; rescue _.class\n#{line}\n""end"
         @workspace.local_variable_set(:_, exception)
       end
+
+      # Transform a non-identifier alias (ex: @, $)
+      command, args = line.split(/\s/, 2)
+      if original = symbol_alias(command)
+        line = line.gsub(/\A#{Regexp.escape(command)}/, original.to_s)
+        command = original
+      end
+
+      # Hook command-specific transformation
+      command_class = ExtendCommandBundle.load_command(command)
+      if command_class&.respond_to?(:transform_args)
+        line = "#{command} #{command_class.transform_args(args)}"
+      end
+
       set_last_value(@workspace.evaluate(self, line, irb_path, line_no))
     end
 
@@ -518,5 +540,15 @@ module IRB
     end
     alias __to_s__ to_s
     alias to_s inspect
+
+    def local_variables # :nodoc:
+      workspace.binding.local_variables
+    end
+
+    # Return a command name if it's aliased from the argument and it's not an identifier.
+    def symbol_alias(command)
+      return nil if command.match?(/\A\w+\z/)
+      command_aliases[command.to_sym]
+    end
   end
 end

data/lib/irb/ext/save-history.rb

@@ -73,7 +73,7 @@ module IRB
         open(history_file, "r:#{IRB.conf[:LC_MESSAGES].encoding}") do |f|
           f.each { |l|
             l = l.chomp
-            if self.class == ReidlineInputMethod and history.last&.end_with?("\\")
+            if self.class == RelineInputMethod and history.last&.end_with?("\\")
               history.last.delete_suffix!("\\")
               history.last << "\n" << l
             else

data/lib/irb/extend-command.rb

@@ -116,6 +116,14 @@ module IRB # :nodoc:
         [:kill, OVERRIDE_PRIVATE_ONLY],
       ],
 
+      [
+        :irb_debug, :Debug, "cmd/debug",
+        [:debug, NO_OVERRIDE],
+      ],
+      [
+        :irb_edit, :Edit, "cmd/edit",
+        [:edit, NO_OVERRIDE],
+      ],
       [
         :irb_help, :Help, "cmd/help",
         [:help, NO_OVERRIDE],
@@ -147,21 +155,21 @@ module IRB # :nodoc:
 
     ]
 
-    # Installs the default irb commands:
-    #
-    # +irb_current_working_workspace+::   Context#main
-    # +irb_change_workspace+::            Context#change_workspace
-    # +irb_workspaces+::                  Context#workspaces
-    # +irb_push_workspace+::              Context#push_workspace
-    # +irb_pop_workspace+::               Context#pop_workspace
-    # +irb_load+::                        #irb_load
-    # +irb_require+::                     #irb_require
-    # +irb_source+::                      IrbLoader#source_file
-    # +irb+::                             IRB.irb
-    # +irb_jobs+::                        JobManager
-    # +irb_fg+::                          JobManager#switch
-    # +irb_kill+::                        JobManager#kill
-    # +irb_help+::                        IRB@Command+line+options
+    # Convert a command name to its implementation class if such command exists
+    def self.load_command(command)
+      command = command.to_sym
+      @EXTEND_COMMANDS.each do |cmd_name, cmd_class, load_file, *aliases|
+        next if cmd_name != command && aliases.all? { |alias_name, _| alias_name != command }
+
+        if !defined?(ExtendCommand) || !ExtendCommand.const_defined?(cmd_class, false)
+          require_relative load_file
+        end
+        return ExtendCommand.const_get(cmd_class, false)
+      end
+      nil
+    end
+
+    # Installs the default irb commands.
     def self.install_extend_commands
       for args in @EXTEND_COMMANDS
         def_extend_command(*args)

data/lib/irb/init.rb

@@ -44,7 +44,7 @@ module IRB # :nodoc:
     @CONF[:IRB_RC] = nil
 
     @CONF[:USE_SINGLELINE] = false unless defined?(ReadlineInputMethod)
-    @CONF[:USE_COLORIZE] = !ENV['NO_COLOR']
+    @CONF[:USE_COLORIZE] = (nc = ENV['NO_COLOR']).nil? || nc.empty?
     @CONF[:USE_AUTOCOMPLETE] = true
     @CONF[:INSPECT_MODE] = true
     @CONF[:USE_TRACER] = false
@@ -158,6 +158,11 @@ module IRB # :nodoc:
     @CONF[:LC_MESSAGES] = Locale.new
 
     @CONF[:AT_EXIT] = []
+
+    @CONF[:COMMAND_ALIASES] = {
+      :'$' => :show_source,
+      :'@' => :whereami,
+    }
   end
 
   def IRB.set_measure_callback(type = nil, arg = nil, &block)
@@ -255,8 +260,20 @@ module IRB # :nodoc:
       when "--nosingleline", "--noreadline"
         @CONF[:USE_SINGLELINE] = false
       when "--multiline", "--reidline"
+        if opt == "--reidline"
+          warn <<~MSG.strip
+            --reidline is deprecated, please use --multiline instead.
+          MSG
+        end
+
         @CONF[:USE_MULTILINE] = true
       when "--nomultiline", "--noreidline"
+        if opt == "--noreidline"
+          warn <<~MSG.strip
+            --noreidline is deprecated, please use --nomultiline instead.
+          MSG
+        end
+
         @CONF[:USE_MULTILINE] = false
       when /^--extra-doc-dir(?:=(.+))?/
         opt = $1 || argv.shift
@@ -379,11 +396,9 @@ module IRB # :nodoc:
     end
     if xdg_config_home = ENV["XDG_CONFIG_HOME"]
       irb_home = File.join(xdg_config_home, "irb")
-      unless File.exist? irb_home
-        require 'fileutils'
-        FileUtils.mkdir_p irb_home
+      if File.directory?(irb_home)
+        yield proc{|rc| irb_home + "/irb#{rc}"}
       end
-      yield proc{|rc| irb_home + "/irb#{rc}"}
     end
     if home = ENV["HOME"]
       yield proc{|rc| home+"/.irb#{rc}"}

data/lib/irb/input-method.rb

@@ -286,7 +286,8 @@ module IRB
         if IRB.conf[:USE_COLORIZE]
           proc do |output, complete: |
             next unless IRB::Color.colorable?
-            IRB::Color.colorize_code(output, complete: complete)
+            lvars = IRB.CurrentContext&.local_variables || []
+            IRB::Color.colorize_code(output, complete: complete, local_variables: lvars)
           end
         else
           proc do |output|
@@ -295,8 +296,13 @@ module IRB
         end
       Reline.dig_perfect_match_proc = IRB::InputCompletor::PerfectMatchedProc
       Reline.autocompletion = IRB.conf[:USE_AUTOCOMPLETE]
+
       if IRB.conf[:USE_AUTOCOMPLETE]
-        Reline.add_dialog_proc(:show_doc, SHOW_DOC_DIALOG, Reline::DEFAULT_DIALOG_CONTEXT)
+        begin
+          require 'rdoc'
+          Reline.add_dialog_proc(:show_doc, SHOW_DOC_DIALOG, Reline::DEFAULT_DIALOG_CONTEXT)
+        rescue LoadError
+        end
       end
     end
 
@@ -320,11 +326,6 @@ module IRB
         [195, 164], # The "ä" that appears when Alt+d is pressed on xterm.
         [226, 136, 130] # The "∂" that appears when Alt+d in pressed on iTerm2.
       ]
-      begin
-        require 'rdoc'
-      rescue LoadError
-        return nil
-      end
 
       if just_cursor_moving and completion_journey_data.nil?
         return nil
@@ -460,7 +461,7 @@ module IRB
     # For debug message
     def inspect
       config = Reline::Config.new
-      str = "ReidlineInputMethod with Reline #{Reline::VERSION}"
+      str = "RelineInputMethod with Reline #{Reline::VERSION}"
       if config.respond_to?(:inputrc_path)
         inputrc_path = File.expand_path(config.inputrc_path)
       else

data/lib/irb/ruby-lex.rb

@@ -48,7 +48,7 @@ class RubyLex
   end
 
   # io functions
-  def set_input(io, p = nil, context: nil, &block)
+  def set_input(io, p = nil, context:, &block)
     @io = io
     if @io.respond_to?(:check_termination)
       @io.check_termination do |code|
@@ -65,6 +65,12 @@ class RubyLex
             false
           end
         else
+          # Accept any single-line input starting with a non-identifier alias (ex: @, $)
+          command = code.split(/\s/, 2).first
+          if context.symbol_alias(command)
+            next true
+          end
+
           code.gsub!(/\s*\z/, '').concat("\n")
           ltype, indent, continue, code_block_open = check_state(code, context: context)
           if ltype or indent > 0 or continue or code_block_open
@@ -136,16 +142,18 @@ class RubyLex
     :on_param_error
   ]
 
+  def self.generate_local_variables_assign_code(local_variables)
+    "#{local_variables.join('=')}=nil;" unless local_variables.empty?
+  end
+
   def self.ripper_lex_without_warning(code, context: nil)
     verbose, $VERBOSE = $VERBOSE, nil
-    if context
-      lvars = context.workspace&.binding&.local_variables
-      if lvars && !lvars.empty?
-        code = "#{lvars.join('=')}=nil\n#{code}"
-        line_no = 0
-      else
-        line_no = 1
-      end
+    lvars_code = generate_local_variables_assign_code(context&.local_variables || [])
+    if lvars_code
+      code = "#{lvars_code}\n#{code}"
+      line_no = 0
+    else
+      line_no = 1
     end
 
     compile_with_errors_suppressed(code, line_no: line_no) do |inner_code, line_no|
@@ -162,7 +170,7 @@ class RubyLex
           end
         end
       else
-        lexer.parse.reject { |it| it.pos.first == 0 }
+        lexer.parse.reject { |it| it.pos.first == 0 }.sort_by(&:pos)
       end
     end
   ensure
@@ -214,6 +222,8 @@ class RubyLex
     ltype = process_literal_type(tokens)
     indent = process_nesting_level(tokens)
     continue = process_continue(tokens)
+    lvars_code = self.class.generate_local_variables_assign_code(context.local_variables)
+    code = "#{lvars_code}\n#{code}" if lvars_code
     code_block_open = check_code_block(code, tokens)
     [ltype, indent, continue, code_block_open]
   end
@@ -233,13 +243,13 @@ class RubyLex
     @code_block_open = false
   end
 
-  def each_top_level_statement
+  def each_top_level_statement(context)
     initialize_input
     catch(:TERM_INPUT) do
       loop do
         begin
           prompt
-          unless l = lex
+          unless l = lex(context)
             throw :TERM_INPUT if @line == ''
           else
             @line_no += l.count("\n")
@@ -269,18 +279,15 @@ class RubyLex
     end
   end
 
-  def lex
+  def lex(context)
     line = @input.call
     if @io.respond_to?(:check_termination)
       return line # multiline
     end
     code = @line + (line.nil? ? '' : line)
     code.gsub!(/\s*\z/, '').concat("\n")
-    @tokens = self.class.ripper_lex_without_warning(code)
-    @continue = process_continue
-    @code_block_open = check_code_block(code)
-    @indent = process_nesting_level
-    @ltype = process_literal_type
+    @tokens = self.class.ripper_lex_without_warning(code, context: context)
+    @ltype, @indent, @continue, @code_block_open = check_state(code, @tokens, context: context)
     line
   end
 
@@ -706,6 +713,7 @@ class RubyLex
     i = 0
     start_token = []
     end_type = []
+    pending_heredocs = []
     while i < tokens.size
       t = tokens[i]
       case t.event
@@ -729,18 +737,27 @@ class RubyLex
           end
         end
       when :on_backtick
-        start_token << t
-        end_type << :on_tstring_end
+        if t.state.allbits?(Ripper::EXPR_BEG)
+          start_token << t
+          end_type << :on_tstring_end
+        end
       when :on_qwords_beg, :on_words_beg, :on_qsymbols_beg, :on_symbols_beg
         start_token << t
         end_type << :on_tstring_end
       when :on_heredoc_beg
-        start_token << t
-        end_type << :on_heredoc_end
+        pending_heredocs << t
+      end
+
+      if pending_heredocs.any? && t.tok.include?("\n")
+        pending_heredocs.reverse_each do |t|
+          start_token << t
+          end_type << :on_heredoc_end
+        end
+        pending_heredocs = []
       end
       i += 1
     end
-    start_token.last.nil? ? nil : start_token.last
+    pending_heredocs.first || start_token.last
   end
 
   def process_literal_type(tokens = @tokens)

data/lib/irb/version.rb

@@ -11,7 +11,7 @@
 #
 
 module IRB # :nodoc:
-  VERSION = "1.4.2"
+  VERSION = "1.5.0"
   @RELEASE_VERSION = VERSION
-  @LAST_UPDATE_DATE = "2022-10-03"
+  @LAST_UPDATE_DATE = "2022-11-20"
 end

data/lib/irb.rb

@@ -53,6 +53,50 @@ require_relative "irb/easter-egg"
 #
 #   :include: ./irb/lc/help-message
 #
+# == Commands
+#
+# The following commands are available on IRB.
+#
+# * cwws
+#   * Show the current workspace.
+# * cb, cws, chws
+#   * Change the current workspace to an object.
+# * bindings, workspaces
+#   * Show workspaces.
+# * pushb, pushws
+#   * Push an object to the workspace stack.
+# * popb, popws
+#   * Pop a workspace from the workspace stack.
+# * load
+#   * Load a Ruby file.
+# * 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.
+# * help
+#   * Enter the mode to look up RI documents.
+# * irb_info
+#   * Show information about IRB.
+# * ls
+#   * Show methods, constants, and variables.
+#     -g [query] or -G [query] allows you to filter out the output.
+# * measure
+#   * measure enables the mode to measure processing time. measure :off disables it.
+# * $, show_source
+#   * Show the source code of a given method or constant.
+# * @, whereami
+#   * Show the source code around binding.irb again.
+# * debug
+#   * Start the debugger of debug.gem.
+#
 # == Configuration
 #
 # IRB reads a personal initialization file when it's invoked.
@@ -93,9 +137,9 @@ require_relative "irb/easter-egg"
 #
 # === Autocompletion
 #
-# To enable autocompletion for irb, add the following to your +.irbrc+:
+# To disable autocompletion for irb, add the following to your +.irbrc+:
 #
-#     require 'irb/completion'
+#     IRB.conf[:USE_AUTOCOMPLETE] = false
 #
 # === History
 #
@@ -426,10 +470,25 @@ module IRB
     def initialize(workspace = nil, input_method = nil)
       @context = Context.new(self, workspace, input_method)
       @context.main.extend ExtendCommandBundle
+      @context.command_aliases.each do |alias_name, cmd_name|
+        next if @context.symbol_alias(alias_name)
+        @context.main.install_alias_method(alias_name, cmd_name)
+      end
       @signal_status = :IN_IRB
       @scanner = RubyLex.new
     end
 
+    # A hook point for `debug` command's TracePoint after :IRB_EXIT as well as its clean-up
+    def debug_break
+      # it means the debug command is executed
+      if defined?(DEBUGGER__) && DEBUGGER__.respond_to?(:capture_frames_without_irb)
+        # after leaving this initial breakpoint, revert the capture_frames patch
+        DEBUGGER__.singleton_class.send(:alias_method, :capture_frames, :capture_frames_without_irb)
+        # and remove the redundant method
+        DEBUGGER__.singleton_class.send(:undef_method, :capture_frames_without_irb)
+      end
+    end
+
     def run(conf = IRB.conf)
       conf[:IRB_RC].call(context) if conf[:IRB_RC]
       conf[:MAIN_CONTEXT] = context
@@ -506,13 +565,15 @@ module IRB
 
       @scanner.set_auto_indent(@context) if @context.auto_indent_mode
 
-      @scanner.each_top_level_statement do |line, line_no|
+      @scanner.each_top_level_statement(@context) do |line, line_no|
         signal_status(:IN_EVAL) do
           begin
             line.untaint if RUBY_VERSION < '2.7'
             if IRB.conf[:MEASURE] && IRB.conf[:MEASURE_CALLBACKS].empty?
               IRB.set_measure_callback
             end
+            # Assignment expression check should be done before @context.evaluate to handle code like `a /2#/ if false; a = 1`
+            is_assignment = assignment_expression?(line)
             if IRB.conf[:MEASURE] && !IRB.conf[:MEASURE_CALLBACKS].empty?
               result = nil
               last_proc = proc{ result = @context.evaluate(line, line_no, exception: exc) }
@@ -529,7 +590,7 @@ module IRB
               @context.evaluate(line, line_no, exception: exc)
             end
             if @context.echo?
-              if assignment_expression?(line)
+              if is_assignment
                 if @context.echo_on_assignment?
                   output_value(@context.echo_on_assignment? == :truncate)
                 end
@@ -592,11 +653,7 @@ module IRB
 
       if exc.backtrace
         order = nil
-        if '2.5.0' == RUBY_VERSION
-          # Exception#full_message doesn't have keyword arguments.
-          message = exc.full_message # the same of (highlight: true, order: bottom)
-          order = :bottom
-        elsif '2.5.1' <= RUBY_VERSION && RUBY_VERSION < '3.0.0'
+        if RUBY_VERSION < '3.0.0'
           if STDOUT.tty?
             message = exc.full_message(order: :bottom)
             order = :bottom
@@ -827,9 +884,12 @@ module IRB
       # array of parsed expressions. The first element of each expression is the
       # expression's type.
       verbose, $VERBOSE = $VERBOSE, nil
-      result = ASSIGNMENT_NODE_TYPES.include?(Ripper.sexp(line)&.dig(1,-1,0))
+      code = "#{RubyLex.generate_local_variables_assign_code(@context.local_variables) || 'nil;'}\n#{line}"
+      # Get the last node_type of the line. drop(1) is to ignore the local_variables_assign_code part.
+      node_type = Ripper.sexp(code)&.dig(1)&.drop(1)&.dig(-1, 0)
+      ASSIGNMENT_NODE_TYPES.include?(node_type)
+    ensure
       $VERBOSE = verbose
-      result
     end
 
     ATTR_TTY = "\e[%sm"
@@ -919,12 +979,13 @@ class Binding
   #
   #
   # See IRB@IRB+Usage for more information.
-  def irb
+  def irb(show_code: true)
     IRB.setup(source_location[0], argv: [])
     workspace = IRB::WorkSpace.new(self)
-    STDOUT.print(workspace.code_around_binding)
+    STDOUT.print(workspace.code_around_binding) if show_code
     binding_irb = IRB::Irb.new(workspace)
     binding_irb.context.irb_path = File.expand_path(source_location[0])
     binding_irb.run(IRB.conf)
+    binding_irb.debug_break
   end
 end

data/man/irb.1

@@ -173,8 +173,19 @@ The default value is 16.
 .El
 .Pp
 .Sh ENVIRONMENT
-.Bl -tag -compact
+.Bl -tag -compact -width "XDG_CONFIG_HOME"
+.It Ev IRB_LANG
+The locale used for
+.Nm .
+.Pp
 .It Ev IRBRC
+The path to the personal initialization file.
+.Pp
+.It Ev XDG_CONFIG_HOME
+.Nm
+respects XDG_CONFIG_HOME. If this is set, load
+.Pa $XDG_CONFIG_HOME/irb/irbrc
+as a personal initialization file.
 .Pp
 .El
 .Pp
@@ -186,7 +197,17 @@ depends on same variables as
 .Sh FILES
 .Bl -tag -compact
 .It Pa ~/.irbrc
-Personal irb initialization.
+Personal irb initialization. If
+.Ev IRBRC
+is set, read
+.Pa $IRBRC
+instead. If
+.Ev IRBRC
+is not set and
+.Ev XDG_CONFIG_HOME
+is set,
+.Pa $XDG_CONFIG_HOME/irb/irbrc
+is loaded.
 .Pp
 .El
 .Pp

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: irb
 version: !ruby/object:Gem::Version
-  version: 1.4.2
+  version: 1.5.0
 platform: ruby
 authors:
 - aycabta
 - Keiju ISHITSUKA
-autorequire:
+autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-10-05 00:00:00.000000000 Z
+date: 2022-11-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: reline
@@ -47,6 +47,8 @@ files:
 - irb.gemspec
 - lib/irb.rb
 - lib/irb/cmd/chws.rb
+- lib/irb/cmd/debug.rb
+- lib/irb/cmd/edit.rb
 - lib/irb/cmd/fork.rb
 - lib/irb/cmd/help.rb
 - lib/irb/cmd/info.rb
@@ -99,7 +101,7 @@ licenses:
 - Ruby
 - BSD-2-Clause
 metadata: {}
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -107,15 +109,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '2.6'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.0.dev
-signing_key:
+rubygems_version: 3.3.7
+signing_key: 
 specification_version: 4
 summary: Interactive Ruby command-line tool for REPL (Read Eval Print Loop).
 test_files: []