Module: 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:

• Reads each character as you type. You can modify the IRB context to change the way input works. See Input.
• 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. See Output.

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 .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:

• Can then be debugged in IRB.
• Configures IRB itself.
• Requires or loads files.

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

• The value of variable $IRBRC, if defined.
• The value of variable $XDG_CONFIG_HOME/irb/irbrc, if defined.
• File $HOME/.irbrc, if it exists.
• File $HOME/.config/irb/irbrc, if it exists.
• File .irbrc in the current directory, if it exists.
• File irb.rc in the current directory, if it exists.
• File _irbrc in the current directory, if it exists.
• File $irbrc in the current directory, if it exists.

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 .conf

The initial entries in hash .conf are determined by:

• Default values.
• Command-line options, which may override defaults.
• Direct assignments in the configuration file.

You can see the hash by typing .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

• Any conflict between an entry in hash .conf and a command-line option is resolved in favor of the hash entry.
• Hash .conf affects the context only once, when the configuration file is interpreted; any subsequent changes to it do not affect the context and are therefore essentially meaningless.

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:

• 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[: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:

• Adding IRB.conf[:USE_AUTOCOMPLETE] = 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.

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

• 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 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:

• Adding to the configuration file: IRB.conf[:ECHO] = 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):

  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[:ECHO_ON_ASSIGNMENT] = 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[:INSPECT_MODE] = 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[:EVAL_HISTORY] = n. (Examples below assume that we've added IRB.conf[:EVAL_HISTORY] = 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:

  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:

  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:

    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
    irb(main):014> __
    =>
    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:

      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:

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

    • Zero m: contains nil:

      irb(main):019> __[0]
      #=> nil

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 name of the running program (.irb); see IRB Name.
• The name of the current session (main); See IRB Sessions.
• A 3-digit line number (1-based).

The default prompt actually defines three formats:

• One for most situations (as above):

  irb(main):003> Dir
  #=> Dir

• One for when the typed command is a statement continuation (adds trailing asterisk):

  irb(main):004* Dir.

• One for when the typed command is a string continuation (adds trailing single-quote):

  irb(main):005' Dir.entries('.

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:

• Adding to the configuration file: IRB.conf[:PROMPT] = mode where mode is the symbol name of a prompt mode.

• Giving a command-line option:

  • --prompt *mode*: sets the prompt mode to mode. where mode is the symbol name of a prompt mode.
  • --simple-prompt or --sample-book-mode: sets the prompt mode to :SIMPLE.
  • --inf-ruby-mode: sets the prompt mode to :INF_RUBY and suppresses both --multiline and --singleline.
  • --noprompt: suppresses prompting; does not affect echoing.

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:

• conf.prompt_mode, conf.prompt_mode=.
• conf.prompt_c, conf.c=.
• conf.prompt_i, conf.i=.
• conf.prompt_s, conf.s=.
• conf.return_format, return_format=.

Prompt Specifiers

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

• %N: the name of the running program.
• %m: the value of self.to_s.
• %M: the value of self.inspect.
• %l: an indication of the type of string; one of ", ', /, ].
• %NNi: Indentation level. NN is a 2-digit number that specifies the number of digits of the indentation level (03 will result in 001).
• %NNn: Line number. NN is a 2-digit number that specifies the number of digits of the line number (03 will result in 001).
• %%: Literal %.

Verbosity

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

You can enable verbosity by:

• Adding to the configuration file: IRB.conf[:VERBOSE] = true (the default is nil).
• Giving command-line options --verbose (the default is --noverbose).

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:

• Input: As you type, IRB reads the typed characters and highlights elements that it recognizes; it also highlights errors such as mismatched parentheses.
• Output: IRB highlights syntactical elements.

You can disable color highlighting by:

• Adding to the configuration file: IRB.conf[:USE_COLORIZE] = false (the default value is true).
• Giving command-line option --nocolorize

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;

• 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:

• Command-line option -r

   $ irb -r csv -r json
  irb(main):001> conf.load_modules
  #=> ["csv", "json"]

• Hash entry IRB.conf[:LOAD_MODULES] = *array*:

  IRB.conf[:LOAD_MODULES] = %w[csv, json]

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:

• Command-line option --extra_doc_dir

  $ irb --extra-doc-dir your_doc_dir --extra-doc-dir my_doc_dir
  irb(main):001> conf.extra_doc_dirs
  #=> ["your_doc_dir", "my_doc_dir"]

• Hash entry IRB.conf[:EXTRA_DOC_DIRS] = *array*:

  IRB.conf[:EXTRA_DOC_DIRS] = %w[your_doc_dir my_doc_dir]

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 .conf, specify the default behavior of Irb.irb.

On the other hand, each conf in IRB@Command-Line+Options is used to individually configure .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:

• Because IRB evaluates input immediately after it is syntactically complete, some results may be slightly different.
• Forking may not be well behaved.