Documentation
¶
Overview ¶
Package commonerrors defines typical errors which can happen.
- Copyright (C) 2020-2026 Arm Limited or its affiliates and Contributors. All rights reserved.
- SPDX-License-Identifier: Apache-2.0
Index ¶
- Constants
- Variables
- func Any(target error, err ...error) bool
- func ConvertContextError(err error) error
- func CorrespondTo(target error, description ...string) bool
- func DescribeCircumstance(originalError error, circumstance string) error
- func DescribeCircumstanceAndKeepType(err error, circumstance string) error
- func DescribeCircumstanceAndKeepTypef(err error, circumstanceFormat string, args ...any) error
- func DescribeCircumstancef(err error, circumstanceFormat string, args ...any) error
- func DeserialiseError(text []byte) (deserialisedError, err error)
- func ErrFromContext(ctx context.Context) error
- func Errorf(targetErr error, format string, args ...any) error
- func GetCommonErrorReason(srcErr error) (reason string, err error)
- func GetErrorReason(srcErr error) (reason string, err error)
- func GetUnderlyingErrorType(srcErr error) (commonerrorType, err error)
- func Ignore(target error, ignore ...error) error
- func IgnoreCorrespondTo(target error, ignore ...string) error
- func IsCommonError(target error) bool
- func IsEmpty(err error) bool
- func IsFailure(target error) bool
- func IsWarning(target error) bool
- func Join(errs ...error) error
- func MarkAsFailure(err error) error
- func New(targetError error, msg string) error
- func NewFailure(msgFormat string, args ...any) error
- func NewWarning(target error) (ok bool, err error)
- func NewWarningMessage(msgFormat string, args ...any) error
- func Newf(targetError error, msgFormat string, args ...any) error
- func None(target error, err ...error) bool
- func ParseWarning(target error) (ok bool, err error)
- func RelatesTo(target string, errors ...error) bool
- func RetrieveCommonError(target error) (isCommonError bool, commonError error)
- func SerialiseError(err error) ([]byte, error)
- func UndefinedParameter(msg string) error
- func UndefinedParameterf(msgFormat string, args ...any) error
- func UndefinedVariable(variableName string) error
- func UndefinedVariableWithMessage(variableName string, msg string) error
- func WrapError(targetError, originalError error, msg string) error
- func WrapErrorf(targetError, originalError error, msgFormat string, args ...any) error
- func WrapIfNotCommonError(targetError, originalError error, msg string) error
- func WrapIfNotCommonErrorf(targetError, originalError error, msgFormat string, args ...any) error
Constants ¶
const ( TypeReasonErrorSeparator = ':' MultipleErrorSeparator = '\n' )
Variables ¶
var ( ErrNotImplemented = errors.New("not implemented") ErrNoExtension = errors.New("missing extension") ErrNoLogger = errors.New("missing logger") ErrNoLoggerSource = errors.New("missing logger source") ErrNoLogSource = errors.New("missing log source") ErrUndefined = errors.New("undefined") ErrInvalidDestination = errors.New("invalid destination") ErrTimeout = errors.New("timeout") ErrLocked = errors.New("locked") ErrStaleLock = errors.New("stale lock") ErrExists = errors.New("already exists") ErrNotFound = errors.New("not found") ErrUnsupported = errors.New("unsupported") ErrWrongUser = errors.New("wrong user") ErrUnknown = errors.New("unknown") ErrInvalid = errors.New("invalid") ErrConflict = errors.New("conflict") ErrMarshalling = errors.New("unserialisable") ErrCancelled = errors.New("cancelled") ErrEmpty = errors.New("empty") ErrUnexpected = errors.New("unexpected") ErrTooLarge = errors.New("too large") ErrForbidden = errors.New("forbidden") ErrCondition = errors.New("failed condition") ErrEOF = errors.New("end of file") ErrMalicious = errors.New("suspected malicious intent") ErrOutOfRange = errors.New("out of range") ErrInterrupted = errors.New("interrupted") // ErrFailed should be used as a generic error where an error is an expected and valid state. // For example a failing command may cause subprocess.Execute to return an error if the command exits with 1 but // this wouldn't be a system error, and you might want to distinguish between this and the subprocess wrapper erroring // when you pass the message up the stack. ErrFailed = errors.New(failureStr) // ErrWarning is a generic error that can be used when an error should be raised but it shouldn't necessary be // passed up the chain, for example in cases where an error should be logged but the program should continue. In // these situations it should be handled immediately and then ignored/set to nil. ErrWarning = errors.New(warningStr) )
List of common errors used to qualify and categorise go errors Note: if adding error types to this list, ensure mapping functions (below) are also updated.
Functions ¶
func ConvertContextError ¶
ConvertContextError converts a context error into common errors.
func CorrespondTo ¶
CorrespondTo determines whether a `target` error corresponds to a specific error described by `description` It will check whether the error contains the string in its description. It is not case-sensitive. ```code
CorrespondTo(errors.New("feature a is not supported"), "not supported") = True
```
func DescribeCircumstance ¶
DescribeCircumstance adds some context to a particular error. If the error is of a known type (as in, a common error), it will be kept. Otherwise, it will be set as Unexpected.
func DescribeCircumstanceAndKeepType ¶
DescribeCircumstanceAndKeepType does almost the same as DescribeCircumstance but if the error is not a common error, it won't wrap it but just add the context string to it.
func DescribeCircumstanceAndKeepTypef ¶
DescribeCircumstanceAndKeepTypef is like DescribeCircumstanceAndKeepType but uses a message format to describe the error context.
func DescribeCircumstancef ¶
DescribeCircumstancef is the same as DescribeCircumstance but uses a format for capturing the error context.
func DeserialiseError ¶
DeserialiseError unmarshals text into an error. It tries to determine the error type.
func ErrFromContext ¶
ErrFromContext extracts the error from the context. If the error has a cause that is a common error then that will be returned over the underlying context error
func Errorf ¶
Errorf is similar to fmt.Errorf although it will try to follow the error convention we use i.e. `errortype: message` but differs in that the wrapped error will be the targetErr
func GetCommonErrorReason ¶
func GetErrorReason ¶
func GetUnderlyingErrorType ¶
func IgnoreCorrespondTo ¶
IgnoreCorrespondTo will return nil if the target error matches one of the descriptions of errors to ignore
func IsCommonError ¶
IsCommonError returns whether an error is a commonerror
func IsEmpty ¶
IsEmpty states whether an error is empty or not. An error is considered empty if it is `nil` or has no description.
func IsFailure ¶
IsFailure returns whether an error is unexpected (i.e. deviation from an expected state) but not a system error e.g. test failure
func MarkAsFailure ¶
MarkAsFailure will tent an error as failure. It will retain its original error type but IsFailure should return true.
func NewFailure ¶
NewFailure creates a failure object.
func NewWarning ¶
NewWarning will create a warning wrapper around an existing commonerror so that it can be easily recovered. If the underlying error is not a commonerror then ok will be set to false
func NewWarningMessage ¶
NewWarningMessage creates a warning message.
func ParseWarning ¶
ParseWarning will extract the error that has been wrapped by ErrWarning. It will return nil if the error was not one of ErrWarning with ok set to false. It will also set ok to false if the underlying error cannot be parsed
func RelatesTo ¶
RelatesTo determines whether an error description string could relate to a particular set of common errors This assumes that the error description follows the convention of placing the type of errors at the start of the string.
func RetrieveCommonError ¶
RetrieveCommonError tries to return the common error of an error.
func SerialiseError ¶
SerialiseError marshals an error following a certain convention: `error type: reason`.
func UndefinedParameter ¶
UndefinedParameter returns an undefined error with a message
func UndefinedParameterf ¶
UndefinedParameterf returns an undefined error with a message
func UndefinedVariable ¶
UndefinedVariable returns an undefined error related to a variable.
func UndefinedVariableWithMessage ¶
UndefinedVariableWithMessage returns an undefined error with a message.
func WrapError ¶
WrapError wraps an error into a particular targetError. However, if the original error has to do with a contextual error (i.e. ErrCancelled or ErrTimeout) or should be considered as a failure rather than an error, it will be passed through without having its type changed. Same is true with warnings. This method should be used to safely wrap errors without losing information about context control information. If the target error is not set, the wrapped error will be of type ErrUnknown.
func WrapErrorf ¶
WrapErrorf is similar to WrapError but uses a format for the message
func WrapIfNotCommonError ¶
WrapIfNotCommonError is similar to WrapError but only wraps an error if it is not a common error.
Types ¶
This section is empty.