module IRB

IRB

Module IRB (“Interactive Ruby”) provides a shell-like interface that supports user interaction with the Ruby interpreter.

It operates as a read-eval-print loop (REPL) that:

Example:

$ irb
irb(main):001> File.basename(Dir.pwd)
=> "irb"
irb(main):002> Dir.entries('.').size
=> 25
irb(main):003* Dir.entries('.').select do |entry|
irb(main):004*   entry.start_with?('R')
irb(main):005> end
=> ["README.md", "Rakefile"]

The typed input may also include IRB-specific commands.

As seen above, you can start IRB by using the shell command irb.

You can stop an IRB session by typing command exit:

irb(main):006> exit
$

At that point, IRB calls any hooks found in array IRB.conf[:AT_EXIT], then exits.

Startup

At startup, IRB:

  1. Interprets (as Ruby code) the content of the configuration file (if given).

  2. Constructs the initial session context from hash IRB.conf and from default values; the hash content may have been affected by command-line options, and by direct assignments in the configuration file.

  3. Assigns the context to variable conf.

  4. Assigns command-line arguments to variable ARGV.

  5. Prints the prompt.

  6. Puts the content of the initialization script onto the IRB shell, just as if it were user-typed commands.

The Command Line

On the command line, all options precede all arguments; the first item that is not recognized as an option is treated as an argument, as are all items that follow.

Command-Line Options

Many command-line options affect entries in hash IRB.conf, which in turn affect the initial configuration of the IRB session.

Details of the options are described in the relevant subsections below.

A cursory list of the IRB command-line options may be seen in the help message, which is also displayed if you use command-line option --help.

If you are interested in a specific option, consult the index.

Command-Line Arguments

Command-line arguments are passed to IRB in array ARGV:

$ irb --noscript Foo Bar Baz
irb(main):001> ARGV
=> ["Foo", "Bar", "Baz"]
irb(main):002> exit
$

Command-line option -- causes everything that follows to be treated as arguments, even those that look like options:

$ irb --noscript -- --noscript -- Foo Bar Baz
irb(main):001> ARGV
=> ["--noscript", "--", "Foo", "Bar", "Baz"]
irb(main):002> exit
$

Configuration File

You can initialize IRB via a configuration file.

If command-line option -f is given, no configuration file is looked for.

Otherwise, IRB reads and interprets a configuration file if one is available.

The configuration file can contain any Ruby code, and can usefully include user code that:

The path to the configuration file is the first found among:

If the search fails, there is no configuration file.

If the search succeeds, the configuration file is read as Ruby code, and so can contain any Ruby programming you like.

Method conf.rc? returns true if a configuration file was read, false otherwise. Hash entry IRB.conf[:RC] also contains that value.

Hash IRB.conf

The initial entries in hash IRB.conf are determined by:

You can see the hash by typing IRB.conf.

Details of the entries’ meanings are described in the relevant subsections below.

If you are interested in a specific entry, consult the index.

Notes on Initialization Precedence

Initialization Script

By default, the first command-line argument (after any options) is the path to a Ruby initialization script.

IRB reads the initialization script and puts its content onto the IRB shell, just as if it were user-typed commands.

Command-line option --noscript causes the first command-line argument to be treated as an ordinary argument (instead of an initialization script); --script is the default.

Input

This section describes the features that allow you to change the way IRB input works; see also Input and Output.

Input Command History

By default, IRB stores a history of up to 1000 input commands in a file named .irb_history. The history file will be in the same directory as the configuration file if one is found, or in ~/ otherwise.

A new IRB session creates the history file if it does not exist, and appends to the file if it does exist.

You can change the filepath by adding to your configuration file: IRB.conf[:HISTORY_FILE] = filepath, where filepath is a string filepath.

During the session, method conf.history_file returns the filepath, and method conf.history_file = new_filepath copies the history to the file at new_filepath, which becomes the history file for the session.

You can change the number of commands saved by adding to your configuration file: IRB.conf[:SAVE_HISTORY] = n, where n is one of:

During the session, you can use methods conf.save_history or conf.save_history= to retrieve or change the count.

Command Aliases

By default, IRB defines several command aliases:

irb(main):001> conf.command_aliases
=> {:"$"=>:show_source, :"@"=>:whereami}

You can change the initial aliases in the configuration file with:

IRB.conf[:COMMAND_ALIASES] = {foo: :show_source, bar: :whereami}

You can replace the current aliases at any time with configuration method conf.command_aliases=; Because conf.command_aliases is a hash, you can modify it.

End-of-File

By default, IRB.conf[:IGNORE_EOF] is false, which means that typing the end-of-file character Ctrl-D causes the session to exit.

You can reverse that behavior by adding IRB.conf[:IGNORE_EOF] = true to the configuration file.

During the session, method conf.ignore_eof? returns the setting, and method conf.ignore_eof = boolean sets it.

SIGINT

By default, IRB.conf[:IGNORE_SIGINT] is true, which means that typing the interrupt character Ctrl-C causes the session to exit.

You can reverse that behavior by adding IRB.conf[:IGNORE_SIGING] = false to the configuration file.

During the session, method conf.ignore_siging? returns the setting, and method conf.ignore_sigint = boolean sets it.

Automatic Completion

By default, IRB enables automatic completion:

You can disable it by either of these:

Method conf.use_autocomplete? returns true if automatic completion is enabled, false otherwise.

The setting may not be changed during the session.

Automatic Indentation

By default, IRB automatically indents lines of code to show structure (e.g., it indent the contents of a block).

The current setting is returned by the configuration method conf.auto_indent_mode.

The default initial setting is true:

irb(main):001> conf.auto_indent_mode
=> true
irb(main):002* Dir.entries('.').select do |entry|
irb(main):003*   entry.start_with?('R')
irb(main):004> end
=> ["README.md", "Rakefile"]

You can change the initial setting in the configuration file with:

IRB.conf[:AUTO_INDENT] = false

Note that the current setting may not be changed in the IRB session.

Input Method

The IRB input method determines how command input is to be read; by default, the input method for a session is IRB::RelineInputMethod.

You can set the input method by:

Method conf.use_multiline? and its synonym conf.use_reline return:

Method conf.use_singleline? and its synonym conf.use_readline return:

Output

This section describes the features that allow you to change the way IRB output works; see also Input and Output.

Return-Value Printing (Echoing)

By default, IRB prints (echoes) the values returned by all input commands.

You can change the initial behavior and suppress all echoing by:

During the session, you can change the current setting with configuration method conf.echo= (set to true or false).

As stated above, by default IRB prints the values returned by all input commands; but IRB offers special treatment for values returned by assignment statements, which may be:

> “abcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabc…

You can change the initial behavior by:

During the session, you can change the current setting with configuration method conf.echo_on_assignment= (set to true, false, or :truncate).

By default, IRB formats returned values by calling method inspect.

You can change the initial behavior by:

During the session, you can change the setting using method conf.inspect_mode=.

Multiline Output

By default, IRB prefixes a newline to a multiline response.

You can change the initial default value by adding to the configuration file:

IRB.conf[:NEWLINE_BEFORE_MULTILINE_OUTPUT] = false

During a session, you can retrieve or set the value using methods conf.newline_before_multiline_output? and conf.newline_before_multiline_output=.

Examples:

irb(main):001> conf.inspect_mode = false
=> false
irb(main):002> "foo\nbar"
=>
foo
bar
irb(main):003> conf.newline_before_multiline_output = false
=> false
irb(main):004> "foo\nbar"
=> foo
bar

Evaluation History

By default, IRB saves no history of evaluations (returned values), and the related methods conf.eval_history, _, and __ are undefined.

You can turn on that history, and set the maximum number of evaluations to be stored:

If n is zero, all evaluation history is stored.

Doing either of the above:

Prompt and Return Formats

By default, IRB uses the prompt and return value formats defined in its :DEFAULT prompt mode.

The Default Prompt and Return Format

The default prompt and return values look like this:

irb(main):001> 1 + 1
=> 2
irb(main):002> 2 + 2
=> 4

The prompt includes:

The default prompt actually defines three formats:

You can see the prompt change as you type the characters in the following:

irb(main):001* Dir.entries('.').select do |entry|
irb(main):002*   entry.start_with?('R')
irb(main):003> end
=> ["README.md", "Rakefile"]

Pre-Defined Prompts

IRB has several pre-defined prompts, stored in hash IRB.conf[:PROMPT]:

irb(main):001> IRB.conf[:PROMPT].keys
=> [:NULL, :DEFAULT, :CLASSIC, :SIMPLE, :INF_RUBY, :XMP]

To see the full data for these, type IRB.conf[:PROMPT].

Most of these prompt definitions include specifiers that represent values like the IRB name, session name, and line number; see Prompt Specifiers.

You can change the initial prompt and return format by:

You can retrieve or set the current prompt mode with methods

conf.prompt_mode and conf.prompt_mode=.

If you’re interested in prompts and return formats other than the defaults, you might experiment by trying some of the others.

Custom Prompts

You can also define custom prompts and return formats, which may be done either in an IRB session or in the configuration file.

A prompt in IRB actually defines three prompts, as seen above. For simple custom data, we’ll make all three the same:

irb(main):001* IRB.conf[:PROMPT][:MY_PROMPT] = {
irb(main):002*   PROMPT_I: ': ',
irb(main):003*   PROMPT_C: ': ',
irb(main):004*   PROMPT_S: ': ',
irb(main):005*   RETURN: '=> '
irb(main):006> }
=> {:PROMPT_I=>": ", :PROMPT_C=>": ", :PROMPT_S=>": ", :RETURN=>"=> "}

If you define the custom prompt in the configuration file, you can also make it the current prompt by adding:

IRB.conf[:PROMPT_MODE] = :MY_PROMPT

Regardless of where it’s defined, you can make it the current prompt in a session:

conf.prompt_mode = :MY_PROMPT

You can view or modify the current prompt data with various configuration methods:

Prompt Specifiers

A prompt’s definition can include specifiers for which certain values are substituted:

Verbosity

By default, IRB verbosity is disabled, which means that output is smaller rather than larger.

You can enable verbosity by:

During a session, you can retrieve or set verbosity with methods conf.verbose and conf.verbose=.

Help

Command-line option --version causes IRB to print its help text and exit.

Version

Command-line option --version causes IRB to print its version text and exit.

Input and Output

Color Highlighting

By default, IRB color highlighting is enabled, and is used for both:

You can disable color highlighting by:

Debugging

Command-line option -d sets variables $VERBOSE and $DEBUG to true; these have no effect on IRB output.

Warnings

Command-line option -w suppresses warnings.

Command-line option <tt>-W[level]<tt> sets warning level; 0=silence, 1=medium, 2=verbose.

Other Features

Load Modules

You can specify the names of modules that are to be required at startup.

Array conf.load_modules determines the modules (if any) that are to be required during session startup. The array is used only during session startup, so the initial value is the only one that counts.

The default initial value is [] (load no modules):

irb(main):001> conf.load_modules
=> []

You can set the default initial value via:

Note that the configuration file entry overrides the command-line options.

RI Documentation Directories

You can specify the paths to RI documentation directories that are to be loaded (in addition to the default directories) at startup; see details about RI by typing ri --help.

Array conf.extra_doc_dirs determines the directories (if any) that are to be loaded during session startup. The array is used only during session startup, so the initial value is the only one that counts.

The default initial value is [] (load no extra documentation):

irb(main):001> conf.extra_doc_dirs
=> []

You can set the default initial value via:

Note that the configuration file entry overrides the command-line options.

IRB Name

You can specify a name for IRB.

The default initial value is 'irb':

irb(main):001> conf.irb_name
=> "irb"

You can set the default initial value via hash entry IRB.conf[:IRB_NAME] = string:

IRB.conf[:IRB_NAME] = 'foo'

Application Name

You can specify an application name for the IRB session.

The default initial value is 'irb':

irb(main):001> conf.ap_name
=> "irb"

You can set the default initial value via hash entry IRB.conf[:AP_NAME] = string:

IRB.conf[:AP_NAME] = 'my_ap_name'

Configuration Monitor

You can monitor changes to the configuration by assigning a proc to IRB.conf[:IRB_RC] in the configuration file:

IRB.conf[:IRB_RC] = proc {|conf| puts conf.class }

Each time the configuration is changed, that proc is called with argument conf:

Encodings

Command-line option -E ex[:in] sets initial external (ex) and internal (in) encodings.

Command-line option -U sets both to UTF-8.

Commands

Please use the ‘help` command to see the list of available commands.

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.

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.

Restrictions

Ruby code typed into IRB behaves the same as Ruby code in a file, except that:

nop.rb -

by Keiju ISHITSUKA(keiju@ruby-lang.org)

multi.rb -

by Keiju ISHITSUKA(keiju@ruby-lang.org)

irb/multi-irb.rb - multiple irb module

by Keiju ISHITSUKA(keiju@ruby-lang.org)

frame.rb -

by Keiju ISHITSUKA(Nihon Rational Software Co.,Ltd)

irb/help.rb - print usage module

by Keiju ISHITSUKA(keiju@ishitsuka.com)

irb/lc/error.rb -

by Keiju ISHITSUKA(keiju@ruby-lang.org)

irb/lc/ja/error.rb -

by Keiju ISHITSUKA(keiju@ruby-lang.org)

output-method.rb - output methods used by irb

by Keiju ISHITSUKA(keiju@ruby-lang.org)

Constants

TOPLEVEL_BINDING

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 868
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 169
def IRB.JobManager
  @JobManager
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 182
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 895
def IRB.irb_abort(irb, exception = Abort)
  irb.context.thread.raise exception, "abort then interrupt!"
end
irb_exit(*) click to toggle source

Quits irb

# File lib/irb.rb, line 888
def IRB.irb_exit(*)
  throw :IRB_EXIT, false
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 873
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

Private Class Methods

easter_egg(type = nil) click to toggle source
# File lib/irb/easter-egg.rb, line 109
        def easter_egg(type = nil)
  type ||= [:logo, :dancing].sample
  case type
  when :logo
    require "rdoc"
    RDoc::RI::Driver.new.page do |io|
      io.write easter_egg_logo(:large)
    end
  when :dancing
    STDOUT.cooked do
      interrupted = false
      prev_trap = trap("SIGINT") { interrupted = true }
      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
        break if interrupted
      end
    rescue Interrupt
    ensure
      print "\e[0m\e[?1049l"
      trap("SIGINT", prev_trap)
    end
  end
end