Types and specs

Elixir is a dynamically typed language, so all types in Elixir are inferred by the runtime. Nonetheless, Elixir comes with typespecs, which are a notation used for:

  1. declaring custom data types;
  2. declaring typed function signatures (specifications).

Function specifications

By default, Elixir provides some basic types, such as integer or pid, as well as more complex types: for example, the round/1 function, which rounds a float to its nearest integer, takes a number as an argument (an integer or a float) and returns an integer. As you can see in its documentation, round/1’s typed signature is written as:

round(number) :: integer

:: means that the function on the left side returns a value whose type is what’s on the right side. Function specs are written with the @spec directive, placed right before the function definition. The round/1 function could be written as:

@spec round(number) :: integer
def round(number), do: # implementation...

Elixir supports compound types as well. For example, a list of integers has type [integer]. You can see all the built-in types provided by Elixir in the typespecs docs.

Defining custom types

While Elixir provides a lot of useful built-in types, it’s convenient to define custom types when appropriate. This can be done when defining modules through the @type directive.

Say we have a LousyCalculator module, which performs the usual arithmetic operations (sum, product and so on) but, instead of returning numbers, it returns tuples with the result of an operation as the first element and a random remark as the second element.

defmodule LousyCalculator do
  @spec add(number, number) :: {number, String.t}
  def add(x, y), do: {x + y, "You need a calculator to do that?!"}

  @spec multiply(number, number) :: {number, String.t}
  def multiply(x, y), do: {x * y, "Jeez, come on!"}
end

As you can see in the example, tuples are a compound type and each tuple is identified by the types inside it. To understand why String.t is not written as string, have another look at the notes in the typespecs docs.

Defining function specs this way works, but it quickly becomes annoying since we’re repeating the type {number,String.t} over and over. We can use the @type directive in order to declare our own custom type.

defmodule LousyCalculator do
  @typedoc """
  Just a number followed by a string.
  """
  @type number_with_remark :: {number, String.t}

  @spec add(number, number) :: number_with_remark
  def add(x, y), do: {x + y, "You need a calculator to do that?"}

  @spec multiply(number, number) :: number_with_remark
  def multiply(x, y), do: {x * y, "It is like addition on steroids."}
end

The @typedoc directive, similarly to the @doc and @moduledoc directives, is used to document custom types.

Custom types defined through @type are exported and available outside the module they’re defined in:

defmodule QuietCalculator do
  @spec add(number, number) :: number
  def add(x, y), do: make_quiet(LousyCalculator.add(x, y))

  @spec make_quiet(LousyCalculator.number_with_remark) :: number
  defp make_quiet({num, _remark}), do: num
end

If you want to keep a custom type private, you can use the @typep directive instead of @type.

Static code analysis

Typespecs are not only useful to developers and as additional documentation. The Erlang tool Dialyzer, for example, uses typespecs in order to perform static analysis of code. That’s why, in the QuietCalculator example, we wrote a spec for the make_quiet/1 function even if it was defined as a private function.