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:
-
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:
-
Interprets (as Ruby code) the content of the configuration file (if given).
-
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.
-
Assigns the context to variable
conf
. -
Assigns command-line arguments to variable
ARGV
. -
Prints the prompt.
-
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:
-
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 IRB.conf
¶ ↑
The initial entries in hash IRB.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 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¶ ↑
-
Any conflict between an entry in hash
IRB.conf
and a command-line option is resolved in favor of the hash entry. -
Hash
IRB.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
, wheHISTORY_FILEre n is one of:
-
Positive integer: the number of commands to be saved,
-
Zero: all commands are to be saved.
-
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](en.wikipedia.org/wiki/Autocomplete#In_command-line_interpr eters):
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 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:
-
Adding to the configuration file:
-
IRB.conf[:USE_SINGLELINE] = true
orIRB.conf[:USE_MULTILINE]= false
sets the input method toIRB::ReadlineInputMethod
. -
IRB.conf[:USE_SINGLELINE] = false
orIRB.conf[:USE_MULTILINE] = true
sets the input method toIRB::RelineInputMethod
.
-
-
Giving command-line options:
-
--singleline
or--nomultiline
sets the input method toIRB::ReadlineInputMethod
. -
--nosingleline
or--multiline
sets the input method toIRB::RelineInputMethod
. -
--nosingleline
together with--nomultiline
sets the input toIRB::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 isnil
, which means the same astrue
.) -
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 isniL
, 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 istrue
.) -
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 addedIRB.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 sizen
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, ornil
if none; same as methodconf.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, ornil
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 ofself.to_s
. -
%M
: the value ofself.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 isnil
). -
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 istrue
). -
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 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:
-
Because
IRB
evaluates input immediately after it is syntactically complete, some results may be slightly different. -
Forking may not be well behaved.
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
- ExtendCommand
- TOPLEVEL_BINDING
Public Class Methods
Initializes IRB
and creates a new Irb.irb object at the TOPLEVEL_BINDING
# File irb.rb, line 893 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
# File 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
# File irb/easter-egg.rb, line 101 def easter_egg_logo(type) @easter_egg_logos ||= File.read(File.join(__dir__, 'ruby_logo.aa'), encoding: 'UTF-8:UTF-8') .split(/TYPE: ([A-Z]+)\n/)[1..] .each_slice(2) .to_h @easter_egg_logos[type.to_s.upcase] end