package errors

Import Path
	github.com/go-faster/errors (on go.dev)

Dependency Relation
	imports 9 packages, and imported by 24 packages


Involved Source Files

	    adaptor.go
	
		Package errors implements functions to manipulate errors.
		
		This package expands "errors" with stack traces and explicit error
		wrapping.

	    errors.go
	    format.go
	    frame.go
	    into.go
	    join_go120.go
	    must.go
	    trace.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"
			"os"
		
			"github.com/go-faster/errors"
		)
		
		func main() {
			_, err := os.Open("non-existing")
			if err != nil {
				var pathError *os.PathError
				if errors.As(err, &pathError) {
					fmt.Println("Failed at path:", pathError.Path)
				}
			}
		
		}

	
		package main
		
		import (
			"fmt"
		
			"github.com/go-faster/errors"
		)
		
		type MyError2 struct {
			Message string
			frame   errors.Frame
		}
		
		func (m *MyError2) Error() string {
			return m.Message
		}
		
		func (m *MyError2) Format(f fmt.State, c rune) { // implements fmt.Formatter
			errors.FormatError(m, f, c)
		}
		
		func (m *MyError2) FormatError(p errors.Printer) error { // implements errors.Formatter
			p.Print(m.Message)
			if p.Detail() {
				m.frame.Format(p)
			}
			return nil
		}
		
		func main() {
			err := &MyError2{Message: "oops", frame: errors.Caller(1)}
			fmt.Printf("%v\n", err)
			fmt.Println()
			fmt.Printf("%+v\n", err)
		}

	
		package main
		
		import (
			"fmt"
			"os"
		
			"github.com/go-faster/errors"
		)
		
		func main() {
			_, err := os.Open("non-existing")
			if err != nil {
				if pathError, ok := errors.Into[*os.PathError](err); ok {
					fmt.Println("Failed at path:", pathError.Path)
				}
			}
		
		}

	
		package main
		
		import (
			"fmt"
			"net/url"
		
			"github.com/go-faster/errors"
		)
		
		func main() {
			r := errors.Must(url.Parse(`https://google.com`))
			fmt.Println(r.String())
		
		}




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


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

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

		
			
		
			 Formatter : 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.

			
				Location reports the file, line, and function of a frame.
				
				The returned function may be "" even if file and line are not.

		
			func Caller(skip int) Frame
			func Cause(err error) (f Frame, r 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.

		
			
				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.

		
			*github.com/cenkalti/backoff/v4.PermanentError
			*github.com/gotd/td/internal/exchange.ServerExchangeError
			*crypto/tls.CertificateVerificationError
			 crypto/x509.SystemRootsError
			*encoding/json.MarshalerError
			*io/fs.PathError
			*net.DNSConfigError
			*net.OpError
			*net/url.Error
			*os.LinkError
			*os.SyscallError
			*strconv.NumError
			


	


Package-Level Functions (total 18, in which 16 are exported)


	
		As finds the first error in err's chain that matches target, and if so, sets
		target to that error value and returns true. Otherwise, it returns false.
		
		The chain consists of err itself followed by the sequence of errors obtained by
		repeatedly calling Unwrap.
		
		An error matches target if the error's concrete value is assignable to the value
		pointed to by target, or if the error has a method As(interface{}) bool such that
		As(target) returns true. In the latter case, the As method is responsible for
		setting target.
		
		An error type might provide an As method so it can be treated as if it were a
		different error type.
		
		As panics if target is not a non-nil pointer to either a type that implements
		error, or to any interface type.


	
		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.


	
		Cause returns first recorded Frame.


	
		DisableTrace disables capturing caller frames.


	
		Errorf creates new error with format.


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


	

		Type Parameters:
			T: error

		Into finds the first error in err's chain that matches target type T, and if so, returns it.
		
		Into is type-safe alternative to As.


	
		Is reports whether any error in err's chain matches target.
		
		The chain consists of err itself followed by the sequence of errors obtained by
		repeatedly calling Unwrap.
		
		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.
		
		An error type might provide an Is method so it can be treated as equivalent
		to an existing error. For example, if MyError defines
		
			func (m MyError) Is(target error) bool { return target == fs.ErrExist }
		
		then Is(MyError{}, fs.ErrExist) returns true. See syscall.Errno.Is for
		an example in the standard library.


	
		Join returns an error that wraps the given errors.
		Any nil error values are discarded.
		Join returns nil if every value in errs is nil.
		The error formats as the concatenation of the strings obtained
		by calling the Error method of each element of errs, with a newline
		between each string.
		
		A non-nil error returned by Join implements the Unwrap() []error method.
		
		Available only for go 1.20 or superior.


	

		Type Parameters:
			T: any

		Must is a generic helper, like template.Must, that wraps a call to a function returning (T, error)
		and panics if the error is non-nil.


	
		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.


	
		Trace reports whether caller stack capture is enabled.


	
		Unwrap returns the result of calling the Unwrap method on err, if err's
		type contains an Unwrap method returning error.
		Otherwise, Unwrap returns nil.


	
		Wrap error with message and caller.


	
		Wrapf wraps error with formatted message and caller.


	


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

	


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