mirror of
https://github.com/golang/go.git
synced 2026-04-03 09:49:56 +09:00
1d0f5c478a
This commit amends package errors' documentation to include a reference
to the https://go.dev/blog/go1.13-errors blog article. The motivation
is multi-fold, but chiefly the article includes good information about
error philosophy (e.g., when to wrap), and developers who have come to
Go in the intervening five years are likely not have seen this article
at all given the nature of blog publishing and post fanfare. The
material deserves a promotion in visibility.
Change-Id: Ia6f8307784521dd59de3a3d638dbc0a7fcd445e6
GitHub-Last-Rev: 20980dd507
GitHub-Pull-Request: golang/go#69698
Reviewed-on: https://go-review.googlesource.com/c/go/+/616341
Reviewed-by: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Damien Neil <dneil@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Michael Knyszek <mknyszek@google.com>
91 lines
3.0 KiB
Go
91 lines
3.0 KiB
Go
// Copyright 2011 The Go Authors. All rights reserved.
|
|
// Use of this source code is governed by a BSD-style
|
|
// license that can be found in the LICENSE file.
|
|
|
|
// Package errors implements functions to manipulate errors.
|
|
//
|
|
// The [New] function creates errors whose only content is a text message.
|
|
//
|
|
// An error e wraps another error if e's type has one of the methods
|
|
//
|
|
// Unwrap() error
|
|
// Unwrap() []error
|
|
//
|
|
// If e.Unwrap() returns a non-nil error w or a slice containing w,
|
|
// then we say that e wraps w. A nil error returned from e.Unwrap()
|
|
// indicates that e does not wrap any error. It is invalid for an
|
|
// Unwrap method to return an []error containing a nil error value.
|
|
//
|
|
// An easy way to create wrapped errors is to call [fmt.Errorf] and apply
|
|
// the %w verb to the error argument:
|
|
//
|
|
// wrapsErr := fmt.Errorf("... %w ...", ..., err, ...)
|
|
//
|
|
// Successive unwrapping of an error creates a tree. The [Is] and [As]
|
|
// functions inspect an error's tree by examining first the error
|
|
// itself followed by the tree of each of its children in turn
|
|
// (pre-order, depth-first traversal).
|
|
//
|
|
// See https://go.dev/blog/go1.13-errors for a deeper discussion of the
|
|
// philosophy of wrapping and when to wrap.
|
|
//
|
|
// [Is] examines the tree of its first argument looking for an error that
|
|
// matches the second. It reports whether it finds a match. It should be
|
|
// used in preference to simple equality checks:
|
|
//
|
|
// if errors.Is(err, fs.ErrExist)
|
|
//
|
|
// is preferable to
|
|
//
|
|
// if err == fs.ErrExist
|
|
//
|
|
// because the former will succeed if err wraps [io/fs.ErrExist].
|
|
//
|
|
// [As] examines the tree of its first argument looking for an error that can be
|
|
// assigned to its second argument, which must be a pointer. If it succeeds, it
|
|
// performs the assignment and returns true. Otherwise, it returns false. The form
|
|
//
|
|
// var perr *fs.PathError
|
|
// if errors.As(err, &perr) {
|
|
// fmt.Println(perr.Path)
|
|
// }
|
|
//
|
|
// is preferable to
|
|
//
|
|
// if perr, ok := err.(*fs.PathError); ok {
|
|
// fmt.Println(perr.Path)
|
|
// }
|
|
//
|
|
// because the former will succeed if err wraps an [*io/fs.PathError].
|
|
package errors
|
|
|
|
// New returns an error that formats as the given text.
|
|
// Each call to New returns a distinct error value even if the text is identical.
|
|
func New(text string) error {
|
|
return &errorString{text}
|
|
}
|
|
|
|
// errorString is a trivial implementation of error.
|
|
type errorString struct {
|
|
s string
|
|
}
|
|
|
|
func (e *errorString) Error() string {
|
|
return e.s
|
|
}
|
|
|
|
// ErrUnsupported indicates that a requested operation cannot be performed,
|
|
// because it is unsupported. For example, a call to [os.Link] when using a
|
|
// file system that does not support hard links.
|
|
//
|
|
// Functions and methods should not return this error but should instead
|
|
// return an error including appropriate context that satisfies
|
|
//
|
|
// errors.Is(err, errors.ErrUnsupported)
|
|
//
|
|
// either by directly wrapping ErrUnsupported or by implementing an [Is] method.
|
|
//
|
|
// Functions and methods should document the cases in which an error
|
|
// wrapping this will be returned.
|
|
var ErrUnsupported = New("unsupported operation")
|