Documentation
¶
Overview ¶
Package errors implements the Terramate standard error type. It's heavily influenced by Rob Pike `errors` package in the Upspin project:
https://commandcenter.blogspot.com/2017/12/error-handling-in-upspin.html
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Error ¶
type Error struct {
// Kind is the kind of error.
Kind Kind
// Description of the error.
Description string
// FileRange holds the error source.
FileRange hcl.Range
// Err holds the underlying error.
Err error
}
Error is the default Terramate error type. At least one of the error fields must be set. See E() for its usage.
func E ¶
func E(args ...interface{}) *Error
E builds an error value from its arguments. There must be at least one argument or E panics. The type of each argument determines its meaning. Multiple underlying errors can be provided and in such case E() builds a *List of errors as its underlying error. If multiple arguments of same type is presented (and it's not an underlying error type), only the last one is recorded.
The supported types are:
errors.Kind The kind of error (eg.: HCLSyntax, TerramateSchema, etc).
hcl.Range The file range where the error originated.
info.Range The file range where the error originated, with extra Terramate specific info. Currently it will be converted to an hcl.Range.
errors.StackMeta The stack that originated the error.
hcl.Diagnostics The underlying hcl error that triggered this one. Only the first hcl.Diagnostic will be used. If hcl.Range is not set, the diagnostic subject range is pulled. If the string Description is not set, the diagnostic detail field is pulled.
hcl.Diagnostic Same behavior as hcl.Diagnostics but for a single diagnostic.
string The error description. It supports formatting using the Go's fmt verbs as long as the arguments are not one of the defined types.
The underlying error types are:
*errors.List The underlying error list wrapped by this one. This error wraps all of its individual errors so they carry all the context to print them individually but keeping the wrapped error as as an *errors.List. If the list length is 1 the underlying error will be the single error inside the list, so the wrapped error will not be a *errors.List.
hcl.Diagnostics The underlying list of hcl errors wrapped by this one. This type is converted to a *List containing only the hcl.DiagError values.
hcl.Diagnostic The underlying hcl error wrapped by this one. It's ignored if its type is not hcl.DiagError. If hcl.Range is not already set, the diagnostic subject range is pulled. If the string Description is not set, the diagnostic detail field is pulled.
error The underlying error that triggered this one.
If the error is printed, only those items that have been set to non-zero values will appear in the result. For the `hcl.Range` type, the `range.Empty()` method is used.
When the underlying error is a single error, then the fields below are promoted from the underlying error when absent:
- errors.Kind - errors.StackMeta - hcl.Range
Minimization:
In order to avoid duplicated messages, if the underlying error is an *Error, we erase the fields present in it if already set with same value in this error.
func (*Error) AsList ¶ added in v0.1.2
AsList returns the error as a list. If it's underlying error is a *List, then it just returns it because they're already explicitly wrapped.
func (*Error) Is ¶
Is tells if err matches the target error. The target error must be of errors.Error type and it will try to match the following fields: - Kind - Description - Stack - FileRange Any fields absent (empty) on the target error are ignored even if they exist on err (partial match).
type Kind ¶
type Kind string
Kind defines the kind of an error.
const ( // ErrInternal indicates that an unrecoverable internal error // happened. This error kind is intended to be used when panicking. ErrInternal Kind = "terramate internal error" )
type List ¶ added in v0.1.0
type List struct {
// contains filtered or unexported fields
}
List represents a list of error instances that also implements Go's error interface.
List implements Go's errors.Is protocol matching the target error with all the errors inside it, returning true if any of the errors is a match.
func L ¶ added in v0.1.0
L builds a List instance with all errs provided as arguments. Any nil errors on errs will be discarded.
Any error of type hcl.Diagnostics will be flattened inside the error list, each hcl.Diagnostic will become an error.Error.
Any error of type errors.List will be flattened inside the error list, each will become an error.Error.
func (*List) Append ¶ added in v0.1.0
Append appends the provided errs on the error list, ignoring nil values.
Any error of type hcl.Diagnostics will have its hcl.Diagnostic elements added to the error list.
Any error of type errors.List will be flattened inside the error list.
func (*List) AppendWrap ¶ added in v0.1.11
AppendWrap is like Append() but wrap all errors with the provided kind.
func (*List) AsError ¶ added in v0.1.0
AsError returns the error list as an error instance if the errors list is non-empty. If the list is empty it will return nil.
func (*List) Detailed ¶ added in v0.1.0
Detailed returns a detailed string representation of the error list. It will return all errors contained on the list as a single string. One error per line.
func (*List) Error ¶ added in v0.1.0
Error returns the string representation of the error list. Only the first error message is returned, all other errors are elided. For a full representation of all errors use the List.Detailed method.
func (*List) Errors ¶ added in v0.1.0
Errors returns all errors contained on the list. It flattens out the wrapped error lists inside *error.Error.
func (*List) Is ¶ added in v0.1.0
Is will call errors.Is for each of the errors on its list returning true on the first match it finds or false if no error inside the list matches the given target.
If target is also an *error.List then the target list must have the same errors inside on the same order.
Source Files
Directories