README
¶
This repository holds the transition packages for the new Go 1.13 error values. See golang.org/design/29934-error-values.
Documentation
¶
Overview ¶
Package xerrors implements functions to manipulate errors.
This package is based on the Go 2 proposal for error values:
https://golang.org/design/29934-error-values
These functions were incorporated into the standard library's errors package in Go 1.13: - Is - As - Unwrap
Also, Errorf's %w verb was incorporated into fmt.Errorf.
Use this package to get equivalent behavior in all supported Go versions.
No other features of this package were included in Go 1.13, and at present there are no plans to include any of them.
Example ¶
package main
import (
"fmt"
"time"
)
// MyError is an error implementation that includes a time and message.
type MyError struct {
When time.Time
What string
}
func (e MyError) Error() string {
return fmt.Sprintf("%v: %v", e.When, e.What)
}
func oops() error {
return MyError{
time.Date(1989, 3, 15, 22, 30, 0, 0, time.UTC),
"the file system has gone away",
}
}
func main() {
if err := oops(); err != nil {
fmt.Println(err)
}
}
Output: 1989-03-15 22:30:00 +0000 UTC: the file system has gone away
Index ¶
- func As(err error, target interface{}) booldeprecated
- func Errorf(format string, a ...interface{}) error
- func FormatError(f Formatter, s fmt.State, verb rune)
- func Is(err, target error) booldeprecated
- func New(text string) error
- func Opaque(err error) error
- func Unwrap(err error) errordeprecated
- type Formatter
- type Frame
- type Printer
- type Wrapper
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func As
deprecated
As finds the first error in err's chain that matches the type to which target points, and if so, sets the target to its value and returns true. An error matches a type if it is assignable to the target type, or if it has a method As(interface{}) bool such that As(target) returns true. As will panic if target is not a non-nil pointer to a type which implements error or is of interface type.
The As method should set the target to its value and return true if err matches the type to which target points.
Deprecated: As of Go 1.13, use errors.As instead.
Example ¶
package main
import (
"fmt"
"os"
"golang.org/x/xerrors"
)
func main() {
_, err := os.Open("non-existing")
if err != nil {
var pathError *os.PathError
if xerrors.As(err, &pathError) {
fmt.Println("Failed at path:", pathError.Path)
}
}
}
Output: Failed at path: non-existing
func Errorf ¶
Errorf formats according to a format specifier and returns the string as a value that satisfies error.
The returned error includes the file and line number of the caller when formatted with additional detail enabled. If the last argument is an error the returned error's Format method will return it if the format string ends with ": %s", ": %v", or ": %w". If the last argument is an error and the format string ends with ": %w", the returned error implements an Unwrap method returning it.
If the format specifier includes a %w verb with an error operand in a position other than at the end, the returned error will still implement an Unwrap method returning the operand, but the error's Format method will not return the wrapped error.
It is invalid to include more than one %w verb or to supply it with an operand that does not implement the error interface. The %w verb is otherwise a synonym for %v.
Note that as of Go 1.13, the fmt.Errorf function will do error formatting, but it will not capture a stack backtrace.
func FormatError ¶
FormatError calls the FormatError method of f with an errors.Printer configured according to s and verb, and writes the result to s.
Example ¶
package main
import (
"fmt"
"golang.org/x/xerrors"
)
type MyError2 struct {
Message string
frame xerrors.Frame
}
func (m *MyError2) Error() string {
return m.Message
}
func (m *MyError2) Format(f fmt.State, c rune) { // implements fmt.Formatter
xerrors.FormatError(m, f, c)
}
func (m *MyError2) FormatError(p xerrors.Printer) error { // implements xerrors.Formatter
p.Print(m.Message)
if p.Detail() {
m.frame.Format(p)
}
return nil
}
func main() {
err := &MyError2{Message: "oops", frame: xerrors.Caller(1)}
fmt.Printf("%v\n", err)
fmt.Println()
fmt.Printf("%+v\n", err)
}
Output:
func Is
deprecated
func New ¶
New returns an error that formats as the given text.
The returned error contains a Frame set to the caller's location and implements Formatter to show this information when printed with details.
Example ¶
package main
import (
"fmt"
"golang.org/x/xerrors"
)
func main() {
err := xerrors.New("emit macho dwarf: elf header corrupted")
if err != nil {
fmt.Print(err)
}
}
Output: emit macho dwarf: elf header corrupted
Example (Errorf) ¶
The fmt package's Errorf function lets us use the package's formatting features to create descriptive error messages.
package main
import (
"fmt"
)
func main() {
const name, id = "bimmler", 17
err := fmt.Errorf("user %q (id %d) not found", name, id)
if err != nil {
fmt.Print(err)
}
}
Output: user "bimmler" (id 17) not found
Types ¶
type Formatter ¶
type Formatter interface {
error
// FormatError prints the receiver's first error and returns the next error in
// the error chain, if any.
FormatError(p Printer) (next error)
}
A Formatter formats error messages.
type Frame ¶
type Frame struct {
// contains filtered or unexported fields
}
A Frame contains part of a call stack.
type Printer ¶
type Printer interface {
// Print appends args to the message output.
Print(args ...interface{})
// Printf writes a formatted string.
Printf(format string, args ...interface{})
// Detail reports whether error detail is requested.
// After the first call to Detail, all text written to the Printer
// is formatted as additional detail, or ignored when
// detail has not been requested.
// If Detail returns false, the caller can avoid printing the detail at all.
Detail() bool
}
A Printer formats error messages.
The most common implementation of Printer is the one provided by package fmt during Printf (as of Go 1.13). Localization packages such as golang.org/x/text/message typically provide their own implementations.
Source Files
Directories