IRB Documentation (original) (raw)

//badge.fury.io/rb/irb.svg:Gem Version //github.com/ruby/irb/actions/workflows/test.yml/badge.svg:build

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:

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 in COMPARED_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:

To learn more about debugging with IRB, see Debugging with IRB.

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.

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

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 ↑

See Configurations for more details.

Input ↑

This section describes the features that allow you to change the way IRB input works; see also 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:

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

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.

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 ↑

Install ruby/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:

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.

Some features like type narrowing are not implemented.

def f(arg = [0, 'a'].sample) if arg.is_a?(String) arg.

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:

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.

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:

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:

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‘s commands:

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

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:

To learn about these features, refer to debug.gem‘s commands 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 like binding.break.
  2. As IRB doesn’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 ↑

See CONTRIBUTING.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, visit EXTEND_IRB.md.

License ↑

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