Fex (fEx v0.2.0) View Source

Documentation for Fex.

This is an experimental package - do not use in production!

Many Elixir functions are returning two types of tuples:

{:ok, data}
{:error, error}

Together they maps quite closely to "either" structure. Idea is to instead of using the case function(s) to check was operation successfull:

  with {:ok, json} <- File.read("list.json"),
       {:ok, data} <- Jason.decode(json)
  do

    data
    |> Enum.sum()

  else
      Logger.error("Error occurred")
      IO.inspect(msg)
      0
  end

we could use functions that are operating on "either" looking structures:

  File.read("list.json") do
  |> Fex.chain(&Jason.decode/1)
  |> Fex.apply(&Enum.sum/1)
  |> Fex.fold(&(&1), fn msg ->
      Logger.error("Error occurred")
      IO.inspect(msg)
      0
  end)

Above approach gives some advatanges over the "usual" approach:

developer has freedom to decide when to handle the "error" case, which makes it easier to divide code to dirty and pure parts
error cases can be grouped together
code is easier to reason about with a little bit of understanding about the "either" idea

Link to this section Summary

Functions

apply(arg, function)

Applies function over data

chain(arg, function)

Like apply but doesn't wrap function in the "either" format. It relies on the fact that applied function will return the "either" format.

fold(arg, success_fn, error_fn)

When you would like to extract the pure value out of the "either" struct.

map(arg, iteration_fn)

Maps list of results using Enum.map/2

Link to this section Functions

apply(arg, function)

Applies function over data

Examples

iex> Fex.apply({:ok, [1, 2]}, &Enum.sum/1)
{:ok, 3}

iex> Fex.map({:error, "Error message"}, &Enum.sum/1)
{:error, "Error message"}

chain(arg, function)

Like apply but doesn't wrap function in the "either" format. It relies on the fact that applied function will return the "either" format.

Useful when you have an "either" structure already and you need to pass it to function that returns another "either" structure(using apply would cause "nesting" of eithers).

Examples

iex> Fex.chain({:ok, "{}"}, &Jason.decode/1)
{:ok, %{}}

iex> Fex.chain({:error, "Error message"}, &Jason.decode/1)
{:error, "Error message"}

fold(arg, success_fn, error_fn)

When you would like to extract the pure value out of the "either" struct.

Examples

iex> Fex.fold({:ok, 5}, &(&1), &(&1))
5

iex> Fex.fold({:error, "Error message"},  &(&1), &(&1))
"Error message"

map(arg, iteration_fn)

Maps list of results using Enum.map/2

Examples

iex> Fex.map({:ok, [1, 2]}, &(&1 + 2))
{:ok, [3, 4]}

iex> Fex.map({:error, "Error message"}, &(&1 + 2))
{:error, "Error message"}