MscmpSystError exception (mscmp_syst_error v0.1.0)

API for defining a standard for error handling and reporting.

This module defines a nested structure for reporting errors in contexts where a result should be represented by an error result. By capturing lower level errors and reporting them in a standard way, various application errors, especially non-fatal errors, can be handled as appropriate and logged for later analysis.

The basic form of a reportable application error is: {:error, %MscmpSystError{}} where %MscmpSystError{} contains basic fields to identify the kind of error, the source of the error, and other error related data.

Functions in this API are used to work with the returned exception.

Summary

Error Parsing

get_root_cause(error)

Returns the root cause of an MscmpSystError exception object.

Types

t()

Defines a nestable exception format for reporting MuseBMS application exceptions.

Error Parsing

get_root_cause(error)

@spec get_root_cause(any()) :: any()

Returns the root cause of an MscmpSystError exception object.

The MscmpSystError exception handling framework allows for nested exceptions to be reported stack trace style from lower levels of the application where an exception was caused into higher levels of the application which enter a failure state due to the lower level root cause.

This function will traverse the nesting and return the bottom most Error Struct. If some other object, such as a standard error tuple is passed to the function, the function will simply return the value.

Examples

iex> my_err = %MscmpSystError{
...>            code:    :example_error,
...>            message: "Outer error message",
...>            cause:    %MscmpSystError{
...>                        code:    :example_error,
...>                        message: "Intermediate error message",
...>                        cause:    %MscmpSystError{
...>                                    code:    :example_error,
...>                                    message: "Root error message",
...>                                    cause:    {:error, "Example Error"},
...>                                  },
...>                      },
...>          }
iex> MscmpSystError.get_root_cause(my_err)
%MscmpSystError{
  code:     :example_error,
  message:  "Root error message",
  cause:    {:error, "Example Error"}
}

iex> MscmpSystError.get_root_cause({:error, "Example Error"})
{:error, "Example Error"}

Types

t()

@type t() :: %MscmpSystError{
  __exception__: true,
  cause: any(),
  code: MscmpSystError.Types.mscmp_error(),
  message: String.t()
}

Defines a nestable exception format for reporting MuseBMS application exceptions.

Fields in the exception are:

code - classifies the error into a specific kind of exception likely to be seen in application. Useful for pattern matching, logging, and determining if any raised exception should be handled or not.
message - the text description of the error condition. This should be meaningful to humans.
cause - includes information that may be helpful in understanding the cause of the error condition. This could include nested t:MscmpSystError/0 objects, exception data created outside of this exception framework, or pertinent data such as parameters and data that is directly related to the exception.