package xerrors

Import Path
	golang.org/x/xerrors (on go.dev)

Dependency Relation
	imports 10 packages, and imported by 2 packages


Involved Source Files

	      adaptor.go
	
		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.

	      errors.go
	      fmt.go
	      format.go
	      frame.go
	      wrap.go


Code Examples

	
		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)
			}
		}


	
		package main
		
		import (
			"fmt"
			"golang.org/x/xerrors"
			"os"
		)
		
		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)
				}
			}
		
		}


	
		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)
		}




Package-Level Type Names (total 10, in which 4 are exported)


	/* sort exporteds by:  |  */
	
		A Formatter formats error messages.

		
			( T) Error() builtin.string
			
				FormatError prints the receiver's first error and returns the next error in
				the error chain, if any.

		
			
		
			 T : error
		
			func FormatError(f Formatter, s fmt.State, verb rune)


	
		A Frame contains part of a call stack.

		
			
		
			
				Format prints the stack as error detail.
				It should be called from an error's Format implementation
				after printing any other error detail.

			
		
			func Caller(skip int) Frame


	
		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.

		
			
				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.

			
				Print appends args to the message output.

			
				Printf writes a formatted string.

		
			
		
			func Formatter.FormatError(p Printer) (next error)
			func Frame.Format(p Printer)


	
		A Wrapper provides context around another error.

		
			
				Unwrap returns the next error in the error chain.
				If there is no next error, Unwrap returns nil.

		
			*golang.org/x/mod/modfile.Error
			*golang.org/x/mod/module.InvalidVersionError
			*golang.org/x/mod/module.ModuleError
			 golang.org/x/mod/zip.FileError
			*golang.org/x/pkgsite/internal/derrors.StackError
			 crypto/x509.SystemRootsError
			*encoding/json.MarshalerError
			 github.com/go-redis/redis/v8/internal/pool.BadConnError
			 github.com/jackc/pgx/v4.ScanArgError
			*io/fs.PathError
			*net.DNSConfigError
			*net.OpError
			*net/url.Error
			*os.LinkError
			*os.SyscallError
			*os/exec.Error
			*strconv.NumError
			 text/template.ExecError
			


	


Package-Level Functions (total 12, in which 8 are exported)


	
		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.


	
		Caller returns a Frame that describes a frame on the caller's stack.
		The argument skip is the number of frames to skip over.
		Caller(0) returns the frame for the caller of Caller.


	
		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.


	
		FormatError calls the FormatError method of f with an errors.Printer
		configured according to s and verb, and writes the result to s.


	
		Is reports whether any error in err's chain matches target.

		An error is considered to match a target if it is equal to that target or if
		it implements a method Is(error) bool such that Is(target) returns true.


	
		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.


	
		Opaque returns an error with the same error formatting as err
		but that does not match err and cannot be unwrapped.


	
		Unwrap returns the result of calling the Unwrap method on err, if err implements
		Unwrap. Otherwise, Unwrap returns nil.


	


Package-Level Variables (total 2, neither is exported)

	


Package-Level Constants (only one, which is unexported)