Clean up various docs for Pry::REPL
This commit is contained in:
parent
04dbded0c2
commit
7df023b890
|
@ -1 +1,3 @@
|
||||||
--markup markdown --private
|
--markup markdown
|
||||||
|
--private
|
||||||
|
--hide-void-return
|
||||||
|
|
|
@ -3,21 +3,22 @@ require 'forwardable'
|
||||||
class Pry
|
class Pry
|
||||||
class REPL
|
class REPL
|
||||||
extend Forwardable
|
extend Forwardable
|
||||||
|
def_delegators :@pry, :input, :output
|
||||||
|
|
||||||
|
# @return [Pry] The instance of {Pry} that the user is controlling.
|
||||||
attr_accessor :pry
|
attr_accessor :pry
|
||||||
|
|
||||||
def_delegators :pry, :input, :output
|
# Instantiate a new {Pry} instance with the given options, then start a
|
||||||
|
# {REPL} instance wrapping it.
|
||||||
# Start a new Pry::REPL wrapping a pry created with the given options.
|
# @option options See {Pry#initialize}
|
||||||
#
|
|
||||||
# @option options (see Pry#initialize)
|
|
||||||
def self.start(options)
|
def self.start(options)
|
||||||
new(Pry.new(options)).start
|
new(Pry.new(options)).start
|
||||||
end
|
end
|
||||||
|
|
||||||
# Create a new REPL.
|
# Create an instance of {REPL} wrapping the given {Pry}.
|
||||||
#
|
# @param [Pry] pry The instance of {Pry} that this {REPL} will control.
|
||||||
# @param [Pry] pry The instance of pry in which to eval code.
|
# @param [Hash] options Options for this {REPL} instance.
|
||||||
# @option options [Object] :target The target to REPL on.
|
# @option options [Object] :target The initial target of the session.
|
||||||
def initialize(pry, options = {})
|
def initialize(pry, options = {})
|
||||||
@pry = pry
|
@pry = pry
|
||||||
@indent = Pry::Indent.new
|
@indent = Pry::Indent.new
|
||||||
|
@ -27,10 +28,11 @@ class Pry
|
||||||
end
|
end
|
||||||
end
|
end
|
||||||
|
|
||||||
# Start the read-eval-print-loop.
|
# Start the read-eval-print loop.
|
||||||
#
|
# @return [Object?] If the session throws `:breakout`, return the value
|
||||||
# @return [Object] anything returned by the user from within Pry
|
# thrown with it.
|
||||||
# @raise [Exception] anything raise-up'd by the user from within Pry
|
# @raise [Exception] If the session throws `:raise_up`, raise the exception
|
||||||
|
# thrown with it.
|
||||||
def start
|
def start
|
||||||
prologue
|
prologue
|
||||||
repl
|
repl
|
||||||
|
@ -40,23 +42,27 @@ class Pry
|
||||||
|
|
||||||
private
|
private
|
||||||
|
|
||||||
# Set up the repl session
|
# Set up the repl session.
|
||||||
|
# @return [void]
|
||||||
def prologue
|
def prologue
|
||||||
pry.exec_hook :before_session, pry.output, pry.current_binding, pry
|
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
|
if Pry.config.correct_indent
|
||||||
Kernel.print Pry::Helpers::BaseHelpers.windows_ansi? ? "\e[0F" : "\e[0G"
|
Kernel.print Pry::Helpers::BaseHelpers.windows_ansi? ? "\e[0F" : "\e[0G"
|
||||||
end
|
end
|
||||||
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
|
# The {REPL} instance is responsible for reading and looping, whereas the
|
||||||
# to Pry for the evaling and printing.
|
# {Pry} instance is responsible for evaluating user input and printing
|
||||||
|
# return values and command output.
|
||||||
#
|
#
|
||||||
# @return [Object] anything returned by the user from Pry
|
# @return [Object?] If the session throws `:breakout`, return the value
|
||||||
# @raise [Exception] anything raise-up'd by the user from Pry
|
# thrown with it.
|
||||||
|
# @raise [Exception] If the session throws `:raise_up`, raise the exception
|
||||||
|
# thrown with it.
|
||||||
def repl
|
def repl
|
||||||
loop do
|
loop do
|
||||||
case val = read
|
case val = read
|
||||||
|
@ -73,17 +79,17 @@ class Pry
|
||||||
end
|
end
|
||||||
end
|
end
|
||||||
|
|
||||||
# Clean-up after the repl session.
|
# Clean up after the repl session.
|
||||||
|
# @return [void]
|
||||||
def epilogue
|
def epilogue
|
||||||
pry.exec_hook :after_session, pry.output, pry.current_binding, pry
|
pry.exec_hook :after_session, pry.output, pry.current_binding, pry
|
||||||
end
|
end
|
||||||
|
|
||||||
# Read a line of input from the user, special handling for:
|
# Read a line of input from the user.
|
||||||
#
|
# @return [String] The line entered by the user.
|
||||||
# @return [nil] on <ctrl+d>
|
# @return [nil] On `<Ctrl-D>`.
|
||||||
# @return [:control_c] on <ctrl+c>
|
# @return [:control_c] On `<Ctrl+C>`.
|
||||||
# @return [:no_more_input] on EOF from Pry.input
|
# @return [:no_more_input] On EOF.
|
||||||
# @return [String] The line from the user
|
|
||||||
def read
|
def read
|
||||||
@indent.reset if pry.eval_string.empty?
|
@indent.reset if pry.eval_string.empty?
|
||||||
|
|
||||||
|
@ -122,19 +128,20 @@ class Pry
|
||||||
indented_val
|
indented_val
|
||||||
end
|
end
|
||||||
|
|
||||||
# Manage switching of input objects on encountering EOFErrors
|
# Manage switching of input objects on encountering `EOFError`s.
|
||||||
#
|
# @return [Object] Whatever the given block returns.
|
||||||
# @return [:no_more_input] if no more input can be read.
|
# @return [:no_more_input] Indicates that no more input can be read.
|
||||||
# @return [String?]
|
|
||||||
def handle_read_errors
|
def handle_read_errors
|
||||||
should_retry = true
|
should_retry = true
|
||||||
exception_count = 0
|
exception_count = 0
|
||||||
|
|
||||||
begin
|
begin
|
||||||
yield
|
yield
|
||||||
rescue EOFError
|
rescue EOFError
|
||||||
pry.input = Pry.config.input
|
pry.input = Pry.config.input
|
||||||
if !should_retry
|
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
|
return :no_more_input
|
||||||
end
|
end
|
||||||
should_retry = false
|
should_retry = false
|
||||||
|
@ -143,9 +150,9 @@ class Pry
|
||||||
rescue Interrupt
|
rescue Interrupt
|
||||||
raise
|
raise
|
||||||
|
|
||||||
# If we get a random error when trying to read a line we don't want to automatically
|
# If we get a random error when trying to read a line we don't want to
|
||||||
# retry, as the user will see a lot of error messages scroll past and be unable to do
|
# automatically retry, as the user will see a lot of error messages
|
||||||
# anything about it.
|
# scroll past and be unable to do anything about it.
|
||||||
rescue RescuableException => e
|
rescue RescuableException => e
|
||||||
puts "Error: #{e.message}"
|
puts "Error: #{e.message}"
|
||||||
output.puts e.backtrace
|
output.puts e.backtrace
|
||||||
|
@ -154,7 +161,8 @@ class Pry
|
||||||
retry
|
retry
|
||||||
end
|
end
|
||||||
puts "FATAL: Pry failed to get user input using `#{input}`."
|
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.input = STDIN"
|
||||||
puts " Pry.config.output = STDOUT"
|
puts " Pry.config.output = STDOUT"
|
||||||
puts " binding.pry"
|
puts " binding.pry"
|
||||||
|
@ -162,9 +170,9 @@ class Pry
|
||||||
end
|
end
|
||||||
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.
|
# @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)
|
def read_line(current_prompt)
|
||||||
handle_read_errors do
|
handle_read_errors do
|
||||||
if defined? Coolline and input.is_a? Coolline
|
if defined? Coolline and input.is_a? Coolline
|
||||||
|
|
Loading…
Reference in New Issue