Add finish command

Author: nixme

README.md

@@ -3,8 +3,8 @@ pry-debugger
 
 _Fast execution control in Pry_
 
-Adds **step**, **next**, and **continue** commands and **breakpoints** to
-[Pry][pry] using [debugger][debugger].
+Adds **step**, **next**, **finish**, and **continue** commands and
+**breakpoints** to [Pry][pry] using [debugger][debugger].
 
 To use, invoke pry normally. No need to start your script or app differently.
 
@@ -15,9 +15,8 @@ def some_method
 end
 ```
 
-To create a fully flexible debugging environment,
-[pry-stack_explorer][pry-stack_explorer] is recommended as a companion Pry
-plugin to add call-stack frame navigation.
+For a complete debugging environment, add
+[pry-stack_explorer][pry-stack_explorer] for call-stack frame navigation.
 
 
 ## Execution Commands
@@ -28,6 +27,8 @@ argument to step multiple times.
 **next:** Step over to the next line within the same frame. Also takes an
 optional numeric argument to step multiple lines.
 
+**finish:** Execute until current stack frame returns.
+
 **continue:** Continue program execution and end the Pry session.
 
 
@@ -36,9 +37,9 @@ optional numeric argument to step multiple lines.
 You can set and adjust breakpoints directly from a Pry session using the
 following commands:
 
-**break:** Set a new breakpoint. Accepts a line number in the current file, a
-file and line number, or a method, and an optional condition. By passing various
-flags, existing breakpoints can be changed.
+**break:** Set a new breakpoint from a line number in the current file, a file
+and line number, or a method. Pass an optional expression to create a
+conditional breakpoint. Edit existing breakpoints via various flags.
 
 Examples:
 
@@ -118,6 +119,7 @@ Stepping through code often? Add the following shortcuts to `~/.pryrc`:
 Pry.commands.alias_command 'c', 'continue'
 Pry.commands.alias_command 's', 'step'
 Pry.commands.alias_command 'n', 'next'
+Pry.commands.alias_command 'f', 'finish'
 ```
 
 

lib/pry-debugger/commands.rb

@@ -25,7 +25,7 @@ def process
 
 
  create_command 'next' do
- description 'Execute the next line within the same stack frame.'
+ description 'Execute the next line within the current stack frame.'
 
  banner <<-BANNER
  Usage: next [LINES]
@@ -46,6 +46,16 @@ def process
  end
 
 
+ create_command 'finish' do
+ description 'Execute until current stack frame returns.'
+
+ def process
+ check_file_context
+ breakout_navigation :finish
+ end
+ end
+
+
  create_command 'continue' do
  description 'Continue program execution and end the Pry session.'
 
@@ -194,12 +204,12 @@ def process
 
 
  helpers do
- def breakout_navigation(action, times)
+ def breakout_navigation(action, times = nil)
  _pry_.binding_stack.clear # Clear the binding stack.
  throw :breakout_nav, { # Break out of the REPL loop and
  :action => action, # signal the tracer.
- :times => times,
- :pry => _pry_
+ :times  => times,
+ :pry  => _pry_
  }
  end
 

lib/pry-debugger/processor.rb

@@ -22,7 +22,7 @@ def run(initial = true, &block)
  times = (command[:times] || 1).to_i # Command argument
  times = 1 if times <= 0
 
- if [:step, :next].include? command[:action]
+ if [:step, :next, :finish].include? command[:action]
  @pry = command[:pry] # Pry instance to resume after stepping
  Debugger.start unless Debugger.started?
 
@@ -37,8 +37,11 @@ def run(initial = true, &block)
  elsif :next == command[:action]
  step_over times
 
- else # :step == command[:action]
+ elsif :step == command[:action]
  step times
+
+ elsif :finish == command[:action]
+ finish
  end
  else
  stop
@@ -79,6 +82,10 @@ def at_line(context, file, line)
  step @delayed[:step] - 1
  @delayed = Hash.new(0)
 
+ elsif @delayed[:finish] > 0
+ finish
+ @delayed = Hash.new(0)
+
  else # Otherwise, resume the pry session at the stopped line.
  resume_pry context
  end
@@ -126,6 +133,11 @@ def step_over(lines)
  Debugger.current_context.step_over(lines, 0)
  end
 
+ # Execute until current frame returns.
+ def finish
+ Debugger.current_context.stop_frame = 0
+ end
+
  # Cleanup when debugging is stopped and execution continues.
  def stop
  Debugger.stop if !@always_enabled && Debugger.started?