* 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

1 files changed, 261 insertions, 3 deletions

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 <code>~/.irbrc</code> when it's invoked.
+#
+# If <code>~/.irbrc</code> doesn't exist, +irb+ will try to read in the following order:
+#
+# * +.irbrc+
+# * +irb.rc+
+# * +_irbrc+
+# * <code>$irbrc</code>
+#
+# 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:
+#
+# <code>_</code>::
+#   The value command executed, as a local variable
+# <code>__</code>::
+#   The history of evaluated commands
+# <code>__[line_no]</code>::
+#   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 (#<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 sesssions, should only include main session
+#   irb(main):009:0> jobs
+#     #0->irb on main (#<Thread:0x400fb7e4> : 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)