Home

Pry Stack explorer

### Quick Menu:

• The EE abbreviation
• The intercept method
• The skip_until and skip_while decorators
• Intercepting all exceptions
• REPL interception
• Wrapped interceptions
• Intercepting C-level exceptions

### EE shortcut

As an alternative to using the full module name PryExceptionExplorer, you can use the constant EE instead. They both refer to the same object, but the abbreviated form may make programs more concise.

### The intercept method

This method allows the user to define the situations where an exception interception occurs. This method can be invoked in two ways.

1. Block-form

The general form takes a block, the block is passed both the frame where the exception was raised, and the exception itself. The user then creates an assertion (a stack-assertion) based on these attributes. If the assertion is later satisfied by a raised exception, that exception will be intercepted.

The first parameter yielded to the block is a PryExceptionExplorer::LazyFrame instance, the second is the exception object.

The PryExceptionExplorer::LazyFrame instance supports a number of methods that expose details of the stack frame:

• self the self of the stack frame.
• method_name the method name (as a Symbol) of the frame's method (if it exists).
• klass the class of the frame's self
• prev the previous stack frame (as another instance of LazyFrame).

The assertion is known as a stack assertion as the user can assert on the state of any frame in the call-stack, selecting the precise frame they want by using the LazyFrame#prev method.

Example: Asserting that the exception must be a RuntimeError and the frame method is alpha and its caller beta:

EE.intercept do |frame, ex|
  ex.is_a?(RuntimeError) && frame.method_name == :alpha
  && frame.prev.method_name == :beta
end

2. Exception classes

In the second form, the method simply takes an exception class, or a number of exception classes. If one of these exceptions is raised, it will be intercepted.

Example: Intercept all ArgumentError and NoMethodError exceptions

EE.intercept(ArgumentError, NoMethodError)

### The `skip_until` and `skip_while` decorators

The EE.intercept method returns an instance of PryExceptionExplorer::Intercept, onto this we can optionally chain the skip, skip_until and skip_while methods. These methods determine where in the call-stack the Pry session will start.

This can be useful when an exception is raised fairly deep down in code but a session at a parent stack frame could be more useful to the user. See the Plymouth project for an interesting application of this.

Example: Start the session on nearest stack frame with the method name run

EE.intercept(ArgumentError).skip_until { |frame| frame.method_name == :run }

Runtime interception

Intercepting all exceptions

When you require pry-exception_explorer in your program it is disabled by default. Once you enable it using EE.enable! it will automatically intercept every exception that's raised, regardless of whether that exception is properly handled (rescued) in the code.

In the example below we configure EE to intercept every ArgumentError exception that's raised:

require 'pry-exception_explorer'

EE.enable!
EE.intercept(ArgumentError)