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.

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.

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.

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