defmodule Croma.Result do
@moduledoc """
A simple data structure to represent a result of computation that can either succeed or fail,
in the form of `{:ok, any}` or `{:error, any}`.
In addition to many utility functions, this module also provides implementation of
`Croma.Monad` interface for `t:Croma.Result.t/1`.
This enables the following Haskell-ish syntax:
iex> use Croma
...> Croma.Result.m do
...> x <- {:ok, 1}
...> y <- {:ok, 2}
...> pure x + y
...> end
{:ok, 3}
The above code is expanded to the code that uses `pure/1` and `bind/2`.
Croma.Result.bind({:ok, 1}, fn x ->
Croma.Result.bind({:ok, 2}, fn y ->
Croma.Result.pure(x + y)
end)
end)
This is useful when handling multiple computations that may go wrong in a short-circuit manner:
iex> use Croma
...> Croma.Result.m do
...> x <- {:error, :foo}
...> y <- {:ok, 2}
...> pure x + y
...> end
{:error, :foo}
"""
use Croma.Monad
import Croma.Defun
@type t(a, b) :: {:ok, a} | {:error, b}
@type t(a) :: t(a, any)
@type t :: t(any)
@doc """
Simply checks if the given term is ok- or error-tuple.
Using this function you can write e.g.
`r :: v[Croma.Result.t(integer)]`
in your parameter list of `defun` macro to validate `r` is of type `t:t/0`.
However note that this function only checks the outmost structure of an argument;
2nd value in the 2-tuple won't be validated for the given type parameter
(in the above example it won't verify whether `r` contains an `integer` or not).
"""
defun valid?(t :: any) :: boolean do
{:ok , _} -> true
{:error, _} -> true
_ -> false
end
@doc """
Implementation of `pure` operation of Monad (or Applicative).
Wraps the given value into a `Croma.Result`, i.e., returns `{:ok, arg}`.
"""
def pure(a), do: {:ok, a}
@doc """
Implementation of `bind` operation of Monad.
Executes the given function if the result is in `:ok` state; otherwise returns the failed result.
"""
def bind({:ok, val} , f), do: f.(val)
def bind({:error, _} = result, _), do: result
# Override default implementation to make it tail-recursive
def sequence(l) do
sequence_impl(l, [])
end
defunp sequence_impl(l :: [t(a)], acc :: [a]) :: t([a]) when a: any do
([] , acc) -> {:ok, Enum.reverse(acc)}
([h | t], acc) ->
case h do
{:ok , v} -> sequence_impl(t, [v | acc])
{:error, _} = e -> e
end
end
@doc """
Returns the value associated with `:ok` in the given result.
Returns `nil` if the result is in the form of `{:error, _}`.
## Examples
iex> Croma.Result.get({:ok, 1})
1
iex> Croma.Result.get({:error, :foo})
nil
"""
defun get(result :: t(a)) :: nil | a when a: any do
{:ok , val} -> val
{:error, _ } -> nil
end
@doc """
Returns the value associated with `:ok` in the given result.
Returns `default` if the result is in the form of `{:error, _}`.
## Examples
iex> Croma.Result.get({:ok, 1}, 0)
1
iex> Croma.Result.get({:error, :foo}, 0)
0
"""
defun get(result :: t(a), default :: a) :: a when a: any do
({:ok , val}, _ ) -> val
({:error, _ }, default) -> default
end
@doc """
Returns the value associated with `:ok` in the given result.
Raises `ArgumentError` if the result is in the form of `{:error, _}`.
## Examples
iex> Croma.Result.get!({:ok, 1})
1
iex> Croma.Result.get!({:error, :foo})
** (ArgumentError) element not present: {:error, :foo}
"""
defun get!(result :: t(a)) :: a when a: any do
{:ok , val} -> val
{:error, _ } = e -> raise ArgumentError, message: "element not present: #{inspect(e)}"
end
@doc """
Returns true if the given result is in the form of `{:ok, _value}`.
"""
defun ok?(result :: t(a)) :: boolean when a: any do
{:ok , _} -> true
{:error, _} -> false
end
@doc """
Returns true if the given result is in the form of `{:error, _}`.
"""
defun error?(result :: t(a)) :: boolean when a: any do
!ok?(result)
end
@doc """
Executes the given function within a try-rescue block and wraps the return value as `{:ok, retval}`.
If the function raises an exception, `try/1` returns the exception in the form of `{:error, exception}`.
## Examples
iex> Croma.Result.try(fn -> 1 + 1 end)
{:ok, 2}
iex> Croma.Result.try(fn -> raise "foo" end)
{:error, %RuntimeError{message: "foo"}}
"""
defun try(f :: (-> a)) :: t(a) when a: any do
try do
{:ok, f.()}
rescue
e -> {:error, {e, [:try]}}
end
end
@doc """
Tries to take one result in `:ok` state from the given two.
If the first result is in `:ok` state it is returned.
Otherwise the second result is returned.
Note that `or_else/2` is a macro instead of a function in order to short-circuit evaluation of the second argument,
i.e. the second argument is evaluated only when the first argument is in `:error` state.
"""
defmacro or_else(result1, result2) do
quote do
case unquote(result1) do
{:ok , _} = r1 -> r1
{:error, _} -> unquote(result2)
end
end
end
@doc """
Transforms a result by applying a function to its contained `:error` value.
If the given result is in `:ok` state it is returned without using the given function.
"""
defun map_error(result :: t(a), f :: ((any) -> any)) :: t(a) when a: any do
case result do
{:error, e} -> {:error, f.(e)}
{:ok, _} = r -> r
end
end
@doc """
Wraps a given value in an `:ok` tuple if `mod.valid?/1` returns true for the value.
Otherwise returns an `:error` tuple.
"""
defun wrap_if_valid(v :: a, mod :: module) :: t(a) when a: any do
case mod.valid?(v) do
true -> {:ok, v}
false -> {:error, {:invalid_value, [mod]}}
end
end
@doc """
Based on existing functions that return `Croma.Result.t(any)`, defines functions that raise on error.
Each generated function simply calls the specified function and then passes the returned value to `Croma.Result.get!/1`.
## Examples
iex> defmodule M do
...> def f(a) do
...> {:ok, a + 1}
...> end
...> Croma.Result.define_bang_version_of(f: 1)
...> end
iex> M.f(1)
{:ok, 2}
iex> M.f!(1)
2
If appropriate spec of original function is available, spec of the bang version is also declared.
For functions that have default arguments it's necessary to explicitly pass all arities to `Croma.Result.define_bang_version_of/1`.
"""
defmacro define_bang_version_of(name_arity_pairs) do
quote bind_quoted: [name_arity_pairs: name_arity_pairs, caller: Macro.escape(__CALLER__)] do
specs = Croma.TypeUtil.fetch_spec_info_at_compile_time(__MODULE__)
Enum.each(name_arity_pairs, fn {name, arity} ->
spec = Enum.find_value(specs, &Croma.Result.Impl.match_and_convert_spec(name, arity, &1, caller))
if spec do
@spec unquote(spec)
end
vars = Croma.Result.Impl.make_vars(arity, __MODULE__)
def unquote(:"#{name}!")(unquote_splicing(vars)) do
unquote(name)(unquote_splicing(vars)) |> Croma.Result.get!()
end
end)
end
end
defmodule Impl do
@moduledoc false
def match_and_convert_spec(name, arity, spec, caller_env) do
case spec do
{:::, meta1, [{^name, meta2, args}, ret_type]} when length(args) == arity ->
convert(name, meta1, meta2, args, ret_type, caller_env)
_ ->
nil
end
end
defp convert(name, meta1, meta2, args, ret_type, caller_env) do
make_spec_fun = fn r -> {:::, meta1, [{:"#{name}!", meta2, args}, r]} end
case ret_type do
{:ok, r} -> make_spec_fun.(r)
{:|, _, types} ->
Enum.find_value(types, fn
{:ok, r} -> make_spec_fun.(r)
_ -> nil
end)
{{:., _, [mod_alias, :t]}, _, r} ->
if Macro.expand(mod_alias, caller_env) == Croma.Result, do: make_spec_fun.(hd(r)), else: nil
_ -> nil
end
end
def make_vars(n, module) do
if n == 0 do
[]
else
Enum.map(0 .. n-1, fn i -> Macro.var(String.to_atom("arg#{i}"), module) end)
end
end
end
defmodule ErrorReason do
@moduledoc false
@type context :: module | {module, atom}
defun add_context(reason :: term, context :: context) :: {term, [context]} do
({reason, contexts}, context) -> {reason, [context | contexts]}
(term , context) -> {term , [context ]}
end
end
end
