View Source Croma.Result (croma v0.11.3)
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 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}Link to this section Summary
Functions
Default implementation of Applicative's ap operation.
Modules that implement Croma.Monad may override this default implementation.
Note that the order of arguments is different from the Haskell counterpart, in order to leverage Elixir's pipe operator |>.
Implementation of bind operation of Monad.
Executes the given function if the result is in :ok state; otherwise returns the failed result.
Based on existing functions that return Croma.Result.t(any), defines functions that raise on error.
Returns true if the given result is in the form of {:error, _}.
Returns the value associated with :ok in the given result.
Returns nil if the result is in the form of {:error, _}.
Returns the value associated with :ok in the given result.
Returns default if the result is in the form of {:error, _}.
Returns the value associated with :ok in the given result.
Raises ArgumentError if the result is in the form of {:error, _}.
A macro that provides Hakell-like do-notation.
Default implementation of Functor's fmap operation.
Modules that implement Croma.Monad may override this default implementation.
Note that the order of arguments is different from the Haskell counterpart, in order to leverage Elixir's pipe operator |>.
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.
Returns true if the given result is in the form of {:ok, _value}.
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.
Implementation of pure operation of Monad (or Applicative).
Wraps the given value into a Croma.Result, i.e., returns {:ok, arg}.
Converts the given list of monadic (to be precise, applicative) objects into a monadic object that contains a single list.
Modules that implement Croma.Monad may override this default implementation.
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}.
Simply checks if the given term is ok- or error-tuple.
Wraps a given value in an :ok tuple if mod.valid?/1 returns true for the value.
Otherwise returns an :error tuple.
Link to this section Types
@type t(a, b) :: {:ok, a} | {:error, b}
Link to this section Functions
Default implementation of Applicative's ap operation.
Modules that implement Croma.Monad may override this default implementation.
Note that the order of arguments is different from the Haskell counterpart, in order to leverage Elixir's pipe operator |>.
Implementation of bind operation of Monad.
Executes the given function if the result is in :ok state; otherwise returns the failed result.
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
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)
2If 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.
Returns true if the given result is in the form of {:error, _}.
Returns the value associated with :ok in the given result.
Returns nil if the result is in the form of {:error, _}.
examples
Examples
iex> Croma.Result.get({:ok, 1})
1
iex> Croma.Result.get({:error, :foo})
nilReturns the value associated with :ok in the given result.
Returns default if the result is in the form of {:error, _}.
examples
Examples
iex> Croma.Result.get({:ok, 1}, 0)
1
iex> Croma.Result.get({:error, :foo}, 0)
0Returns the value associated with :ok in the given result.
Raises ArgumentError if the result is in the form of {:error, _}.
examples
Examples
iex> Croma.Result.get!({:ok, 1})
1
iex> Croma.Result.get!({:error, :foo})
** (ArgumentError) element not present: {:error, :foo}A macro that provides Hakell-like do-notation.
examples
Examples
MonadImpl.m do
x <- mx
y <- my
pure f(x, y)
endis expanded to
MonadImpl.bind(mx, fn x ->
MonadImpl.bind(my, fn y ->
MonadImpl.pure f(x, y)
end)
end)Default implementation of Functor's fmap operation.
Modules that implement Croma.Monad may override this default implementation.
Note that the order of arguments is different from the Haskell counterpart, in order to leverage Elixir's pipe operator |>.
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.
Returns true if the given result is in the form of {:ok, _value}.
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.
Implementation of pure operation of Monad (or Applicative).
Wraps the given value into a Croma.Result, i.e., returns {:ok, arg}.
Converts the given list of monadic (to be precise, applicative) objects into a monadic object that contains a single list.
Modules that implement Croma.Monad may override this default implementation.
examples-using-croma-result
Examples (using Croma.Result)
iex> Croma.Result.sequence([{:ok, 1}, {:ok, 2}, {:ok, 3}])
{:ok, [1, 2, 3]}
iex> Croma.Result.sequence([{:ok, 1}, {:error, :foo}, {:ok, 3}])
{:error, :foo}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
Examples
iex> Croma.Result.try(fn -> 1 + 1 end)
{:ok, 2}
iex> Croma.Result.try(fn -> raise "foo" end)
{:error, %RuntimeError{message: "foo"}}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/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).
Wraps a given value in an :ok tuple if mod.valid?/1 returns true for the value.
Otherwise returns an :error tuple.