Bang function for add_entries/2

Bang function for add_entry/2

add_error/2 adds a single error to the existing results.

Examples

iex> {:ok, status} = new!() |> add_error(42)
...> status |> get_results!
...> |> List.first |> elem(1) |> Exception.message
"42"

Bang function for add_error/2

add_errors/2 adds a list of errors to the existing results.

Examples

iex> new!(add_errors: [42, :got_an_error, :good_one])
...> |> export!
[error: [[v: 42]], error: [[v: :got_an_error]], error: [[v: :good_one]]]

Bang function for add_errors/2

add_ok/2 adds a single ok value to the existing results.

Examples

iex> {:ok, status} = new!() |> add_ok(42)
...> status |> export!
[ok: 42]

Bang function for add_ok/2

add_oks/2 adds a list of oks to the existing results.

Examples

iex> new!(add_oks: [42, :got_an_error, :good_one])
...> |> export!
[ok: 42, ok: :got_an_error, ok: :good_one]

Bang function for add_oks/2

add_result/2 calls add_results/2 with the List.wrap/1-ed result.

Examples

iex> {:ok, t} = new!()
...> |> add_result!({:ok, 42})
...> |> add_result!(:error)
...> |> add_result(:ok)
...> t |> get_results!
...> |> Enum.map(fn
...>    {:ok, _} = result -> result
...>    {:error, error} -> {:error, error |> Exception.message}
...> end)
[ok: 42, error: ":error", ok: :ok]

Bang function for add_result/2

add_results/2 adds new results to the existing results.

add_results/2 normalises any {:error, value} results, creating a new Harnais.Error Exception if the value is not an Exception already.

Examples

iex> {:ok, status} = new!() |> add_results(ok: 42, error: :got_an_error, ok: :good_one)
...> status |> get_results!
...> |> Enum.map(fn
...>    {:ok, _} = result -> result
...>    {:error, error} -> {:error, error |> Exception.message}
...> end)
[ok: 42, error: ":got_an_error", ok: :good_one]

iex> new!(add_results: [ok: 42, error: :got_an_error, error: %BadMapError{term: 42}])
...> |> get_results!
...> |> Enum.map(fn
...>    {:ok, _} = result -> result
...>    {:error, error} -> {:error, error |> Exception.message}
...> end)
[ok: 42, error: ":got_an_error", error: "expected a map, got: 42"]

iex> {:ok, status} = new!() |> add_results(ok: 42, error: :got_an_error, ok: :good_one)
...> status |> export!
[ok: 42, error: [[v: :got_an_error]], ok: :good_one]

iex> {:ok, status} = new!() |> add_results(ok: 42)
...> {:ok, status} = status |> add_results(error: :got_an_error, ok: :good_one)
...> status |> export!
[ok: 42, error: [[v: :got_an_error]], ok: :good_one]

Bang function for add_results/2

empty?/1 returns true if the status has no results, else false.

Examples

iex> new!() |> empty?
true

iex> new!() |> add_error!(:error1) |> add_ok!(:ok1) |> empty?
false

Callback implementation for Exception.exception/1.

export/2 takes an instance of the module’s struct and optional opts and exports it.

If the opts are not empty, update/2 is called with the struct and opts before performing the export.

A custom arity one export function can be given in the field :export_function and will be passed the struct.

Otherwise the default export function is used which exports each entry and merges the answers.

Exporting an :ok result returns [ok: value].

If an :error entry is neither a Harnais.Error nor Harnais.Error.Status, Exception.message/1 is called and [error: [m: message]] returned.

If the export works, {:ok, export} is returned.

Examples

This example shows the default exporter:

iex> new!(add_results: [ok: 42, error: :got_an_error, error: %BadMapError{term: 42}])
...> |> export
{:ok, [ok: 42, error: [[v: :got_an_error]], error: [[m: "expected a map, got: 42"]]]}

This custom exporter counts the :ok and :error entries:

iex> fun = fn %{entries: entries} ->
...>   entries
...>   |> case do
...>       x when is_list(x) ->
...>         x
...>         |> Enum.split_with(fn {verb,_} -> verb == :ok end)
...>         |> case do
...>              {oks,errors} -> {:ok, {oks |> length, errors |> length}}
...>            end
...>       _ -> {:ok, {0,0}}
...>     end
...> end
...> new!(
...>   export_function: fun,
...>   add_results: [ok: 42, error: :got_an_error, error: %BadMapError{term: 42}])
...> |> export
{:ok, {1, 2}}

Bang function for export/1

get_errors/2 returns {:ok, errors}.

Examples

iex> {:error, error} = new!() |> get_errors
 ...> error |> Exception.message
 "Harnais.Error.Status has no errors"

 iex> {:ok, errors} = new!()
 ...> |> add_result!({:ok, 42})
 ...> |> add_result!({:error, %BadMapError{term: 42}})
 ...> |> add_result!({:error, :got_an_error})
 ...> |> add_result!({:ok, :good_one})
 ...> |> get_errors
 ...> errors |> Enum.map(&Exception.message/1)
 ["expected a map, got: 42", ":got_an_error"]

Bang function for get_errors/1

get_last_error/2 returns the last ok result in the results.

If there are no results, it returns nil.

Examples

iex> {:error, error} = new!() |> get_last_error
...> error |> Exception.message
"Harnais.Error.Status has no errors"

iex> new!()
...> |> add_result!({:ok, 42})
...> |> add_result!({:error, :got_an_error})
...> |> add_result!({:ok, :good_one})
...> |> get_last_error!
...> |> Exception.message
":got_an_error"

Bang function for get_last_error/1

get_last_error_result/2 returns a the last {:ok, value} tuple in the results.

If there are no results, it returns nil.

Examples

iex> {:error, error} = new!() |> get_last_error_result
 ...> error |> Exception.message
 "Harnais.Error.Status has no errors"

 iex> {:ok, error} = new!()
 ...> |> add_result!({:ok, 42})
 ...> |> add_result!({:error, :got_an_error})
 ...> |> add_result!({:ok, :good_one})
 ...> |> get_last_error_result
 ...> error |> Exception.message
 ":got_an_error"

Bang function for get_last_error_result/1

get_last_ok/1 returns {:ok, ok} where ok is the last ok.

Examples

iex> {:error, error} = new!() |> get_last_ok
 ...> error |> Exception.message
 "Harnais.Error.Status has no oks"

 iex> new!()
 ...> |> add_result!({:ok, 42})
 ...> |> add_result!({:error, :got_an_error})
 ...> |> add_result!({:ok, :good_one})
 ...> |> get_last_ok!
 :good_one

Bang function for get_last_ok/1

get_last_ok_result/2 returns {:ok, result} where result is the last ok result.

Examples

iex> {:error, error} = new!() |> get_last_ok_result
...> error |> Exception.message
"Harnais.Error.Status has no oks"

iex> new!()
...> |> add_result!({:ok, 42})
...> |> add_result!({:error, :got_an_error})
...> |> add_result!({:ok, :good_one})
...> |> get_last_ok_result!
{:ok, :good_one}

Bang function for get_last_ok_result/1

get_last_result/2 returns a the last {:ok, value} or {:error, value} tuple in the results.

If there are no results, it returns nil.

Examples

iex> {:error, error} = new!() |> get_last_result
...> error |> Exception.message
"Harnais.Error.Status has no results"

iex> new!()
...> |> add_result!({:ok, 42})
...> |> add_result!({:error, :got_an_error})
...> |> add_result!({:ok, :good_one})
...> |> get_last_result!
{:ok, :good_one}

Bang function for get_last_result/1

get_oks/2 returns {:ok, oks}.

Examples

iex> {:error, error} = new!() |> get_oks
...> error |> Exception.message
"Harnais.Error.Status has no oks"

iex> new!()
...> |> add_result!({:ok, 42})
...> |> add_result!({:error, :got_an_error})
...> |> add_result!({:ok, :good_one})
...> |> get_oks
{:ok, [42, :good_one]}

Bang function for get_oks/1

get_results/1 returns the complete collection of results as {:ok, results}.

Examples

iex> {:error, error} = new!() |> get_results
...> error |> Exception.message
"Harnais.Error.Status has no results"

iex> {:ok, status} = new!() |> add_results([ok: 42, error: :got_an_error, ok: :good_one])
...> status |> export!
[ok: 42, error: [[v: :got_an_error]], ok: :good_one]

Bang function for get_results/1

has_errors?/1 returns true if the status has any :ok results, else false.

Examples

iex> new!() |> has_errors?
false

iex> new!() |> add_error!(:error1) |> add_ok!(:ok1) |> has_errors?
true

has_oks?/1 returns true if the status has any :ok results, else false.

Examples

iex> new!() |> has_oks?
false

iex> new!() |> add_error!(:error1) |> add_ok!(:ok1) |> has_oks?
true

has_errors?/1 returns true if the status has any results, else false.

Examples

iex> new!() |> has_results?
false

iex> new!() |> add_error!(:error1) |> add_ok!(:ok1) |> has_results?
true

message/1 is the standard Exception callback.

Examples

iex> new!() |> message
 "Harnais.Error.Status has no errors"

 iex> new!()
 ...> |> add_result!({:ok, 42})
 ...> |> add_result!({:error, :got_an_error})
 ...> |> add_result!({:ok, :good_one})
 ...> |> message
 ":got_an_error"

 iex> new!()
 ...> |> add_result!({:ok, 42})
 ...> |> add_result!({:error, :got_an_error})
 ...> |> add_result!({:ok, :good_one})
 ...> |> add_result!({:error, :another_error})
 ...> |> message
 ":got_an_error; :another_error"

new/1 creates a new instance of the status exception, returning {:ok, status}.

new/1 takes optional (Keyword) options (opts) where the keys can be one of the add_ functions (e.g. add_ok/2).

Examples

iex> {:ok, status} = new()
...> match?(%Harnais.Error.Status{}, status)
true

iex> {:ok, t} = new(
...>   add_result: {:ok, 42},
...>   add_error: :failed_miserably,
...>   add_ok: :worked_fine,
...>   add_errors: [:e1, :e2])
...> t |> export!
[ok: 42, error: [[v: :failed_miserably]], ok: :worked_fine, error: [[v: :e1]], error: [[v: :e2]]]

new!/1 calls new/1 and, if the result is {:ok, instance} returns the instance.

reset/1 reinitialised the status.

Examples

iex> {:ok, status} = new!() |> reset()
...> status |> empty?
true

iex> {:ok, status} = new!() |> add_error!(:error1) |> add_ok!(:ok1) |> reset()
...> status |> size
0

Bang function for reset/1

size/1 returns the number of results in the status.

Examples

iex> new!() |> size
0

iex> new!() |> add_error!(:error1) |> add_ok!(:ok1) |> size
2

update/2 takes an instance of the module’s struct and an optional opts.

The opts are normalised by calling the module’s update_canonical_opts/1 and then reduced with update_field/2:

opts |> Enum.reduce(instance, fn {k,v}, s -> s |> update_field({k,v}) end)

{:ok, instance} is returned.

update!/2 calls update/2 and, if the result is {:ok, instance} returns the instance.