xerrors: copied files from x/exp/errors

changed paths and removed experimental notice

Also made panic test pass: the output differed
for different Go versions.

Change-Id: Iadd367fb253459d288c3ec7e3aaafce9af939983
Reviewed-on: https://go-review.googlesource.com/c/159777
Run-TryBot: Marcel van Lohuizen <[email protected]>
TryBot-Result: Gobot Gobot <[email protected]>
Reviewed-by: Damien Neil <[email protected]>

Author: mpvl

adaptor.go

@@ -0,0 +1,188 @@
+// Copyright 2018 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 xerrors
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"reflect"
+	"strconv"
+)
+
+// FormatError calls the FormatError method of f with an errors.Printer
+// configured according to s and verb, and writes the result to s.
+func FormatError(f Formatter, s fmt.State, verb rune) {
+	// Assuming this function is only called from the Format method, and given
+	// that FormatError takes precedence over Format, it cannot be called from
+	// any package that supports errors.Formatter. It is therefore safe to
+	// disregard that State may be a specific printer implementation and use one
+	// of our choice instead.
+
+	// limitations: does not support printing error as Go struct.
+
+	var (
+		sep    = " " // separator before next error
+		p      = &state{State: s}
+		direct = true
+	)
+
+	var err error = f
+
+	switch verb {
+	// Note that this switch must match the preference order
+	// for ordinary string printing (%#v before %+v, and so on).
+
+	case 'v':
+		if s.Flag('#') {
+			if stringer, ok := err.(fmt.GoStringer); ok {
+				io.WriteString(&p.buf, stringer.GoString())
+				goto exit
+			}
+			// proceed as if it were %v
+		} else if s.Flag('+') {
+			p.printDetail = true
+			sep = "\n  - "
+		}
+	case 's':
+	case 'q', 'x', 'X':
+		// Use an intermediate buffer in the rare cases that precision,
+		// truncation, or one of the alternative verbs (q, x, and X) are
+		// specified.
+		direct = false
+
+	default:
+		p.buf.WriteString("%!")
+		p.buf.WriteRune(verb)
+		p.buf.WriteByte('(')
+		switch {
+		case err != nil:
+			p.buf.WriteString(reflect.TypeOf(f).String())
+		default:
+			p.buf.WriteString("<nil>")
+		}
+		p.buf.WriteByte(')')
+		io.Copy(s, &p.buf)
+		return
+	}
+
+loop:
+	for {
+		p.inDetail = false
+
+		switch v := err.(type) {
+		case Formatter:
+			err = v.FormatError((*printer)(p))
+		case fmt.Formatter:
+			v.Format(p, 'v')
+			break loop
+		default:
+			io.WriteString(&p.buf, v.Error())
+			break loop
+		}
+		if err == nil {
+			break
+		}
+		if !p.inDetail || !p.printDetail {
+			p.buf.WriteByte(':')
+		}
+		// Strip last newline of detail.
+		if bytes.HasSuffix(p.buf.Bytes(), detailSep) {
+			p.buf.Truncate(p.buf.Len() - len(detailSep))
+		}
+		p.buf.WriteString(sep)
+		p.inDetail = false
+	}
+
+exit:
+	width, okW := s.Width()
+	prec, okP := s.Precision()
+
+	if !direct || (okW && width > 0) || okP {
+		// Construct format string from State s.
+		format := []byte{'%'}
+		if s.Flag('-') {
+			format = append(format, '-')
+		}
+		if s.Flag('+') {
+			format = append(format, '+')
+		}
+		if s.Flag(' ') {
+			format = append(format, ' ')
+		}
+		if okW {
+			format = strconv.AppendInt(format, int64(width), 10)
+		}
+		if okP {
+			format = append(format, '.')
+			format = strconv.AppendInt(format, int64(prec), 10)
+		}
+		format = append(format, string(verb)...)
+		fmt.Fprintf(s, string(format), p.buf.String())
+	} else {
+		io.Copy(s, &p.buf)
+	}
+}
+
+var detailSep = []byte("\n    ")
+
+// state tracks error printing state. It implements fmt.State.
+type state struct {
+	fmt.State
+	buf bytes.Buffer
+
+	printDetail bool
+	inDetail    bool
+	needNewline bool
+}
+
+func (s *state) Write(b []byte) (n int, err error) {
+	if s.printDetail {
+		if len(b) == 0 {
+			return 0, nil
+		}
+		if s.inDetail && s.needNewline {
+			s.needNewline = false
+			s.buf.WriteByte(':')
+			s.buf.Write(detailSep)
+			if b[0] == '\n' {
+				b = b[1:]
+			}
+		}
+		k := 0
+		for i, c := range b {
+			if c == '\n' {
+				s.buf.Write(b[k:i])
+				s.buf.Write(detailSep)
+				k = i + 1
+			}
+		}
+		s.buf.Write(b[k:])
+		s.needNewline = !s.inDetail
+	} else if !s.inDetail {
+		s.buf.Write(b)
+	}
+	return len(b), nil
+}
+
+// printer wraps a state to implement an xerrors.Printer.
+type printer state
+
+func (s *printer) Print(args ...interface{}) {
+	if !s.inDetail || s.printDetail {
+		fmt.Fprint((*state)(s), args...)
+	}
+}
+
+func (s *printer) Printf(format string, args ...interface{}) {
+	if !s.inDetail || s.printDetail {
+		fmt.Fprintf((*state)(s), format, args...)
+	}
+}
+
+func (s *printer) Detail() bool {
+	s.inDetail = true
+	return s.printDetail
+}

doc.go

@@ -0,0 +1,25 @@
+// Copyright 2019 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 xerrors implements functions to manipulate errors.
+//
+// This package supports transitioning to the Go 2 proposal for error values:
+//   https://golang.org/design/29934-error-values
+//
+// Most of the functions and types in this package will be incorporated into the
+// standard library's errors package in Go 1.13; the behavior of this package's
+// Errorf function will be incorporated into the standard library's fmt.Errorf.
+// Use this package to get equivalent behavior in all supported Go versions. For
+// example, create errors using
+//
+//    xerrors.New("write failed")
+//
+// or
+//
+//    xerrors.Errorf("while reading: %v", err)
+//
+// If you want your error type to participate in the new formatting
+// implementation for %v and %+v, provide it with a Format method that calls
+// xerrors.FormatError, as shown in the example for FormatError.
+package xerrors // import "golang.org/x/xerrors"

errors.go

@@ -0,0 +1,29 @@
+// 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 xerrors
+
+// errorString is a trivial implementation of error.
+type errorString struct {
+	s     string
+	frame Frame
+}
+
+// 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.
+func New(text string) error {
+	return &errorString{text, Caller(1)}
+}
+
+func (e *errorString) Error() string {
+	return e.s
+}
+
+func (e *errorString) FormatError(p Printer) (next error) {
+	p.Print(e.s)
+	e.frame.Format(p)
+	return nil
+}

errors_test.go

@@ -0,0 +1,54 @@
+// 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 xerrors_test
+
+import (
+	"fmt"
+	"testing"
+
+	"golang.org/x/xerrors"
+)
+
+func TestNewEqual(t *testing.T) {
+	// Different allocations should not be equal.
+	if xerrors.New("abc") == xerrors.New("abc") {
+		t.Errorf(`New("abc") == New("abc")`)
+	}
+	if xerrors.New("abc") == xerrors.New("xyz") {
+		t.Errorf(`New("abc") == New("xyz")`)
+	}
+
+	// Same allocation should be equal to itself (not crash).
+	err := xerrors.New("jkl")
+	if err != err {
+		t.Errorf(`err != err`)
+	}
+}
+
+func TestErrorMethod(t *testing.T) {
+	err := xerrors.New("abc")
+	if err.Error() != "abc" {
+		t.Errorf(`New("abc").Error() = %q, want %q`, err.Error(), "abc")
+	}
+}
+
+func ExampleNew() {
+	err := xerrors.New("emit macho dwarf: elf header corrupted")
+	if err != nil {
+		fmt.Print(err)
+	}
+	// Output: emit macho dwarf: elf header corrupted
+}
+
+// The fmt package's Errorf function lets us use the package's formatting
+// features to create descriptive error messages.
+func ExampleNew_errorf() {
+	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
+}

example_As_test.go

@@ -0,0 +1,25 @@
+// Copyright 2019 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 xerrors_test
+
+import (
+	"fmt"
+	"os"
+
+	"golang.org/x/xerrors"
+)
+
+func ExampleAs() {
+	_, 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
+}

example_FormatError_test.go

@@ -0,0 +1,39 @@
+// Copyright 2019 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 xerrors_test
+
+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 ExampleFormatError() {
+	err := &MyError2{Message: "oops", frame: xerrors.Caller(1)}
+	fmt.Printf("%v\n", err)
+	fmt.Println()
+	fmt.Printf("%+v\n", err)
+}