defmodule Hike.Either do
alias __MODULE__, as: Either
@moduledoc"""
`Hike.Either` represents a value that can be one of two possibilities: either a `left` state or a `right` state.
It is commonly used in error handling or when a function can return different types of
results.
Creating an Either
To create an Either instance,
you can use the `Hike.Either.right/1` and `Hike.Either.left/1` function to wrap a value in
`right` and `left` state respectively :
```elixir
iex> Hike.Either.right(5)
%Hike.Either{l_value: nil, r_value: 5, is_left?: false}
iex> Hike.Either.left("Hello")
%Hike.Either{l_value: "Hello", r_value: nil, is_left?: true}
```
```elixir
# Example can be written with `Either`
# Define a User struct
defmodule User do
@derive Jason.Encoder
defstruct [:id, :age, :name]
end
defmodule TestHike do
# Import the Hike.Either module
import Hike.Either
# Simulating a database fetch function
@spec fetch_user(number) :: Hike.Either.either(%User{}) | Hike.Either.either()
def fetch_user(id) do
# Simulating a database query to fetch a user by ID
# Returns an Either<User, string> with left(user) if the user is found
# Returns an Either<User, string> with right("User not found") if the user is not found
case id do
1 -> left(%User{id: 1, age: 30, name: "Vineet Sharma"})
2 -> left(%User{id: 2, age: 20, name: "Jane Smith"})
_ -> right("User not found")
end
end
# Function to update the user's name to uppercase if possible
# This function takes a User struct and returns an Either<User, string>
def update_name_to_uppercase(user) do
case user.name do
nil -> right("User name is missing")
name -> left(%User{user | name: String.upcase(name)})
end
end
# Function to increase the user's age by one
# This function takes a User struct and returns a real data type User with updated values.
def increase_age_by_1(user) do
%User{user | age: user.age + 1}
end
# Function to print a user struct as a JSON-represented string
def print_user_as_json(user) do
user
|> Jason.encode!()
|> IO.puts()
end
# Example: Fetching a user from the database, updating the name, and matching the result
def test_user() do
user_id = 1
# Fetch the user from the database
fetch_user(user_id)
# Update the name to uppercase using bind
|> bind_left(&update_name_to_uppercase/1)
# Increase the age by one using map
|> map_left(&increase_age_by_1/1)
# Print the user as a JSON string using map
|> map_left(&print_user_as_json/1)
# finally match the respective result with a appropriate function.
|> match(fn x -> x end, fn err ->err end)
user_id = 3
# Fetch the user from the database
fetch_user(user_id)
# Update the name to uppercase using bind
|> bind_left(&update_name_to_uppercase/1)
# Increase the age by one using map
|> map_left(&increase_age_by_1/1)
# Print the user as a JSON string using map
|> map_left(&print_user_as_json/1)
# finally match the respective result with a appropriate function.
|> match(fn x -> x end, fn err -> err end)
end
end
```
```shell
#output
iex> TestHike.test_user
#user_id = 1
{"age":31,"id":1,"name":"VINEET SHARMA"}
#user_id = 3
"User not found"
```
"""
@typedoc """
generic input type `<T>`.
"""
@type t :: any()
@typedoc """
generic return type `<TR>`.
"""
@type tr :: any()
@typedoc """
`func()` represent a function which take no parameter and return value of type `<TR>`.
"""
@type func :: (() -> tr)
@typedoc """
`func(t)` represent a function which take a parameter of type `<T>`
and return a value of type `<TR>`.
"""
@type func(t) :: (t -> tr)
@typedoc """
`mapper()` represent a mapping function which take no parameter and return
a value of type `<TR>`.
"""
@type mapper :: (() -> tr)
@typedoc """
`mapper(t)` represent a mapping function which take a parameter of type `<T>`
and return a value of type `<TR>`.
"""
@type mapper(t) :: (t -> tr)
@typedoc """
`binder()` represent a binding(mapping) function which take no parameter and
return an Either of type `<TR>`.
## Example
iex> right_bind_func = fn () -> Either.right(:ok) end
iex> left_bind_func = fn () -> Either.left(:ok) end
"""
@type binder :: (() -> either_left(tr) | either_right(tr))
@typedoc """
`binder(t)` represent a binding(mapping) function which take a parameter of type `<T>`
and return an `Either` of type `<TR>`.
## Example
iex> right_bind_func = fn (x) -> Either.right(x) end
iex> left_bind_func = fn (y) -> Either.left(y) end
"""
@type binder(t) :: (t -> either_left(tr) | either_right(tr))
@typedoc """
generic input type `<T_Left>` represent a type of value on `Left`state.
"""
@type t_left :: any()
@typedoc """
generic input type `<T_Right>`represent a type of value on `Right`state.
"""
@type t_right :: any()
@typedoc """
represent a type of `Either` that could be in either `Left` or `Right` state
with a value of given type.
"""
@type either(t_left, t_right) :: %__MODULE__{
l_value: t_left,
r_value: t_right,
is_left?: boolean()
}
@typedoc """
represent a type of `Either` that could be in either `Left` or `Right` state
"""
@opaque either() :: %__MODULE__{
l_value: t_left(),
r_value: t_right(),
is_left?: boolean()
}
@typedoc """
Elevated data type of `Either` struct that represents `Right` state.
"""
@type either_right :: %__MODULE__{
l_value: nil,
r_value: t_right(),
is_left?: false
}
@typedoc """
Elevated data type of `Either` struct that represents `Right` state and have a value of type `<T>`.
"""
@type either_right(t) :: %__MODULE__{
l_value: nil,
r_value: t,
is_left?: false
}
@typedoc """
represent a type of `Either` in `Left` state.
"""
@type either_left :: %__MODULE__{
l_value: t_left(),
r_value: nil,
is_left?: true
}
@typedoc """
represent a type of `Either` in `Left` state.
"""
@type either_left(t) :: %__MODULE__{
l_value: t,
r_value: nil,
is_left?: true
}
@doc """
`%Hike.Either{l_value: t_left(), r_value: t_right(), is_left?:boolean()}` is a struct that represents an "either/or" value.
It can contain either a `left` value or a `right` value, but not both.
* `l_value`: the left value (if `is_left?` is true)
* `r_value`: the right value (if `is_left?` is false)
* `is_left?`: a boolean flag indicating whether the value is a left value (`true`) or a right value (`false`)
"""
defstruct [:l_value, :r_value, :is_left?]
defmacro is_not_nil(value) do
quote do
unquote(value) !== nil
end
end
@doc """
Creates a new Left Either object with a given value for the left side.
## Examples
iex> left("foo bar")
%Hike.Either{l_value: "foo bar", r_value: nil, is_left?: true}
"""
@spec left(t_left) :: Either.either_left(t_left)
def left(value) when is_not_nil(value),
do: %__MODULE__{l_value: value, r_value: nil, is_left?: true}
def left(nil), do: raise(ArgumentError, message: "Left value cannot be nil")
@doc """
Creates a new `Either` in `Right` state with a given value.
## Examples
iex> right("foo bar")
%Hike.Either{l_value: nil, r_value: "foo bar", is_left?: false}
"""
@spec right(t_right()) :: Either.either_right(t_right)
def right(value) when is_not_nil(value),
do: %__MODULE__{l_value: nil, r_value: value, is_left?: false}
def right(nil), do: raise(ArgumentError, message: "Right value cannot be nil")
@doc """
Check whether an`either` is in `Left` state or not .
## Examples
iex> right("foo bar") |> Either.is_left?()
false
iex> left("foo bar") |> Either.is_left?()
true
"""
@spec is_left?(Either.either()) :: boolean()
def is_left?(%__MODULE__{is_left?: true} = _either), do: true
def is_left?(_), do: false
@doc """
Check whether an`either` is in `Right` state or not .
## Examples
iex> right("foo bar") |> Either.is_right?()
true
iex> left("foo bar") |> Either.is_right?()
false
"""
@spec is_right?(Either.either()) :: boolean()
def is_right?(%__MODULE__{is_left?: false} = _either), do: true
def is_right?(_), do: false
@doc """
`apply_left` applies a given function to a given `Either` if `Either` is in left state and
return a new `Either` with new transformed value in `Left` state
else return new `Either` in `Right` state with existing right value.
## Examples
iex> (Either.left 5) |> Either.apply_left(fn num -> num + num end)
%Hike.Either{l_value: 10, r_value: nil, is_left?: true}
iex> (Either.right 5) |> Either.apply_left(fn num -> num + num end)
%Hike.Either{l_value: nil, r_value: 5, is_left?: false}
"""
@spec apply_left(Either.either_left(t_left()), (t_left() -> tr())) :: Either.either_left(tr())
def apply_left(%__MODULE__{l_value: l_value, is_left?: true} = _either, func)
when is_function(func, 1),
do: func.(l_value) |> left
@spec apply_left(Either.either_right(t_right), (t_left() -> tr())) ::
Either.either_right(t_right())
def apply_left(%__MODULE__{r_value: r_value, is_left?: false} = _either, _func),
do: r_value |> right
@doc """
`apply_right` applies a given function to a given `Either` if `Either` is in right state and
return a new `Either` with new transformed value in `Right` state
else return new `Either` in `Left` state with existing left value.
## Examples
iex> (Either.right "hello") |> Either.apply_right(fn str -> String.upcase(str) end)
%Hike.Either{l_value: nil, r_value: "HELLO", is_left?: false}
iex> (Either.left "hello") |> Either.apply_right(fn str -> String.upcase(str) end)
%Hike.Either{l_value: "hello", r_value: nil, is_left?: true}
"""
@spec apply_right(Either.either_left(t_left), (t_right() -> tr())) ::
Either.either_left(t_left())
def apply_right(%__MODULE__{l_value: l_value, is_left?: true} = _either, func)
when is_function(func, 1),
do: l_value |> left
@spec apply_right(Either.either_right(t_right()), (t_right() -> tr)) ::
Either.either_right(tr())
def apply_right(%__MODULE__{r_value: r_value, is_left?: false} = _either, func)
when is_function(func, 1),
do: func.(r_value) |> right
@doc """
Maps the value of the `Either` from left state using the given function.
If the `Either` is in the right state, the function returns the `Either`
unchanged. If the `Either` is in the left state, the function applies the
given function to the value of the left state, and returns a new `Either`
with the transformed value.
## Examples
iex> (Either.left 5) |> Either.map_left(fn num -> num + num end)
%Hike.Either{l_value: 10, r_value: nil, is_left?: true}
iex> (Either.right 5) |> Either.map_left(fn num -> num + num end)
%Hike.Either{l_value: nil, r_value: 5, is_left?: false}
iex> either = %Either{l_value: "hello", is_left?: true}
iex> new_either = Either.map_left(either, &String.upcase/1)
%Hike.Either{l_value: "HELLO", is_left?: true}
iex> either = %Either{r_value: 10, is_left?: false}
iex> new_either = Either.map_left(either, &String.downcase/1)
%Hike.Either{r_value: 10, is_left?: false}
"""
@spec map_left(Either.either_left(t_left()), (t_left() -> tr())) :: Either.either_left(tr())
def map_left(%__MODULE__{l_value: l, r_value: _r, is_left?: true} = _e, func)
when is_function(func, 1) do
left(func.(l))
end
@spec map_left(Either.either_right(t_right()), (t_left() -> tr())) ::
Either.either_right(t_right())
def map_left(%__MODULE__{l_value: _l, r_value: r, is_left?: false} = _e, _f) do
right(r)
end
@doc """
Maps the value of the`Either` from right state using the given function.
If the `Either` is in the left state, the function returns the `Either`
unchanged. If the `Either` is in the right state, the function applies the
given function to the value of the right state, and returns a new `Either`
with the transformed value.
## Examples
iex> (Either.right "hello") |> Either.map_right(fn str -> String.upcase(str) end)
%Hike.Either{l_value: nil, r_value: "HELLO", is_left?: false}
iex> (Either.left "hello") |> Either.map_right(fn str -> String.upcase(str) end)
%Hike.Either{l_value: "hello", r_value: nil, is_left?: true}
"""
@spec map_right(Either.either_right(t_right()), (t_right -> tr())) :: Either.either_right(tr())
def map_right(%__MODULE__{l_value: _l, r_value: r, is_left?: false} = _either, func)
when is_function(func, 1),
do: func.(r) |> right
@spec map_right(Either.either_left(t_left()), (t_right -> tr())) :: Either.either_left(t_left())
def map_right(%__MODULE__{l_value: l, r_value: _r, is_left?: true} = _either, _func),
do: left(l)
@doc """
Binds a function that returns an `Either` value for an `Either` in the left state.
If the input Either is in the right state,
the function is not executed and the input Either is returned as is.
## Examples
iex> (Either.left "hello") |> Either.bind_left(fn str -> Either.left(String.upcase(str)) end)
%Hike.Either{l_value: "HELLO", r_value: nil, is_left?: true}
iex> (Either.left "hello") |> Either.bind_left(fn str -> Either.right(String.upcase(str)) end)
%Hike.Either{l_value: nil, r_value: "HELLO", is_left?: false}
iex> (Either.right "hello") |> Either.bind_left(fn str -> Either.left(String.upcase(str)) end)
%Hike.Either{l_value: nil, r_value: "hello", is_left?: false}
"""
@spec bind_left(Either.either_left(t_left), binder(t_left)) ::
Either.either_left(tr) | Either.either_right(tr)
def bind_left(%__MODULE__{l_value: l_val, is_left?: true} = _either, func)
when is_function(func, 1),
do: func.(l_val)
@spec bind_left(Either.either_right(t_right()), binder(t_left)) ::
Either.either_right(t_right())
def bind_left(%__MODULE__{l_value: _l_val, r_value: r_val, is_left?: false} = _either, _func),
do: right(r_val)
@doc """
Binds a function that returns an Either value to an Either in the right state.
If the input Either is in the left state,
the function is not executed and the input Either is returned as is.
## Examples
iex> (Either.right "hello") |> Either.bind_right(fn str -> Either.right(String.upcase(str)) end)
%Hike.Either{l_value: nil, r_value: "HELLO", is_left?: false}
iex> (Either.right "hello") |> Either.bind_right(fn str -> Either.left(String.upcase(str)) end)
%Hike.Either{l_value: "HELLO", r_value: nil, is_left?: true}
iex> (Either.left "hello") |> Either.bind_right(fn str -> Either.right(String.upcase(str)) end)
%Hike.Either{l_value: "hello", r_value: nil, is_left?: true}
"""
@spec bind_right(Either.either_right(t_right), binder(t_right)) ::
Either.either_right(tr) | Either.either_left(tr)
def bind_right(%__MODULE__{r_value: r_val, is_left?: false} = _either, func)
when is_function(func, 1),
do: func.(r_val)
@spec bind_right(Either.either_left(t_left()), binder(t_right())) ::
Either.either_left(t_left())
def bind_right(%__MODULE__{l_value: l_val, r_value: _r_val, is_left?: true}, _func),
do: left(l_val)
@doc """
Matches an `Either` value and applies the corresponding function.
## Examples
iex> (Either.left "hello") |> Either.match(fn str -> String.upcase(str) end, fn ()-> "NOT FOUND" end)
"HELLO"
iex> (Either.right 4) |> Either.match(fn num-> num * num end, fn num-> num + num end)
8
"""
@spec match(Either.either(t_left, t_right), (t_left -> tr), (t_right -> tr)) :: tr
def match(%__MODULE__{l_value: x, is_left?: true} = _either, left_fn, _)
when is_function(left_fn, 1),
do: left_fn.(x)
def match(%__MODULE__{r_value: x, is_left?: false} = _either, _, right_fn)
when is_function(right_fn, 1),
do: right_fn.(x)
@doc """
Create new Either from result. if result is `{:ok, val}` `Either` will be in
right state. else if result is `{:error, val}` `Either` will be in left state.
with respective value `val` in respective side.
"""
@spec from_result({:ok, t()}) :: either_right(t())
@spec from_result({:error, t()}) :: either_left(t())
def from_result({:error, val}), do: left(val)
def from_result({:ok, val}), do: right(val)
end
