Home

Pry Stack explorer

Quick Menu:

• Overview
• The show-stack command
• The up command
• The down command
• The frame command

Overview

pry-stack_explorer is a plugin for the Pry REPL that enables navigation of the call-stack. From the point a Pry session is started, the user can move up the stack through parent frames, examine state, and even evaluate code.

Back to the top

The show-stack command

The show-stack command is used to display the current backtrace. Unlike the normal Ruby caller method, it only displays those frames that are accessible to Pry -- so frames for C functions are skipped. show-stack also displays more information about each frame, including the frame type, and the class-name.

The following options are supported:

• Use the -v option to include extra information such as the file and line associated with the frame.
• Use the -H option to display the first N stack frames (defaults to 10).
• Use the -T option to display the last N stack frames (defaults to 10).
• Use the -c option to display N frames either side of current frame (default to 5).

Example: Using -c switch to display 1 frame either side of current

[9] (pry) main: 0> show-stack -c 1

Showing all accessible frames in stack (6 in total):
--
   #2 [method]  parse_options <Pry::CLI.parse_options(args=?)>
=> #3 [top]     <top (required)> 
   #4 [eval]    <main> 

Back to the top

The up command

This command moves up to the parent frame. It also accepts optional numeric parameter for how many frames to move up.

Alternatively accepts a string (regex) instead of numeric; for jumping to nearest parent method frame which matches the regex.

Example: Moving up 2 frames

[11] (pry) main: 0> up 2

Frame number: 2/5
Frame type: method

From: /Users/john/.rvm/gems/ruby-1.9.3-p0/gems/pry-0.9.8.2/lib/pry/cli.rb @ line 59 in Pry::CLI.parse_options:

    54: 
    55:       def parse_options(args=ARGV.dup)
    56:         raise NoOptionsError, "No command line options defined! Use Pry::CLI.add_options to add command line options." if !options
    57: 
    58:         opts = Slop.parse(args, :help => true, :multiple_switches => false, &options)
 => 59:         option_processors.each { |processor| processor.call(opts) } if option_processors # option processors are optional
    60: 
    61:         self
    62:       end
    63: 
    64:     end

[12] (pry) Pry::CLI: 0> 

Example: Jump to first parent frame that matches ph regex

[12] (pry) main: 0> up ph

Frame number: 2/4
Frame type: method

From: /Users/john/ruby/projects/pry-exception_explorer/examples/example_inline.rb @ line 13 in Object#alpha:

     8: PryExceptionExplorer.enabled = true
     9: PryExceptionExplorer.intercept(ArgumentError)
    10: 
    11: def alpha
    12:   name = "john"
 => 13:   beta
    14:   puts name
    15: end
    16: 
    17: def beta
    18:   x = "john"

[13] (pry) main: 0> 

Back to the top

The down command

This command moves down to the callee frame. It also accepts optional numeric parameter for how many frames to move down.

Alternatively accepts a string (regex) instead of numeric; for jumping to nearest child method frame which matches the regex.

Example: Moving down 1 frame

[3] (pry) main: 0> down

Frame number: 0/14
Frame type: method

From: (pry) @ line 5 in Object#beta:

    1: def alpha
    2:   beta
    3: end
    4: def beta
 => 5:   binding.pry
    6: end

[4] (pry) main: 0> 

Example: Jump to first child frame that matches ga regex

[10] (pry) main: 0> down ga

Frame number: 0/4
Frame type: method

From: /Users/john/ruby/projects/pry-exception_explorer/examples/example_inline.rb @ line 23 in Object#gamma:

    18:   x = "john"
    19:   gamma(x)
    20: end
    21: 
    22: def gamma(x)
 => 23:   raise ArgumentError, "x must be a number!" if !x.is_a?(Numeric)
    24:   puts "2 * x = #{2 * x}"
    25: end
    26: 
    27: alpha

[11] (pry) main: 0> 

Back to the top

The frame command

This command switches to a particular frame. It accepts either a numeric parameter for the frame (as numbered by the show-stack command) or a regex of the method name to move to.

• In the case of a regex argument it only moves to the nearest parent frame whose method matches that regex.
• In the case of numeric parameters, negative numbers are also accepted (with -1 being the last frame).
• When no parameter is given, information about the current frame is displayed.

Example: Jump to nearest frame whose method name matches the text al

[7] (pry) main: 0> frame al

Frame number: 1/14
Frame type: method

From: (pry) @ line 2 in Object#alpha:

    1: def alpha
 => 2:   beta
    3: end
    4: def beta
    5:   binding.pry
    6: end
    7: shows-stack

[8] (pry) main: 0> 

Example: Show information about the current frame

10] (pry) #<Pry>: 0> frame
#3 [method]  re <Pry#re(target=?)>
      in #<Pry> @ /Users/john/.rvm/gems/ruby-1.9.3-p0/gems/pry-0.9.8.2/lib/pry/pry_instance.rb:245
[11] (pry) #<Pry>: 0> 

Back to the top