Add finish command

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?