errors

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

• func As(err error, target interface{}) bool
• func HasCode(err error, code Kind) bool
• func Is(err, target error) bool
• func IsAnyKind(err error, kinds ...Kind) bool
• func IsKind(err error, k Kind) bool
• type DetailedError
  • func D(format string, a ...any) *DetailedError
  • func (e DetailedError) Error() string
  • func (e DetailedError) Inspect(f func(i int, msg string, cause error, details []ErrorDetails))
  • func (e *DetailedError) Is(target error) bool
  • func (e *DetailedError) Unwrap() error
  • func (e *DetailedError) WithCause(cause error) *DetailedError
  • func (e *DetailedError) WithCode(code Kind) *DetailedError
  • func (e *DetailedError) WithDetails(verbosity int, format string, a ...any) *DetailedError
• type Error
  • func E(args ...interface{}) *Error
  • func (e *Error) AsList() *List
  • func (e *Error) Detailed() string
  • func (e *Error) Error() string
  • func (e *Error) Is(target error) bool
  • func (e *Error) Message() string
  • func (e *Error) Unwrap() error
• type ErrorDetails
• type Kind
• type List
  • func L(errs ...error) *List
  • func (l *List) Append(errs ...error)
  • func (l *List) AppendWrap(kind Kind, errs ...error)
  • func (l *List) AsError() error
  • func (l *List) Detailed() string
  • func (l *List) Error() string
  • func (l *List) Errors() []error
  • func (l *List) Is(target error) bool

Functions

func As

func As(err error, target interface{}) bool

As is just an alias to Go stdlib errors.As

func HasCode

func HasCode(err error, code Kind) bool

HasCode tells if the error tree rooted at err contains the given code.

func Is

func Is(err, target error) bool

Is is just an alias to Go stdlib errors.Is

func IsAnyKind

func IsAnyKind(err error, kinds ...Kind) bool

IsAnyKind returns true if err is of any of the provided kinds.

func IsKind

func IsKind(err error, k Kind) bool

IsKind tells if err is of kind k. It is a small wrapper around calling errors.Is(err, errors.Kind(k)).

Types

type DetailedError

type DetailedError struct {
	Msg     string
	Code    Kind
	Cause   error
	Details []ErrorDetails
}

DetailedError represents an error with additional detail information. These could be details about the error, hints, instructions etc. Optionally, the error might reference another error that caused it.

func D

func D(format string, a ...any) *DetailedError

D is a constructor function to create a new DetailedError with a formatted message.

func (DetailedError) Error

func (e DetailedError) Error() string

Error implements the error interface to return a string representation. It only shows the main message and ignores additional details.

func (DetailedError) Inspect

func (e DetailedError) Inspect(f func(i int, msg string, cause error, details []ErrorDetails))

Inspect traverses a hierarchy of DetailedErrors along the cause field and invokes the given traversal function with the data from each item. If the type of the error is not DetailedError, it's still passed to the traversal function, but the traversal ends. If cause is nil, the traversal ends.

func (*DetailedError) Is

func (e *DetailedError) Is(target error) bool

Is tells if e matches the target error. The target error must be of type DetailedError and it will try to match the following fields: - Msg - Details - Tags (match any) Any fields absent (empty) on the target error are ignored even if they exist on err (partial match).

func (*DetailedError) Unwrap

func (e *DetailedError) Unwrap() error

Unwrap returns the wrapped error, if there is any. Returns nil if there is no wrapped error.

func (*DetailedError) WithCause

func (e *DetailedError) WithCause(cause error) *DetailedError

WithCause sets the wrapped cause of the error. The caller is modified but also returned for convenience.

func (*DetailedError) WithCode

func (e *DetailedError) WithCode(code Kind) *DetailedError

WithCode tags the error with an error code. This field is useful for error testing. The caller is modified but also returned for convenience.

func (*DetailedError) WithDetails

func (e *DetailedError) WithDetails(verbosity int, format string, a ...any) *DetailedError

WithDetails adds details to an error with the given verbosity level. The caller is modified but also returned for convenience.

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

func (e *Error) AsList() *List

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) Detailed

func (e *Error) Detailed() string

Detailed returns a detailed error message.

func (*Error) Error

func (e *Error) Error() string

Error returns the error message.

func (*Error) Is

func (e *Error) Is(target error) bool

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).

func (*Error) Message

func (e *Error) Message() string

Message returns the error message without some metadata. This method is suitable for editor extensions that needs to handle the metadata themselves.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap returns the wrapped error, if there is any. Returns nil if there is no wrapped error.

type ErrorDetails

type ErrorDetails struct {
	Msg       string
	Verbosity int
}

ErrorDetails contains a detailed message related to an error with a verbosity level.

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

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

func L(errs ...error) *List

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

func (l *List) Append(errs ...error)

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

func (l *List) AppendWrap(kind Kind, errs ...error)

AppendWrap is like Append() but wrap all errors with the provided kind.

func (*List) AsError

func (l *List) AsError() error

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

func (l *List) Detailed() string

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

func (l *List) Error() string

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

func (l *List) Errors() []error

Errors returns all errors contained on the list. It flattens out the wrapped error lists inside *error.Error.

func (*List) Is

func (l *List) Is(target error) bool

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.