class IRB::Context - Documentation for Ruby 3.3

# class IRB::Context

A class that wraps the current state of the irb session, including the configuration of IRB.conf.

### Constants

KEYWORD_ALIASES

  because all input will eventually be evaluated as Ruby code, command names that conflict with Ruby keywords need special workaround we can remove them once we implemented a better command system for `IRB`

### Attributes

ap_name[RW]

A copy of the default `IRB.conf[:AP_NAME]`

auto_indent_mode[RW]

Can be either the default `IRB.conf[:AUTO_INDENT]`, or the mode set by `prompt_mode=`

To disable auto-indentation in irb:

    IRB.conf[:AUTO_INDENT] = false

or

    irb_context.auto_indent_mode = false

or

    IRB.CurrentContext.auto_indent_mode = false

See Configuration at `IRB` for more information.

back_trace_limit[RW]

The limit of backtrace lines displayed as top `n` and tail `n`.

The default value is 16.

Can also be set using the `--back-trace-limit` command line option.

command_aliases[RW]

User-defined `IRB` command aliases

echo[RW]

Whether to echo the return value to output or not.

Uses `IRB.conf[:ECHO]` if available, or defaults to `true`.

    puts "hello"
    # hello
    #=> nil
    IRB.CurrentContext.echo = false
    puts "omg"
    # omg

echo?[RW]

Whether to echo the return value to output or not.

Uses `IRB.conf[:ECHO]` if available, or defaults to `true`.

    puts "hello"
    # hello
    #=> nil
    IRB.CurrentContext.echo = false
    puts "omg"
    # omg

echo_on_assignment[RW]

Whether to echo for assignment expressions.

If set to `false`, the value of assignment will not be shown.

If set to `true`, the value of assignment will be shown.

If set to `:truncate`, the value of assignment will be shown and truncated.

It defaults to `:truncate`.

    a = "omg"
    #=> omg

    a = "omg" * 10
    #=> omgomgomgomgomgomgomg...

    IRB.CurrentContext.echo_on_assignment = false
    a = "omg"

    IRB.CurrentContext.echo_on_assignment = true
    a = "omg" * 10
    #=> omgomgomgomgomgomgomgomgomgomg

To set the behaviour of showing on assignment in irb:

    IRB.conf[:ECHO_ON_ASSIGNMENT] = :truncate or true or false

or

    irb_context.echo_on_assignment = :truncate or true or false

or

    IRB.CurrentContext.echo_on_assignment = :truncate or true or false

echo_on_assignment?[RW]

Whether to echo for assignment expressions.

If set to `false`, the value of assignment will not be shown.

If set to `true`, the value of assignment will be shown.

If set to `:truncate`, the value of assignment will be shown and truncated.

It defaults to `:truncate`.

    a = "omg"
    #=> omg

    a = "omg" * 10
    #=> omgomgomgomgomgomgomg...

    IRB.CurrentContext.echo_on_assignment = false
    a = "omg"

    IRB.CurrentContext.echo_on_assignment = true
    a = "omg" * 10
    #=> omgomgomgomgomgomgomgomgomgomg

To set the behaviour of showing on assignment in irb:

    IRB.conf[:ECHO_ON_ASSIGNMENT] = :truncate or true or false

or

    irb_context.echo_on_assignment = :truncate or true or false

or

    IRB.CurrentContext.echo_on_assignment = :truncate or true or false

eval_history[R]

The command result history limit. This method is not available until `eval_history=` was called with non-nil value (directly or via setting `IRB.conf[:EVAL_HISTORY]` in `.irbrc`).

extra_doc_dirs[RW]

Specify the installation locations of the ri file to be displayed in the document dialog.

ignore_eof[RW]

Whether `^D` (`control-d`) will be ignored or not.

If set to `false`, `^D` will quit irb.

ignore_eof?[RW]

Whether `^D` (`control-d`) will be ignored or not.

If set to `false`, `^D` will quit irb.

ignore_sigint[RW]

Whether `^C` (`control-c`) will be ignored or not.

If set to `false`, `^C` will quit irb.

If set to `true`,

- during input: cancel input then return to top level.

- during execute: abandon current execution.

ignore_sigint?[RW]

Whether `^C` (`control-c`) will be ignored or not.

If set to `false`, `^C` will quit irb.

If set to `true`,

- during input: cancel input then return to top level.

- during execute: abandon current execution.

inspect_mode[R]

A copy of the default `IRB.conf[:INSPECT_MODE]`

io[RW]

The current input method.

Can be either `StdioInputMethod`, `ReadlineInputMethod`, `RelineInputMethod`, `FileInputMethod` or other specified when the context is created. See `::new` for more # information on `input_method`.

irb[RW]

Current irb session.

irb_name[RW]

Can be either name from `IRB.conf[:IRB_NAME]`, or the number of the current job set by JobManager, such as `irb#2`

irb_path[R]

Can be one of the following:

- the `irb_name` surrounded by parenthesis

- the `input_method` passed to `Context.new`

- the file path of the current `IRB` context in a binding.irb session

last_value[R]

The return value of the last statement evaluated.

load_modules[RW]

A copy of the default `IRB.conf[:LOAD_MODULES]`

newline_before_multiline_output[RW]

Whether a newline is put before multiline output.

Uses `IRB.conf[:NEWLINE_BEFORE_MULTILINE_OUTPUT]` if available, or defaults to `true`.

    "abc\ndef"
    #=>
    abc
    def
    IRB.CurrentContext.newline_before_multiline_output = false
    "abc\ndef"
    #=> abc
    def

newline_before_multiline_output?[RW]

Whether a newline is put before multiline output.

Uses `IRB.conf[:NEWLINE_BEFORE_MULTILINE_OUTPUT]` if available, or defaults to `true`.

    "abc\ndef"
    #=>
    abc
    def
    IRB.CurrentContext.newline_before_multiline_output = false
    "abc\ndef"
    #=> abc
    def

prompt_c[RW]

`IRB` prompt for continuated statement. (e.g. immediately after an `if`)

See Custom Prompts for more information.

prompt_i[RW]

Standard `IRB` prompt.

See Custom Prompts for more information.

prompt_mode[R]

A copy of the default `IRB.conf[:PROMPT_MODE]`

prompt_s[RW]

`IRB` prompt for continuated strings.

See Custom Prompts for more information.

rc[RW]

A copy of the default `IRB.conf[:RC]`

rc?[RW]

A copy of the default `IRB.conf[:RC]`

return_format[RW]

The format of the return statement, set by `prompt_mode=` using the `:RETURN` of the `mode` passed to set the current `prompt_mode`.

thread[R]

The current thread in this context.

use_autocomplete[R]

Whether colorization is enabled or not.

A copy of the default `IRB.conf[:USE_AUTOCOMPLETE]`

use_autocomplete?[R]

Whether colorization is enabled or not.

A copy of the default `IRB.conf[:USE_AUTOCOMPLETE]`

use_multiline[R]

Whether multiline editor mode is enabled or not.

A copy of the default `IRB.conf[:USE_MULTILINE]`

use_multiline?[R]

Whether multiline editor mode is enabled or not.

A copy of the default `IRB.conf[:USE_MULTILINE]`

use_readline[R]

Whether singleline editor mode is enabled or not.

A copy of the default `IRB.conf[:USE_SINGLELINE]`

use_readline?[R]

Whether singleline editor mode is enabled or not.

A copy of the default `IRB.conf[:USE_SINGLELINE]`

use_reline[R]

Whether multiline editor mode is enabled or not.

A copy of the default `IRB.conf[:USE_MULTILINE]`

use_reline?[R]

Whether multiline editor mode is enabled or not.

A copy of the default `IRB.conf[:USE_MULTILINE]`

use_singleline[R]

Whether singleline editor mode is enabled or not.

A copy of the default `IRB.conf[:USE_SINGLELINE]`

use_singleline?[R]

Whether singleline editor mode is enabled or not.

A copy of the default `IRB.conf[:USE_SINGLELINE]`

verbose[RW]

Whether verbose messages are displayed or not.

A copy of the default `IRB.conf[:VERBOSE]`

with_debugger[RW]
workspace_home[R]

The toplevel workspace, see `home_workspace`

### Public Class Methods

new(irb, workspace = nil, input_method = nil) click to toggle source

Creates a new `IRB` context.

The optional `input_method` argument:

`nil`

  uses stdin or `Reline` or `Readline`

`String`

  uses a `File`

`other`

  uses this as `InputMethod`

    # File lib/irb/context.rb, line 23
        def initialize(irb, workspace = nil, input_method = nil)
          @irb = irb
          @workspace_stack = []
          if workspace
            @workspace_stack << workspace
          else
            @workspace_stack << WorkSpace.new
          end
          @thread = Thread.current

          # copy of default configuration
          @ap_name = IRB.conf[:AP_NAME]
          @rc = IRB.conf[:RC]
          @load_modules = IRB.conf[:LOAD_MODULES]

          if IRB.conf.has_key?(:USE_SINGLELINE)
            @use_singleline = IRB.conf[:USE_SINGLELINE]
          elsif IRB.conf.has_key?(:USE_READLINE) # backward compatibility
            @use_singleline = IRB.conf[:USE_READLINE]
          else
            @use_singleline = nil
          end
          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_MULTILINE instead.
            MSG
            @use_multiline = IRB.conf[:USE_REIDLINE]
          else
            @use_multiline = nil
          end
          @use_autocomplete = IRB.conf[:USE_AUTOCOMPLETE]
          @verbose = IRB.conf[:VERBOSE]
          @io = nil

          self.inspect_mode = IRB.conf[:INSPECT_MODE]
          self.use_tracer = IRB.conf[:USE_TRACER]
          self.use_loader = IRB.conf[:USE_LOADER] if IRB.conf[:USE_LOADER]
          self.eval_history = IRB.conf[:EVAL_HISTORY] if IRB.conf[:EVAL_HISTORY]

          @ignore_sigint = IRB.conf[:IGNORE_SIGINT]
          @ignore_eof = IRB.conf[:IGNORE_EOF]

          @back_trace_limit = IRB.conf[:BACK_TRACE_LIMIT]

          self.prompt_mode = IRB.conf[:PROMPT_MODE]

          if IRB.conf[:SINGLE_IRB] or !defined?(IRB::JobManager)
            @irb_name = IRB.conf[:IRB_NAME]
          else
            @irb_name = IRB.conf[:IRB_NAME]+"#"+IRB.JobManager.n_jobs.to_s
          end
          self.irb_path = "(" + @irb_name + ")"

          case input_method
          when nil
            @io = nil
            case use_multiline?
            when nil
              if term_interactive? && IRB.conf[:PROMPT_MODE] != :INF_RUBY && !use_singleline?
                # Both of multiline mode and singleline mode aren't specified.
                @io = RelineInputMethod.new(build_completor)
              else
                @io = nil
              end
            when false
              @io = nil
            when true
              @io = RelineInputMethod.new(build_completor)
            end
            unless @io
              case use_singleline?
              when nil
                if (defined?(ReadlineInputMethod) && term_interactive? &&
                    IRB.conf[:PROMPT_MODE] != :INF_RUBY)
                  @io = ReadlineInputMethod.new
                else
                  @io = nil
                end
              when false
                @io = nil
              when true
                if defined?(ReadlineInputMethod)
                  @io = ReadlineInputMethod.new
                else
                  @io = nil
                end
              else
                @io = nil
              end
            end
            @io = StdioInputMethod.new unless @io

          when '-'
            @io = FileInputMethod.new($stdin)
            @irb_name = '-'
            self.irb_path = '-'
          when String
            @io = FileInputMethod.new(input_method)
            @irb_name = File.basename(input_method)
            self.irb_path = input_method
          else
            @io = input_method
          end
          @extra_doc_dirs = IRB.conf[:EXTRA_DOC_DIRS]

          @echo = IRB.conf[:ECHO]
          if @echo.nil?
            @echo = true
          end

          @echo_on_assignment = IRB.conf[:ECHO_ON_ASSIGNMENT]
          if @echo_on_assignment.nil?
            @echo_on_assignment = :truncate
          end

          @newline_before_multiline_output = IRB.conf[:NEWLINE_BEFORE_MULTILINE_OUTPUT]
          if @newline_before_multiline_output.nil?
            @newline_before_multiline_output = true
          end

          @user_aliases = IRB.conf[:COMMAND_ALIASES].dup
          @command_aliases = @user_aliases.merge(KEYWORD_ALIASES)
        end

### Public Instance Methods

_set_last_value(value)

See `set_last_value`

Alias for: set_last_value
change_workspace(*_main) click to toggle source

Changes the current workspace to given object or binding.

If the optional argument is omitted, the workspace will be `home_workspace` which is inherited from `TOPLEVEL_BINDING` or the main object, `IRB.conf[:MAIN_CONTEXT]` when irb was initialized.

See `IRB::WorkSpace.new` for more information.

    # File lib/irb/ext/change-ws.rb, line 26
    def change_workspace(*_main)
      if _main.empty?
        replace_workspace(home_workspace)
        return main
      end

      workspace = WorkSpace.new(_main[0])
      replace_workspace(workspace)
      workspace.load_helper_methods_to_main
    end

eval_history=(val) click to toggle source

    # File lib/irb/context.rb, line 175
    def eval_history=(val)
      self.class.remove_method(__method__)
      require_relative "ext/eval_history"
      __send__(__method__, val)
    end

file_input?() click to toggle source

Whether `io` uses a `File` for the `input_method` passed when creating the current context, see `::new`

    # File lib/irb/context.rb, line 535
    def file_input?
      @io.class == FileInputMethod
    end

from_binding?() click to toggle source

    # File lib/irb/context.rb, line 610
    def from_binding?
      @irb.from_binding
    end

history_file() click to toggle source

A copy of the default `IRB.conf[:HISTORY_FILE]`

    # File lib/irb/context.rb, line 229
    def history_file
      IRB.conf[:HISTORY_FILE]
    end

history_file=(hist) click to toggle source

`Set` `IRB.conf[:HISTORY_FILE]` to the given `hist`.

    # File lib/irb/context.rb, line 234
    def history_file=(hist)
      IRB.conf[:HISTORY_FILE] = hist
    end

home_workspace() click to toggle source

Inherited from `TOPLEVEL_BINDING`.

    # File lib/irb/ext/change-ws.rb, line 11
    def home_workspace
      if defined? @home_workspace
        @home_workspace
      else
        @home_workspace = workspace
      end
    end

inspect?() click to toggle source

Whether `inspect_mode` is set or not, see `inspect_mode=` for more detail.

    # File lib/irb/context.rb, line 529
    def inspect?
      @inspect_mode.nil? or @inspect_mode
    end

inspect_mode=(opt) click to toggle source

Specifies the inspect mode with `opt`:

`true`

  display `inspect`

`false`

  display `to_s`

`nil`

  inspect mode in non-math mode, non-inspect mode in math mode

See `IRB::Inspector` for more information.

Can also be set using the `--inspect` and `--noinspect` command line options.

    # File lib/irb/context.rb, line 550
    def inspect_mode=(opt)

      if i = Inspector::INSPECTORS[opt]
        @inspect_mode = opt
        @inspect_method = i
        i.init
      else
        case opt
        when nil
          if Inspector.keys_with_inspector(Inspector::INSPECTORS[true]).include?(@inspect_mode)
            self.inspect_mode = false
          elsif Inspector.keys_with_inspector(Inspector::INSPECTORS[false]).include?(@inspect_mode)
            self.inspect_mode = true
          else
            puts "Can't switch inspect mode."
            return
          end
        when /^\s*\{.*\}\s*$/
          begin
            inspector = eval "proc#{opt}"
          rescue Exception
            puts "Can't switch inspect mode(#{opt})."
            return
          end
          self.inspect_mode = inspector
        when Proc
          self.inspect_mode = IRB::Inspector(opt)
        when Inspector
          prefix = "usr%d"
          i = 1
          while Inspector::INSPECTORS[format(prefix, i)]; i += 1; end
          @inspect_mode = format(prefix, i)
          @inspect_method = opt
          Inspector.def_inspector(format(prefix, i), @inspect_method)
        else
          puts "Can't switch inspect mode(#{opt})."
          return
        end
      end
      print "Switch to#{unless @inspect_mode; ' non';end} inspect mode.\n" if verbose?
      @inspect_mode
    end

irb_path=(path) click to toggle source

Sets @irb_path to the given `path` as well as @eval_path @eval_path is used for evaluating code in the context of `IRB` session It’s the same as `irb_path`, but with the `IRB` name postfix This makes sure users can distinguish the methods defined in the `IRB` session from the methods defined in the current file’s context, especially with binding.irb

    # File lib/irb/context.rb, line 288
    def irb_path=(path)
      @irb_path = path

      if File.exist?(path)
        @eval_path = "#{path}(#{IRB.conf[:IRB_NAME]})"
      else
        @eval_path = path
      end
    end

main() click to toggle source

The top-level workspace, see `WorkSpace#main`

    # File lib/irb/context.rb, line 250
    def main
      workspace.main
    end

pop_workspace() click to toggle source

Removes the last element from the current workspaces stack and returns it, or `nil` if the current workspace stack is empty.

Also, see `push_workspace`.

    # File lib/irb/ext/workspaces.rb, line 32
    def pop_workspace
      @workspace_stack.pop if @workspace_stack.size > 1
    end

prompt_mode=(mode) click to toggle source

Sets the `mode` of the prompt in this context.

See Custom Prompts for more information.

    # File lib/irb/context.rb, line 513
    def prompt_mode=(mode)
      @prompt_mode = mode
      pconf = IRB.conf[:PROMPT][mode]
      @prompt_i = pconf[:PROMPT_I]
      @prompt_s = pconf[:PROMPT_S]
      @prompt_c = pconf[:PROMPT_C]
      @return_format = pconf[:RETURN]
      @return_format = "%s\n" if @return_format == nil
      if ai = pconf.include?(:AUTO_INDENT)
        @auto_indent_mode = ai
      else
        @auto_indent_mode = IRB.conf[:AUTO_INDENT]
      end
    end

prompt_n() click to toggle source

TODO: Remove this when developing v2.0

    # File lib/irb/context.rb, line 329
    def prompt_n
      warn "IRB::Context#prompt_n is deprecated and will be removed in the next major release."
      ""
    end

prompt_n=(_) click to toggle source

TODO: Remove this when developing v2.0

    # File lib/irb/context.rb, line 335
    def prompt_n=(_)
      warn "IRB::Context#prompt_n= is deprecated and will be removed in the next major release."
      ""
    end

prompting?() click to toggle source

Whether `verbose?` is `true`, and `input_method` is either `StdioInputMethod` or `RelineInputMethod` or `ReadlineInputMethod`, see `io` for more information.

    # File lib/irb/context.rb, line 496
    def prompting?
      verbose? || @io.prompting?
    end

push_workspace(*_main) click to toggle source

Creates a new workspace with the given object or binding, and appends it onto the current workspaces stack.

See `IRB::Context#change_workspace` and `IRB::WorkSpace.new` for more information.

    # File lib/irb/ext/workspaces.rb, line 14
    def push_workspace(*_main)
      if _main.empty?
        if @workspace_stack.size > 1
          # swap the top two workspaces
          previous_workspace, current_workspace = @workspace_stack.pop(2)
          @workspace_stack.push current_workspace, previous_workspace
        end
      else
        new_workspace = WorkSpace.new(workspace.binding, _main[0])
        @workspace_stack.push new_workspace
        new_workspace.load_helper_methods_to_main
      end
    end

replace_workspace(workspace) click to toggle source

Replace the current workspace with the given `workspace`.

    # File lib/irb/context.rb, line 244
    def replace_workspace(workspace)
      @workspace_stack.pop
      @workspace_stack.push(workspace)
    end

save_history() click to toggle source

    # File lib/irb/context.rb, line 224
    def save_history
      IRB.conf[:SAVE_HISTORY]
    end

save_history=(val) click to toggle source

    # File lib/irb/context.rb, line 220
    def save_history=(val)
      IRB.conf[:SAVE_HISTORY] = val
    end

set_last_value(value) click to toggle source

Sets the return value from the last statement evaluated in this context to `last_value`.

    # File lib/irb/context.rb, line 505
    def set_last_value(value)
      @last_value = value
      workspace.local_variable_set :_, value
    end

Also aliased as: _set_last_value
use_loader() click to toggle source

Returns whether `irb`‘s own file reader method is used by `load`/`require` or not.

This mode is globally affected (irb-wide).

    # File lib/irb/ext/use-loader.rb, line 37
    def use_loader
      IRB.conf[:USE_LOADER]
    end

Also aliased as: use_loader?
use_loader=(val) click to toggle source

    # File lib/irb/context.rb, line 181
    def use_loader=(val)
      self.class.remove_method(__method__)
      require_relative "ext/use-loader"
      __send__(__method__, val)
    end

use_loader?()
Alias for: use_loader
use_tracer=(val) click to toggle source

    # File lib/irb/context.rb, line 170
    def use_tracer=(val)
      require_relative "ext/tracer" if val
      IRB.conf[:USE_TRACER] = val
    end

verbose?() click to toggle source

Returns whether messages are displayed or not.

    # File lib/irb/context.rb, line 477
    def verbose?
      if @verbose.nil?
        if @io.kind_of?(RelineInputMethod)
          false
        elsif defined?(ReadlineInputMethod) && @io.kind_of?(ReadlineInputMethod)
          false
        elsif !STDIN.tty? or @io.kind_of?(FileInputMethod)
          true
        else
          false
        end
      else
        @verbose
      end
    end

workspace() click to toggle source

Workspace in the current context.

    # File lib/irb/context.rb, line 239
    def workspace
      @workspace_stack.last
    end

### Private Instance Methods

build_completor() click to toggle source

    # File lib/irb/context.rb, line 187
            def build_completor
      completor_type = IRB.conf[:COMPLETOR]
      case completor_type
      when :regexp
        return RegexpCompletor.new
      when :type
        completor = build_type_completor
        return completor if completor
      else
        warn "Invalid value for IRB.conf[:COMPLETOR]: #{completor_type}"
      end
      # Fallback to RegexpCompletor
      RegexpCompletor.new
    end

build_type_completor() click to toggle source

    # File lib/irb/context.rb, line 202
            def build_type_completor
      if RUBY_ENGINE == 'truffleruby'
        # Avoid SyntaxError. truffleruby does not support endless method definition yet.
        warn 'TypeCompletor is not supported on TruffleRuby yet'
        return
      end

      begin
        require 'repl_type_completor'
      rescue LoadError => e
        warn "TypeCompletor requires `gem repl_type_completor`: #{e.message}"
        return
      end

      ReplTypeCompletor.preload_rbs
      TypeCompletor.new(self)
    end

term_interactive?() click to toggle source

    # File lib/irb/context.rb, line 154
            def term_interactive?
      return true if ENV['TEST_IRB_FORCE_INTERACTIVE']
      STDIN.tty? && ENV['TERM'] != 'dumb'
    end