Before we get started, go to the installation page and make sure you have Elixir installed.

When you’re ready to go, open up your terminal and run iex . You should see the following:

Erlang/OTP 19 [erts-8.3] [source] [64-bit] [smp:8:8] [async-threads:10] [hipe] [kernel-poll:false] [dtrace]

Interactive Elixir (1.4.2) - press Ctrl+C to exit (type h() ENTER for help)
iex(1)> 

You’ll notice a few things:

  • Version numbers; which might be different for you.
  • How to quit from iex Ctrl+C
  • And the wonderful h() function, which we’ll cover below.

The number in iex(1)> will increment on every expression executed.

iex(1)> 1 + 1
2
iex(2)> :true
true
iex(3)> IO.puts "Hello!"
Hello!
:ok
iex(4)> 

Now let’s run that h() function and see what happens:

iex(6)> h()

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

From the output you’ll notice that iex has one helluva help section. It lists the helper functions that you’ll most likely want to use. You might be looking at those functions and thinking “why do they have a forward slash followed with a number?” It’s rather simple and intuitive - it’s showing you the arity of the function. The number of arguments/parameters that the function accepts. We’ll dive deep into functions in future posts.

h() is your best friend when it comes to figuring out what modules and functions do. Let’s see it in action:

iex(8)> h IO.puts

                        def puts(device \\ :stdio, item)                        

Writes item to the given device, similar to write/2, but adds a newline at the
end.

iex(9)> 

Where IO.puts is the equivalent of say print or echo in other languages. Now what happens when we give h() the entire IO module:

iex(9)> h IO

                                       IO                                       

Functions handling input/output (IO).

Many functions in this module expect an IO device as an argument. An IO device
must be a PID or an atom representing a process. For convenience, Elixir
provides :stdio and :stderr as shortcuts to Erlang's :standard_io and
:standard_error.

The majority of the functions expect chardata, i.e. strings or lists of
characters and strings. In case another type is given, functions will convert
to string via the String.Chars protocol (as shown in typespecs).

The functions starting with bin expect iodata as an argument, i.e. binaries or
lists of bytes and binaries.

## IO devices

An IO device may be an atom or a PID. In case it is an atom, the atom must be
the name of a registered process. In addition, Elixir provides two shortcuts:

  • :stdio - a shortcut for :standard_io, which maps to the current
    Process.group_leader/0 in Erlang
  • :stderr - a shortcut for the named process :standard_error provided in
    Erlang

IO devices maintain their position, that means subsequent calls to any reading
or writing functions will start from the place when the device was last
accessed. Position of files can be changed using the :file.position/2 function.

iex(10)> 

What more could you possibly want.

In future posts we’ll go through more examples of how to utilize iex.