<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="ExDoc v0.19.1">
<title>IEx – IEx v1.7.2</title>
<link rel="stylesheet" href="dist/app-240d7fc7e5.css" />
<link rel="canonical" href="https://hexdocs.pm/iex/v1.7/IEx.html" />
<script src="dist/sidebar_items-6ccc90797b.js"></script>
</head>
<body data-type="modules">
<script>try { if(localStorage.getItem('night-mode')) document.body.className += ' night-mode'; } catch (e) { }</script>
<div class="main">
<button class="sidebar-button sidebar-toggle">
<span class="icon-menu" aria-hidden="true"></span>
<span class="sr-only">Toggle Sidebar</span>
</button>
<button class="sidebar-button night-mode-toggle">
<span class="icon-theme" aria-hidden="true"></span>
<span class="sr-only">Toggle Theme</span>
</button>
<section class="sidebar">
<a href="http://elixir-lang.org/docs.html" class="sidebar-projectLink">
<div class="sidebar-projectDetails">
<h1 class="sidebar-projectName">
IEx </h1>
<h2 class="sidebar-projectVersion">
v1.7.2
</h2>
</div>
<img src="assets/logo.png" alt="IEx" class="sidebar-projectImage">
</a>
<form class="sidebar-search" action="search.html">
<button type="submit" class="search-button">
<span class="icon-search" aria-hidden="true"></span>
</button>
<input name="q" type="text" id="search-list" class="search-input" placeholder="Search" aria-label="Search" autocomplete="off" />
</form>
<ul class="sidebar-listNav">
<li><a id="extras-list" href="#full-list">Pages</a></li>
<li><a id="modules-list" href="#full-list">Modules</a></li>
</ul>
<div class="gradient"></div>
<ul id="full-list" class="sidebar-fullList"></ul>
</section>
<section class="content">
<div class="content-outer">
<div id="content" class="content-inner">
<h1>
<small class="visible-xs">IEx v1.7.2</small>
IEx
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/iex/lib/iex.ex#L1" title="View Source" class="view-source" rel="help">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
</h1>
<section id="moduledoc">
<p>Elixir’s interactive shell.</p>
<p>Some of the functionalities described here will not be available
depending on your terminal. In particular, if you get a message
saying that the smart terminal could not be run, some of the
features described here won’t work.</p>
<h2 id="module-helpers" class="section-heading">
<a href="#module-helpers" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Helpers
</h2>
<p>IEx provides a bunch of helpers. They can be accessed by typing
<code class="inline">h()</code> into the shell or as a documentation for the <a href="IEx.Helpers.html"><code class="inline">IEx.Helpers</code></a> module.</p>
<h2 id="module-autocomplete" class="section-heading">
<a href="#module-autocomplete" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Autocomplete
</h2>
<p>To discover a module’s public functions or other modules, type the module name
followed by a dot, then press tab to trigger autocomplete. For example:</p>
<pre><code class="nohighlight makeup elixir"><span class="nc">Enum</span><span class="o">.</span></code></pre>
<p>A module may export functions that are not meant to be used directly: these
functions won’t be autocompleted by IEx. IEx will not autocomplete functions
annotated with <code class="inline">@doc false</code>, <code class="inline">@impl true</code>, or functions that aren’t explicitly
documented and where the function name is in the form of <code class="inline">__foo__</code>.</p>
<p>Autocomplete may not be available on some Windows shells. You may need
to pass the <code class="inline">--werl</code> flag when starting IEx, as in <code class="inline">iex --werl</code> for it
to work. <code class="inline">--werl</code> may be permanently enabled by setting the <code class="inline">IEX_WITH_WERL</code>
environment variable.</p>
<h2 id="module-shell-history" class="section-heading">
<a href="#module-shell-history" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Shell history
</h2>
<p>From Erlang/OTP 20, it is possible to get shell history by passing some
flags that enable it in the VM. This can be done on a per-need basis
when starting IEx:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">iex</span><span class="w"> </span><span class="o">--</span><span class="n">erl</span><span class="w"> </span><span class="s">"-kernel shell_history enabled"</span></code></pre>
<p>If you would rather enable it on your system as a whole, you can use
the <code class="inline">ERL_AFLAGS</code> environment variable and make sure that it is set
accordingly on your terminal/shell configuration.</p>
<p>On Linux:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">export</span><span class="w"> </span><span class="nc">ERL_AFLAGS</span><span class="o">=</span><span class="s">"-kernel shell_history enabled"</span></code></pre>
<p>On Windows:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">set</span><span class="w"> </span><span class="nc">ERL_AFLAGS</span><span class="w"> </span><span class="s">"-kernel shell_history enabled"</span></code></pre>
<h2 id="module-expressions-in-iex" class="section-heading">
<a href="#module-expressions-in-iex" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Expressions in IEx
</h2>
<p>As an interactive shell, IEx evaluates expressions. This has some
interesting consequences that are worth discussing.</p>
<p>The first one is that the code is truly evaluated and not compiled.
This means that any benchmarking done in the shell is going to have
skewed results. So never run any profiling nor benchmarks in the shell.</p>
<p>Second, IEx allows you to break an expression into many lines,
since this is common in Elixir. For example:</p>
<pre><code class="nohighlight makeup elixir"><span class="gp unselectable">iex(1)> </span><span class="s">"ab
...(1)> c"</span><span class="w">
</span><span class="s">"ab</span><span class="se">\n</span><span class="s">c"</span></code></pre>
<p>In the example above, the shell will be expecting more input until it
finds the closing quote. Sometimes it is not obvious which character
the shell is expecting, and the user may find themselves trapped in
the state of incomplete expression with no ability to terminate it other
than by exiting the shell.</p>
<p>For such cases, there is a special break-trigger (<code class="inline">#iex:break</code>) that when
encountered on a line by itself will force the shell to break out of any
pending expression and return to its normal state:</p>
<pre><code class="nohighlight makeup elixir"><span class="gp unselectable">iex(1)> </span><span class="p" data-group-id="0787644882-1">[</span><span class="s">"ab
...(1)> c"</span><span class="w">
</span><span class="gp unselectable">...(1)> </span><span class="err">"</span><span class="w">
</span><span class="gp unselectable">...(1)> </span><span class="p" data-group-id="0787644882-1">]</span><span class="w">
</span><span class="gp unselectable">...(1)> </span><span class="c1">#iex:break</span><span class="w">
</span><span class="gt">** (TokenMissingError) iex:1: incomplete expression</span></code></pre>
<h2 id="module-the-break-command" class="section-heading">
<a href="#module-the-break-command" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
The Break command
</h2>
<p>Inside IEx, hitting <code class="inline">Ctrl+C</code> will open up the <code class="inline">BREAK</code> menu. In this
menu you can quit the shell, see process and ets tables information
and much more.</p>
<h2 id="module-exiting-the-shell" class="section-heading">
<a href="#module-exiting-the-shell" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Exiting the shell
</h2>
<p>There are a few ways to quit the IEx shell:</p>
<ul>
<li>via the <code class="inline">BREAK</code> menu (available via <code class="inline">Ctrl+C</code>) by typing <code class="inline">q</code>, pressing enter
</li>
<li>by hitting <code class="inline">Ctrl+C</code>, <code class="inline">Ctrl+C</code>
</li>
<li>by hitting <code class="inline">Ctrl+\</code>
</li>
</ul>
<p>If you are connected to remote shell, it remains alive after disconnection.</p>
<h2 id="module-prying-and-breakpoints" class="section-heading">
<a href="#module-prying-and-breakpoints" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Prying and breakpoints
</h2>
<p>IEx also has the ability to set breakpoints on Elixir code and
“pry” into running processes. This allows the developer to have
an IEx session run inside a given function.</p>
<p><a href="IEx.html#pry/0"><code class="inline">IEx.pry/0</code></a> can be used when you are able to modify the source
code directly and recompile it:</p>
<pre><code class="nohighlight makeup elixir"><span class="kd">def</span><span class="w"> </span><span class="nf">my_fun</span><span class="p" data-group-id="8343700714-1">(</span><span class="n">arg1</span><span class="p">,</span><span class="w"> </span><span class="n">arg2</span><span class="p" data-group-id="8343700714-1">)</span><span class="w"> </span><span class="k" data-group-id="8343700714-2">do</span><span class="w">
</span><span class="kn">require</span><span class="w"> </span><span class="nc">IEx</span><span class="p">;</span><span class="w"> </span><span class="nc">IEx</span><span class="o">.</span><span class="n">pry</span><span class="w">
</span><span class="n">...</span><span class="w"> </span><span class="n">implementation</span><span class="w"> </span><span class="n">...</span><span class="w">
</span><span class="k" data-group-id="8343700714-2">end</span></code></pre>
<p>When the code is executed, it will ask you for permission to be
introspected.</p>
<p>Alternatively, you can use <a href="IEx.html#break!/4"><code class="inline">IEx.break!/4</code></a> to setup a breakpoint
on a given module, function and arity you have no control of.
While <a href="IEx.html#break!/4"><code class="inline">IEx.break!/4</code></a> is more flexible, it requires Erlang/OTP 20+ and
it does not contain information about imports and aliases from
the source code.</p>
<h2 id="module-the-user-switch-command" class="section-heading">
<a href="#module-the-user-switch-command" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
The User Switch command
</h2>
<p>Besides the break command, one can type <code class="inline">Ctrl+G</code> to get to the
user switch command menu. When reached, you can type <code class="inline">h</code> to
get more information.</p>
<p>In this menu, developers are able to start new shells and
alternate between them. Let’s give it a try:</p>
<pre><code class="nohighlight makeup elixir"><span class="nc">User</span><span class="w"> </span><span class="n">switch</span><span class="w"> </span><span class="n">command</span><span class="w">
</span><span class="o">--</span><span class="o">></span><span class="w"> </span><span class="n">s</span><span class="w"> </span><span class="sc">'Elixir.IEx'</span><span class="w">
</span><span class="o">--</span><span class="o">></span><span class="w"> </span><span class="n">c</span></code></pre>
<p>The command above will start a new shell and connect to it.
Create a new variable called <code class="inline">hello</code> and assign some value to it:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">hello</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="ss">:world</span></code></pre>
<p>Now, let’s roll back to the first shell:</p>
<pre><code class="nohighlight makeup elixir"><span class="nc">User</span><span class="w"> </span><span class="n">switch</span><span class="w"> </span><span class="n">command</span><span class="w">
</span><span class="o">--</span><span class="o">></span><span class="w"> </span><span class="n">c</span><span class="w"> </span><span class="mi">1</span></code></pre>
<p>Now, try to access the <code class="inline">hello</code> variable again:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">hello</span><span class="w">
</span><span class="gt">** (UndefinedFunctionError) undefined function hello/0</span></code></pre>
<p>The command above fails because we have switched shells.
Since shells are isolated from each other, you can’t access the
variables defined in one shell from the other one.</p>
<p>The User Switch command can also be used to terminate an existing
session, for example when the evaluator gets stuck in an infinite
loop or when you are stuck typing an expression:</p>
<pre><code class="nohighlight makeup elixir"><span class="nc">User</span><span class="w"> </span><span class="n">switch</span><span class="w"> </span><span class="n">command</span><span class="w">
</span><span class="o">--</span><span class="o">></span><span class="w"> </span><span class="n">i</span><span class="w">
</span><span class="o">--</span><span class="o">></span><span class="w"> </span><span class="n">c</span></code></pre>
<p>The user switch command menu also allows developers to connect to
remote shells using the <code class="inline">r</code> command. A topic which we will discuss next.</p>
<h2 id="module-remote-shells" class="section-heading">
<a href="#module-remote-shells" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Remote shells
</h2>
<p>IEx allows you to connect to another node in two fashions.
First of all, we can only connect to a shell if we give names
both to the current shell and the shell we want to connect to.</p>
<p>Let’s give it a try. First start a new shell:</p>
<pre><code class="nohighlight makeup elixir"><span class="err">$</span><span class="w"> </span><span class="n">iex</span><span class="w"> </span><span class="o">--</span><span class="n">sname</span><span class="w"> </span><span class="n">foo</span><span class="w">
</span><span class="n">iex</span><span class="p" data-group-id="7062298963-1">(</span><span class="n">foo</span><span class="err">@</span><span class="nc">HOST</span><span class="p" data-group-id="7062298963-1">)</span><span class="mi">1</span><span class="o">></span></code></pre>
<p>The string between the parentheses in the prompt is the name
of your node. We can retrieve it by calling the <a href="https://hexdocs.pm/elixir/Kernel.html#node/0"><code class="inline">node/0</code></a>
function:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">iex</span><span class="p" data-group-id="7023599246-1">(</span><span class="n">foo</span><span class="err">@</span><span class="nc">HOST</span><span class="p" data-group-id="7023599246-1">)</span><span class="mi">1</span><span class="o">></span><span class="w"> </span><span class="n">node</span><span class="p" data-group-id="7023599246-2">(</span><span class="p" data-group-id="7023599246-2">)</span><span class="w">
</span><span class="ss">:"foo@HOST"</span><span class="w">
</span><span class="n">iex</span><span class="p" data-group-id="7023599246-3">(</span><span class="n">foo</span><span class="err">@</span><span class="nc">HOST</span><span class="p" data-group-id="7023599246-3">)</span><span class="mi">2</span><span class="o">></span><span class="w"> </span><span class="nc">Node</span><span class="o">.</span><span class="n">alive?</span><span class="p" data-group-id="7023599246-4">(</span><span class="p" data-group-id="7023599246-4">)</span><span class="w">
</span><span class="no">true</span></code></pre>
<p>For fun, let’s define a simple module in this shell too:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">iex</span><span class="p" data-group-id="3583317895-1">(</span><span class="n">foo</span><span class="err">@</span><span class="nc">HOST</span><span class="p" data-group-id="3583317895-1">)</span><span class="mi">3</span><span class="o">></span><span class="w"> </span><span class="kd">defmodule</span><span class="w"> </span><span class="nc">Hello</span><span class="w"> </span><span class="k" data-group-id="3583317895-2">do</span><span class="w">
</span><span class="n">...</span><span class="p" data-group-id="3583317895-3">(</span><span class="n">foo</span><span class="err">@</span><span class="nc">HOST</span><span class="p" data-group-id="3583317895-3">)</span><span class="mi">3</span><span class="o">></span><span class="w"> </span><span class="kd">def</span><span class="w"> </span><span class="nf">world</span><span class="p">,</span><span class="w"> </span><span class="ss">do</span><span class="p">:</span><span class="w"> </span><span class="s">"it works!"</span><span class="w">
</span><span class="n">...</span><span class="p" data-group-id="3583317895-4">(</span><span class="n">foo</span><span class="err">@</span><span class="nc">HOST</span><span class="p" data-group-id="3583317895-4">)</span><span class="mi">3</span><span class="o">></span><span class="w"> </span><span class="k" data-group-id="3583317895-2">end</span></code></pre>
<p>Now, let’s start another shell, giving it a name as well:</p>
<pre><code class="nohighlight makeup elixir"><span class="err">$</span><span class="w"> </span><span class="n">iex</span><span class="w"> </span><span class="o">--</span><span class="n">sname</span><span class="w"> </span><span class="n">bar</span><span class="w">
</span><span class="n">iex</span><span class="p" data-group-id="5356366148-1">(</span><span class="n">bar</span><span class="err">@</span><span class="nc">HOST</span><span class="p" data-group-id="5356366148-1">)</span><span class="mi">1</span><span class="o">></span></code></pre>
<p>If we try to dispatch to <code class="inline">Hello.world</code>, it won’t be available
as it was defined only in the other shell:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">iex</span><span class="p" data-group-id="1362890608-1">(</span><span class="n">bar</span><span class="err">@</span><span class="nc">HOST</span><span class="p" data-group-id="1362890608-1">)</span><span class="mi">1</span><span class="o">></span><span class="w"> </span><span class="nc">Hello</span><span class="o">.</span><span class="n">world</span><span class="w">
</span><span class="gt">** (UndefinedFunctionError) undefined function Hello.world/0</span></code></pre>
<p>However, we can connect to the other shell remotely. Open up
the User Switch prompt (Ctrl+G) and type:</p>
<pre><code class="nohighlight makeup elixir"><span class="nc">User</span><span class="w"> </span><span class="n">switch</span><span class="w"> </span><span class="n">command</span><span class="w">
</span><span class="o">--</span><span class="o">></span><span class="w"> </span><span class="n">r</span><span class="w"> </span><span class="sc">'foo@HOST'</span><span class="w"> </span><span class="sc">'Elixir.IEx'</span><span class="w">
</span><span class="o">--</span><span class="o">></span><span class="w"> </span><span class="n">c</span></code></pre>
<p>Now we are connected into the remote node, as the prompt shows us,
and we can access the information and modules defined over there:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">rem</span><span class="p" data-group-id="2820254334-1">(</span><span class="n">foo</span><span class="na">@macbook</span><span class="p" data-group-id="2820254334-1">)</span><span class="mi">1</span><span class="o">></span><span class="w"> </span><span class="nc">Hello</span><span class="o">.</span><span class="n">world</span><span class="w">
</span><span class="s">"it works"</span></code></pre>
<p>In fact, connecting to remote shells is so common that we provide
a shortcut via the command line as well:</p>
<pre><code class="nohighlight makeup elixir"><span class="err">$</span><span class="w"> </span><span class="n">iex</span><span class="w"> </span><span class="o">--</span><span class="n">sname</span><span class="w"> </span><span class="n">baz</span><span class="w"> </span><span class="o">--</span><span class="n">remsh</span><span class="w"> </span><span class="n">foo</span><span class="err">@</span><span class="nc">HOST</span></code></pre>
<p>Where “remsh” means “remote shell”. In general, Elixir supports:</p>
<ul>
<li>remsh from an Elixir node to an Elixir node
</li>
<li>remsh from a plain Erlang node to an Elixir node (through the ^G menu)
</li>
<li>remsh from an Elixir node to a plain Erlang node (and get an <code class="inline">erl</code> shell there)
</li>
</ul>
<p>Connecting an Elixir shell to a remote node without Elixir is
<strong>not</strong> supported.</p>
<h2 id="module-the-iex-exs-file" class="section-heading">
<a href="#module-the-iex-exs-file" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
The .iex.exs file
</h2>
<p>When starting, IEx looks for a local <code class="inline">.iex.exs</code> file (located in the current
working directory), then a global one (located at <code class="inline">~/.iex.exs</code>) and loads the
first one it finds (if any). The code in the loaded <code class="inline">.iex.exs</code> file is
evaluated in the shell’s context. So, for instance, any modules that are
loaded or variables that are bound in the <code class="inline">.iex.exs</code> file will be available in the
shell after it has booted.</p>
<p>For example, take the following <code class="inline">.iex.exs</code> file:</p>
<pre><code class="nohighlight makeup elixir"><span class="c1"># Load another ".iex.exs" file</span><span class="w">
</span><span class="n">import_file</span><span class="w"> </span><span class="s">"~/.iex.exs"</span><span class="w">
</span><span class="c1"># Import some module from lib that may not yet have been defined</span><span class="w">
</span><span class="n">import_if_available</span><span class="w"> </span><span class="nc">MyApp.Mod</span><span class="w">
</span><span class="c1"># Print something before the shell starts</span><span class="w">
</span><span class="nc">IO</span><span class="o">.</span><span class="n">puts</span><span class="w"> </span><span class="s">"hello world"</span><span class="w">
</span><span class="c1"># Bind a variable that'll be accessible in the shell</span><span class="w">
</span><span class="n">value</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">13</span></code></pre>
<p>Running IEx in the directory where the above <code class="inline">.iex.exs</code> file is located
results in:</p>
<pre><code class="nohighlight makeup elixir"><span class="err">$</span><span class="w"> </span><span class="n">iex</span><span class="w">
</span><span class="nc">Erlang</span><span class="w"> </span><span class="mi">19</span><span class="w"> </span><span class="p" data-group-id="5505831382-1">[</span><span class="n">...</span><span class="p" data-group-id="5505831382-1">]</span><span class="w">
</span><span class="n">hello</span><span class="w"> </span><span class="n">world</span><span class="w">
</span><span class="nc">Interactive</span><span class="w"> </span><span class="nc">Elixir</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="n">press</span><span class="w"> </span><span class="nc">Ctrl</span><span class="o">+</span><span class="nc">C</span><span class="w"> </span><span class="n">to</span><span class="w"> </span><span class="n">exit</span><span class="w"> </span><span class="p" data-group-id="5505831382-2">(</span><span class="n">type</span><span class="w"> </span><span class="n">h</span><span class="p" data-group-id="5505831382-3">(</span><span class="p" data-group-id="5505831382-3">)</span><span class="w"> </span><span class="nc">ENTER</span><span class="w"> </span><span class="k">for</span><span class="w"> </span><span class="n">help</span><span class="p" data-group-id="5505831382-2">)</span><span class="w">
</span><span class="gp unselectable">iex(1)> </span><span class="n">value</span><span class="w">
</span><span class="mi">13</span></code></pre>
<p>It is possible to load another file by supplying the <code class="inline">--dot-iex</code>
option to IEx. See <code class="inline">iex --help</code>.</p>
<h2 id="module-configuring-the-shell" class="section-heading">
<a href="#module-configuring-the-shell" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Configuring the shell
</h2>
<p>There are a number of customization options provided by IEx. Take a look
at the docs for the <a href="IEx.html#configure/1"><code class="inline">IEx.configure/1</code></a> function by typing <code class="inline">h IEx.configure/1</code>.</p>
<p>Those options can be configured in your project configuration file or globally
by calling <a href="IEx.html#configure/1"><code class="inline">IEx.configure/1</code></a> from your <code class="inline">~/.iex.exs</code> file. For example:</p>
<pre><code class="nohighlight makeup elixir"><span class="c1"># .iex.exs</span><span class="w">
</span><span class="nc">IEx</span><span class="o">.</span><span class="n">configure</span><span class="p" data-group-id="2455481067-1">(</span><span class="ss">inspect</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="2455481067-2">[</span><span class="ss">limit</span><span class="p">:</span><span class="w"> </span><span class="mi">3</span><span class="p" data-group-id="2455481067-2">]</span><span class="p" data-group-id="2455481067-1">)</span></code></pre>
<p>Now run the shell:</p>
<pre><code class="nohighlight makeup elixir"><span class="err">$</span><span class="w"> </span><span class="n">iex</span><span class="w">
</span><span class="nc">Erlang</span><span class="w"> </span><span class="mi">19</span><span class="w"> </span><span class="p" data-group-id="8808166619-1">[</span><span class="n">...</span><span class="p" data-group-id="8808166619-1">]</span><span class="w">
</span><span class="nc">Interactive</span><span class="w"> </span><span class="nc">Elixir</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="n">press</span><span class="w"> </span><span class="nc">Ctrl</span><span class="o">+</span><span class="nc">C</span><span class="w"> </span><span class="n">to</span><span class="w"> </span><span class="n">exit</span><span class="w"> </span><span class="p" data-group-id="8808166619-2">(</span><span class="n">type</span><span class="w"> </span><span class="n">h</span><span class="p" data-group-id="8808166619-3">(</span><span class="p" data-group-id="8808166619-3">)</span><span class="w"> </span><span class="nc">ENTER</span><span class="w"> </span><span class="k">for</span><span class="w"> </span><span class="n">help</span><span class="p" data-group-id="8808166619-2">)</span><span class="w">
</span><span class="gp unselectable">iex(1)> </span><span class="p" data-group-id="8808166619-4">[</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="mi">4</span><span class="p">,</span><span class="w"> </span><span class="mi">5</span><span class="p" data-group-id="8808166619-4">]</span><span class="w">
</span><span class="p" data-group-id="8808166619-5">[</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="n">...</span><span class="p" data-group-id="8808166619-5">]</span></code></pre>
</section>
<section id="summary" class="details-list">
<h1 class="section-heading">
<a class="hover-link" href="#summary">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this section</span>
</a>
Summary
</h1>
<div class="summary-functions summary">
<h2>
<a href="#functions">Functions</a>
</h2>
<div class="summary-row">
<div class="summary-signature">
<a href="#after_spawn/0">after_spawn()</a>
</div>
<div class="summary-synopsis"><p>Returns registered <code class="inline">after_spawn</code> callbacks</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#after_spawn/1">after_spawn(fun)</a>
</div>
<div class="summary-synopsis"><p>Registers a function to be invoked after the IEx process is spawned</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#break!/2">break!(ast, stops \\ 1)</a>
</div>
<div class="summary-synopsis"><p>Macro-based shortcut for <a href="IEx.html#break!/4"><code class="inline">IEx.break!/4</code></a></p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#break!/4">break!(module, function, arity, stops \\ 1)</a>
</div>
<div class="summary-synopsis"><p>Sets up a breakpoint in <code class="inline">module</code>, <code class="inline">function</code> and <code class="inline">arity</code> with
the given number of <code class="inline">stops</code></p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#color/2">color(color, string)</a>
</div>
<div class="summary-synopsis"><p>Returns <code class="inline">string</code> escaped using the specified <code class="inline">color</code></p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#configuration/0">configuration()</a>
</div>
<div class="summary-synopsis"><p>Returns IEx configuration</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#configure/1">configure(options)</a>
</div>
<div class="summary-synopsis"><p>Configures IEx</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#inspect_opts/0">inspect_opts()</a>
</div>
<div class="summary-synopsis"><p>Gets the options used for inspecting</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#pry/0">pry()</a>
</div>
<div class="summary-synopsis"><p>Pries into the process environment</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#started?/0">started?()</a>
</div>
<div class="summary-synopsis"><p>Returns <code class="inline">true</code> if IEx was started</p>
</div>
</div>
<div class="summary-row">
<div class="summary-signature">
<a href="#width/0">width()</a>
</div>
<div class="summary-synopsis"><p>Gets the IEx width for printing</p>
</div>
</div>
</div>
</section>
<section id="functions" class="details-list">
<h1 class="section-heading">
<a class="hover-link" href="#functions">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this section</span>
</a>
Functions
</h1>
<div class="detail" id="after_spawn/0">
<div class="detail-header">
<a href="#after_spawn/0" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">after_spawn()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/iex/lib/iex.ex#L412" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
</div>
<section class="docstring">
<p>Returns registered <code class="inline">after_spawn</code> callbacks.</p>
</section>
</div>
<div class="detail" id="after_spawn/1">
<div class="detail-header">
<a href="#after_spawn/1" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">after_spawn(fun)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/iex/lib/iex.ex#L405" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
</div>
<section class="docstring">
<p>Registers a function to be invoked after the IEx process is spawned.</p>
</section>
</div>
<div class="detail" id="break!/2">
<span id="break!/1"></span>
<div class="detail-header">
<a href="#break!/2" class="detail-link" title="Link to this macro">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this macro</span>
</a>
<span class="signature">break!(ast, stops \\ 1)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/iex/lib/iex.ex#L556" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<span class="note">(macro)</span>
<span class="note">(since 1.5.0)</span>
</div>
<section class="docstring">
<p>Macro-based shortcut for <a href="IEx.html#break!/4"><code class="inline">IEx.break!/4</code></a>.</p>
</section>
</div>
<div class="detail" id="break!/4">
<span id="break!/3"></span>
<div class="detail-header">
<a href="#break!/4" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">break!(module, function, arity, stops \\ 1)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/iex/lib/iex.ex#L735" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<span class="note">(since 1.5.0)</span>
</div>
<section class="docstring">
<p>Sets up a breakpoint in <code class="inline">module</code>, <code class="inline">function</code> and <code class="inline">arity</code> with
the given number of <code class="inline">stops</code>.</p>
<p>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.</p>
<p>When a breakpoint is reached, IEx will ask if you want to <code class="inline">pry</code>
the given function and arity. In other words, this works similar
to <a href="IEx.html#pry/0"><code class="inline">IEx.pry/0</code></a> as the running process becomes the evaluator of
IEx commands and is temporarily changed to have a custom group
leader. However, differently from <a href="IEx.html#pry/0"><code class="inline">IEx.pry/0</code></a>, aliases and imports
from the source code won’t be available in the shell.</p>
<p>IEx helpers includes many conveniences related to breakpoints.
Below they are listed with the full module, such as <a href="IEx.Helpers.html#breaks/0"><code class="inline">IEx.Helpers.breaks/0</code></a>,
but remember it can be called directly as <code class="inline">breaks()</code> inside IEx.
They are:</p>
<ul>
<li><a href="IEx.Helpers.html#break!/2"><code class="inline">IEx.Helpers.break!/2</code></a> - sets up a breakpoint for a given <code class="inline">Mod.fun/arity</code>
</li>
<li><a href="IEx.Helpers.html#break!/4"><code class="inline">IEx.Helpers.break!/4</code></a> - sets up a breakpoint for the given module, function, arity
</li>
<li><a href="IEx.Helpers.html#breaks/0"><code class="inline">IEx.Helpers.breaks/0</code></a> - prints all breakpoints and their ids
</li>
<li><a href="IEx.Helpers.html#continue/0"><code class="inline">IEx.Helpers.continue/0</code></a> - continues until the next breakpoint in the same shell
</li>
<li><a href="IEx.Helpers.html#open/0"><code class="inline">IEx.Helpers.open/0</code></a> - opens editor on the current breakpoint
</li>
<li><a href="IEx.Helpers.html#remove_breaks/0"><code class="inline">IEx.Helpers.remove_breaks/0</code></a> - removes all breakpoints in all modules
</li>
<li><a href="IEx.Helpers.html#remove_breaks/1"><code class="inline">IEx.Helpers.remove_breaks/1</code></a> - removes all breakpoints in a given module
</li>
<li><a href="IEx.Helpers.html#reset_break/1"><code class="inline">IEx.Helpers.reset_break/1</code></a> - sets the number of stops on the given id to zero
</li>
<li><a href="IEx.Helpers.html#reset_break/3"><code class="inline">IEx.Helpers.reset_break/3</code></a> - sets the number of stops on the given module, function, arity to zero
</li>
<li><a href="IEx.Helpers.html#respawn/0"><code class="inline">IEx.Helpers.respawn/0</code></a> - starts a new shell (breakpoints will ask for permission once more)
</li>
<li><a href="IEx.Helpers.html#whereami/1"><code class="inline">IEx.Helpers.whereami/1</code></a> - shows the current location
</li>
</ul>
<p>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.</p>
<p>Alternatively, the number of stops can be increased by passing the <code class="inline">stops</code>
argument. <a href="IEx.Helpers.html#reset_break/1"><code class="inline">IEx.Helpers.reset_break/1</code></a> and <a href="IEx.Helpers.html#reset_break/3"><code class="inline">IEx.Helpers.reset_break/3</code></a>
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
<a href="IEx.Helpers.html#remove_breaks/1"><code class="inline">IEx.Helpers.remove_breaks/1</code></a> and on all modules by calling
<a href="IEx.Helpers.html#remove_breaks/0"><code class="inline">IEx.Helpers.remove_breaks/0</code></a>.</p>
<p>To exit a breakpoint, the developer can either invoke <code class="inline">continue()</code>,
which will block the shell until the next breakpoint is found or
the process terminates, or invoke <code class="inline">respawn()</code>, which starts a new IEx
shell, freeing up the pried one.</p>
<p>This functionality only works on Elixir code and requires Erlang/OTP 20+.</p>
<h2 id="break!/4-examples" class="section-heading">
<a href="#break!/4-examples" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Examples
</h2>
<p>The examples below will use <code class="inline">break!</code>, 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 <code class="inline">IEx.break!</code>.</p>
<p>The following sets up a breakpoint on <a href="https://hexdocs.pm/elixir/URI.html#decode_query/2"><code class="inline">URI.decode_query/2</code></a>:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">break!</span><span class="w"> </span><span class="nc">URI</span><span class="p">,</span><span class="w"> </span><span class="ss">:decode_query</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span></code></pre>
<p>This call will setup a breakpoint that stops once.
To set a breakpoint that will stop 10 times:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">break!</span><span class="w"> </span><span class="nc">URI</span><span class="p">,</span><span class="w"> </span><span class="ss">:decode_query</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">10</span></code></pre>
<p><a href="IEx.html#break!/2"><code class="inline">IEx.break!/2</code></a> is a convenience macro that allows breakpoints
to be given in the <code class="inline">Mod.fun/arity</code> format:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">break!</span><span class="w"> </span><span class="nc">URI</span><span class="o">.</span><span class="n">decode_query</span><span class="o">/</span><span class="mi">2</span></code></pre>
<p>Or to set a breakpoint that will stop 10 times:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">break!</span><span class="w"> </span><span class="nc">URI</span><span class="o">.</span><span class="n">decode_query</span><span class="o">/</span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">10</span></code></pre>
<p>This function returns the breakpoint ID and will raise if there
is an error setting up the breakpoint.</p>
<h2 id="break!/4-patterns-and-guards" class="section-heading">
<a href="#break!/4-patterns-and-guards" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Patterns and guards
</h2>
<p><a href="IEx.html#break!/2"><code class="inline">IEx.break!/2</code></a> 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:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">break!</span><span class="w"> </span><span class="nc">URI</span><span class="o">.</span><span class="n">decode_query</span><span class="p" data-group-id="7744094278-1">(</span><span class="s">"foo=bar"</span><span class="p">,</span><span class="w"> </span><span class="bp">_</span><span class="p" data-group-id="7744094278-1">)</span></code></pre>
<p>Or to trigger it whenever the second argument is a map with
more than one element:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">break!</span><span class="w"> </span><span class="nc">URI</span><span class="o">.</span><span class="n">decode_query</span><span class="p" data-group-id="7851216890-1">(</span><span class="bp">_</span><span class="p">,</span><span class="w"> </span><span class="n">map</span><span class="p" data-group-id="7851216890-1">)</span><span class="w"> </span><span class="ow">when</span><span class="w"> </span><span class="n">map_size</span><span class="p" data-group-id="7851216890-2">(</span><span class="n">map</span><span class="p" data-group-id="7851216890-2">)</span><span class="w"> </span><span class="o">></span><span class="w"> </span><span class="mi">0</span></code></pre>
<p>Only a single break point can be set per function. So if you call
<code class="inline">IEx.break!</code> multiple times with different patterns, only the last
pattern is kept.</p>
<p>Notice 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:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">break!</span><span class="w"> </span><span class="nc">MyModule</span><span class="o">.</span><span class="n">some_macro</span><span class="p" data-group-id="7605050753-1">(</span><span class="n">pid</span><span class="p" data-group-id="7605050753-1">)</span><span class="w"> </span><span class="ow">when</span><span class="w"> </span><span class="n">pid</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="n">self</span><span class="p" data-group-id="7605050753-2">(</span><span class="p" data-group-id="7605050753-2">)</span></code></pre>
<p>This breakpoint will never be reached, because a macro never receives
a PID. Even if you call the macro as <code class="inline">MyModule.some_macro(self())</code>,
the macro will receive the AST representing the <code class="inline">self()</code> call, and not
the PID itself.</p>
<h2 id="break!/4-breaks-and-mix-test" class="section-heading">
<a href="#break!/4-breaks-and-mix-test" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Breaks and mix test
</h2>
<p>To use <a href="IEx.html#break!/4"><code class="inline">IEx.break!/4</code></a> during tests, you need to run Mix inside
<code class="inline">iex</code> and pass the <code class="inline">--trace</code> to <code class="inline">mix test</code> to avoid running
into timeouts:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">iex</span><span class="w"> </span><span class="o">-</span><span class="nc">S</span><span class="w"> </span><span class="n">mix</span><span class="w"> </span><span class="n">test</span><span class="w"> </span><span class="o">--</span><span class="n">trace</span><span class="w">
</span><span class="n">iex</span><span class="w"> </span><span class="o">-</span><span class="nc">S</span><span class="w"> </span><span class="n">mix</span><span class="w"> </span><span class="n">test</span><span class="w"> </span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">file</span><span class="ss">:line</span><span class="w"> </span><span class="o">--</span><span class="n">trace</span></code></pre>
</section>
</div>
<div class="detail" id="color/2">
<div class="detail-header">
<a href="#color/2" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">color(color, string)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/iex/lib/iex.ex#L428" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
</div>
<section class="docstring">
<p>Returns <code class="inline">string</code> escaped using the specified <code class="inline">color</code>.</p>
<p>ANSI escapes in <code class="inline">string</code> are not processed in any way.</p>
</section>
</div>
<div class="detail" id="configuration/0">
<div class="detail-header">
<a href="#configuration/0" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">configuration()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/iex/lib/iex.ex#L398" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
</div>
<section class="docstring">
<p>Returns IEx configuration.</p>
</section>
</div>
<div class="detail" id="configure/1">
<div class="detail-header">
<a href="#configure/1" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">configure(options)</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/iex/lib/iex.ex#L391" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
</div>
<section class="docstring">
<p>Configures IEx.</p>
<p>The supported options are:</p>
<ul>
<li><code class="inline">:colors</code>
</li>
<li><code class="inline">:inspect</code>
</li>
<li><code class="inline">:width</code>
</li>
<li><code class="inline">:history_size</code>
</li>
<li><code class="inline">:default_prompt</code>
</li>
<li><code class="inline">:alive_prompt</code>
</li>
</ul>
<p>They are discussed individually in the sections below.</p>
<h2 id="configure/1-colors" class="section-heading">
<a href="#configure/1-colors" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Colors
</h2>
<p>A keyword list that encapsulates all color settings used by the
shell. See documentation for the <a href="https://hexdocs.pm/elixir/IO.ANSI.html"><code class="inline">IO.ANSI</code></a> module for the list of
supported colors and attributes.</p>
<p>List of supported keys in the keyword list:</p>
<ul>
<li><code class="inline">:enabled</code> - boolean value that allows for switching the coloring on and off
</li>
<li><code class="inline">:eval_result</code> - color for an expression’s resulting value
</li>
<li><code class="inline">:eval_info</code> - … various informational messages
</li>
<li><code class="inline">:eval_error</code> - … error messages
</li>
<li><code class="inline">:eval_interrupt</code> - … interrupt messages
</li>
<li><code class="inline">:stack_info</code> - … the stacktrace color
</li>
<li><code class="inline">:blame_diff</code> - … when blaming source with no match
</li>
<li><code class="inline">:ls_directory</code> - … for directory entries (ls helper)
</li>
<li><code class="inline">:ls_device</code> - … device entries (ls helper)
</li>
</ul>
<p>When printing documentation, IEx will convert the Markdown
documentation to ANSI as well. Colors for this can be configured
via:</p>
<ul>
<li><code class="inline">:doc_code</code> - the attributes for code blocks (cyan, bright)
</li>
<li><code class="inline">:doc_inline_code</code> - inline code (cyan)
</li>
<li><code class="inline">:doc_headings</code> - h1 and h2 (yellow, bright)
</li>
<li><code class="inline">:doc_title</code> - the overall heading for the output (reverse, yellow, bright)
</li>
<li><code class="inline">:doc_bold</code> - (bright)
</li>
<li><code class="inline">:doc_underline</code> - (underline)
</li>
</ul>
<p>IEx will also color inspected expressions using the <code class="inline">:syntax_colors</code>
option. Such can be disabled with:</p>
<pre><code class="nohighlight makeup elixir"><span class="nc">IEx</span><span class="o">.</span><span class="n">configure</span><span class="w"> </span><span class="p" data-group-id="7799814794-1">[</span><span class="ss">colors</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="7799814794-2">[</span><span class="ss">syntax_colors</span><span class="p">:</span><span class="w"> </span><span class="no">false</span><span class="p" data-group-id="7799814794-2">]</span><span class="p" data-group-id="7799814794-1">]</span></code></pre>
<p>You can also configure the syntax colors, however, as desired:</p>
<pre><code class="nohighlight makeup elixir"><span class="nc">IEx</span><span class="o">.</span><span class="n">configure</span><span class="w"> </span><span class="p" data-group-id="4556658280-1">[</span><span class="ss">colors</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="4556658280-2">[</span><span class="ss">syntax_colors</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="4556658280-3">[</span><span class="ss">atom</span><span class="p">:</span><span class="w"> </span><span class="ss">:red</span><span class="p" data-group-id="4556658280-3">]</span><span class="p" data-group-id="4556658280-2">]</span><span class="p" data-group-id="4556658280-1">]</span></code></pre>
<p>Configuration for most built-in data types are supported: <code class="inline">:atom</code>,
<code class="inline">:string</code>, <code class="inline">:binary</code>, <code class="inline">:list</code>, <code class="inline">:number</code>, <code class="inline">:boolean</code>, <code class="inline">:nil</code>, etc.
The default is:</p>
<pre><code class="nohighlight makeup elixir"><span class="p" data-group-id="0334801514-1">[</span><span class="ss">number</span><span class="p">:</span><span class="w"> </span><span class="ss">:magenta</span><span class="p">,</span><span class="w"> </span><span class="ss">atom</span><span class="p">:</span><span class="w"> </span><span class="ss">:cyan</span><span class="p">,</span><span class="w"> </span><span class="ss">string</span><span class="p">:</span><span class="w"> </span><span class="ss">:green</span><span class="p">,</span><span class="w">
</span><span class="ss">boolean</span><span class="p">:</span><span class="w"> </span><span class="ss">:magenta</span><span class="p">,</span><span class="w"> </span><span class="ss">nil</span><span class="p">:</span><span class="w"> </span><span class="ss">:magenta</span><span class="p" data-group-id="0334801514-1">]</span></code></pre>
<h2 id="configure/1-inspect" class="section-heading">
<a href="#configure/1-inspect" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Inspect
</h2>
<p>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.</p>
<p>To show all entries, configure the limit to <code class="inline">:infinity</code>:</p>
<pre><code class="nohighlight makeup elixir"><span class="nc">IEx</span><span class="o">.</span><span class="n">configure</span><span class="w"> </span><span class="p" data-group-id="4533499343-1">[</span><span class="ss">inspect</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="4533499343-2">[</span><span class="ss">limit</span><span class="p">:</span><span class="w"> </span><span class="ss">:infinity</span><span class="p" data-group-id="4533499343-2">]</span><span class="p" data-group-id="4533499343-1">]</span></code></pre>
<p>See <a href="https://hexdocs.pm/elixir/Inspect.Opts.html"><code class="inline">Inspect.Opts</code></a> for the full list of options.</p>
<h2 id="configure/1-width" class="section-heading">
<a href="#configure/1-width" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Width
</h2>
<p>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 <code class="inline">:io.columns</code>. 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.</p>
<h2 id="configure/1-history-size" class="section-heading">
<a href="#configure/1-history-size" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
History size
</h2>
<p>Number of expressions and their results to keep in the history.
The value is an integer. When it is negative, the history is unlimited.</p>
<h2 id="configure/1-prompt" class="section-heading">
<a href="#configure/1-prompt" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Prompt
</h2>
<p>This is an option determining the prompt displayed to the user
when awaiting input.</p>
<p>The value is a keyword list with two possible keys representing prompt types:</p>
<ul>
<li><code class="inline">:default_prompt</code> - used when <a href="https://hexdocs.pm/elixir/Node.html#alive?/0"><code class="inline">Node.alive?/0</code></a> returns <code class="inline">false</code>
</li>
<li><code class="inline">:alive_prompt</code> - used when <a href="https://hexdocs.pm/elixir/Node.html#alive?/0"><code class="inline">Node.alive?/0</code></a> returns <code class="inline">true</code>
</li>
</ul>
<p>The following values in the prompt string will be replaced appropriately:</p>
<ul>
<li><code class="inline">%counter</code> - the index of the history
</li>
<li><code class="inline">%prefix</code> - a prefix given by <code class="inline">IEx.Server</code>
</li>
<li><code class="inline">%node</code> - the name of the local node
</li>
</ul>
</section>
</div>
<div class="detail" id="inspect_opts/0">
<div class="detail-header">
<a href="#inspect_opts/0" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">inspect_opts()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/iex/lib/iex.ex#L450" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
</div>
<section class="docstring">
<p>Gets the options used for inspecting.</p>
</section>
</div>
<div class="detail" id="pry/0">
<div class="detail-header">
<a href="#pry/0" class="detail-link" title="Link to this macro">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this macro</span>
</a>
<span class="signature">pry()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/iex/lib/iex.ex#L546" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
<span class="note">(macro)</span>
</div>
<section class="docstring">
<p>Pries into the process environment.</p>
<p>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 <a href="IEx.Helpers.html#respawn/0"><code class="inline">IEx.Helpers.respawn/0</code></a>, which starts a new IEx shell,
freeing up the pried one.</p>
<p>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 <code class="inline">Mod.fun(args)</code>.</p>
<p>Alternatively, you can use <a href="IEx.html#break!/4"><code class="inline">IEx.break!/4</code></a> to setup a breakpoint
on a given module, function and arity you have no control of.
While <a href="IEx.html#break!/4"><code class="inline">IEx.break!/4</code></a> is more flexible, it requires Erlang/OTP 20+ and
it does not contain information about imports and aliases from
the source code.</p>
<h2 id="pry/0-examples" class="section-heading">
<a href="#pry/0-examples" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Examples
</h2>
<p>Let’s suppose you want to investigate what is happening
with some particular function. By invoking <code class="inline">IEx.pry/1</code> 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:</p>
<pre><code class="nohighlight makeup elixir"><span class="kn">import</span><span class="w"> </span><span class="nc">Enum</span><span class="p">,</span><span class="w"> </span><span class="ss">only</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="4053499969-1">[</span><span class="ss">map</span><span class="p">:</span><span class="w"> </span><span class="mi">2</span><span class="p" data-group-id="4053499969-1">]</span><span class="w">
</span><span class="kd">defmodule</span><span class="w"> </span><span class="nc">Adder</span><span class="w"> </span><span class="k" data-group-id="4053499969-2">do</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">add</span><span class="p" data-group-id="4053499969-3">(</span><span class="n">a</span><span class="p">,</span><span class="w"> </span><span class="n">b</span><span class="p" data-group-id="4053499969-3">)</span><span class="w"> </span><span class="k" data-group-id="4053499969-4">do</span><span class="w">
</span><span class="n">c</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">b</span><span class="w">
</span><span class="kn">require</span><span class="w"> </span><span class="nc">IEx</span><span class="p">;</span><span class="w"> </span><span class="nc">IEx</span><span class="o">.</span><span class="n">pry</span><span class="w">
</span><span class="k" data-group-id="4053499969-4">end</span><span class="w">
</span><span class="k" data-group-id="4053499969-2">end</span></code></pre>
<p>When invoking <code class="inline">Adder.add(1, 2)</code>, 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:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">pry</span><span class="p" data-group-id="2673595530-1">(</span><span class="mi">1</span><span class="p" data-group-id="2673595530-1">)</span><span class="o">></span><span class="w"> </span><span class="n">map</span><span class="p" data-group-id="2673595530-2">(</span><span class="p" data-group-id="2673595530-3">[</span><span class="n">a</span><span class="p">,</span><span class="w"> </span><span class="n">b</span><span class="p">,</span><span class="w"> </span><span class="n">c</span><span class="p" data-group-id="2673595530-3">]</span><span class="p">,</span><span class="w"> </span><span class="o">&</span><span class="nc">IO</span><span class="o">.</span><span class="n">inspect</span><span class="p" data-group-id="2673595530-4">(</span><span class="ni">&1</span><span class="p" data-group-id="2673595530-4">)</span><span class="p" data-group-id="2673595530-2">)</span><span class="w">
</span><span class="mi">1</span><span class="w">
</span><span class="mi">2</span><span class="w">
</span><span class="mi">3</span></code></pre>
<p>Keep in mind that <code class="inline">IEx.pry/1</code> runs in the caller process,
blocking the caller during the evaluation cycle. The caller
process can be freed by calling <code class="inline">respawn/0</code>, which starts a
new IEx evaluation cycle, letting this one go:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">pry</span><span class="p" data-group-id="2055290394-1">(</span><span class="mi">2</span><span class="p" data-group-id="2055290394-1">)</span><span class="o">></span><span class="w"> </span><span class="n">respawn</span><span class="p" data-group-id="2055290394-2">(</span><span class="p" data-group-id="2055290394-2">)</span><span class="w">
</span><span class="no">true</span><span class="w">
</span><span class="nc">Interactive</span><span class="w"> </span><span class="nc">Elixir</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="n">press</span><span class="w"> </span><span class="nc">Ctrl</span><span class="o">+</span><span class="nc">C</span><span class="w"> </span><span class="n">to</span><span class="w"> </span><span class="n">exit</span><span class="w"> </span><span class="p" data-group-id="2055290394-3">(</span><span class="n">type</span><span class="w"> </span><span class="n">h</span><span class="p" data-group-id="2055290394-4">(</span><span class="p" data-group-id="2055290394-4">)</span><span class="w"> </span><span class="nc">ENTER</span><span class="w"> </span><span class="k">for</span><span class="w"> </span><span class="n">help</span><span class="p" data-group-id="2055290394-3">)</span></code></pre>
<p>Setting variables or importing modules in IEx does not
affect the caller’s environment. However, sending and
receiving messages will change the process state.</p>
<h2 id="pry/0-pry-and-macros" class="section-heading">
<a href="#pry/0-pry-and-macros" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Pry and macros
</h2>
<p>When setting up Pry inside a code defined by macros, such as:</p>
<pre><code class="nohighlight makeup elixir"><span class="kd">defmacro</span><span class="w"> </span><span class="nf">__using__</span><span class="p" data-group-id="0758817166-1">(</span><span class="bp">_</span><span class="p" data-group-id="0758817166-1">)</span><span class="w"> </span><span class="k" data-group-id="0758817166-2">do</span><span class="w">
</span><span class="k">quote</span><span class="w"> </span><span class="k" data-group-id="0758817166-3">do</span><span class="w">
</span><span class="kd">def</span><span class="w"> </span><span class="nf">add</span><span class="p" data-group-id="0758817166-4">(</span><span class="n">a</span><span class="p">,</span><span class="w"> </span><span class="n">b</span><span class="p" data-group-id="0758817166-4">)</span><span class="w"> </span><span class="k" data-group-id="0758817166-5">do</span><span class="w">
</span><span class="n">c</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">b</span><span class="w">
</span><span class="kn">require</span><span class="w"> </span><span class="nc">IEx</span><span class="p">;</span><span class="w"> </span><span class="nc">IEx</span><span class="o">.</span><span class="n">pry</span><span class="w">
</span><span class="k" data-group-id="0758817166-5">end</span><span class="w">
</span><span class="k" data-group-id="0758817166-3">end</span><span class="w">
</span><span class="k" data-group-id="0758817166-2">end</span></code></pre>
<p>The variables defined inside <code class="inline">quote</code> 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.</p>
<h2 id="pry/0-pry-and-mix-test" class="section-heading">
<a href="#pry/0-pry-and-mix-test" class="hover-link"><span class="icon-link" aria-hidden="true"></span></a>
Pry and mix test
</h2>
<p>To use <a href="IEx.html#pry/0"><code class="inline">IEx.pry/0</code></a> during tests, you need to run Mix inside
<code class="inline">iex</code> and pass the <code class="inline">--trace</code> to <code class="inline">mix test</code> to avoid running
into timeouts:</p>
<pre><code class="nohighlight makeup elixir"><span class="n">iex</span><span class="w"> </span><span class="o">-</span><span class="nc">S</span><span class="w"> </span><span class="n">mix</span><span class="w"> </span><span class="n">test</span><span class="w"> </span><span class="o">--</span><span class="n">trace</span><span class="w">
</span><span class="n">iex</span><span class="w"> </span><span class="o">-</span><span class="nc">S</span><span class="w"> </span><span class="n">mix</span><span class="w"> </span><span class="n">test</span><span class="w"> </span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">file</span><span class="ss">:line</span><span class="w"> </span><span class="o">--</span><span class="n">trace</span></code></pre>
</section>
</div>
<div class="detail" id="started?/0">
<div class="detail-header">
<a href="#started?/0" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">started?()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/iex/lib/iex.ex#L419" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
</div>
<section class="docstring">
<p>Returns <code class="inline">true</code> if IEx was started.</p>
</section>
</div>
<div class="detail" id="width/0">
<div class="detail-header">
<a href="#width/0" class="detail-link" title="Link to this function">
<span class="icon-link" aria-hidden="true"></span>
<span class="sr-only">Link to this function</span>
</a>
<span class="signature">width()</span>
<a href="https://github.com/elixir-lang/elixir/blob/v1.7.2/lib/iex/lib/iex.ex#L443" class="view-source" rel="help" title="View Source">
<span class="icon-code" aria-hidden="true"></span>
<span class="sr-only">View Source</span>
</a>
</div>
<section class="docstring">
<p>Gets the IEx width for printing.</p>
<p>Used by helpers and it has a default maximum cap of 80 chars.</p>
</section>
</div>
</section>
<footer class="footer">
<p>
<span class="line">
Built using
<a href="https://github.com/elixir-lang/ex_doc" title="ExDoc" target="_blank" rel="help noopener">ExDoc</a> (v0.19.1),
</span>
<span class="line">
designed by
<a href="https://twitter.com/dignifiedquire" target="_blank" rel="noopener" title="@dignifiedquire">Friedel Ziegelmayer</a>.
</span>
</p>
</footer>
</div>
</div>
</section>
</div>
<script src="dist/app-a0c90688fa.js"></script>
</body>
</html>
