Module: IRB
Relationships & Source Files | |
Namespace Children | |
Modules:
| |
Classes:
| |
Exceptions:
| |
Super Chains via Extension / Inclusion / Inheritance | |
Class Chain:
self,
Exception2MessageMapper,
Exception2MessageMapper
|
|
Defined in: | lib/irb.rb, lib/irb/completion.rb, lib/irb/context.rb, lib/irb/extend-command.rb, lib/irb/frame.rb, lib/irb/help.rb, lib/irb/init.rb, lib/irb/input-method.rb, lib/irb/inspector.rb, lib/irb/locale.rb, lib/irb/magic-file.rb, lib/irb/notifier.rb, lib/irb/output-method.rb, lib/irb/slex.rb, lib/irb/version.rb, lib/irb/workspace.rb, lib/irb/cmd/chws.rb, lib/irb/cmd/fork.rb, lib/irb/cmd/help.rb, lib/irb/cmd/load.rb, lib/irb/cmd/nop.rb, lib/irb/cmd/pushws.rb, lib/irb/cmd/subirb.rb, lib/irb/ext/change-ws.rb, lib/irb/ext/history.rb, lib/irb/ext/loader.rb, lib/irb/ext/math-mode.rb, lib/irb/ext/multi-irb.rb, lib/irb/ext/save-history.rb, lib/irb/ext/tracer.rb, lib/irb/ext/use-loader.rb, lib/irb/ext/workspaces.rb, lib/irb/lc/error.rb, lib/irb/lc/ja/encoding_aliases.rb, lib/irb/lc/ja/error.rb |
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.
Usage
Use of irb is easy if you know Ruby.
When executing irb, prompts are displayed as follows. Then, enter the Ruby expression. An input is executed when it is syntactically complete.
$ irb
irb(main):001:0> 1+2
#=> 3
irb(main):002:0> class Foo
irb(main):003:1> def foo
irb(main):004:2> print 1
irb(main):005:2> end
irb(main):006:1> end
#=> nil
The Readline extension module can be used with irb. Use of Readline is default if it's installed.
Command line options
Usage: irb.rb [options] [programfile] [arguments]
-f Suppress read of ~/.irbrc
-m Bc mode (load mathn, fraction or matrix are available)
-d Set $DEBUG to true (same as `ruby -d')
-r load-module Same as `ruby -r'
-I path Specify $LOAD_PATH directory
-U Same as `ruby -U`
-E enc Same as `ruby -E`
-w Same as `ruby -w`
-W[level=2] Same as `ruby -W`
--inspect Use `inspect' for output (default except for bc mode)
--noinspect Don't use inspect for output
--readline Use Readline extension module
--noreadline Don't use Readline extension module
--prompt prompt-mode
--prompt-mode prompt-mode
Switch prompt mode. Pre-defined prompt modes are
`default', `simple', `xmp' and `inf-ruby'
--inf-ruby-mode Use prompt appropriate for inf-ruby-mode on emacs.
Suppresses --readline.
--simple-prompt Simple prompt mode
--noprompt No prompt mode
--tracer Display trace for each execution of commands.
--back-trace-limit n
Display backtrace top n and tail n. The default
value is 16.
--irb_debug n Set internal debug level to n (not for popular use)
-v, --version Print the version of irb
Configuration
IRB
reads from ~/.irbrc
when it's invoked.
If ~/.irbrc
doesn't exist, .irb will try to read in the following order:
-
.irbrc
-
irb.rc
-
_irbrc
-
$irbrc
The following are alternatives to the command line options. To use them type as follows in an .irb session:
IRB.conf[:IRB_NAME]="irb"
IRB.conf[:MATH_MODE]=false
IRB.conf[:INSPECT_MODE]=nil
IRB.conf[:IRB_RC] = nil
IRB.conf[:BACK_TRACE_LIMIT]=16
IRB.conf[:USE_LOADER] = false
IRB.conf[:USE_READLINE] = nil
IRB.conf[:USE_TRACER] = false
IRB.conf[:IGNORE_SIGINT] = true
IRB.conf[:IGNORE_EOF] = false
IRB.conf[:PROMPT_MODE] = :DEFAULT
IRB.conf[:PROMPT] = {...}
IRB.conf[:DEBUG_LEVEL]=0
Auto indentation
To enable auto-indent mode in irb, add the following to your .irbrc
:
IRB.conf[:AUTO_INDENT] = true
Autocompletion
To enable autocompletion for irb, add the following to your .irbrc
:
require 'irb/completion'
History
By default, irb disables history and will not store any commands you used.
If you want to enable history, add the following to your .irbrc
:
IRB.conf[:SAVE_HISTORY] = 1000
This will now store the last 1000 commands in ~/.irb_history
.
See Context#save_history= for more information.
Customizing the IRB Prompt
In order to customize the prompt, you can change the following Hash:
IRB.conf[:PROMPT]
This example can be used in your .irbrc
IRB.conf[:PROMPT][:MY_PROMPT] = { # name of prompt mode
:AUTO_INDENT => true, # enables auto-indent mode
:PROMPT_I => ">> ", # simple prompt
:PROMPT_S => nil, # prompt for continuated strings
:PROMPT_C => nil, # prompt for continuated statement
:RETURN => " ==>%s\n" # format to return value
}
IRB.conf[:PROMPT_MODE] = :MY_PROMPT
Or, invoke irb with the above prompt mode by:
irb --prompt my-prompt
Constants PROMPT_I
, PROMPT_S
and PROMPT_C
specify the format. In the prompt specification, some special strings are available:
%N # command name which is running
%m # to_s of main object (self)
%M # inspect of main object (self)
%l # type of string(", ', /, ]), `]' is inner %w[...]
%NNi # indent level. NN is digits and means as same as printf("%NNd").
# It can be omitted
%NNn # line number.
%% # %
For instance, the default prompt mode is defined as follows:
IRB.conf[:PROMPT_MODE][:DEFAULT] = {
:PROMPT_I => "%N(%m):%03n:%i> ",
:PROMPT_S => "%N(%m):%03n:%i%l ",
:PROMPT_C => "%N(%m):%03n:%i* ",
:RETURN => "%s\n" # used to printf
}
irb comes with a number of available modes:
# :NULL:
# :PROMPT_I:
# :PROMPT_N:
# :PROMPT_S:
# :PROMPT_C:
# :RETURN: |
# %s
# :DEFAULT:
# :PROMPT_I: ! '%N(%m):%03n:%i> '
# :PROMPT_N: ! '%N(%m):%03n:%i> '
# :PROMPT_S: ! '%N(%m):%03n:%i%l '
# :PROMPT_C: ! '%N(%m):%03n:%i* '
# :RETURN: |
# => %s
# :CLASSIC:
# :PROMPT_I: ! '%N(%m):%03n:%i> '
# :PROMPT_N: ! '%N(%m):%03n:%i> '
# :PROMPT_S: ! '%N(%m):%03n:%i%l '
# :PROMPT_C: ! '%N(%m):%03n:%i* '
# :RETURN: |
# %s
# :SIMPLE:
# :PROMPT_I: ! '>> '
# :PROMPT_N: ! '>> '
# :PROMPT_S:
# :PROMPT_C: ! '?> '
# :RETURN: |
# => %s
# :INF_RUBY:
# :PROMPT_I: ! '%N(%m):%03n:%i> '
# :PROMPT_N:
# :PROMPT_S:
# :PROMPT_C:
# :RETURN: |
# %s
# :AUTO_INDENT: true
# :XMP:
# :PROMPT_I:
# :PROMPT_N:
# :PROMPT_S:
# :PROMPT_C:
# :RETURN: |2
# ==>%s
Restrictions
Because irb evaluates input immediately after it is syntactically complete, the results may be slightly different than directly using Ruby.
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.
Commands
JobManager provides commands to handle the current sessions:
jobs # List of current sessions
fg # Switches to the session of the given number
kill # Kills the session with the given number
The exit
command, or .irb_exit, will quit the current session and call any exit hooks with .irb_at_exit.
A few commands for loading files within the session are also available:
source
-
Loads a given file in the current session and displays the source lines, see IrbLoader#source_file
irb_load
-
Loads the given file similarly to Kernel#load, see IrbLoader#irb_load
irb_require
-
Loads the given file similarly to Kernel#require
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
__[line_no]
-
Returns the evaluation value at the given line number,
line_no
. Ifline_no
is a negative, the return valueline_no
many lines before the most recent return value.
Example using IRB Sessions
# invoke a new session
irb(main):001:0> irb
# list open sessions
irb.1(main):001:0> jobs
#0->irb on main (#<Thread:0x400fb7e4> : stop)
#1->irb#1 on main (#<Thread:0x40125d64> : running)
# change the active session
irb.1(main):002:0> fg 0
# define class Foo in top-level session
irb(main):002:0> class Foo;end
# invoke a new session with the context of Foo
irb(main):003:0> irb Foo
# define Foo#foo
irb.2(Foo):001:0> def foo
irb.2(Foo):002:1> print 1
irb.2(Foo):003:1> end
# change the active session
irb.2(Foo):004:0> fg 0
# list open sessions
irb(main):004:0> jobs
#0->irb on main (#<Thread:0x400fb7e4> : running)
#1->irb#1 on main (#<Thread:0x40125d64> : stop)
#2->irb#2 on Foo (#<Thread:0x4011d54c> : stop)
# check if Foo#foo is available
irb(main):005:0> Foo.instance_methods #=> [:foo, ...]
# change the active sesssion
irb(main):006:0> fg 2
# define Foo#bar in the context of Foo
irb.2(Foo):005:0> def bar
irb.2(Foo):006:1> print "bar"
irb.2(Foo):007:1> end
irb.2(Foo):010:0> Foo.instance_methods #=> [:bar, :foo, ...]
# change the active session
irb.2(Foo):011:0> fg 0
irb(main):007:0> f = Foo.new #=> #<Foo:0x4010af3c>
# invoke a new session with the context of f (instance of Foo)
irb(main):008:0> irb f
# list open sessions
irb.3(<Foo:0x4010af3c>):001:0> jobs
#0->irb on main (#<Thread:0x400fb7e4> : stop)
#1->irb#1 on main (#<Thread:0x40125d64> : stop)
#2->irb#2 on Foo (#<Thread:0x4011d54c> : stop)
#3->irb#3 on #<Foo:0x4010af3c> (#<Thread:0x4010a1e0> : running)
# evaluate f.foo
irb.3(<Foo:0x4010af3c>):002:0> foo #=> 1 => nil
# evaluate f.bar
irb.3(<Foo:0x4010af3c>):003:0> bar #=> bar => nil
# kill jobs 1, 2, and 3
irb.3(<Foo:0x4010af3c>):004:0> kill 1, 2, 3
# list open sessions, should only include main session
irb(main):009:0> jobs
#0->irb on main (#<Thread:0x400fb7e4> : running)
# quit irb
irb(main):010:0> exit
Class Method Summary
-
.conf
Displays current configuration.
- CurrentContext
- .delete_caller
-
.initialize_tracer
initialize tracing function.
- .inspect
-
.irb(file = nil, *main)
Creates a new
IRB
session, see Irb.new. -
.irb_abort(irb, exception = Abort)
Aborts then interrupts irb.
-
.irb_at_exit
Calls each event hook of
IRB.conf[:AT_EXIT]
when the current session quits. -
.irb_exit(irb, ret)
Quits irb.
-
JobManager
The current JobManager in the session.
-
.print_usage
Outputs the irb help message, see IRB@Command+line+options.
-
.start(ap_path = nil)
Initializes IRB and creates a new
Irb.irb
object at theTOPLEVEL_BINDING
-
.version
Returns the current version of
IRB
, including release version and last updated date.
Class Method Details
.conf
Displays current configuration.
Modifying the configuration is achieved by sending a message to conf
.
See IRB@Configuration for more information.
# File 'lib/irb.rb', line 350
def IRB.conf @CONF end
CurrentContext
The current ::IRB::Context of the session, see .conf
irb
irb(main):001:0> IRB.CurrentContext.irb_name = "foo"
foo(main):002:0> IRB.conf[:MAIN_CONTEXT].irb_name #=> "foo"
See additional method definition at file lib/irb.rb line 369.
# File 'lib/irb/ext/multi-irb.rb', line 182
def IRB.CurrentContext IRB.conf[:MAIN_CONTEXT] end
.delete_caller
[ GitHub ]# File 'lib/irb/workspace.rb', line 112
def IRB.delete_caller end
.initialize_tracer
initialize tracing function
# File 'lib/irb/ext/tracer.rb', line 17
def IRB.initialize_tracer Tracer.verbose = false Tracer.add_filter { |event, file, line, id, binding, *rests| /^#{Regexp.quote(@CONF[:IRB_LIB_PATH])}/ !~ file and File::basename(file) != "irb.rb" } end
.inspect
[ GitHub ]# File 'lib/irb.rb', line 682
def @CONF.inspect IRB.version unless self[:VERSION] array = [] for k, v in sort{|a1, a2| a1[0].id2name <=> a2[0].id2name} case k when :MAIN_CONTEXT, :__TMP__EHV__ array.push format("CONF[:%s]=...myself...", k.id2name) when :PROMPT s = v.collect{ |kk, vv| ss = vv.collect{|kkk, vvv| ":#{kkk.id2name}=>#{vvv.inspect}"} format(":%s=>{%s}", kk.id2name, ss.join(", ")) } array.push format("CONF[:%s]={%s}", k.id2name, s.join(", ")) else array.push format("CONF[:%s]=%s", k.id2name, v.inspect) end end array.join("\n") end
.irb(file = nil, *main)
Creates a new IRB
session, see Irb.new.
The optional file
argument is given to Context.new, along with the workspace created with the remaining arguments, see WorkSpace.new
# File 'lib/irb/ext/multi-irb.rb', line 190
def IRB.irb(file = nil, *main) workspace = WorkSpace.new(*main) parent_thread = Thread.current Thread.start do begin irb = Irb.new(workspace, file) rescue print "Subirb can't start with context(self): ", workspace.main.inspect, "\n" print "return to main irb\n" Thread.pass Thread.main.wakeup Thread.exit end @CONF[:IRB_RC].call(irb.context) if @CONF[:IRB_RC] @JobManager.insert(irb) @JobManager.current_job = irb begin system_exit = false catch(:IRB_EXIT) do irb.eval_input end rescue SystemExit system_exit = true raise #fail ensure unless system_exit @JobManager.delete(irb) if @JobManager.current_job == irb if parent_thread.alive? @JobManager.current_job = @JobManager.irb(parent_thread) parent_thread.run else @JobManager.current_job = @JobManager.main_irb @JobManager.main_thread.run end end end end end Thread.stop @JobManager.current_job = @JobManager.irb(Thread.current) end
.irb_abort(irb, exception = Abort)
Aborts then interrupts irb.
Will raise an ::IRB::Abort exception, or the given exception
.
.irb_at_exit
Calls each event hook of IRB.conf[:AT_EXIT]
when the current session quits.
# File 'lib/irb.rb', line 403
def IRB.irb_at_exit @CONF[:AT_EXIT].each{|hook| hook.call} end
.irb_exit(irb, ret)
Quits irb
# File 'lib/irb.rb', line 408
def IRB.irb_exit(irb, ret) throw :IRB_EXIT, ret end
JobManager
The current ::IRB::JobManager in the session
# File 'lib/irb/ext/multi-irb.rb', line 177
def IRB.JobManager @JobManager end
.print_usage
Outputs the irb help message, see IRB@Command+line+options.
# File 'lib/irb/help.rb', line 17
def IRB.print_usage lc = IRB.conf[:LC_MESSAGES] path = lc.find("irb/help-message") space_line = false IRB::MagicFile.open(path){|f| f.each_line do |l| if /^\s*$/ =~ l lc.puts l unless space_line space_line = true next end space_line = false l.sub!(/#.*$/, "") next if /^\s*$/ =~ l lc.puts l end } end
.start(ap_path = nil)
Initializes IRB and creates a new Irb.irb
object at the TOPLEVEL_BINDING
# File 'lib/irb.rb', line 374
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 @CONF[:IRB_RC].call(irb.context) if @CONF[:IRB_RC] @CONF[:MAIN_CONTEXT] = irb.context trap("SIGINT") do irb.signal_handle end begin catch(:IRB_EXIT) do irb.eval_input end ensure irb_at_exit end end
.version
Returns the current version of IRB
, including release version and last updated date.
# File 'lib/irb.rb', line 356
def IRB.version if v = @CONF[:VERSION] then return v end require "irb/version" rv = @RELEASE_VERSION.sub(/\.0/, "") @CONF[:VERSION] = format("irb %s(%s)", rv, @LAST_UPDATE_DATE) end