README
¶
errutil
errutil is a lightweight Go utility package for structured error handling.
It provides two distinct semantic styles for wrapping errors:
- Explanatory wrapping — Adds human-readable meaning or interpretation to an error, clarifying what went wrong in business or logical terms.
- Stack wrapping — Adds contextual call-path information, showing where in the call chain the error was propagated.
These two patterns serve different purposes:
- Explanatory errors are user-facing and semantic:
e.g.
"failed to load configuration: file not found" - Stack errors are developer-facing and structural:
e.g.
"InitService >> LoadConfig >> file not found"
The goal is to make error wrapping more expressive by clearly separating interpretation (:) from trace
path (>>).
Installation
go get github.com/lvan100/errutil
Usage
Explanatory Wrapping
Use Explain to add semantic meaning to an existing error:
err := errors.New("connection refused")
return errutil.Explain(err, "failed to connect to database")
// Output: "failed to connect to database: connection refused"
Stack Wrapping
Use Stack to add call-path context for debugging or tracing:
err := errors.New("file not found")
return errutil.Stack(err, "LoadConfig")
// Output: "LoadConfig >> file not found"
Combined Usage
Explain and Stack can be combined — first add a semantic explanation,
then attach call-path context:
baseErr := errors.New("file not found")
baseErr = errutil.Explain(baseErr, "failed to load configuration")
err := errutil.Stack(baseErr, "InitService")
// Output: "InitService >> failed to load configuration: file not found"
This pattern preserves both semantic meaning and call-path trace, making it ideal for large or layered systems.
License
This project is licensed under the Apache 2.0 License. See the LICENSE file for details.
Documentation
¶
Overview ¶
Package errutil provides lightweight utilities for structuring and wrapping errors in two distinct semantic ways:
Explanatory wrapping — adds human-readable meaning or interpretation to an error. It clarifies *what* went wrong in business or logical terms.
Stack (or Path) wrapping — adds contextual call-path information, showing *where* in the call chain the error was passed through.
These two patterns serve different purposes:
- Explanatory errors are user-facing or semantic: "cannot load configuration: file not found".
- Stack errors are developer-facing or structural: "InitService >> LoadConfig >> file not found".
The goal is to make error wrapping more expressive by separating *interpretation* (":") from *trace path* (">>").
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrForbiddenMethod = errors.New("forbidden method")
ErrForbiddenMethod is returned when a prohibited method is called.
This constant error can be used to indicate that a function or method must not be invoked under certain conditions (e.g., calling a private or restricted operation).
var ErrUnimplementedMethod = errors.New("unimplemented method")
ErrUnimplementedMethod is returned when a method or operation has not yet been implemented.
It is commonly used as a placeholder to indicate functionality that is intentionally left unimplemented or pending future development.
Functions ¶
func Explain ¶
Explain wraps an existing error by adding *explanatory semantics* — a human-readable interpretation of the underlying cause.
This function represents an "explanatory wrapping" pattern. It answers the question: “What does this error *mean* in the current context?”
Example:
err := errors.New("connection refused")
return errutil.Explain(err, "failed to connect to database")
Output error message:
"failed to connect to database: connection refused"
Core idea:
- Uses ":" to denote *semantic interpretation*
- Adds contextual meaning for upper-level business logic
- Transforms technical errors into understandable messages
If the provided `err` is nil, Explain simply returns a new error created from the formatted message.
func Stack ¶
Stack wraps an existing error by adding *path context* — an indicator of where the error has traveled in the call chain.
This function represents a "stack-style" or "path-style" wrapping pattern. It answers the question: “Where did this error *pass through*?”
Example:
err := errors.New("file not found")
return errutil.Stack(err, "LoadConfig")
Output error message:
"LoadConfig >> file not found"
Core idea:
- Uses ">>" to denote *path or call-trace semantics*
- Emphasizes the structural flow of the error (developer-oriented)
- Does *not* change the meaning of the underlying error
Stack wrapping is useful for tracing propagation paths without redefining the logical meaning of the error.
If the provided `err` is nil, Stack returns a new error constructed from the formatted message.
Types ¶
This section is empty.
Source Files