IEx.Helpers

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:

• b/1 - prints callbacks info and docs for a given module
• c/1 - compiles a file into the current directory
• c/2 - compiles a file to the given path
• cd/1 - changes the current directory
• clear/0 - clears the screen
• 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/1 - prints information about the data type of any given term
• import_file/1 - evaluates the given file in the shell’s context
• l/1 - loads the given module’s BEAM code
• ls/0 - lists the contents of the current directory
• ls/1 - lists the contents of the specified directory
• nl/2 - deploys local BEAM code to a list of nodes
• pid/1 - creates a PID from a string
• pid/3 - creates a PID with the 3 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
• respawn/0 - respawns the current shell
• s/1 - prints spec information
• t/1 - prints type information
• 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 learn more about IEx as a whole, type h(IEx).

Summary

Functions

b(term)

Prints the documentation for the given callback function

c(files, path \\ :in_memory)

Compiles the given files

cd(directory)

Changes the current working directory to the given path

clear()

Clears the console screen

flush()

Flushes all messages sent to the shell and prints them out

h()

Prints the documentation for IEx.Helpers

h(term)

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

i(term)

Prints information about the data type of any given term

import_file(path)

Evaluates the contents of the file at path as if it were directly typed into the shell

import_file(path, opts)

import_file_if_available(path)

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

import_if_available(quoted_module, opts \\ [])

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

l(module)

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

ls(path \\ ".")

Produces a simple list of a directory’s contents

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

Deploys a given module’s BEAM code to a list of nodes

pid(string)

Creates a PID from string

pid(x, y, z)

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

pwd()

Prints the current working directory

r(module)

Recompiles and reloads the given module

recompile()

Recompiles the current Mix application

respawn()

Respawns the current shell by starting a new shell process

s(term)

Prints the specs for the given module or for the given function/arity pair

t(term)

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

v(n \\ -1)

Returns the value of the nth expression in the history

Functions

b(term) (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)

c(files, path \\ :in_memory)

Compiles the given files.

It expects a list of files to compile and an optional path to write the compiled code to (defaults to the current directory). When compiling one file, there is no need to wrap it in a list.

It returns the names of the compiled modules.

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

Examples

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

iex> c "baz.ex"
[Baz]

cd(directory)

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.

flush()

Flushes all messages sent to the shell and prints them out.

h()

Prints the documentation for IEx.Helpers.

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

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

i(term)

Prints information about the data type of any given term.

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(path) (macro)

Evaluates the contents of the file at path as if it were directly typed into the shell.

path has to be a literal string. path 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(path, opts) (macro)

import_file_if_available(path) (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.

import_if_available(quoted_module, opts \\ []) (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(module)

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 filesystem and you want to tell the VM to load it.

ls(path \\ ".")

Produces a simple list of a directory’s contents.

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

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

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}

pid(string)

Creates a PID from string.

Examples

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

pid(x, y, z)

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>

pwd()

Prints the current working directory.

r(module)

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.

recompile()

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 the code is updated but the state does not go through the proper code changes callback. In any case, the supervision tree should notice the failure and restart such servers.

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.

respawn()

Respawns the current shell by starting a new shell process.

Returns true if it worked.

s(term) (macro)

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

Examples

iex> s(Enum)
iex> s(Enum.all?)
iex> s(Enum.all?/2)
iex> s(is_atom)
iex> s(is_atom/1)

t(term) (macro)

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

Examples

iex> t(Enum)
@type t() :: Enumerable.t()
@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()

v(n \\ -1)

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