Permalink
Browse files

Clean up various docs for Pry::REPL

  • Loading branch information...
1 parent 04dbded commit 7df023b8900847547b76320abdad40d049d3140a @rf- rf- committed Dec 29, 2012
Showing with 50 additions and 40 deletions.
  1. +3 −1 .yardopts
  2. +47 −39 lib/pry/repl.rb
View
@@ -1 +1,3 @@
---markup markdown --private
+--markup markdown
+--private
+--hide-void-return
View
@@ -3,21 +3,22 @@
class Pry
class REPL
extend Forwardable
- attr_accessor :pry
+ def_delegators :@pry, :input, :output
- def_delegators :pry, :input, :output
+ # @return [Pry] The instance of {Pry} that the user is controlling.
+ attr_accessor :pry
- # Start a new Pry::REPL wrapping a pry created with the given options.
- #
- # @option options (see Pry#initialize)
+ # Instantiate a new {Pry} instance with the given options, then start a
+ # {REPL} instance wrapping it.
+ # @option options See {Pry#initialize}
def self.start(options)
new(Pry.new(options)).start
end
- # Create a new REPL.
- #
- # @param [Pry] pry The instance of pry in which to eval code.
- # @option options [Object] :target The target to REPL on.
+ # Create an instance of {REPL} wrapping the given {Pry}.
+ # @param [Pry] pry The instance of {Pry} that this {REPL} will control.
+ # @param [Hash] options Options for this {REPL} instance.
+ # @option options [Object] :target The initial target of the session.
def initialize(pry, options = {})
@pry = pry
@indent = Pry::Indent.new
@@ -27,10 +28,11 @@ def initialize(pry, options = {})
end
end
- # Start the read-eval-print-loop.
- #
- # @return [Object] anything returned by the user from within Pry
- # @raise [Exception] anything raise-up'd by the user from within Pry
+ # Start the read-eval-print loop.
+ # @return [Object?] If the session throws `:breakout`, return the value
+ # thrown with it.
+ # @raise [Exception] If the session throws `:raise_up`, raise the exception
+ # thrown with it.
def start
prologue
repl
@@ -40,23 +42,27 @@ def start
private
- # Set up the repl session
+ # Set up the repl session.
+ # @return [void]
def prologue
pry.exec_hook :before_session, pry.output, pry.current_binding, pry
- # Clear the line before starting Pry. This fixes the issue discussed here:
- # https://github.com/pry/pry/issues/566
+
+ # Clear the line before starting Pry. This fixes issue #566.
if Pry.config.correct_indent
Kernel.print Pry::Helpers::BaseHelpers.windows_ansi? ? "\e[0F" : "\e[0G"
end
end
- # The actual read-eval-print-loop.
+ # The actual read-eval-print loop.
#
- # This object is responsible for reading and looping, and it delegates
- # to Pry for the evaling and printing.
+ # The {REPL} instance is responsible for reading and looping, whereas the
+ # {Pry} instance is responsible for evaluating user input and printing
+ # return values and command output.
#
- # @return [Object] anything returned by the user from Pry
- # @raise [Exception] anything raise-up'd by the user from Pry
+ # @return [Object?] If the session throws `:breakout`, return the value
+ # thrown with it.
+ # @raise [Exception] If the session throws `:raise_up`, raise the exception
+ # thrown with it.
def repl
loop do
case val = read
@@ -73,17 +79,17 @@ def repl
end
end
- # Clean-up after the repl session.
+ # Clean up after the repl session.
+ # @return [void]
def epilogue
pry.exec_hook :after_session, pry.output, pry.current_binding, pry
end
- # Read a line of input from the user, special handling for:
- #
- # @return [nil] on <ctrl+d>
- # @return [:control_c] on <ctrl+c>
- # @return [:no_more_input] on EOF from Pry.input
- # @return [String] The line from the user
+ # Read a line of input from the user.
+ # @return [String] The line entered by the user.
+ # @return [nil] On `<Ctrl-D>`.
+ # @return [:control_c] On `<Ctrl+C>`.
+ # @return [:no_more_input] On EOF.
def read
@indent.reset if pry.eval_string.empty?
@@ -122,19 +128,20 @@ def read
indented_val
end
- # Manage switching of input objects on encountering EOFErrors
- #
- # @return [:no_more_input] if no more input can be read.
- # @return [String?]
+ # Manage switching of input objects on encountering `EOFError`s.
+ # @return [Object] Whatever the given block returns.
+ # @return [:no_more_input] Indicates that no more input can be read.
def handle_read_errors
should_retry = true
exception_count = 0
+
begin
yield
rescue EOFError
pry.input = Pry.config.input
if !should_retry
- output.puts "Error: Pry ran out of things to read from! Attempting to break out of REPL."
+ output.puts "Error: Pry ran out of things to read from! " \
+ "Attempting to break out of REPL."
return :no_more_input
end
should_retry = false
@@ -143,9 +150,9 @@ def handle_read_errors
rescue Interrupt
raise
- # If we get a random error when trying to read a line we don't want to automatically
- # retry, as the user will see a lot of error messages scroll past and be unable to do
- # anything about it.
+ # If we get a random error when trying to read a line we don't want to
+ # automatically retry, as the user will see a lot of error messages
+ # scroll past and be unable to do anything about it.
rescue RescuableException => e
puts "Error: #{e.message}"
output.puts e.backtrace
@@ -154,17 +161,18 @@ def handle_read_errors
retry
end
puts "FATAL: Pry failed to get user input using `#{input}`."
- puts "To fix this you may be able to pass input and output file descriptors to pry directly. e.g."
+ puts "To fix this you may be able to pass input and output file " \
+ "descriptors to pry directly. e.g."
puts " Pry.config.input = STDIN"
puts " Pry.config.output = STDOUT"
puts " binding.pry"
return :no_more_input
end
end
- # Returns the next line of input to be used by the pry instance.
+ # Returns the next line of input to be sent to the {Pry} instance.
# @param [String] current_prompt The prompt to use for input.
- # @return [String?] The next line of input, nil on <ctrl+d>
+ # @return [String?] The next line of input, or `nil` on <Ctrl-D>.
def read_line(current_prompt)
handle_read_errors do
if defined? Coolline and input.is_a? Coolline

0 comments on commit 7df023b

Please sign in to comment.