README
¶
eloc
Add a stack trace to Go's errors so that their origin can be easily located.
Documentation
¶
Overview ¶
Package eloc provides tools to add a stack trace to errors so that their origin can be easily located.
As described in the "Errors" section of Effective Go, it is good practice for library authors to add enough context to an error string to identify its origin. Since a library's implementation should be hidden behind its well-defined interface, library authors should not misuse eloc as an excuse for bad error messages to library users. References to the stack of a library contradict the above idea of encapsulation. Rather, eloc should be seen as a helpful addition during the development of the library.
This advice is also recommended to developers of executables! However, compromises may be more tolerable here.
Controlling the Stack Trace ¶
Package eloc allows you to set how invasive the use of eloc is for a package. This can be done in the programme code via Disabled and ErrorFmt. In an application, Disabled and ErrorFmt can also be controlled via the GO_ELOC environment variable:
off: No stack information is added to errors
frame: Only the frame that called an eloc function is added to the error (FmtFrame)
stack: The complete stack is added to the error an printed line by line (FmtStack)
short_stack: The complete stack is added to the error and printed in compact inline format (FmtShortStack)
To completely opt-out from stack-enriched errors compile with the Go build tag eloc_off.
Index ¶
- func At(err error) error
- func Errorf(format string, a ...any) error
- func FmtFrame(w io.Writer, err *Error)
- func FmtShortStack(w io.Writer, err *Error)
- func FmtStack(w io.Writer, err *Error)
- func Frame(err error) runtime.Frame
- func New(text string) error
- func ParseEnv(s string) error
- func Ret[R any](v R, err error) (R, error)
- func Stack(err error, do func(*runtime.Frame) (cont bool))
- type Error
- type Formatter
- type FormatterFunc
- type ShortStack
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FmtShortStack ¶
func New ¶
New is like errors.New but augments the error with the current location.
Types ¶
type Formatter ¶
var ( // Disabled allows to disable/enable all error location handling through // eloc. If this runtime switch is not enough one can also use the Go build // tag 'eloc_off' to remove eloc location handling during comiple time. In // that case setting Disabled has no effect. Disabled atomic.Bool ErrorFmt Formatter = FormatterFunc(FmtShortStack) )
type FormatterFunc ¶
type ShortStack ¶
type ShortStack struct {
// contains filtered or unexported fields
}
func (*ShortStack) String ¶
func (s *ShortStack) String() string
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package must is an experiment to see if a concise way to work with panics will break Go's convention to explicitly check for errors as described in https://blog.golang.org/error-handling-and-go.
|
Package must is an experiment to see if a concise way to work with panics will break Go's convention to explicitly check for errors as described in https://blog.golang.org/error-handling-and-go. |