From 89833152381b759482d5e0ae9dcbdd9ed29a2b6a Mon Sep 17 00:00:00 2001 From: zzak Date: Thu, 13 Dec 2012 05:22:30 +0000 Subject: * lib/irb*: merge doc from doc/irb/ird.rd and improve overall documentation of IRB * doc/irb/irb.rd: remove stale documentation git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@38358 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- lib/irb.rb | 264 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 261 insertions(+), 3 deletions(-) (limited to 'lib/irb.rb') diff --git a/lib/irb.rb b/lib/irb.rb index c8fa04c4e5..e56b69bae0 100644 --- a/lib/irb.rb +++ b/lib/irb.rb @@ -21,14 +21,272 @@ require "irb/locale" STDOUT.sync = true +# 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] = :DEFALUT +# IRB.conf[:PROMPT] = {...} +# IRB.conf[:DEBUG_LEVEL]=0 +# +# == 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 +# :PROMPT_I => nil, # normal prompt +# :PROMPT_S => nil, # prompt for continuated strings +# :PROMPT_C => nil, # prompt for continuated statement +# :RETURN => " ==>%s\n" # format to return value +# } +# +# Then, invoke irb with the above prompt mode by: +# +# irb --prompt my-prompt +# +# Or, add the following in your +.irbrc+: +# +# IRB.conf[:PROMPT_MODE] = :MY_PROMPT +# +# Contants +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 degits and means as same as printf("%NNd"). +# # It can be ommited +# %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 +# } +# +# == Restrictions +# +# Because irb evaluates input immediately after it is syntactically complete, +# the results may be slightly different than directly using ruby. +# +# One of the obvious differences is how irb handles symbols as continuated +# statements: +# +# ruby -e 'p :+' #=> :+ +# irb +# irb(main):001:0> p :+ +# irb(main):002:0* +# +# irb tries to contiue the statement 'p :+' on the next line. +# +# == 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.irb_at_exit. +# +# A few commands for loading files within the session are also available: +# +# +source+:: +# Loads a given file in the current session, 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 IRB.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.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+. +# If +line_no+ is a negative, the return value +line_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 (# : stop) +# #1->irb#1 on main (# : 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 (# : running) +# #1->irb#1 on main (# : stop) +# #2->irb#2 on Foo (# : 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 #=> # +# # invoke a new session with the context of f (instance of Foo) +# irb(main):008:0> irb f +# # list open sessions +# irb.3():001:0> jobs +# #0->irb on main (# : stop) +# #1->irb#1 on main (# : stop) +# #2->irb#2 on Foo (# : stop) +# #3->irb#3 on # (# : running) +# # evaluate f.foo +# irb.3():002:0> foo #=> 1 => nil +# # evaluate f.bar +# irb.3():003:0> bar #=> bar => nil +# # kill jobs 1, 2, and 3 +# irb.3():004:0> kill 1, 2, 3 +# # list open sesssions, should only include main session +# irb(main):009:0> jobs +# #0->irb on main (# : running) +# # quit irb +# irb(main):010:0> exit module IRB @RCS_ID='-$Id$-' class Abort < Exception;end - # @CONF = {} + + # Displays current configuration. + # + # Modifing the configuration is achieved by sending a message to IRB.conf. def IRB.conf @CONF end @@ -75,10 +333,12 @@ module IRB # print "\n" end + # Calls each of the IRB.conf[:AT_EXIT] hooks when the current session quits. def IRB.irb_at_exit @CONF[:AT_EXIT].each{|hook| hook.call} end + # Quits irb def IRB.irb_exit(irb, ret) throw :IRB_EXIT, ret end @@ -91,9 +351,7 @@ module IRB end end - # # irb interpreter main routine - # class Irb def initialize(workspace = nil, input_method = nil, output_method = nil) @context = Context.new(self, workspace, input_method, output_method) -- cgit v1.2.3