IEx.pry

You're seeing just the macro pry, go back to IEx module for more information.

Pries into the process environment.

This is useful for debugging a particular chunk of code when executed by a particular process. The process becomes the evaluator of IEx commands and is temporarily changed to have a custom group leader. Those values are reverted by calling IEx.Helpers.respawn/0, which starts a new IEx shell, freeing up the pried one.

When a process is pried, all code runs inside IEx and has access to all imports and aliases from the original code. However, the code is evaluated and therefore cannot access private functions of the module being pried. Module functions still need to be accessed via Mod.fun(args).

Alternatively, you can use IEx.break!/4 to setup a breakpoint on a given module, function and arity you have no control of. While IEx.break!/4 is more flexible, it does not contain information about imports and aliases from the source code.

Examples

Let's suppose you want to investigate what is happening with some particular function. By invoking IEx.pry/0 from the function, IEx will allow you to access its binding (variables), verify its lexical information and access the process information. Let's see an example:

import Enum, only: [map: 2]

defmodule Adder do
  def add(a, b) do
    c = a + b
    require IEx; IEx.pry()
  end
end

When invoking Adder.add(1, 2), you will receive a message in your shell to pry the given environment. By allowing it, the shell will be reset and you gain access to all variables and the lexical scope from above:

pry(1)> map([a, b, c], &IO.inspect(&1))
1
2
3

Keep in mind that IEx.pry/0 runs in the caller process, blocking the caller during the evaluation cycle. The caller process can be freed by calling respawn/0, which starts a new IEx evaluation cycle, letting this one go:

pry(2)> respawn()
true

Interactive Elixir - press Ctrl+C to exit (type h() ENTER for help)

Setting variables or importing modules in IEx does not affect the caller's environment. However, sending and receiving messages will change the process state.

Pry and macros

When setting up Pry inside a code defined by macros, such as:

defmacro __using__(_) do
  quote do
    def add(a, b) do
      c = a + b
      require IEx; IEx.pry()
    end
  end
end

The variables defined inside quote won't be available during prying due to the hygiene mechanism in quoted expressions. The hygiene mechanism changes the variable names in quoted expressions so they don't collide with variables defined by the users of the macros. Therefore the original names are not available.

Pry and mix test

To use IEx.pry/0 during tests, you need to run mix inside the iex command and pass the --trace to mix test to avoid running into timeouts:

iex -S mix test --trace
iex -S mix test path/to/file:line --trace