@spec after_spawn() :: [(... -> any())]

Returns registered after_spawn callbacks.

@spec after_spawn((... -> any())) :: :ok

Registers a function to be invoked after the IEx process is spawned.

Macro-based shortcut for IEx.break!/4.

@spec break!(module(), atom(), arity(), non_neg_integer()) :: IEx.Pry.id()

Sets up a breakpoint in module, function and arity with the given number of stops.

This function will instrument the given module and load a new version in memory with breakpoints at the given function and arity. If the module is recompiled, all breakpoints are lost.

When a breakpoint is reached, IEx will ask if you want to pry the given function and arity. In other words, this works similar to IEx.pry/0 as the running process becomes the evaluator of IEx commands and is temporarily changed to have a custom group leader. However, differently from IEx.pry/0, aliases and imports from the source code won't be available in the shell.

IEx helpers includes many conveniences related to breakpoints. Below they are listed with the full module, such as IEx.Helpers.breaks/0, but remember it can be called directly as breaks() inside IEx. They are:

• IEx.Helpers.break!/2 - sets up a breakpoint for a given Mod.fun/arity
• IEx.Helpers.break!/4 - sets up a breakpoint for the given module, function, arity
• IEx.Helpers.breaks/0 - prints all breakpoints and their IDs
• IEx.Helpers.continue/0 - continues until the next breakpoint in the same shell
• IEx.Helpers.open/0 - opens editor on the current breakpoint
• IEx.Helpers.remove_breaks/0 - removes all breakpoints in all modules
• IEx.Helpers.remove_breaks/1 - removes all breakpoints in a given module
• IEx.Helpers.reset_break/1 - sets the number of stops on the given ID to zero
• IEx.Helpers.reset_break/3 - sets the number of stops on the given module, function, arity to zero
• IEx.Helpers.respawn/0 - starts a new shell (breakpoints will ask for permission once more)
• IEx.Helpers.whereami/1 - shows the current location

By default, the number of stops in a breakpoint is 1. Any follow-up call won't stop the code execution unless another breakpoint is set.

Alternatively, the number of stops can be increased by passing the stops argument. IEx.Helpers.reset_break/1 and IEx.Helpers.reset_break/3 can be used to reset the number back to zero. Note the module remains "instrumented" even after all stops on all breakpoints are consumed. You can remove the instrumentation in a given module by calling IEx.Helpers.remove_breaks/1 and on all modules by calling IEx.Helpers.remove_breaks/0.

To exit a breakpoint, the developer can either invoke continue(), which will block the shell until the next breakpoint is found or the process terminates, or invoke respawn(), which starts a new IEx shell, freeing up the pried one.

Examples

The examples below will use break!, assuming that you are setting a breakpoint directly from your IEx shell. But you can set up a break from anywhere by using the fully qualified name IEx.break!.

The following sets up a breakpoint on URI.decode_query/2:

break! URI, :decode_query, 2

This call will setup a breakpoint that stops once. To set a breakpoint that will stop 10 times:

break! URI, :decode_query, 2, 10

IEx.break!/2 is a convenience macro that allows breakpoints to be given in the Mod.fun/arity format:

break! URI.decode_query/2

Or to set a breakpoint that will stop 10 times:

break! URI.decode_query/2, 10

This function returns the breakpoint ID and will raise if there is an error setting up the breakpoint.

Patterns and guards

IEx.break!/2 allows patterns to be given, triggering the breakpoint only in some occasions. For example, to trigger the breakpoint only when the first argument is the "foo=bar" string:

break! URI.decode_query("foo=bar", _)

Or to trigger it whenever the second argument is a map with more than one element:

break! URI.decode_query(_, map) when map_size(map) > 0

Only a single break point can be set per function. So if you call IEx.break! multiple times with different patterns, only the last pattern is kept.

Note that, while patterns may be given to macros, remember that macros receive ASTs as arguments, and not values. For example, if you try to break on a macro with the following pattern:

break! MyModule.some_macro(pid) when pid == self()

This breakpoint will never be reached, because a macro never receives a PID. Even if you call the macro as MyModule.some_macro(self()), the macro will receive the AST representing the self() call, and not the PID itself.

Breaks and mix test

To use IEx.break!/4 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

@spec color(atom(), iodata()) :: iodata()

Returns string escaped using the specified color.

ANSI escapes in string are not processed in any way.

@spec configuration() :: keyword()

Returns IEx configuration.

@spec configure(keyword()) :: :ok

Configures IEx.

The supported options are:

• :colors
• :inspect
• :width
• :history_size
• :default_prompt
• :continuation_prompt
• :alive_prompt
• :alive_continuation_prompt
• :parser

They are discussed individually in the sections below.

Colors

A keyword list that encapsulates all color settings used by the shell. See documentation for the IO.ANSI module for the list of supported colors and attributes.

List of supported keys in the keyword list:

• :enabled - boolean value that allows for switching the coloring on and off
• :eval_result - color for an expression's resulting value
• :eval_info - ... various informational messages
• :eval_error - ... error messages
• :eval_interrupt - ... interrupt messages
• :stack_info - ... the stacktrace color
• :blame_diff - ... when blaming source with no match
• :ls_directory - ... for directory entries (ls helper)
• :ls_device - ... device entries (ls helper)

When printing documentation, IEx will convert the Markdown documentation to ANSI as well. Colors for this can be configured via:

• :doc_code - the attributes for code blocks (cyan, bright)
• :doc_inline_code - inline code (cyan)
• :doc_headings - h1 and h2 (yellow, bright)
• :doc_title - the overall heading for the output (reverse, yellow, bright)
• :doc_bold - (bright)
• :doc_underline - (underline)

IEx will also color inspected expressions using the :syntax_colors option. Such can be disabled with:

IEx.configure(colors: [syntax_colors: false])

You can also configure the syntax colors, however, as desired:

IEx.configure(colors: [syntax_colors: [atom: :red]])

Configuration for most built-in data types are supported: :atom, :string, :binary, :list, :number, :boolean, :nil, and others. The default is:

[number: :magenta, atom: :cyan, string: :green,
 boolean: :magenta, nil: :magenta]

Inspect

A keyword list containing inspect options used by the shell when printing results of expression evaluation. Default to pretty formatting with a limit of 50 entries.

To show all entries, configure the limit to :infinity:

IEx.configure(inspect: [limit: :infinity])

See Inspect.Opts for the full list of options.

Width

An integer indicating the maximum number of columns to use in output. The default value is 80 columns. The actual output width is the minimum of this number and result of :io.columns. This way you can configure IEx to be your largest screen size and it should always take up the full width of your current terminal screen.

History size

Number of expressions and their results to keep in the history. The value is an integer. When it is negative, the history is unlimited.

Prompt

This is an option determining the prompt displayed to the user when awaiting input.

The value is a keyword list with two possible keys representing prompt types:

• :default_prompt - used when Node.alive?/0 returns false

• :continuation_prompt - used when Node.alive?/0 returns false and more input is expected

• :alive_prompt - used when Node.alive?/0 returns true

• :alive_continuation_prompt - used when Node.alive?/0 returns true and more input is expected

The following values in the prompt string will be replaced appropriately:

• %counter - the index of the history
• %prefix - a prefix given by IEx.Server
• %node - the name of the local node

Parser

This is an option determining the parser to use for IEx.

The parser is a "mfargs", which is a tuple with three elements: the module name, the function name, and extra arguments to be appended. The parser receives at least three arguments, the current input as a string, the parsing options as a keyword list, and the buffer as a string. It must return {:ok, expr, buffer} or {:incomplete, buffer}.

If the parser raises, the buffer is reset to an empty string.

@spec inspect_opts() :: keyword()

Returns the options used for inspecting.

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

@spec started?() :: boolean()

Returns true if IEx was started, false otherwise.

@spec width() :: pos_integer()

Returns the IEx width for printing.

Used by helpers and it has a default maximum cap of 80 chars.