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](en.wikipedia.org/wiki/Autocomplete#In_command-line_interpr eters):

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. Unless the value of 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 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 -W[level] sets warning level;

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)