# `IEx.Helpers`
[🔗](https://github.com/elixir-lang/elixir/blob/7ff272706afc522e74121493b7166719985cb099/lib/iex/lib/iex/helpers.ex#L5)

Welcome to Interactive Elixir. You are currently
seeing the documentation for the module `IEx.Helpers`
which provides many helpers to make Elixir's shell
more joyful to work with.

This message was triggered by invoking the helper `h()`,
usually referred to as `h/0` (since it expects 0 arguments).

You can use the `h/1` function to invoke the documentation
for any Elixir module or function:

    iex> h(Enum)
    iex> h(Enum.map)
    iex> h(Enum.reverse/1)

You can also use the `i/1` function to introspect any value
you have in the shell:

    iex> i("hello")

There are many other helpers available, here are some examples:

  * `b/1`             - prints callbacks info and docs for a given module
  * `c/1`             - compiles a file
  * `c/2`             - compiles a file and writes bytecode to the given path
  * `cd/1`            - changes the current directory
  * `clear/0`         - clears the screen
  * `exports/1`       - shows all exports (functions + macros) in a module
  * `flush/0`         - flushes all messages sent to the shell
  * `h/0`             - prints this help message
  * `h/1`             - prints help for the given module, function or macro
  * `i/0`             - prints information about the last value
  * `i/1`             - prints information about the given term
  * `ls/0`            - lists the contents of the current directory
  * `ls/1`            - lists the contents of the specified directory
  * `open/1`          - opens the source for the given module or function in your editor
  * `pid/1`           - creates a PID from a string
  * `pid/3`           - creates a PID with the 3 integer arguments passed
  * `port/1`          - creates a port from a string
  * `port/2`          - creates a port with the 2 non-negative integers passed
  * `process_info/1`  - returns information about the given process
  * `pwd/0`           - prints the current working directory
  * `r/1`             - recompiles the given module's source file
  * `recompile/0`     - recompiles the current project
  * `ref/1`           - creates a reference from a string
  * `ref/4`           - creates a reference with the 4 integer arguments passed
  * `runtime_info/0`  - prints runtime info (versions, memory usage, stats)
  * `source/1`        - prints the source location for the given module or function
  * `t/1`             - prints the types for the given module or function
  * `v/0`             - retrieves the last value from the history
  * `v/1`             - retrieves the nth value from the history

There are also several helpers available when debugging, such as:

  * `break!/2`        - sets a breakpoint at `Module.function/arity`
  * `breaks/0`        - prints all breakpoints to the terminal
  * `c/0`             - a shortcut for `continue/0`
  * `continue/0`      - continues execution of the current process
  * `n/0`             - a shortcut for `next/0`
  * `next/0`          - goes to the next line of the current breakpoint
  * `remove_breaks/0` - removes all breakpoints and instrumentation from all modules
  * `whereami/1`      - prints the current location and stacktrace in a pry session

Help for all of those functions can be consulted directly from
the command line using the `h/1` helper itself. Try:

    iex> h(v/0)

To list all IEx helpers available, which is effectively all
exports (functions and macros) in the `IEx.Helpers` module:

    iex> exports(IEx.Helpers)

This module also includes helpers for debugging purposes, see
`IEx.break!/4` for more information.

To learn more about IEx as a whole, type `h(IEx)`.

# `b`
*macro* 

Prints the documentation for the given callback function.

It also accepts single module argument to list
all available behaviour callbacks.

## Examples

    iex> b(Mix.Task.run/1)
    iex> b(Mix.Task.run)
    iex> b(GenServer)

# `break!`
*since 1.5.0* *macro* 

Sets up a breakpoint in the AST of shape `Module.function/arity`
with the given number of `stops`.

See `IEx.break!/4` for a complete description of breakpoints
in IEx.

## Examples

    break! URI.decode_query/2

# `break!`
*since 1.5.0* 

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

See `IEx.break!/4` for a complete description of breakpoints
in IEx.

## Examples

    break! URI, :decode_query, 2

# `breaks`
*since 1.5.0* 

Prints all breakpoints to the terminal.

# `c`
*since 1.17.0* 

A shortcut for `continue/0`.

# `c`

Compiles the given files.

It expects a list of files to compile and an optional path to write
the compiled code to. By default files are in-memory compiled.
To write compiled files to the current directory, `"."` can be given.

It returns the names of the compiled modules.

If you want to recompile an existing module, check `r/1` instead.

> #### Remote compilation {: .warning}
>
> When compiling code, warnings and errors may be printed to standard error.
> However, when connecting to a remote node, the standard error output is not
> redirected to the client. This means that compilation failures will be written
> to the logs or the output terminal of the machine you connect to.

## Examples

In the example below, we pass a directory to where the `c/2` function will
write the compiled `.beam` files to. This directory is typically named "ebin"
in Erlang/Elixir systems:

    iex> c(["foo.ex", "bar.ex"], "ebin")
    [Foo, Bar]

When compiling one file, there is no need to wrap it in a list:

    iex> c("baz.ex")
    [Baz]

# `cd`

Changes the current working directory to the given path.

# `clear`

Clears the console screen.

This function only works if ANSI escape codes are enabled
on the shell, which means this function is by default
unavailable on Windows machines.

# `continue`
*since 1.5.0* 

Continues execution of the current process.

This is usually called by sessions started with `IEx.pry/0`
or `IEx.break!/4`. This allows the current process to execute
until the next breakpoint, which will automatically yield control
back to IEx without requesting permission to pry.

If you simply want to move to the next line of the current breakpoint,
use `n/0` or `next/0` instead.

If the running process terminates, a new IEx session is
started.

While the process executes, the user will no longer have
control of the shell. If you would rather start a new shell,
use `respawn/0` instead.

# `exports`
*since 1.5.0* 

Prints a list of all the functions and macros exported by the given module.

# `flush`

Clears out all messages sent to the shell's inbox and prints them out.

# `h`

Prints the documentation for `IEx.Helpers`.

# `h`
*macro* 

Prints the documentation for the given module
or for the given `function/arity` pair.

## Examples

    iex> h(Enum)

It also accepts functions in the format `function/arity`
and `module.function/arity`, for example:

    iex> h(receive/1)
    iex> h(Enum.all?/2)
    iex> h(Enum.all?)

# `i`

Prints information about the data type of any given term.

If no argument is given, the value of the previous expression
is used.

## Examples

    iex> i(1..5)

Will print:

    Term
      1..5
    Data type
      Range
    Description
      This is a struct. Structs are maps with a __struct__ key.
    Reference modules
      Range, Map

# `import_file`
*since 1.4.0* *macro* 

Injects the contents of the file at `path`.

This would be the equivalent of getting all of the file contents and
pasting it all at once in IEx and executing it.

By default, the contents of a `.iex.exs` file in the same directory
as you are starting IEx are automatically imported. See the section
for ".iex.exs" in the `IEx` module docs for more information.

`path` has to be a literal string and is automatically expanded via
`Path.expand/1`.

## Examples

    # ~/file.exs
    value = 13

    # in the shell
    iex(1)> import_file("~/file.exs")
    13
    iex(2)> value
    13

# `import_file_if_available`
*macro* 

Similar to `import_file` but only imports the file if it is available.

By default, `import_file/1` fails when the given file does not exist.
However, since `import_file/1` is expanded at compile-time, it's not
possible to conditionally import a file since the macro is always
expanded:

    # This raises a File.Error if ~/.iex.exs doesn't exist.
    if "~/.iex.exs" |> Path.expand() |> File.exists?() do
      import_file("~/.iex.exs")
    end

This macro addresses this issue by checking if the file exists or not
in behalf of the user.

# `import_if_available`
*macro* 

Calls `import/2` with the given arguments, but only if the module is available.

This lets you put imports in `.iex.exs` files (including `~/.iex.exs`) without
getting compile errors if you open a console where the module is not available.

## Example

    # In ~/.iex.exs
    import_if_available(Ecto.Query)

# `l`

Loads the given module's BEAM code (and ensures any previous
old version was properly purged before).

This function is useful when you know the bytecode for module
has been updated in the file system and you want to tell the VM
to load it.

# `ls`

Prints a list of the given directory's contents.

If `path` points to a file, prints its full path.

# `n`
*since 1.14.0* 

A shortcut for `next/0`.

# `next`
*since 1.14.0* 

Goes to the next line of the current breakpoint.

This is usually called by sessions started with `IEx.break!/4`.
If instead of the next line you want to move to the next breakpoint,
call `continue/0` instead.

While the process executes, the user will no longer have
control of the shell. If you would rather start a new shell,
use `respawn/0` instead.

# `nl`

Deploys a given module's BEAM code to a list of nodes.

This function is useful for development and debugging when you have code that
has been compiled or updated locally that you want to run on other nodes.

The node list defaults to a list of all connected nodes.

Returns `{:error, :nofile}` if the object code (i.e. ".beam" file) for the module
could not be found locally.

## Examples

    iex> nl(HelloWorld)
    {:ok,
     [
       {:node1@easthost, :loaded, HelloWorld},
       {:node1@westhost, :loaded, HelloWorld}
     ]}

    iex> nl(NoSuchModuleExists)
    {:error, :nofile}

# `open`

Opens the current prying location.

This command only works inside a pry session started manually
via `IEx.pry/0` or a breakpoint set via `IEx.break!/4`. Calling
this function during a regular `IEx` session will print an error.

Keep in mind the `open/0` location may not exist when prying
precompiled source code, such as Elixir itself.

For more information and to open any module or function, see
`open/1`.

# `open`
*macro* 

Opens the given `module`, `module.function/arity`, or `{file, line}`.

This function uses the `ELIXIR_EDITOR` environment variable
and falls back to `EDITOR` if the former is not available.

By default, it attempts to open the file and line using the
`file:line` notation. For example, for Sublime Text you can
set it as:

    ELIXIR_EDITOR="subl"

Which will then try to open it as:

    subl path/to/file:line

For Visual Studio Code, once enabled on the command line,
you can set it to:

    ELIXIR_EDITOR="code --goto"

It is important that you choose an editor command that does
not block nor that attempts to run an editor directly in the
terminal. Command-line based editors likely need extra
configuration so they open up the given file and line in a
separate window.

For more complex use cases, you can use the `__FILE__` and
`__LINE__` notations to explicitly interpolate the file and
line into the command:

    ELIXIR_EDITOR="my_editor +__LINE__ __FILE__"

Since this function prints the result returned by the editor,
`ELIXIR_EDITOR` can be set "echo" if you prefer to display the
location rather than opening it.

Keep in mind the location may not exist when opening precompiled
source code.

## Examples

    iex> open(MyApp)
    iex> open(MyApp.fun/2)
    iex> open({"path/to/file", 1})

# `pid`

```elixir
@spec pid(binary() | atom()) :: pid()
```

Creates a PID from `string` or `atom`.

## Examples

    iex> pid("0.21.32")
    #PID<0.21.32>

    iex> pid("#PID<0.21.32>")
    #PID<0.21.32>

    iex> pid(:init)
    #PID<0.0.0>

# `pid`

```elixir
@spec pid(non_neg_integer(), non_neg_integer(), non_neg_integer()) :: pid()
```

Creates a PID with 3 non-negative integers passed as arguments
to the function.

## Examples

    iex> pid(0, 21, 32)
    #PID<0.21.32>
    iex> pid(0, 64, 2048)
    #PID<0.64.2048>

# `port`
*since 1.8.0* 

```elixir
@spec port(binary()) :: port()
```

Creates a Port from `string`.

## Examples

    iex> port("0.4")
    #Port<0.4>

# `port`
*since 1.8.0* 

```elixir
@spec port(non_neg_integer(), non_neg_integer()) :: port()
```

Creates a Port from two non-negative integers.

## Examples

    iex> port(0, 8080)
    #Port<0.8080>
    iex> port(0, 443)
    #Port<0.443>

# `process_info`
*since 1.19.0* 

Prints information about the given process.

Includes a generic overview and details such as the linked and monitored processes,
the memory usage and the current stacktrace.

## Examples

    iex> process_info(self())
    ...
    iex> process_info({:via, Registry, {MyApp.Registry, :name}})
    ...

# `pwd`

Prints the current working directory.

# `r`

Recompiles and reloads the given `module` or `modules`.

Please note that all the modules defined in the same file as
`modules` are recompiled and reloaded. If you want to reload
multiple modules, it is best to reload them at the same time,
such as in `r [Foo, Bar]`. This is important to avoid false
warnings, since the module is only reloaded in memory and its
latest information is not persisted to disk. See the "In-memory
reloading" section below.

This function is meant to be used for development and
debugging purposes. Do not depend on it in production code.

## In-memory reloading

When we reload the module in IEx, we recompile the module source
code, updating its contents in memory. The original `.beam` file
in disk, probably the one where the first definition of the module
came from, does not change at all.

Since docs, typespecs, and exports information are loaded from the
.beam file, they are not reloaded when you invoke this function.

# `recompile`

```elixir
@spec recompile([{:force, boolean()}]) :: :ok | :error | :noop
```

Recompiles the current Mix project or Mix install
dependencies.

This helper requires either `Mix.install/2` to have been
called within the current IEx session or for IEx to be
started alongside, for example, `iex -S mix`.

In the `Mix.install/1` case, it will recompile any outdated
path dependency declared during install. Within a project,
it will recompile any outdated module.

Note this function simply recompiles Elixir modules, without
reloading configuration or restarting applications. This means
any long running process may crash on recompilation, as changed
modules will be temporarily removed and recompiled, without
going through the proper code change callback.

If you want to reload a single module, consider using
`r(ModuleName)` instead.

This function is meant to be used for development and
debugging purposes. Do not depend on it in production code.

## Options

  * `:force` - when `true`, forces the application to recompile

# `ref`
*since 1.6.0* 

```elixir
@spec ref(binary()) :: reference()
```

Creates a Reference from `string`.

## Examples

    iex> ref("0.1.2.3")
    #Reference<0.1.2.3>

# `ref`
*since 1.6.0* 

```elixir
@spec ref(non_neg_integer(), non_neg_integer(), non_neg_integer(), non_neg_integer()) ::
  reference()
```

Creates a Reference from its 4 non-negative integers components.

## Examples

    iex> ref(0, 1, 2, 3)
    #Reference<0.1.2.3>

# `remove_breaks`
*since 1.5.0* 

Removes all breakpoints and instrumentation from all modules.

# `remove_breaks`
*since 1.5.0* 

Removes all breakpoints and instrumentation from `module`.

# `reset_break`
*since 1.5.0* 

Resets the number of pending stops in the breakpoint
with the given `id` to zero.

Returns `:ok` if there is such breakpoint ID. `:not_found`
otherwise.

Note the module remains "instrumented" on reset. If you would
like to effectively remove all breakpoints and instrumentation
code from a module, use `remove_breaks/1` instead.

# `reset_break`
*since 1.5.0* 

Resets the number of pending stops in the given module,
function and arity to zero.

If the module is not instrumented or if the given function
does not have a breakpoint, it is a no-op and it returns
`:not_found`. Otherwise it returns `:ok`.

Note the module remains "instrumented" on reset. If you would
like to effectively remove all breakpoints and instrumentation
code from a module, use `remove_breaks/1` instead.

# `respawn`

Respawns the current shell by starting a new shell process.

# `runtime_info`
*since 1.5.0* 

Prints VM/runtime information such as versions, memory usage and statistics.

Additional topics are available via `runtime_info/1`.

For more metrics, info, and debugging facilities, see the
[Recon](https://github.com/ferd/recon) project.

# `runtime_info`
*since 1.5.0* 

Just like `runtime_info/0`, except accepts topic or a list of topics.

For example, topic `:applications` will list the applications loaded.

# `source`
*since 1.20.0* *macro* 

Prints the source code for the given module or function.

## Examples

    iex> source(MyApp)
    iex> source(MyApp.fun/2)

# `t`
*macro* 

Prints the types for the given module or for the given function/arity pair.

## Examples

    iex> t(Enum)
    @type t() :: Enumerable.t()
    @type acc() :: any()
    @type element() :: any()
    @type index() :: integer()
    @type default() :: any()

    iex> t(Enum.t/0)
    @type t() :: Enumerable.t()

    iex> t(Enum.t)
    @type t() :: Enumerable.t()

# `use_if_available`
*since 1.7.0* *macro* 

Calls `use/2` with the given arguments, but only if the module is available.

This lets you use the module in `.iex.exs` files (including `~/.iex.exs`) without
getting compile errors if you open a console where the module is not available.

## Example

    # In ~/.iex.exs
    use_if_available(Phoenix.HTML)

# `v`

Returns the value of the `n`th expression in the history.

`n` can be a negative value: if it is, the corresponding expression value
relative to the current one is returned. For example, `v(-2)` returns the
value of the expression evaluated before the last evaluated expression. In
particular, `v(-1)` returns the result of the last evaluated expression and
`v()` does the same.

## Examples

    iex(1)> "hello" <> " world"
    "hello world"
    iex(2)> 40 + 2
    42
    iex(3)> v(-2)
    "hello world"
    iex(4)> v(2)
    42
    iex(5)> v()
    42

# `whereami`
*since 1.5.0* 

Prints the current location and stacktrace in a pry session.

It expects a `radius` which chooses how many lines before and after
the current line we should print. By default the `radius` is of two
lines:

    Location: lib/iex/lib/iex/helpers.ex:79

    77:
    78:   def recompile do
    79:     require IEx; IEx.pry()
    80:     if mix_started?() do
    81:       config = Mix.Project.config

    (IEx.Helpers) lib/iex/lib/iex/helpers.ex:78: IEx.Helpers.recompile/0

This command only works inside a pry session started manually
via `IEx.pry/0` or a breakpoint set via `IEx.break!/4`. Calling
this function during a regular `IEx` session will print an error.

Keep in mind the `whereami/1` location may not exist when prying
precompiled source code, such as Elixir itself.

---

*Consult [api-reference.md](api-reference.md) for complete listing*