diff options
author | zzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2012-12-21 05:45:50 +0000 |
---|---|---|
committer | zzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2012-12-21 05:45:50 +0000 |
commit | 7e9eb32669348b7e0a5775c8e0fc9566be11fc31 (patch) | |
tree | 96be4fc975e7afab8dbf4c85e04d552760dab34c /lib/irb/ext | |
parent | 4f7a6aafa57bf57ce4b0b5e323548f0a6385d527 (diff) | |
download | ruby-7e9eb32669348b7e0a5775c8e0fc9566be11fc31.tar.gz |
* lib/irb.rb, lib/irb/*: Documentation for IRB
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@38515 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'lib/irb/ext')
-rw-r--r-- | lib/irb/ext/change-ws.rb | 1 | ||||
-rw-r--r-- | lib/irb/ext/history.rb | 3 | ||||
-rw-r--r-- | lib/irb/ext/loader.rb | 14 | ||||
-rw-r--r-- | lib/irb/ext/multi-irb.rb | 43 | ||||
-rw-r--r-- | lib/irb/ext/save-history.rb | 11 | ||||
-rw-r--r-- | lib/irb/ext/tracer.rb | 11 | ||||
-rw-r--r-- | lib/irb/ext/use-loader.rb | 4 | ||||
-rw-r--r-- | lib/irb/ext/workspaces.rb | 3 |
8 files changed, 80 insertions, 10 deletions
diff --git a/lib/irb/ext/change-ws.rb b/lib/irb/ext/change-ws.rb index a28754e378..ce921eb5e3 100644 --- a/lib/irb/ext/change-ws.rb +++ b/lib/irb/ext/change-ws.rb @@ -12,6 +12,7 @@ module IRB # :nodoc: class Context + # Inherited from +TOPLEVEL_BINDING+. def home_workspace if defined? @home_workspace @home_workspace diff --git a/lib/irb/ext/history.rb b/lib/irb/ext/history.rb index 4d036e7cf0..3239c57a6c 100644 --- a/lib/irb/ext/history.rb +++ b/lib/irb/ext/history.rb @@ -15,6 +15,7 @@ module IRB # :nodoc: NOPRINTING_IVARS.push "@eval_history_values" + # See #set_last_value alias _set_last_value set_last_value def set_last_value(value) @@ -57,7 +58,7 @@ module IRB # :nodoc: end end - class History + class History # :nodoc: @RCS_ID='-$Id$-' def initialize(size = 16) diff --git a/lib/irb/ext/loader.rb b/lib/irb/ext/loader.rb index 2058a2fa29..6cdc8ec898 100644 --- a/lib/irb/ext/loader.rb +++ b/lib/irb/ext/loader.rb @@ -14,12 +14,16 @@ module IRB # :nodoc: # Raised in the event of an exception in a file loaded from an Irb session class LoadAbort < Exception;end + # Provides a few commands for loading files within an irb session. + # + # See ExtendCommandBundle for more information. module IrbLoader @RCS_ID='-$Id$-' alias ruby_load load alias ruby_require require + # Loads the given file similarly to Kernel#load def irb_load(fn, priv = nil) path = search_file_from_ruby_path(fn) raise LoadError, "No such file to load -- #{fn}" unless path @@ -27,7 +31,7 @@ module IRB # :nodoc: load_file(path, priv) end - def search_file_from_ruby_path(fn) + def search_file_from_ruby_path(fn) # :nodoc: if /^#{Regexp.quote(File::Separator)}/ =~ fn return fn if File.exist?(fn) return nil @@ -41,6 +45,9 @@ module IRB # :nodoc: return nil end + # Loads a given file in the current session and displays the source lines + # + # See Irb#suspend_input_method for more information. def source_file(path) irb.suspend_name(path, File.basename(path)) do irb.suspend_input_method(FileInputMethod.new(path)) do @@ -60,6 +67,9 @@ module IRB # :nodoc: end end + # Loads the given file in the current session's context and evaluates it. + # + # See Irb#suspend_input_method for more information. def load_file(path, priv = nil) irb.suspend_name(path, File.basename(path)) do @@ -88,7 +98,7 @@ module IRB # :nodoc: end end - def old + def old # :nodoc: back_io = @io back_path = @irb_path back_name = @irb_name diff --git a/lib/irb/ext/multi-irb.rb b/lib/irb/ext/multi-irb.rb index 473a4361b7..e49a158fa3 100644 --- a/lib/irb/ext/multi-irb.rb +++ b/lib/irb/ext/multi-irb.rb @@ -12,44 +12,61 @@ IRB.fail CantShiftToMultiIrbMode unless defined?(Thread) require "thread" module IRB - # job management class class JobManager @RCS_ID='-$Id$-' + # Creates a new JobManager object def initialize # @jobs = [[thread, irb],...] @jobs = [] @current_job = nil end + # The active irb session attr_accessor :current_job + # The total number of irb sessions, used to set +irb_name+ of the current + # Context. def n_jobs @jobs.size end + # Returns the thread for the given +key+ object, see #search for more + # information. def thread(key) th, = search(key) th end + # Returns the irb session for the given +key+ object, see #search for more + # information. def irb(key) _, irb = search(key) irb end + # Returns the top level thread. def main_thread @jobs[0][0] end + # Returns the top level irb session. def main_irb @jobs[0][1] end + # Add the given +irb+ session to the jobs Array. def insert(irb) @jobs.push [Thread.current, irb] end + # Changes the current active irb session to the given +key+ in the jobs + # Array. + # + # Raises an IrbAlreadyDead exception if the given +key+ is no longer alive. + # + # If the given irb session is already active, an IrbSwitchedToCurrentThread + # exception is raised. def switch(key) th, irb = search(key) IRB.fail IrbAlreadyDead unless th.alive? @@ -60,6 +77,12 @@ module IRB @current_job = irb(Thread.current) end + # Terminates the irb sessions specified by the given +keys+. + # + # Raises an IrbAlreadyDead exception if one of the given +keys+ is already + # terminated. + # + # See Thread#exit for more information. def kill(*keys) for key in keys th, _ = search(key) @@ -68,6 +91,20 @@ module IRB end end + # Returns the associated job for the given +key+. + # + # If given an Integer, it will return the +key+ index for the jobs Array. + # + # When an instance of Irb is given, it will return the irb session + # associated with +key+. + # + # If given an instance of Thread, it will return the associated thread + # +key+ using Object#=== on the jobs Array. + # + # Otherwise returns the irb session with the same top-level binding as the + # given +key+. + # + # Raises a NoSuchJob exception if no job can be found with the given +key+. def search(key) job = case key when Integer @@ -83,6 +120,7 @@ module IRB job end + # Deletes the job at the given +key+. def delete(key) case key when Integer @@ -106,6 +144,7 @@ module IRB @jobs.push assoc end + # Outputs a list of jobs, see the irb command +irb_jobs+, or +jobs+. def inspect ary = [] @jobs.each_index do @@ -135,10 +174,12 @@ module IRB @JobManager = JobManager.new + # The current JobManager in the session def IRB.JobManager @JobManager end + # The current Context in this session def IRB.CurrentContext IRB.JobManager.irb(Thread.current).context end diff --git a/lib/irb/ext/save-history.rb b/lib/irb/ext/save-history.rb index f9c983ac11..3e0740d6fa 100644 --- a/lib/irb/ext/save-history.rb +++ b/lib/irb/ext/save-history.rb @@ -11,21 +11,24 @@ require "readline" module IRB - module HistorySavingAbility + module HistorySavingAbility # :nodoc: @RCS_ID='-$Id$-' end class Context - def init_save_history + def init_save_history# :nodoc: unless (class<<@io;self;end).include?(HistorySavingAbility) @io.extend(HistorySavingAbility) end end + # A copy of the default <code>IRB.conf[:SAVE_HISTORY]</code> def save_history IRB.conf[:SAVE_HISTORY] end + # Sets <code>IRB.conf[:SAVE_HISTORY]</code> to the given +val+ and calls + # #init_save_history with this context. def save_history=(val) IRB.conf[:SAVE_HISTORY] = val if val @@ -35,16 +38,18 @@ module IRB end end + # A copy of the default <code>IRB.conf[:HISTORY_FILE]</code> def history_file IRB.conf[:HISTORY_FILE] end + # Set <code>IRB.conf[:HISTORY_FILE]</code> to the given +hist+. def history_file=(hist) IRB.conf[:HISTORY_FILE] = hist end end - module HistorySavingAbility + module HistorySavingAbility # :nodoc: include Readline # def HistorySavingAbility.create_finalizer diff --git a/lib/irb/ext/tracer.rb b/lib/irb/ext/tracer.rb index 46a9d53a2e..8c9083dbad 100644 --- a/lib/irb/ext/tracer.rb +++ b/lib/irb/ext/tracer.rb @@ -23,9 +23,16 @@ module IRB end class Context + # Whether Tracer is used when evaluating statements in this context. + # + # See +lib/tracer.rb+ for more information. attr_reader :use_tracer alias use_tracer? use_tracer + # Sets whether or not to use the Tracer library when evaluating statements + # in this context. + # + # See +lib/tracer.rb+ for more information. def use_tracer=(opt) if opt Tracer.set_get_line_procs(@irb_path) { @@ -41,6 +48,10 @@ module IRB class WorkSpace alias __evaluate__ evaluate + # Evaluate the context of this workspace and use the Tracer library to + # output the exact lines of code are being executed in chronological order. + # + # See +lib/tracer.rb+ for more information. def evaluate(context, statements, file = nil, line = nil) if context.use_tracer? && file != nil && line != nil Tracer.on diff --git a/lib/irb/ext/use-loader.rb b/lib/irb/ext/use-loader.rb index 913a64116f..4e98f5b7a2 100644 --- a/lib/irb/ext/use-loader.rb +++ b/lib/irb/ext/use-loader.rb @@ -18,16 +18,16 @@ class Object end module IRB - # :stopdoc: module ExtendCommandBundle + # Loads the given file similarly to Kernel#load, see IrbLoader#irb_load def irb_load(*opts, &b) ExtendCommand::Load.execute(irb_context, *opts, &b) end + # Loads the given file similarly to Kernel#require def irb_require(*opts, &b) ExtendCommand::Require.execute(irb_context, *opts, &b) end end - # :startdoc: class Context diff --git a/lib/irb/ext/workspaces.rb b/lib/irb/ext/workspaces.rb index 1232fee84f..641befbdf3 100644 --- a/lib/irb/ext/workspaces.rb +++ b/lib/irb/ext/workspaces.rb @@ -12,11 +12,12 @@ module IRB # :nodoc: class Context + # Size of the current WorkSpace stack def irb_level workspace_stack.size end - # Workspaces in the current stack + # WorkSpaces in the current stack def workspaces if defined? @workspaces @workspaces |