1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2022-11-09 12:17:21 -05:00

* 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
This commit is contained in:
zzak 2012-12-13 05:22:30 +00:00
parent 0ac361f540
commit 8983315238
29 changed files with 432 additions and 23 deletions

View file

@ -1,3 +1,9 @@
Thu Dec 13 14:20:00 2012 Zachary Scott <zachary@zacharyscott.net>
* lib/irb*: merge doc from doc/irb/ird.rd and improve overall
documentation of IRB
* doc/irb/irb.rd: remove stale documentation
Thu Dec 13 14:10:00 2012 Shugo Maeda <shugo@ruby-lang.org>
* marshal.c (r_entry0): don't taint classes and modules because

View file

@ -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)

View file

@ -12,6 +12,7 @@
require "irb/cmd/nop.rb"
require "irb/ext/change-ws.rb"
# :stopdoc:
module IRB
module ExtendCommand
@ -29,4 +30,4 @@ module IRB
end
end
end
# :startdoc:

View file

@ -11,7 +11,7 @@
@RCS_ID='-$Id$-'
# :stopdoc:
module IRB
module ExtendCommand
class Fork<Nop
@ -34,5 +34,6 @@ module IRB
end
end
end
# :startdoc:

View file

@ -12,6 +12,7 @@ require 'rdoc/ri/driver'
require "irb/cmd/nop.rb"
# :stopdoc:
module IRB
module ExtendCommand
class Help<Nop
@ -37,3 +38,4 @@ module IRB
end
end
end
# :startdoc:

View file

@ -12,6 +12,7 @@
require "irb/cmd/nop.rb"
require "irb/ext/loader"
# :stopdoc:
module IRB
module ExtendCommand
class Load<Nop
@ -64,3 +65,4 @@ module IRB
end
end
# :startdoc:

View file

@ -8,6 +8,7 @@
#
#
#
# :stopdoc:
module IRB
module ExtendCommand
class Nop
@ -35,4 +36,4 @@ module IRB
end
end
end
# :startdoc:

View file

@ -12,6 +12,7 @@
require "irb/cmd/nop.rb"
require "irb/ext/workspaces.rb"
# :stopdoc:
module IRB
module ExtendCommand
class Workspaces<Nop
@ -35,4 +36,5 @@ module IRB
end
end
end
# :startdoc:

View file

@ -11,6 +11,7 @@
require "irb/cmd/nop.rb"
require "irb/ext/multi-irb"
# :stopdoc:
module IRB
module ExtendCommand
class IrbCommand<Nop
@ -38,3 +39,4 @@ module IRB
end
end
end
# :startdoc:

View file

@ -13,12 +13,13 @@ require "irb/inspector"
module IRB
class Context
# Creates a new IRB context.
#
# Arguments:
# input_method: nil -- stdin or readline
# String -- File
# other -- using this as InputMethod
# The optional +input_method+ argument:
#
# +nil+:: uses stdin or Readline
# +String+:: uses a File
# +other+:: uses this as InputMethod
def initialize(irb, workspace = nil, input_method = nil, output_method = nil)
@irb = irb
if workspace
@ -116,31 +117,69 @@ module IRB
attr_accessor :irb_name
attr_accessor :irb_path
# Whether +Readline+ is enabled or not.
#
# See #use_readline= for more information.
attr_reader :use_readline
attr_reader :inspect_mode
attr_reader :prompt_mode
# Standard IRB prompt
#
# See IRB@Customizing+the+IRB+Prompt for more information.
attr_accessor :prompt_i
# IRB prompt for continuated strings
#
# See IRB@Customizing+the+IRB+Prompt for more information.
attr_accessor :prompt_s
# IRB prompt for continuated statement (e.g. immediately after an +if+)
#
# See IRB@Customizing+the+IRB+Prompt for more information.
attr_accessor :prompt_c
# See IRB@Customizing+the+IRB+Prompt for more information.
attr_accessor :prompt_n
attr_accessor :auto_indent_mode
attr_accessor :return_format
# Whether <code>^C</code> (+control-c+) will be ignored or not.
#
# If set to +false+, <code>^C</code> will quit irb.
#
# If set to +true+,
#
# * during input: cancel input then return to top level.
# * during execute: abandon current execution.
attr_accessor :ignore_sigint
# Whether <code>^D</code> (+control-d+) will be ignored or not.
#
# If set to +false+, <code>^D</code> will quit irb.
attr_accessor :ignore_eof
attr_accessor :echo
# Whether verbose messages are displayed or not.
attr_accessor :verbose
# The debug level of irb
#
# See #debug_level= for more information.
attr_reader :debug_level
# The limit of backtrace lines displayed as top +n+ and tail +n+.
#
# The default value is 16.
#
# Can also be set using the +--back-trace-limit+ command line option.
#
# See IRB@Command+line+options for more command line options.
attr_accessor :back_trace_limit
# Alias for #use_readline
alias use_readline? use_readline
# Alias for #rc
alias rc? rc
alias ignore_sigint? ignore_sigint
alias ignore_eof? ignore_eof
alias echo? echo
# Returns whether messages are displayed or not.
def verbose?
if @verbose.nil?
if defined?(ReadlineInputMethod) && @io.kind_of?(ReadlineInputMethod)
@ -190,6 +229,17 @@ module IRB
@io.class == FileInputMethod
end
# Specifies the inspect mode with +opt+:
#
# +true+:: display +inspect+
# +false+:: display +to_s+
# +nil+:: inspect mode in non-math mode,
# non-inspect mode in math mode
#
# Can also be set using the +--inspect+ and +--noinspect+ command line
# options.
#
# See IRB@Command+line+options for more command line options.
def inspect_mode=(opt)
if i = INSPECTORS[opt]
@ -234,11 +284,27 @@ module IRB
end
# Sets whether or not to use the Readline extension
#
# +true+:: enables +Readline+
# +false+:: disables +Readline+
# +nil+:: intends to use +Readline+,
# except for when +inf-ruby-mode+ is active.
#
# Can also be set using the +--noreadline+ and +--readline+ command line
# options.
#
# See IRB@Command+line+options for more command line options.
def use_readline=(opt)
@use_readline = opt
print "use readline module\n" if @use_readline
end
# Sets the debug level of irb
#
# Can also be set using the +--irb_debug+ command line option.
#
# See IRB@Command+line+options for more command line options.
def debug_level=(value)
@debug_level = value
RubyLex.debug_level = value
@ -261,6 +327,7 @@ module IRB
end
alias __exit__ exit
# Exits the current session, see IRB.irb_exit
def exit(ret = 0)
IRB.irb_exit(@irb, ret)
end

View file

@ -9,7 +9,7 @@
#
#
module IRB
module IRB # :nodoc:
class Context
def home_workspace
@ -20,6 +20,13 @@ module IRB
end
end
# Changes the current workspace to given object or binding.
#
# If the optional argument is omitted, the workspace will be
# #home_workspace which is inherited from +TOPLEVEL_BINDING+ or the main
# object, <code>IRB.conf[:MAIN_CONTEXT]</code> when irb was initialized.
#
# See IRB::WorkSpace.new for more information.
def change_workspace(*_main)
if _main.empty?
@workspace = home_workspace

View file

@ -9,7 +9,7 @@
#
#
module IRB
module IRB # :nodoc:
class Context
@ -29,7 +29,17 @@ module IRB
@last_value
end
# The command result history limit.
attr_reader :eval_history
# Sets command result history limit.
#
# +no+ is an Integer or +nil+.
#
# Returns +no+ of history items if greater than 0.
#
# If +no+ is 0, the number of history items is unlimited.
#
# If +no+ is +nil+, execution result history isn't used (default).
def eval_history=(no)
if no
if defined?(@eval_history) && @eval_history

View file

@ -10,7 +10,8 @@
#
module IRB
module IRB # :nodoc:
# Raised in the event of an exception in a file loaded from an Irb session
class LoadAbort < Exception;end
module IrbLoader

View file

@ -12,9 +12,20 @@ require "mathn"
module IRB
class Context
# Returns whether bc mode is enabled.
#
# See #math_mode=
attr_reader :math_mode
# Alias for #math_mode
alias math? math_mode
# Sets bc mode, which loads +lib/mathn.rb+ so fractions or matrix are
# available.
#
# Also available as the +-m+ command line option.
#
# See IRB@Command+line+options and the unix manpage <code>bc(1)</code> for
# more information.
def math_mode=(opt)
if @math_mode == true && opt == false
IRB.fail CantReturnToNormalMode

View file

@ -143,7 +143,10 @@ module IRB
IRB.JobManager.irb(Thread.current).context
end
# invoke multi-irb
# 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
def IRB.irb(file = nil, *main)
workspace = WorkSpace.new(*main)
parent_thread = Thread.current

View file

@ -18,6 +18,7 @@ class Object
end
module IRB
# :stopdoc:
module ExtendCommandBundle
def irb_load(*opts, &b)
ExtendCommand::Load.execute(irb_context, *opts, &b)
@ -26,17 +27,25 @@ module IRB
ExtendCommand::Require.execute(irb_context, *opts, &b)
end
end
# :startdoc:
class Context
IRB.conf[:USE_LOADER] = false
# Returns whether +irb+'s own file reader method is used by
# +load+/+require+ or not.
#
# This mode is globally affected (irb-wide).
def use_loader
IRB.conf[:USE_LOADER]
end
alias use_loader? use_loader
# Sets IRB.conf[:USE_LOADER]
#
# See #use_loader for more information.
def use_loader=(opt)
if IRB.conf[:USE_LOADER] != opt

View file

@ -9,13 +9,14 @@
#
#
module IRB
module IRB # :nodoc:
class Context
def irb_level
workspace_stack.size
end
# Workspaces in the current stack
def workspaces
if defined? @workspaces
@workspaces
@ -24,6 +25,11 @@ module IRB
end
end
# Creates a new workspace with the given object or binding, and appends it
# onto the current #workspaces stack.
#
# See IRB::Context#change_workspace and IRB::WorkSpace.new for more
# information.
def push_workspace(*_main)
if _main.empty?
if workspaces.empty?
@ -43,6 +49,10 @@ module IRB
end
end
# Removes the last element from the current #workspaces stack and returns
# it, or +nil+ if the current workspace stack is empty.
#
# Also, see #push_workspace.
def pop_workspace
if workspaces.empty?
print "workspace stack empty\n"

View file

@ -8,7 +8,7 @@
#
#
#
module IRB
module IRB # :nodoc:
#
# IRB extended command
#
@ -23,6 +23,9 @@ module IRB
irb_context.exit(ret)
end
# Displays current configuration.
#
# Modifing the configuration is achieved by sending a message to IRB.conf.
def irb_context
IRB.CurrentContext
end

View file

@ -9,7 +9,7 @@
#
#
module IRB
module IRB # :nodoc:
# initialize config
def IRB.setup(ap_path)

View file

@ -10,7 +10,7 @@
#
#
module IRB
module IRB # :nodoc:
def IRB::Inspector(inspect, init = nil)
Inspector.new(inspect, init)

View file

@ -10,6 +10,7 @@
#
require "e2mmap"
# :stopdoc:
module IRB
# exceptions
@ -26,4 +27,4 @@ module IRB
def_exception :UndefinedPromptMode, "Undefined prompt mode(%s)."
end
# :startdoc:

View file

@ -1,3 +1,4 @@
# :stopdoc:
module IRB
class Locale
@@legacy_encoding_alias_map = {
@ -6,3 +7,4 @@ module IRB
}.freeze
end
end
# :startdoc:

View file

@ -10,6 +10,7 @@
#
require "e2mmap"
# :stopdoc:
module IRB
# exceptions
extend Exception2MessageMapper
@ -24,4 +25,5 @@ module IRB
def_exception :CantChangeBinding, 'バインディング(%s)に変更できません.'
def_exception :UndefinedPromptMode, 'プロンプトモード(%s)は定義されていません.'
end
# :startdoc:
# vim:fileencoding=utf-8

View file

@ -8,7 +8,7 @@
#
#
#
module IRB
module IRB # :nodoc:
class Locale
@RCS_ID='-$Id$-'

View file

@ -13,6 +13,7 @@ require "e2mmap"
require "irb/slex"
require "irb/ruby-token"
# :stopdoc:
class RubyLex
@RCS_ID='-$Id$-'
@ -1185,3 +1186,4 @@ class RubyLex
end
end
end
# :startdoc:

View file

@ -8,6 +8,7 @@
#
#
#
# :stopdoc:
module RubyToken
EXPR_BEG = :EXPR_BEG
EXPR_MID = :EXPR_MID
@ -263,3 +264,4 @@ module RubyToken
def_token(*defs)
end
end
# :startdoc:

View file

@ -12,6 +12,7 @@
require "e2mmap"
require "irb/notifier"
# :stopdoc:
module IRB
class SLex
@RCS_ID='-$Id$-'
@ -243,6 +244,7 @@ module IRB
end
end
end
# :startdoc:
if $0 == __FILE__
# Tracer.on

View file

@ -9,7 +9,7 @@
#
#
module IRB
module IRB # :nodoc:
@RELEASE_VERSION = "0.9.6"
@LAST_UPDATE_DATE = "09/06/30"
end

View file

@ -8,9 +8,11 @@
#
#
#
module IRB
module IRB # :nodoc:
class WorkSpace
# create new workspace. set self to main if specified, otherwise
# Creates a new workspace.
#
# set self to main if specified, otherwise
# inherit main from TOPLEVEL_BINDING.
def initialize(*main)
if main[0].kind_of?(Binding)