From 4fe06f46675801c5be392551813baabadf43c87c Mon Sep 17 00:00:00 2001
From: zverok <zverok.offline@gmail.com>
Date: Sat, 26 Oct 2019 11:04:24 +0300
Subject: IRB: Document command evaluation history.

---
 lib/irb.rb             | 14 +++++++++++--
 lib/irb/ext/history.rb | 53 ++++++++++++++++++++++++++++++++++++++++++--------
 2 files changed, 57 insertions(+), 10 deletions(-)

(limited to 'lib')

diff --git a/lib/irb.rb b/lib/irb.rb
index 6efb6c0e69..e95927f8ec 100644
--- a/lib/irb.rb
+++ b/lib/irb.rb
@@ -124,7 +124,7 @@ require "irb/version"
 # === History
 #
 # By default, irb will store the last 1000 commands you used in
-# <code>~/.irb_history</code>.
+# <code>IRB.conf[:HISTORY_FILE]</code> (<code>~/.irb_history</code> by default).
 #
 # If you want to disable history, add the following to your +.irbrc+:
 #
@@ -132,6 +132,14 @@ require "irb/version"
 #
 # See IRB::Context#save_history= for more information.
 #
+# The history of _resuls_ of commands evaluated is not stored by default,
+# but can be turned on to be stored with this +.irbrc+ setting:
+#
+#     IRB.conf[:EVAL_HISTORY] = <number>
+#
+# See IRB::Context#eval_history= and History class. The history of command
+# results is not permanently saved in any file.
+#
 # == Customizing the IRB Prompt
 #
 # In order to customize the prompt, you can change the following Hash:
@@ -274,7 +282,9 @@ require "irb/version"
 # <code>_</code>::
 #   The value command executed, as a local variable
 # <code>__</code>::
-#   The history of evaluated commands
+#   The history of evaluated commands. Available only if
+#   <code>IRB.conf[:EVAL_HISTORY]</code> is not +nil+ (which is the default).
+#   See also IRB::Context#eval_history= and IRB::History.
 # <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
diff --git a/lib/irb/ext/history.rb b/lib/irb/ext/history.rb
index 43c3e4dbf3..30e3fb901f 100644
--- a/lib/irb/ext/history.rb
+++ b/lib/irb/ext/history.rb
@@ -31,9 +31,12 @@ module IRB # :nodoc:
     end
 
     remove_method :eval_history= if method_defined?(:eval_history=)
-    # The command result history limit.
+    # The command result history limit. This method is not available until
+    # #eval_history= was called with non-nil value (directly or via
+    # setting <code>IRB.conf[:EVAL_HISTORY]</code> in <code>.irbrc</code>).
     attr_reader :eval_history
-    # Sets command result history limit.
+    # Sets command result history limit. Default value is set from
+    # <code>IRB.conf[:EVAL_HISTORY]</code>.
     #
     # +no+ is an Integer or +nil+.
     #
@@ -42,6 +45,9 @@ module IRB # :nodoc:
     # If +no+ is 0, the number of history items is unlimited.
     #
     # If +no+ is +nil+, execution result history isn't used (default).
+    #
+    # History values are available via <code>__</code> variable, see
+    # IRB::History.
     def eval_history=(no)
       if no
         if defined?(@eval_history) && @eval_history
@@ -59,20 +65,51 @@ module IRB # :nodoc:
     end
   end
 
-  class History # :nodoc:
-
-    def initialize(size = 16)
+  # Represents history of results of previously evaluated commands.
+  #
+  # Available via <code>__</code> variable, only if <code>IRB.conf[:EVAL_HISTORY]</code>
+  # or <code>IRB::CurrentContext().eval_history</code> is non-nil integer value
+  # (by default it is +nil+).
+  #
+  # Example (in `irb`):
+  #
+  #    # Initialize history
+  #    IRB::CurrentContext().eval_history = 10
+  #    # => 10
+  #
+  #    # Perform some commands...
+  #    1 + 2
+  #    # => 3
+  #    puts 'x'
+  #    # x
+  #    # => nil
+  #    raise RuntimeError
+  #    # ...error raised
+  #
+  #    # Inspect history (format is "<item number> <evaluated value>":
+  #    __
+  #    # => 1 10
+  #    # 2 3
+  #    # 3 nil
+  #
+  #    __[1]
+  #    # => 10
+  #
+  class History
+
+    def initialize(size = 16)  # :nodoc:
       @size = size
       @contents = []
     end
 
-    def size(size)
+    def size(size) # :nodoc:
       if size != 0 && size < @size
         @contents = @contents[@size - size .. @size]
       end
       @size = size
     end
 
+    # Get one item of the content (both positive and negative indexes work).
     def [](idx)
       begin
         if idx >= 0
@@ -85,14 +122,14 @@ module IRB # :nodoc:
       end
     end
 
-    def push(no, val)
+    def push(no, val)  # :nodoc:
       @contents.push [no, val]
       @contents.shift if @size != 0 && @contents.size > @size
     end
 
     alias real_inspect inspect
 
-    def inspect
+    def inspect  # :nodoc:
       if @contents.empty?
         return real_inspect
       end
-- 
cgit v1.2.3