harnais_error v0.1.0 Harnais.Error exception View Source
The Exception for the Harnais Package Family.
Many of the functions in the Harnais packages return
either {:ok, any}
or {error, error}
where error
will be an
Exception
.
Many of the errors will be instances of Harnais.Error
struct
.
Exporting the Exception
As well as supporting the usual Exception
callbacks, the package
support “exporting” the exception using Harnais.Error.export/1
.
See the exception fields :export_function
and :export_config
for
how to contol what the export does.
Exception State
The exception struct
has a number of fields
Field | Aliases |
---|---|
:message | :m, :msg |
:reason | :r |
:type | :t |
:location | :l, :loc, :ndx, :index, :i |
:value0 | :v, :v0, :value, :e, :error |
:value1 | :v1 |
:value2 | :v2 |
:message_function | |
:message_config | |
:export_function | |
:export_config |
Exception Field: :message
The explanatory message, normally a string.
Exception Field: :reason
The reason for the error; normally an Atom
.
Exception Field: :type
An aribtrary term defining the type of the error e.g. :arg
, :key
, :value
, etc
Exception Field: :location
An aribtrary term defining where the error happened.
For example this could be a key, index in a list, whatever.
Exception Field: :value0
, :value1
, :value2
Arbitrary terms identifying the cause of the error.
Three fields are useful when, for example, :value0
holds the name of
a key and :value1
and :value2
hold the values of the key that
were expected to be equal.
Sometimes :value0
holds an instance of Harnais.Error.Status
.
Exception Field: :message_function
The module implements its own Exception.message/1
callback but
this can be overridden by this field.
If supplied, it must be an arity 1 function that is passed the
struct
and must return a string.
Exception Field: :message_config
This field is used by the default Exception.message/1
formatter to
hold the fields to be included in the message. It can be overridden
to set the wanted fields.
If an explicit :message_function
function is supplied, this field
can also be used to hold configuration for it.
Exception Field: :export_function
The exception can be “exported” using Harnais.Error.export/1
which
is passed the exception struct.
The default exporter creates a Keyword
of selected fields where
the keys are the shortest alias for the field (e.g. :m
for
:message
).
A custom export function can be provided using this field.
Exception Field: :export_config
The default exporter using this field to hold the fields to be included in the export.
If a custom export function is provided, this field can be used to provide configuration for it.
Standard API
Unless otherwise specified, functions return either {:ok, status}
or {:error, error}
when error
will be an Exception..
Many functions have peer bang functions that returns either the value
in {:ok, value}
or raise the error
in {:error, error}
.
Link to this section Summary
Functions
Callback implementation for Exception.exception/1
new/1
creates an instance of the error module’s struct t
update/2
takes an instance
of the module’s struct
and an optional opts
Link to this section Types
Link to this section Functions
Callback implementation for Exception.exception/1
.
export/1
takes an instance of the module’s struct
and exports it.
A custom arity one export function can be given in the field :export_function
.
Otherwise the default export function is used which creates Keyword
with one key (:error
) whose value is a list, currently with only
one entry which is itself a Keyword
of the set fields in the
error where the keys are the short form of the full field name (e.g. :m
for :message
)
If the export works, {:ok, export}
is returned.
Examples
iex> {:ok, error} = [message: "something broke", type: :arg, value: 42] |> new
...> error |> export
{:ok, [error: [[m: "something broke", t: :arg, v: 42]]]}
iex> export_fun = fn error -> {:ok, error.value} end
...> {:ok, error} = [export_function: export_fun, message: "something broke", type: :arg, value: 42] |> new
...> error |> export
{:ok, 42}
new/1
creates an instance of the error module’s struct t
.
If the opts
are not empty, it calls update/2
with t
and the opts
.
Either {:ok, t}
or {:error, error}
is returned where error
is
an exception generated during the creation.
Examples
iex> {:ok, t} = new()
...> match?(%Harnais.Error{}, t)
true
iex> {:ok, t} = new(m: "failed again", r: :usual_cause, v: 42)
...> t |> Exception.message
"failed again, reason=:usual_cause, got: 42"
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.