`IRB`

Overview

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.

IRB provides a shell-like interface that supports user interaction with the Ruby interpreter. It operates as a read-eval-print loop REPL) that:

Reads each character as you type. You can modify the IRB context to change the way input works. SeeInput.
Evaluates the code each time it has read a syntactically complete passage.
Prints after evaluating. You can modify the IRB context to change the way output works. SeeOutput.

Installation

Note

IRB is a default gem of Ruby, so you shouldn't need to install it separately. However, if you're using Ruby 2.6 or later and want to upgrade/install a specific version of IRB, follow these steps.

To install it with bundler, add this line to your application's Gemfile:

gem 'irb'

Then execute:

$ bundle

Or install it directly with:

$ gem install irb

Usage

Note

We're working hard to match Pry's variety of powerful features in IRB. Track our progress or find contribution ideas inCOMPARED_WITH_PRY.md.

Starting IRB

You can start a fresh IRB session by typing irb in your terminal. In the session, you can evaluate Ruby expressions or prototype small Ruby scripts. Input is executed when it is syntactically complete.

$ irb
irb(main):001> 1 + 2
=> 3
irb(main):002* class Foo
irb(main):003*   def foo
irb(main):004*     puts 1
irb(main):005*   end
irb(main):006> end
=> :foo
irb(main):007> {Foo.new}.foo
1
=> nil

The `binding.irb` Breakpoint

If you use Ruby 2.5 or later versions, you can use binding.irb in your program as breakpoints. Once binding.irb is evaluated, a new IRB session starts with the surrounding context:

$ ruby test.rb

From: test.rb @ line 2 :

    1: def greet(word)
 => 2:   binding.irb
    3:   puts "Hello #{word}"
    4: end
    5:
    6: greet("World")

irb(main):001> word
=> "World"
irb(main):002> exit
Hello World

Debugging

You can use IRB as a debugging console with debug.gem with these options:

In binding.irb, use the debug command to start an irb:rdbg session with access to all debug.gem commands.
Use the RUBY_DEBUG_IRB_CONSOLE=1 environment variable to make debug.gem use IRB as the debugging console.

To learn more about debugging with IRB, seeDebugging with IRB.

Startup

At startup, IRB:

Interprets (as Ruby code) the content of theconfiguration file (if given).
Constructs the initial session context fromhash IRB.conf](file.li>.html"Command_Line">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 relevant subsections below. A cursory list of IRB command-line options may be seen in thehelp message, which is also displayed if you use command-line option --help.

If you are interested in a specific option, consult theindex.

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
$
```
Commands

The following commands are available in IRB. Use the help command to see the list of available commands.
```
Help
  help           List all available commands. Use `help <command>` to get information about a specific command.

IRB
  context        Displays current configuration.
  exit           Exit the current irb session.
  exit!          Exit the current process.
  irb_load       Load a Ruby file.
  irb_require    Require a Ruby file.
  source         Loads a given file in the current session.
  irb_info       Show information about IRB.
  history        Shows the input history. `-g [query]` or `-G [query]` allows you to filter the output.
  disable_irb    Disable binding.irb.

Workspace
  cwws           Show the current workspace.
  chws           Change the current workspace to an object.
  workspaces     Show workspaces.
  pushws         Push an object to the workspace stack.
  popws          Pop a workspace from the workspace stack.
  cd             Move into the given object or leave the current context.

Multi-irb (DEPRECATED)
  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.

Debugging
  debug          Start the debugger of debug.gem.
  break          Start the debugger of debug.gem and run its `break` command.
  catch          Start the debugger of debug.gem and run its `catch` command.
  next           Start the debugger of debug.gem and run its `next` command.
  delete         Start the debugger of debug.gem and run its `delete` command.
  step           Start the debugger of debug.gem and run its `step` command.
  continue       Start the debugger of debug.gem and run its `continue` command.
  finish         Start the debugger of debug.gem and run its `finish` command.
  backtrace      Start the debugger of debug.gem and run its `backtrace` command.
  info           Start the debugger of debug.gem and run its `info` command.

Misc
  edit           Open a file or source location.
  measure        `measure` enables the mode to measure processing time. `measure :off` disables it.
  copy           Copy expression output to clipboard

Context
  show_doc       Look up documentation with RI.
  ls             Show methods, constants, and variables.
  show_source    Show the source code of a given method, class/module, or constant.
  whereami       Show the source code around binding.irb again.

Helper methods
  conf           Returns the current IRB context.

Aliases
  $              Alias for `show_source`
  @              Alias for `whereami`
```
Configure IRB

SeeConfigurations for more details.

Input

This section describes the features that allow you to change the way IRB input works; see alsoOutput.

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 theconfiguration 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 = 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 = n, where n is one of:
- Positive integer: the number of commands to be saved.
- Negative integer: all commands are to be saved.
- Zero or nil: no commands are to be saved.
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 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 = 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 is true, which means that typing the interrupt character Ctrl-C does not cause the session to exit.

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

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

Automatic Completion

By default, IRB enablesautomatic completion:

To cycle through the completion suggestions, use the tab key (and shift-tab to reverse).

You can disable it by either of these:
- Adding IRB.conf = false to the configuration file.
- Giving command-line option --noautocomplete (--autocomplete is the default).
Method conf.use_autocomplete? returns true if automatic completion is enabled, false otherwise.

The setting may not be changed during the session.

Type Based Completion

IRB's default completion ::IRB::RegexpCompletor uses Regexp. IRB offers an experimental completion ::IRB::TypeCompletor that uses type analysis.

How to Enable ::IRB::TypeCompletor

Installruby/repl_type_completor with:
```
$ gem install repl_type_completor
```
Or add these lines to your project's Gemfile.
```
gem 'irb'
gem 'repl_type_completor', group: [:development, :test]
```
Now you can use type-based completion by:
- Running IRB with the --type-completor option
```
```console
  $ irb --type-completor
```
```
- Or writing this line to IRB's rc-file (e.g., ~/.irbrc)
```
```ruby
  IRB.conf[:COMPLETOR] = :type # default is :regexp
```
```
- Or setting the environment variable IRB_COMPLETOR
```
```ruby
  ENV['IRB_COMPLETOR'] = 'type'
  IRB.start
```
```
To check if it's enabled, type irb_info into IRB and see the Completion section.
```
irb(main):001> irb_info
...
# Enabled
Completion: Autocomplete, ReplTypeCompletor: 0.1.0, Prism: 0.18.0, RBS: 3.3.0
# Not enabled
Completion: Autocomplete, RegexpCompletor
...
```
If you have a sig/ directory or rbs_collection.lock.yaml in the current directory, IRB will load it.

Advantage over Default ::IRB::RegexpCompletor

::IRB::TypeCompletor can autocomplete chained methods, block parameters, and more if type information is available. These are some examples ::IRB::RegexpCompletor cannot complete.
```
irb(main):001> 'Ruby'.upcase.chars.s # Array methods (sample, select, shift, size)
```
```
irb(main):001> 10.times.map(&:to_s).each do |s|
irb(main):002>   s.up # String methods (upcase, upcase!, upto)
```
```
irb(main):001> class User < ApplicationRecord
irb(main):002>   def foo
irb(main):003>     sa # save, save!
```
As a trade-off, completion calculation takes more time than ::IRB::RegexpCompletor.

Difference between Steep's Completion

Compared with Steep, ::IRB::TypeCompletor has some differences and limitations.
```
[0, 'a'].sample.
# Steep completes the intersection of Integer methods and String methods
# IRB::TypeCompletor completes both Integer and String methods
```
Some features like type narrowing are not implemented.
```
def f(arg = [0, 'a'].sample)
  if arg.is_a?(String)
    arg. # Completes both Integer and String methods
```
Unlike other static type checkers, ::IRB::TypeCompletor uses runtime information to provide better completion.
```
irb(main):001> a = [1]
=> [1]
irb(main):002> a.first. # Completes Integer methods
```
Automatic Indentation

By default, IRB automatically indents lines of code to show structure (e.g., it indents 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 read; by default, the input method for a session is ::IRB::RelineInputMethod unless the TERM environment variable is 'dumb', in which case the most simplistic input method is used.

You can set the input method by:
- Adding to the configuration file:
```
- `IRB.conf[:USE_SINGLELINE] = true` or `IRB.conf[:USE_MULTILINE] = false` sets the input method to IRB::ReadlineInputMethod.
- `IRB.conf[:USE_SINGLELINE] = false` or `IRB.conf[:USE_MULTILINE] = true` sets the input method to IRB::RelineInputMethod.
```
- Giving command-line options:
- --singleline or --nomultiline sets the input method to IRB::ReadlineInputMethod.
- --nosingleline or --multiline sets the input method to IRB::RelineInputMethod.
- --nosingleline together with --nomultiline sets the input to IRB::StdioInputMethod.
Method conf.use_multiline? and its synonym conf.use_reline return:
- true if option --multiline was given.
- false if option --nomultiline was given.
- nil if neither was given.
Method conf.use_singleline? and its synonym conf.use_readline return:
- true if option --singleline was given.
- false if option --nosingleline was given.
- nil if neither was given.
Output

This section describes the features that allow you to change the way IRB output works; see alsoInput.

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:
- Adding to the configuration file: IRB.conf = false. (The default value for this entry is nil, which means the same as true.)
- Giving command-line option --noecho. (The default is --echo.)
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:
- Printed with truncation (to fit on a single line of output), which is the default; an ellipsis (... is suffixed, to indicate the truncation):
```
```console
  irb(main):001> x = 'abc' * 100
  > "abcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabcabc..."
```
```
- Printed in full (regardless of the length).
- Suppressed (not printed at all).
You can change the initial behavior by:
- Adding to the configuration file: IRB.conf = false. (The default value for this entry is nil, which means the same as :truncate.)
- Giving command-line option --noecho-on-assignment or --echo-on-assignment. (The default is --truncate-echo-on-assignment.)
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:
- Adding to the configuration file: IRB.conf = false. (The default value for this entry is true.)
- Giving command-line option --noinspect. (The default is --inspect.)
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:
- In the configuration file: add IRB.conf = n. (Examples below assume that we've added IRB.conf = 5.)
- In the session (at any time): conf.eval_history = n.
If n is zero, all evaluation history is stored.

Doing either of the above:
- Sets the maximum size of the evaluation history; defines method conf.eval_history, which returns the maximum size n of the evaluation history:
```
```console
  irb(main):001> conf.eval_history = 5
  #=> 5
  irb(main):002> conf.eval_history
  #=> 5
```
```
- Defines variable _, which contains the most recent evaluation, or nil if none; same as method conf.last_value:
```
```console
  irb(main):003> _
  #=> 5
  irb(main):004> :foo
  #=> :foo
  irb(main):005> :bar
  #=> :bar
  irb(main):006> _
  #=> :bar
  irb(main):007> _
  #=> :bar
```
```
- Defines variable __:
```
- `__` unadorned: contains all evaluation history:

```console
  irb(main):008> :foo
  #=> :foo
  irb(main):009> :bar
  #=> :bar
  irb(main):010> :baz
  #=> :baz
  irb(main):011> :bat
  #=> :bat
  irb(main):012> :bam
  #=> :bam
  irb(main):013> __
  =>
  9 :bar
  10 :baz
  11 :bat
  12 :bam
  13 ...self-history...
```

Note that when the evaluation is multiline, it is displayed differently.

- `__[m]`:

- Positive `m`: contains the evaluation for the given line number, or `nil` if that line number is not in the evaluation history:

  ```console
    irb(main):015> __[12]
    #=> :bam
    irb(main):016> __[1]
    #=> nil
  ```

- Negative `m`: contains the `mth`-from-end evaluation, or `nil` if that evaluation is not in the evaluation history:

  ```console
    irb(main):017> __[-3]
    #=> :bam
    irb(main):018> __[-13]
    #=> nil
  ```

- Zero `m`: contains `nil`:

  ```console
    irb(main):019> __[0]
    #=> nil
  ```
```
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.

Debugging with IRB

Starting from version 1.8.0, IRB offers a powerful integration with debug.gem, providing a debugging experience similar to pry-byebug.

After hitting a binding.irb breakpoint, you can activate the debugger with the debug command. Alternatively, if the debug method is already defined in the current scope, you can call irb_debug.
```
From: test.rb @ line 3 :

    1:
    2: def greet(word)
 => 3:   binding.irb
    4:   puts "Hello #{word}"
    5: end
    6:
    7: greet("World")

irb(main):001> debug
irb:rdbg(main):002>
```
Once activated, the prompt's header changes from irb to irb:rdbg, enabling you to use any of debug.gem'scommands:
```
irb:rdbg(main):002> info # use info command to see available variables
%self = main
_ = nil
word = "World"
irb:rdbg(main):003> next # use next command to move to the next line
[1, 7] in test.rb
     1|
     2| def greet(word)
     3|   binding.irb
=>   4|   puts "Hello #{word}"
     5| end
     6|
     7| greet("World")
=>#0    {Object#greet}(word="World") at test.rb:4
  #1    <main> at test.rb:7
irb:rdbg(main):004>
```
Simultaneously, you maintain access to IRB's commands, such as show_source:
```
irb:rdbg(main):004> show_source greet

From: test.rb:2

def greet(word)
  binding.irb
  puts "Hello #{word}"
end
```
More about debug.gem

debug.gem offers many advanced debugging features that simple REPLs can't provide, including:
- Step-debugging
- Frame navigation
- Setting breakpoints with commands
- Thread control
- ...and many more
To learn about these features, refer to debug.gem'scommands list.

In the irb:rdbg session, the help command also displays all commands from debug.gem.

Advantages Over debug.gem's Console

This integration offers several benefits over debug.gem's native console:
1. Access to handy IRB commands like show_source or show_doc.
2. Support for multi-line input.
3. Symbol shortcuts such as @ (whereami) and $ (show_source).
4. Autocompletion.
5. Customizable prompt.
However, there are some limitations to be aware of:
1. binding.irb doesn't support pre and do arguments likebinding.break.
2. As IRBdoesn't currently support remote-connection, it can't be used with debug.gem's remote debugging feature.
3. Access to the previous return value via the underscore _ is not supported.
Encodings

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

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

Contributing

SeeCONTRIBUTING.md for more information.

Extending IRB

IRB v1.13.0 and later versions allow users/libraries to extend its functionality through official APIs.

For more information, visitEXTEND_IRB.md.

License

The gem is available as open source under the terms of the2-Clause BSD License.

`IRB`

Overview

Installation

Usage

Starting IRB

The `binding.irb` Breakpoint

Debugging

Startup

Command-Line Options

Command-Line Arguments

Commands

Configure IRB

Input

Input Command History

Command Aliases

End-of-File

SIGINT

Automatic Completion

Type Based Completion

How to Enable `::IRB::TypeCompletor`

Advantage over Default `::IRB::RegexpCompletor`

Difference between Steep's Completion

Automatic Indentation

Input Method

Output

Return-Value Printing (Echoing)

Multiline Output

Evaluation History

Initialization Script

Debugging with IRB

More about `debug.gem`

Advantages Over `debug.gem`'s Console

Encodings

Contributing

Extending IRB

License

IRB

Overview

Installation

Usage

Starting IRB

The binding.irb Breakpoint

Debugging

Startup

Command-Line Options

Command-Line Arguments

Commands

Configure IRB

Input

Input Command History

Command Aliases

End-of-File

SIGINT

Automatic Completion

Type Based Completion

How to Enable ::IRB::TypeCompletor

Advantage over Default ::IRB::RegexpCompletor

Difference between Steep's Completion

Automatic Indentation

Input Method

Output

Return-Value Printing (Echoing)

Multiline Output

Evaluation History

Initialization Script

Debugging with IRB

More about debug.gem

Advantages Over debug.gem's Console

Encodings

Contributing

Extending IRB

License

`IRB`

The `binding.irb` Breakpoint

How to Enable `::IRB::TypeCompletor`

Advantage over Default `::IRB::RegexpCompletor`

More about `debug.gem`

Advantages Over `debug.gem`'s Console