IEx v1.8.0 IEx.Helpers View Source

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
  • ref/1 - creates a reference from a string
  • ref/4 - creates a reference with the 4 integer arguments passed
  • pwd/0 - prints the current working directory
  • r/1 - recompiles the given module's source file
  • recompile/0 - recompiles the current project
  • runtime_info/0 - prints runtime info (versions, memory usage, stats)
  • v/0 - retrieves the last value from the history
  • v/1 - retrieves the nth value from the history

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).

Link to this section Summary

Functions

Prints the documentation for the given callback function.

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

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

Prints all breakpoints to the terminal.

Compiles the given files.

Changes the current working directory to the given path.

Clears the console screen.

Continues execution of the current process.

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

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

h()

Prints the documentation for IEx.Helpers.

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

Prints information about the data type of any given term.

Injects the contents of the file at path as if it was typed into the shell.

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

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

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

Prints a list of the given directory's contents.

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

Opens the current prying location.

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

Creates a PID from string.

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

Creates a Port from string.

Creates a Port from two non-negative integers.

Prints the current working directory.

Recompiles and reloads the given module.

Recompiles the current Mix application.

Creates a Reference from string.

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

Removes all breakpoints and instrumentation from all modules.

Removes all breakpoints and instrumentation from module.

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

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

Respawns the current shell by starting a new shell process.

Prints vm/runtime information such as versions, memory usage and statistics. Additional topics are available via runtime_info/1.

Just like runtime_info/0, except accepts topic or a list of topics. E.g. topic :applications will list the applications loaded.

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

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

Returns the value of the nth expression in the history.

Prints the current location and stacktrace in a pry session.

Link to this section Functions

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)
Link to this macro

break!(ast, stops \\ 1)

View Source (macro) (since 1.5.0)

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

Link to this function

break!(module, function, arity, stops \\ 1)

View Source (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.

Prints all breakpoints to the terminal.

Link to this function

c(files, path \\ :in_memory)

View Source

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, an empty string can be given.

It returns the names of the compiled modules.

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

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]

Changes the current working directory to the given path.

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.

Link to this function

continue()

View Source (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 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.

Link to this function

exports(module \\ Kernel)

View Source (since 1.5.0)

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

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

Prints the documentation for IEx.Helpers.

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 fun/arity and module.fun/arity, for example:

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

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
Link to this macro

import_file(path)

View Source (macro) (since 1.4.0)

Injects the contents of the file at path as if it was typed into the shell.

This would be the equivalent of getting all of the file contents and packing it all into a single line 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
Link to this macro

import_file_if_available(path)

View Source (macro)

Similar to import_file but only imports the file it 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.

Link to this macro

import_if_available(quoted_module, opts \\ [])

View Source (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

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.

Prints a list of the given directory's contents.

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

Link to this function

nl(nodes \\ Node.list(), module)

View Source

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}

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.

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, if your editor is called subl, it will open the file as:

subl path/to/file:line

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.

Custom editors are supported by using the __FILE__ and __LINE__ notations, for example:

ELIXIR_EDITOR="my_editor +__LINE__ __FILE__"

and Elixir will properly interpolate values.

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})

Creates a PID from string.

Examples

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

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>
Link to this function

port(string)

View Source (since 1.8.0)

Creates a Port from string.

Examples

iex> port("0.4")
#Port<0.4>
Link to this function

port(major, minor)

View Source (since 1.8.0)

Creates a Port from two non-negative integers.

Examples

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

Prints the current working directory.

Recompiles and reloads the given module.

Please note that all the modules defined in the same file as module are recompiled and reloaded.

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 typespecs and docs are loaded from the .beam file (they are not loaded in memory with the module because there is no need for them to be in memory), they are not reloaded when you reload the module.

Link to this function

recompile(options \\ [])

View Source

Recompiles the current Mix application.

This helper only works when IEx is started with a Mix project, for example, iex -S mix. The application is not restarted after compilation, which means any long running process may crash as any changed module will be temporarily removed and recompiled, without going through the proper code changes 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
Link to this function

ref(string)

View Source (since 1.6.0)

Creates a Reference from string.

Examples

iex> ref("0.1.2.3")
#Reference<0.1.2.3>
Link to this function

ref(w, x, y, z)

View Source (since 1.6.0)

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

Examples

iex> ref(0, 1, 2, 3)
#Reference<0.1.2.3>
Link to this function

remove_breaks()

View Source (since 1.5.0)

Removes all breakpoints and instrumentation from all modules.

Link to this function

remove_breaks(module)

View Source (since 1.5.0)

Removes all breakpoints and instrumentation from module.

Link to this function

reset_break(id)

View Source (since 1.5.0)

Sets 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.

Link to this function

reset_break(module, function, arity)

View Source (since 1.5.0)

Sets 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.

Respawns the current shell by starting a new shell process.

Link to this function

runtime_info()

View Source (since 1.5.0)

Prints vm/runtime information such as versions, memory usage and statistics. Additional topics are available via runtime_info/1.

Just like runtime_info/0, except accepts topic or a list of topics. E.g. topic :applications will list the applications loaded.

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()
Link to this macro

use_if_available(quoted_module, opts \\ [])

View Source (macro) (since 1.7.0)

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

Returns the value of the nth 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
Link to this function

whereami(radius \\ 2)

View Source (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.