Elixir Cookbook

To get started, we need to have Elixir installed. Instructions on how to install Elixir can be found at http://elixir-lang.org/install.html. This page covers installation on OSX, Unix and Unix-like systems, and Windows. It also gives some instructions on how to install Erlang, which is the only prerequisite to run Elixir.

To prototype and test the ideas using IEx, follow these steps:

IEx evaluates expressions as they are typed, allowing us to get instant feedback. This allows and encourages experimenting ideas without the overhead of editing a source file and compiling it in order to see any changes made.

It is possible to define modules inside an IEx session.

In this recipe, we will be importing two files that define the Greeter and Echoer modules into our IEx session.

In the following lines, we will list the contents of these modules:

code\greeter.ex
defmodule Greeter do

  def greet(name \\ "you") do
    "Hello #{name} !"
  end

end

code/echoer.ex
defmodule Echoer do

  def echo(msg) do
    IO.puts "#{msg} ... #{msg} ...... #{msg}"
  end

end

We will follow these steps to load and compile the modules:

When c("file_name.ex") is invoked from IEx, the file is loaded and compiled (a corresponding file with the .beam extension will be created).

The module (or modules) defined on each imported file become available. It is possible to invoke functions on these modules using the ModuleName.function_name(args) syntax.

If a module_name.beam file exists for a given module, then every time you import that module into an IEx session, you will see the following warning:

module_name.ex:1: warning: redefining module ModuleName

The warning means that a new compiled .beam file is being created, potentially redefining the module. If no changes were made to the source code, the code will be the same, although the warning is still issued.

In step 6, the pipe operator (|>) is used to simplify the code. This operator means that the output of the left operation will be fed as the first argument to the right operation.

This is equivalent to writing the following:

Echoer.echo(Greeter.greet("Me"))

In steps 2 and 3, the greeter.ex and echoer.ex files are imported without indicating the path because they are under the same directory from where the IEx session was started.

It is possible to use relative or full paths when loading files:

We will follow these steps to get help and access documentation in an IEx session:

When we define modules, it is possible to use the @moduledoc and @doc annotations to define documentation related to the whole module or to a specific function in that module.

IEx parses the documentation defined with these annotations and makes it available in a convenient way so that there's no need to leave the session when help or some more information is needed.

IEx itself has several helper functions defined (refer to the first screenshot of this recipe), and among them, we find h/0 and h/1.

There are several defined functions that allow accessing information on function specifications and types (if defined). To learn more, you can use s/1 and t/1.

As an example, to get information on the types defined for the Enum module, we would use t(Enum), and to get information on the specifications, we would use s(Enum).

To use Erlang code in Elixir, we start a new IEx session.

These are some examples of how to invoke Erlang code from Elixir:

In Elixir, Erlang modules are represented as atoms. Functions in these modules are invoked in the same way as any Elixir function.

Existing Erlang libraries can be included in Elixir applications, widening the available options. It is also possible to choose an Erlang implementation of a module over Elixir's.

The Elixir standard library has a List module defined. The Erlang counterpart is lists.

If we wish to get the last element of a list, we could use both modules:

Start a new IEx session.

We will follow these steps to get information on our running system:

As we saw in the previous recipe, Using Erlang from Elixir, it is possible to seamlessly call Erlang code from Elixir. Even though there is no specific Elixir code to perform these inspections, it is easy to get these abilities via Erlang libraries.

Start an IEx session.

To use the Observer GUI application, we will follow these steps:

To create a new Elixir application, follow these steps:

The Elixir application is ready to be used either on your local machine or, if a node is started, it could even be used from another machine.

The Elixir installation provides a command-line tool called Mix. Mix is a build tool. With this tool, it is possible to invoke several tasks to create applications, manage their dependencies, run them, and more.

Mix even allows the creation of custom tasks.

To add a dependency to our application, we will follow these steps:

Dependencies are preferably added using hex.pm (https://hex.pm/).

{:httpoison, github: " edgurgel/httpoison "} 

 {:httpotion, path: "path/to/httpotion"}

Once the dependencies are declared inside the mix.exs file, there are Mix tasks to get, compile, and clean them. The dependencies are then fetched, and if these dependencies have more dependencies on themselves, Mix is smart enough to fetch them.

When compiling dependencies, Mix is also capable of figuring out whether any dependent application has its own dependencies and whether they need to be compiled.

Starting IEx with the –S Mix loads the Mix environment inside IEx, and the application becomes accessible.

As shown in the Inspecting your system recipe, it is possible to get a list of running applications and check whether our dependency (and its own dependencies) are running. In the particular case of HTTPoison, automatic start is ensured by adding the atom representing the application name to the list under applications ([applications: [:logger, :httpoison]]).

To generate an application with a supervision tree and an application module callback, we run mix new supervised_app –-sup in the command line. This is shown in the following screenshot:

When mix new task is invoked with the –-sup option, although the generated application appears to be identical to the application created in the Creating a simple application recipe, a few things change, which are as follows:

supervised_app/mix.exs
def application do
  [applications: [:logger],
  mod: {SupervisedApp, []}]
end

An application module callback is added like this:

supervised_app/lib/supervised_app.ex
defmodule SupervisedApp do
  use Application
  def start(_type, _args) do
    import Supervisor.Spec, warn: false
    children = [
      # Define workers and child supervisors to be supervised
      # worker(SupervisedApp.Worker, [arg1, arg2, arg3])
    ]
    opts = [strategy: :one_for_one, name: SupervisedApp.Supervisor]
    Supervisor.start_link(children, opts)
  end
end

The Application module behavior is declared, and a start function must be defined to comply with this behavior. Inside the start function, a list of children (usually worker processes) is declared, and so are the supervision options (opts). The supervisor is then started, passing the list of processes to be supervised and the options.

By generating this structure of the application with subprojects under the apps directory, Elixir makes dependency management, compilation, and testing easier. It is possible to perform these tasks at the umbrella application level, affecting all the subprojects, or at each subproject level, allowing a high level of granularity.

To manage an application configuration, we follow these steps:

When we include the last line in config.exs (import_config "#{Mix.env}.exs"), the Mix configuration is loaded from the files, in this case with the Mix environment as its name and .exs as its extension.

The configuration from the imported files will override any existing configuration (with the same key) in the config.exs file. In fact, Configuration values are merged recursively. See the example at https://github.com/alco/mix-config-example.

To access configuration values, we use Application.get_env(:app, :key).

The steps required to create a custom task are as follows:

Mix tasks are just modules that are declared as Mix.Tasks.<MODULENAME> with a run function defined.

In meminfo.ex, we use the Mix.Task module by declaring use Mix.Task. The use directive allows us to use a given module in the current context.

The @shortdoc attribute allows us to define a short description to display when some help on Mix or the mix.task is displayed.

The run/1 function is the place where all of the task's work is done. In this particular case, we use an Erlang function to return a keyword list with several entries, and print them for the user in a formatted way.