module IRB - Documentation for Ruby 3.2

# module IRB

`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.

## Usage¶ ↑

Use of irb is easy if you know Ruby.

When executing irb, prompts are displayed as follows. Then, enter the Ruby expression. An input is executed when it is syntactically complete.

    $ irb
    irb(main):001:0> 1+2
    #=> 3
    irb(main):002:0> class Foo
    irb(main):003:1>  def foo
    irb(main):004:2>    print 1
    irb(main):005:2>  end
    irb(main):006:1> end
    #=> nil

The singleline editor module or multiline editor module can be used with irb. Use of multiline editor is default if it’s installed.

## Command line options¶ ↑

    Usage:  irb.rb [options] [programfile] [arguments]
      -f                Don't initialize from configuration file.
      -d                Set $DEBUG and $VERBOSE to true (same as 'ruby -d').
      -r load-module    Require load-module (same as 'ruby -r').
      -I path           Specify $LOAD_PATH directory (same as 'ruby -I').
      -U                Set external and internal encodings to UTF-8.
      -E ex[:in]        Set default external (ex) and internal (in) encodings
                        (same as 'ruby -E').
      -w                Suppress warnings (same as 'ruby -w').
      -W[level=2]       Set warning level: 0=silence, 1=medium, 2=verbose
                        (same as 'ruby -W').
      --context-mode n  Set n[0-4] to method to create Binding Object,
                        when new workspace was created.
      --extra-doc-dir   Add an extra doc dir for the doc dialog.
      --echo            Show result (default).
      --noecho          Don't show result.
      --echo-on-assignment
                        Show result on assignment.
      --noecho-on-assignment
                        Don't show result on assignment.
      --truncate-echo-on-assignment
                        Show truncated result on assignment (default).
      --inspect         Use 'inspect' for output.
      --noinspect       Don't use 'inspect' for output.
      --multiline       Use multiline editor module.
      --nomultiline     Don't use multiline editor module (default).
      --singleline      Use single line editor module.
      --nosingleline    Don't use single line editor module (default).
      --colorize        Use color-highlighting (default).
      --nocolorize      Don't use color-highlighting.
      --autocomplete    Use auto-completion (default).
      --noautocomplete  Don't use auto-completion.
      --prompt prompt-mode, --prompt-mode prompt-mode
                        Set prompt mode. Pre-defined prompt modes are:
                        'default', 'classic', 'simple', 'inf-ruby', 'xmp', 'null'.
      --inf-ruby-mode   Use prompt appropriate for inf-ruby-mode on emacs.
                        Suppresses --multiline and --singleline.
      --sample-book-mode, --simple-prompt
                        Set prompt mode to 'simple'.
      --noprompt        Don't output prompt.
      --script          Script mode (default, treat first argument as script)
      --noscript        No script mode (leave arguments in argv)
      --single-irb      Share self with sub-irb.
      --tracer          Show stack trace for each command.
      --back-trace-limit n[=16]
                        Display backtrace top n and bottom n.
      --verbose         Show details.
      --noverbose       Don't show details.
      -v, --version     Print the version of irb.
      -h, --help        Print help.
      --                Separate options of irb from the list of command-line args.

## 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.

- break, delete, next, step, continue, finish, backtrace, info, catch

  - Start the debugger of debug.gem and run the command on it.

## Configuration¶ ↑

`IRB` reads a personal initialization file when it’s invoked. `IRB` searches a file in the following order and loads the first one found.

- `$IRBRC` (if `$IRBRC` is set)

- `$XDG_CONFIG_HOME/irb/irbrc` (if `$XDG_CONFIG_HOME` is set)

- `~/.irbrc`

- `.config/irb/irbrc`

- `.irbrc`

- `irb.rc`

- `_irbrc`

- `$irbrc`

The following are alternatives to the command line options. To use them type as follows in an `irb` session:

    IRB.conf[:IRB_NAME]="irb"
    IRB.conf[:INSPECT_MODE]=nil
    IRB.conf[:IRB_RC] = nil
    IRB.conf[:BACK_TRACE_LIMIT]=16
    IRB.conf[:USE_LOADER] = false
    IRB.conf[:USE_MULTILINE] = nil
    IRB.conf[:USE_SINGLELINE] = nil
    IRB.conf[:USE_COLORIZE] = true
    IRB.conf[:USE_TRACER] = false
    IRB.conf[:USE_AUTOCOMPLETE] = true
    IRB.conf[:IGNORE_SIGINT] = true
    IRB.conf[:IGNORE_EOF] = false
    IRB.conf[:PROMPT_MODE] = :DEFAULT
    IRB.conf[:PROMPT] = {...}

### Auto indentation¶ ↑

To disable auto-indent mode in irb, add the following to your `.irbrc`:

    IRB.conf[:AUTO_INDENT] = false

### Autocompletion¶ ↑

To disable autocompletion for irb, add the following to your `.irbrc`:

    IRB.conf[:USE_AUTOCOMPLETE] = false

### `History`¶ ↑

By default, irb will store the last 1000 commands you used in `IRB.conf[:HISTORY_FILE]` (`~/.irb_history` by default).

If you want to disable history, add the following to your `.irbrc`:

    IRB.conf[:SAVE_HISTORY] = nil

See `IRB::Context#save_history=` for more information.

The history of results of commands evaluated is not stored by default, but can be turned on to be stored with this `.irbrc` setting:

    IRB.conf[:EVAL_HISTORY] = <number>

See `IRB::Context#eval_history=` and `History` class. The history of command results is not permanently saved in any file.

## Customizing the `IRB` Prompt¶ ↑

In order to customize the prompt, you can change the following Hash:

    IRB.conf[:PROMPT]

This example can be used in your `.irbrc`

    IRB.conf[:PROMPT][:MY_PROMPT] = { # name of prompt mode
      :AUTO_INDENT => false,          # disables auto-indent mode
      :PROMPT_I =>  ">> ",            # simple prompt
      :PROMPT_S => nil,               # prompt for continuated strings
      :PROMPT_C => nil,               # prompt for continuated statement
      :RETURN => "    ==>%s\n"        # format to return value
    }

    IRB.conf[:PROMPT_MODE] = :MY_PROMPT

Or, invoke irb with the above prompt mode by:

    irb --prompt my-prompt

Constants `PROMPT_I`, `PROMPT_S` and `PROMPT_C` specify the format. In the prompt specification, some special strings are available:

    %N    # command name which is running
    %m    # to_s of main object (self)
    %M    # inspect of main object (self)
    %l    # type of string(", ', /, ]), `]' is inner %w[...]
    %NNi  # indent level. NN is digits and means as same as printf("%NNd").
          # It can be omitted
    %NNn  # line number.
    %%    # %

For instance, the default prompt mode is defined as follows:

    IRB.conf[:PROMPT_MODE][: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" # used to printf
    }

irb comes with a number of available modes:

    # :NULL:
    #   :PROMPT_I:
    #   :PROMPT_N:
    #   :PROMPT_S:
    #   :PROMPT_C:
    #   :RETURN: |
    #     %s
    # :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
    # :CLASSIC:
    #   :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
    # :SIMPLE:
    #   :PROMPT_I: ! '>> '
    #   :PROMPT_N: ! '>> '
    #   :PROMPT_S:
    #   :PROMPT_C: ! '?> '
    #   :RETURN: |
    #     => %s
    # :INF_RUBY:
    #   :PROMPT_I: ! '%N(%m):%03n:%i> '
    #   :PROMPT_N:
    #   :PROMPT_S:
    #   :PROMPT_C:
    #   :RETURN: |
    #     %s
    #   :AUTO_INDENT: true
    # :XMP:
    #   :PROMPT_I:
    #   :PROMPT_N:
    #   :PROMPT_S:
    #   :PROMPT_C:
    #   :RETURN: |2
    #         ==>%s

## Restrictions¶ ↑

Because irb evaluates input immediately after it is syntactically complete, the results may be slightly different than directly using Ruby.

## `IRB` Sessions¶ ↑

`IRB` has a special feature, that allows you to manage many sessions at once.

You can create new sessions with Irb.irb, and get a list of current sessions with the `jobs` command in the prompt.

### Commands¶ ↑

`JobManager` provides commands to handle the current sessions:

    jobs    # List of current sessions
    fg      # Switches to the session of the given number
    kill    # Kills the session with the given number

The `exit` command, or `::irb_exit`, will quit the current session and call any exit hooks with `IRB.irb_at_exit`.

A few commands for loading files within the session are also available:

`source`

  Loads a given file in the current session and displays the source lines, see `IrbLoader#source_file`

`irb_load`

  Loads the given file similarly to `Kernel#load`, see `IrbLoader#irb_load`

`irb_require`

  Loads the given file similarly to `Kernel#require`

### Configuration¶ ↑

The command line options, or `IRB.conf`, specify the default behavior of Irb.irb.

On the other hand, each conf in Command line options at `IRB` is used to individually configure `IRB.irb`.

If a proc is set for `IRB.conf[:IRB_RC]`, its will be invoked after execution of that proc with the context of the current session as its argument. Each session can be configured using this mechanism.

### Session variables¶ ↑

There are a few variables in every `Irb` session that can come in handy:

`_`

  The value command executed, as a local variable

`__`

  The history of evaluated commands. Available only if `IRB.conf[:EVAL_HISTORY]` is not `nil` (which is the default). See also `IRB::Context#eval_history=` and `IRB::History`.

`__[line_no]`

  Returns the evaluation value at the given line number, `line_no`. If `line_no` is a negative, the return value `line_no` many lines before the most recent return value.

### Example using `IRB` Sessions¶ ↑

    # invoke a new session
    irb(main):001:0> irb
    # list open sessions
    irb.1(main):001:0> jobs
      #0->irb on main (#<Thread:0x400fb7e4> : stop)
      #1->irb#1 on main (#<Thread:0x40125d64> : running)

    # change the active session
    irb.1(main):002:0> fg 0
    # define class Foo in top-level session
    irb(main):002:0> class Foo;end
    # invoke a new session with the context of Foo
    irb(main):003:0> irb Foo
    # define Foo#foo
    irb.2(Foo):001:0> def foo
    irb.2(Foo):002:1>   print 1
    irb.2(Foo):003:1> end

    # change the active session
    irb.2(Foo):004:0> fg 0
    # list open sessions
    irb(main):004:0> jobs
      #0->irb on main (#<Thread:0x400fb7e4> : running)
      #1->irb#1 on main (#<Thread:0x40125d64> : stop)
      #2->irb#2 on Foo (#<Thread:0x4011d54c> : stop)
    # check if Foo#foo is available
    irb(main):005:0> Foo.instance_methods #=> [:foo, ...]

    # change the active session
    irb(main):006:0> fg 2
    # define Foo#bar in the context of Foo
    irb.2(Foo):005:0> def bar
    irb.2(Foo):006:1>  print "bar"
    irb.2(Foo):007:1> end
    irb.2(Foo):010:0>  Foo.instance_methods #=> [:bar, :foo, ...]

    # change the active session
    irb.2(Foo):011:0> fg 0
    irb(main):007:0> f = Foo.new  #=> #<Foo:0x4010af3c>
    # invoke a new session with the context of f (instance of Foo)
    irb(main):008:0> irb f
    # list open sessions
    irb.3(<Foo:0x4010af3c>):001:0> jobs
      #0->irb on main (#<Thread:0x400fb7e4> : stop)
      #1->irb#1 on main (#<Thread:0x40125d64> : stop)
      #2->irb#2 on Foo (#<Thread:0x4011d54c> : stop)
      #3->irb#3 on #<Foo:0x4010af3c> (#<Thread:0x4010a1e0> : running)
    # evaluate f.foo
    irb.3(<Foo:0x4010af3c>):002:0> foo #=> 1 => nil
    # evaluate f.bar
    irb.3(<Foo:0x4010af3c>):003:0> bar #=> bar => nil
    # kill jobs 1, 2, and 3
    irb.3(<Foo:0x4010af3c>):004:0> kill 1, 2, 3
    # list open sessions, should only include main session
    irb(main):009:0> jobs
      #0->irb on main (#<Thread:0x400fb7e4> : running)
    # quit irb
    irb(main):010:0> exit

    nop.rb -
        $Release Version: 0.9.6$
        $Revision$
        by Keiju ISHITSUKA(keiju@ruby-lang.org)

–

    irb/multi-irb.rb - multiple irb module
        $Release Version: 0.9.6$
        $Revision$
        by Keiju ISHITSUKA(keiju@ruby-lang.org)

–

    save-history.rb -
        $Release Version: 0.9.6$
        $Revision$
        by Keiju ISHITSUKA(keiju@ruby-lang.org)

–

    frame.rb -
        $Release Version: 0.9$
        $Revision$
        by Keiju ISHITSUKA(Nihon Rational Software Co.,Ltd)

–

    irb/lc/error.rb -
        $Release Version: 0.9.6$
        $Revision$
        by Keiju ISHITSUKA(keiju@ruby-lang.org)

–

    irb/lc/ja/error.rb -
        $Release Version: 0.9.6$
        $Revision$
        by Keiju ISHITSUKA(keiju@ruby-lang.org)

–

    output-method.rb - output methods used by irb
        $Release Version: 0.9.6$
        $Revision$
        by Keiju ISHITSUKA(keiju@ruby-lang.org)

–

DO NOT WRITE ANY MAGIC COMMENT HERE.

### Constants

TOPLEVEL_BINDING
TracerLoadError

### Public Class Methods

CurrentContext() click to toggle source

The current `IRB::Context` of the session, see `IRB.conf`

    irb
    irb(main):001:0> IRB.CurrentContext.irb_name = "foo"
    foo(main):002:0> IRB.conf[:MAIN_CONTEXT].irb_name #=> "foo"

    # File lib/irb.rb, line 405
    def IRB.CurrentContext
      IRB.conf[:MAIN_CONTEXT]
    end

JobManager() click to toggle source

The current `JobManager` in the session

    # File lib/irb/ext/multi-irb.rb, line 175
    def IRB.JobManager
      @JobManager
    end

conf() click to toggle source

Displays current configuration.

Modifying the configuration is achieved by sending a message to `IRB.conf`.

See Configuration at `IRB` for more information.

    # File lib/irb.rb, line 388
    def IRB.conf
      @CONF
    end

default_src_encoding() click to toggle source

    # File lib/irb/src_encoding.rb, line 4
    def self.default_src_encoding
      return __ENCODING__
    end

initialize_tracer() click to toggle source

initialize tracing function

    # File lib/irb/ext/tracer.rb, line 30
    def IRB.initialize_tracer
      Tracer.verbose = false
      Tracer.add_filter {
        |event, file, line, id, binding, *rests|
        /^#{Regexp.quote(@CONF[:IRB_LIB_PATH])}/ !~ file and
          File::basename(file) != "irb.rb"
      }
    end

irb(file = nil, *main) click to toggle source

Creates a new `IRB` session, see `Irb.new`.

The optional `file` argument is given to `Context.new`, along with the workspace created with the remaining arguments, see `WorkSpace.new`

    # File lib/irb/ext/multi-irb.rb, line 188
    def IRB.irb(file = nil, *main)
      workspace = WorkSpace.new(*main)
      parent_thread = Thread.current
      Thread.start do
        begin
          irb = Irb.new(workspace, file)
        rescue
          print "Subirb can't start with context(self): ", workspace.main.inspect, "\n"
          print "return to main irb\n"
          Thread.pass
          Thread.main.wakeup
          Thread.exit
        end
        @CONF[:IRB_RC].call(irb.context) if @CONF[:IRB_RC]
        @JobManager.insert(irb)
        @JobManager.current_job = irb
        begin
          system_exit = false
          catch(:IRB_EXIT) do
            irb.eval_input
          end
        rescue SystemExit
          system_exit = true
          raise
          #fail
        ensure
          unless system_exit
            @JobManager.delete(irb)
            if @JobManager.current_job == irb
              if parent_thread.alive?
                @JobManager.current_job = @JobManager.irb(parent_thread)
                parent_thread.run
              else
                @JobManager.current_job = @JobManager.main_irb
                @JobManager.main_thread.run
              end
            end
          end
        end
      end
      Thread.stop
      @JobManager.current_job = @JobManager.irb(Thread.current)
    end

irb_abort(irb, exception = Abort) click to toggle source

Aborts then interrupts irb.

Will raise an `Abort` exception, or the given `exception`.

    # File lib/irb.rb, line 437
    def IRB.irb_abort(irb, exception = Abort)
      irb.context.thread.raise exception, "abort then interrupt!"
    end

irb_at_exit() click to toggle source

Calls each event hook of `IRB.conf[:AT_EXIT]` when the current session quits.

    # File lib/irb.rb, line 425
    def IRB.irb_at_exit
      @CONF[:AT_EXIT].each{|hook| hook.call}
    end

irb_exit(irb, ret) click to toggle source

Quits irb

    # File lib/irb.rb, line 430
    def IRB.irb_exit(irb, ret)
      throw :IRB_EXIT, ret
    end

print_usage() click to toggle source

Outputs the irb help message, see Command line options at `IRB`.

    # File lib/irb/help.rb, line 17
    def IRB.print_usage
      lc = IRB.conf[:LC_MESSAGES]
      path = lc.find("irb/help-message")
      space_line = false
      IRB::MagicFile.open(path){|f|
        f.each_line do |l|
          if /^\s*$/ =~ l
            lc.puts l unless space_line
            space_line = true
            next
          end
          space_line = false

          l.sub!(/#.*$/, "")
          next if /^\s*$/ =~ l
          lc.puts l
        end
      }
    end

start(ap_path = nil) click to toggle source

Initializes `IRB` and creates a new Irb.irb object at the `TOPLEVEL_BINDING`

    # File lib/irb.rb, line 410
    def IRB.start(ap_path = nil)
      STDOUT.sync = true
      $0 = File::basename(ap_path, ".rb") if ap_path

      IRB.setup(ap_path)

      if @CONF[:SCRIPT]
        irb = Irb.new(nil, @CONF[:SCRIPT])
      else
        irb = Irb.new
      end
      irb.run(@CONF)
    end

version() click to toggle source

Returns the current version of `IRB`, including release version and last updated date.

    # File lib/irb.rb, line 394
    def IRB.version
      if v = @CONF[:VERSION] then return v end

      @CONF[:VERSION] = format("irb %s (%s)", @RELEASE_VERSION, @LAST_UPDATE_DATE)
    end

### Private Class Methods

easter_egg(type = nil) click to toggle source

    # File lib/irb/easter-egg.rb, line 101
            def easter_egg(type = nil)
      type ||= [:logo, :dancing].sample
      case type
      when :logo
        File.open(File.join(__dir__, 'ruby_logo.aa')) do |f|
          require "rdoc"
          RDoc::RI::Driver.new.page do |io|
            IO.copy_stream(f, io)
          end
        end
      when :dancing
        begin
          canvas = Canvas.new(Reline.get_screen_size)
          Reline::IOGate.set_winch_handler do
            canvas = Canvas.new(Reline.get_screen_size)
          end
          ruby_model = RubyModel.new
          print "\e[?1049h"
          0.step do |i| # TODO (0..).each needs Ruby 2.6 or later
            buff = canvas.draw do
              ruby_model.render_frame(i) do |p1, p2|
                canvas.line(p1, p2)
              end
            end
            buff[0, 20] = "\e[0mPress Ctrl+C to stop\e[31m\e[1m"
            print "\e[H" + buff
            sleep 0.05
          end
        rescue Interrupt
        ensure
          print "\e[0m\e[?1049l"
        end
      end
    end