examples_test.go

package errors_test

import (
	"encoding/json"
	"fmt"
	"regexp"
	"runtime"
	"strings"

	"github.com/secureworks/errors"
)

var sharedPath = "/home/testuser/pkgs/errors/"
var matchInternalPath = regexp.MustCompile(`((/.+)+)/src/`)
var matchPackagePath = regexp.MustCompile(`((/.+)+)/errors/`)
var matchLineNumbers = regexp.MustCompile(`:[0-9]+`)

// pprint allows these tests to pass in any environment by grepping
// filepaths in the output, and to ease matching by removing line
// numbers from the call stacks.
func pprint(v ...interface{}) {
	entries := strings.Split(fmt.Sprint(v...), " ")
	for i := range entries {
		entries[i] = matchInternalPath.ReplaceAllString(entries[i], "/go/src/")
		entries[i] = matchPackagePath.ReplaceAllString(entries[i], sharedPath)
		entries[i] = matchLineNumbers.ReplaceAllString(entries[i], ":0")
	}
	fmt.Print(strings.Join(entries, " "))
}

// pprintf allows these tests to pass in any environment by grepping
// filepaths in the output, and to ease matching by removing line
// numbers from the call stacks.
func pprintf(format string, v ...interface{}) {
	entries := strings.Split(fmt.Sprintf(format, v...), " ")
	for i := range entries {
		entries[i] = matchInternalPath.ReplaceAllString(entries[i], "/go/src/")
		entries[i] = matchPackagePath.ReplaceAllString(entries[i], sharedPath)
		entries[i] = matchLineNumbers.ReplaceAllString(entries[i], ":0")
	}
	fmt.Print(strings.Join(entries, " "))
}

func ExampleCaller() {
	fr := errors.Caller()
	pprint(fr)

	// Output: /home/testuser/pkgs/errors/examples_test.go:0
}

// The underlying type generated here implements the unexported
// interface programCounter.
func ExampleFrame_programCounter() {
	type programCounter interface {
		PC() uintptr
	}

	localFr, ok := errors.Caller().(programCounter)
	if !ok {
		panic(errors.New("well this is a fine predicament"))
	}

	synthFr, ok := errors.NewFrame("fn.name", "file.go", 10).(programCounter)
	if !ok {
		panic(errors.New("well this is a fine predicament"))
	}

	// Who knows what the actual pointer value is: >0 means it was generated
	// from a local call stack, while 0 means it was created synthetically.
	fmt.Printf("%t %t", localFr.PC() > 0, synthFr.PC() > 0)

	// Output: true false
}

// The underlying type generated here implements fmt.Formatter.
func ExampleFrame_printf() {
	fr := errors.Caller()

	fmt.Println()
	pprintf("%%s:  %s\n", fr)
	pprintf("%%q:  %q\n", fr)
	pprintf("%%n:  %n\n", fr)
	pprintf("%%d:  %d\n", fr)
	pprintf("%%v:  %v\n", fr)
	pprintf("%%#v: %#v\n", fr)
	pprintf("%%+v: %+v\n", fr)

	// Output:
	// %s:  examples_test.go:0
	// %q:  "examples_test.go:0"
	// %n:  ExampleFrame_printf
	// %d:  77
	// %v:  /home/testuser/pkgs/errors/examples_test.go:0
	// %#v: errors.Frame("/home/testuser/pkgs/errors/examples_test.go:0")
	// %+v: github.com/secureworks/errors_test.ExampleFrame_printf
	// 	/home/testuser/pkgs/errors/examples_test.go:0
}

func ExampleNewFrame() {
	fr := errors.NewFrame("fn.name", "file.go", 10)
	pprintf("%+v", fr)

	// Output: fn.name
	// 	file.go:0
}

func ExampleFrameFromPC() {
	pc, _, _, _ := runtime.Caller(0)
	fr := errors.FrameFromPC(pc)
	pprintf("%+v", fr)

	// Output: github.com/secureworks/errors_test.ExampleFrameFromPC
	// 	/home/testuser/pkgs/errors/examples_test.go:0
}

func ExamplePCFromFrame_runtimePC() {
	framePC, _, _, _ := runtime.Caller(0)

	pc := errors.PCFromFrame(framePC)
	fmt.Printf("%t", pc == framePC)

	// Output: true
}
func ExamplePCFromFrame_runtimeFrame() {
	var pcs [1]uintptr
	runtime.Callers(0, pcs[:])
	frames := runtime.CallersFrames(pcs[:])
	frame, _ := frames.Next()

	pc := errors.PCFromFrame(frame)
	fmt.Printf(" %t", pc == pcs[0]-1)

	// Output: true
}
func ExamplePCFromFrame_runtimeProgramCounter() {
	type programCounter interface {
		PC() uintptr
	}
	fr := errors.Caller()
	pcer, _ := fr.(programCounter)

	pc := errors.PCFromFrame(fr)
	fmt.Printf(" %t", pc == pcer.PC())

	// Output: true
}

func ExampleFrames() {
	stack := errors.CallStack()
	pprint(stack)

	// Output: [/home/testuser/pkgs/errors/examples_test.go:0 /go/src/testing/run_example.go:0 /go/src/testing/example.go:0 /go/src/testing/testing.go:0 _testmain.go:0 /go/src/runtime/proc.go:0]
}

func ExampleFrames_printf() {
	stack := errors.CallStack()

	fmt.Println()
	pprintf("%+v", stack)

	// Output:
	// github.com/secureworks/errors_test.ExampleFrames_printf
	// 	/home/testuser/pkgs/errors/examples_test.go:0
	// testing.runExample
	// 	/go/src/testing/run_example.go:0
	// testing.runExamples
	// 	/go/src/testing/example.go:0
	// testing.(*M).Run
	// 	/go/src/testing/testing.go:0
	// main.main
	// 	_testmain.go:0
	// runtime.main
	// 	/go/src/runtime/proc.go:0
}

// The underlying types generated by errors implement json.Marshaler.
// This may not hold for slices of other types that implement
// errors.Frame.
func ExampleFrames_jsonMarshal() {
	stack := errors.CallStack()[0:1] // Remove stdlib frames.
	byt, err := json.MarshalIndent(stack, "", "    ")
	if err != nil {
		panic(errors.New("well this is a fine predicament"))
	}

	pprintf("\n%s", string(byt))

	// Output:
	// [
	//     {
	//         "function": "github.com/secureworks/errors_test.ExampleFrames_jsonMarshal",
	//         "file": "/home/testuser/pkgs/errors/examples_test.go",
	//         "line": 180
	//     }
	// ]
}

func ExampleFramesFromBytes() {
	stackDump := []byte(`err message
github.com/secureworks/errors_test.FnName
	/home/testuser/pkgs/errors/examples_test.go:0
github.com/secureworks/errors_test.FnWrapper
	/home/testuser/pkgs/errors/examples_test.go:0
runtime.main
	/go/src/runtime/proc.go:0
`)
	stack, _ := errors.FramesFromBytes(stackDump)
	fmt.Printf("\n%+v", stack)

	// Output:
	// github.com/secureworks/errors_test.FnName
	// 	/home/testuser/pkgs/errors/examples_test.go:0
	// github.com/secureworks/errors_test.FnWrapper
	// 	/home/testuser/pkgs/errors/examples_test.go:0
	// runtime.main
	// 	/go/src/runtime/proc.go:0
}

func ExampleFramesFromJSON() {
	rawJSON := []byte(`[
    {
        "function": "github.com/secureworks/errors_test.FnName",
        "file": "/home/testuser/pkgs/errors/examples_test.go",
        "line": 200
    },
    {
        "function": "github.com/secureworks/errors_test.FnWrapper",
        "file": "/home/testuser/pkgs/errors/examples_test.go",
        "line": 190
    },
    {
        "function": "runtime.main",
        "file": "/go/src/runtime/proc.go",
        "line": 255
    }
]`)
	stack, _ := errors.FramesFromJSON(rawJSON)
	pprintf("\n%+v", stack)

	// Output:
	// github.com/secureworks/errors_test.FnName
	// 	/home/testuser/pkgs/errors/examples_test.go:0
	// github.com/secureworks/errors_test.FnWrapper
	// 	/home/testuser/pkgs/errors/examples_test.go:0
	// runtime.main
	// 	/go/src/runtime/proc.go:0
}

func ExampleNew() {
	err := errors.New("err message")
	pprintf("%+v", err)

	// Output: err message
}

func ExampleNewWithFrame() {
	err := errors.NewWithFrame("err message")
	pprintf("%+v", err)

	// Output: err message
	// github.com/secureworks/errors_test.ExampleNewWithFrame
	// 	/home/testuser/pkgs/errors/examples_test.go:0
}

func ExampleNewWithFrameAt() {
	err := errors.NewWithFrameAt("err message", 1)
	pprintf("%+v", err)

	// Output: err message
	// testing.runExample
	// 	/go/src/testing/run_example.go:0
}

func ExampleNewWithFrames() {
	frames := errors.CallStackAtMost(0, 2)
	err := errors.NewWithFrames("err message", frames)
	pprintf("%+v", err)

	// Output: err message
	// github.com/secureworks/errors_test.ExampleNewWithFrames
	// 	/home/testuser/pkgs/errors/examples_test.go:0
	// testing.runExample
	// 	/go/src/testing/run_example.go:0
}

func ExampleNewWithStackTrace() {
	err := errors.NewWithStackTrace("err message")
	pprintf("%+v", err)

	// Output: err message
	// github.com/secureworks/errors_test.ExampleNewWithStackTrace
	// 	/home/testuser/pkgs/errors/examples_test.go:0
	// testing.runExample
	// 	/go/src/testing/run_example.go:0
	// testing.runExamples
	// 	/go/src/testing/example.go:0
	// testing.(*M).Run
	// 	/go/src/testing/testing.go:0
	// main.main
	// 	_testmain.go:0
	// runtime.main
	// 	/go/src/runtime/proc.go:0
}

func ExampleWithFrame() {
	err := errors.New("err message")
	err = errors.WithFrame(err)
	pprintf("%+v", err)

	// Output: err message
	// github.com/secureworks/errors_test.ExampleWithFrame
	// 	/home/testuser/pkgs/errors/examples_test.go:0
}

func ExampleWithFrameAt() {
	err := errors.New("err message")
	err = errors.WithFrameAt(err, 1)
	pprintf("%+v", err)

	// Output: err message
	// testing.runExample
	// 	/go/src/testing/run_example.go:0
}

func ExampleWithFrames() {
	err := errors.New("err message")
	frames := errors.CallStackAtMost(0, 2)
	err = errors.WithFrames(err, frames)
	pprintf("%+v", err)

	// Output: err message
	// github.com/secureworks/errors_test.ExampleWithFrames
	// 	/home/testuser/pkgs/errors/examples_test.go:0
	// testing.runExample
	// 	/go/src/testing/run_example.go:0
}

func ExampleWithStackTrace() {
	err := errors.New("err message")
	err = errors.WithStackTrace(err)
	pprintf("%+v", err)

	// Output: err message
	// github.com/secureworks/errors_test.ExampleWithStackTrace
	// 	/home/testuser/pkgs/errors/examples_test.go:0
	// testing.runExample
	// 	/go/src/testing/run_example.go:0
	// testing.runExamples
	// 	/go/src/testing/example.go:0
	// testing.(*M).Run
	// 	/go/src/testing/testing.go:0
	// main.main
	// 	_testmain.go:0
	// runtime.main
	// 	/go/src/runtime/proc.go:0
}

func ExampleErrorf() {
	err := errors.New("err message")
	err = errors.Errorf("outer context: %w", err)
	pprintf("%+v", err)

	// Output: outer context: err message
	// github.com/secureworks/errors_test.ExampleErrorf
	// 	/home/testuser/pkgs/errors/examples_test.go:0
}

func ExampleErrorf_appendingDebuggingContext() {
	err := errors.New("err message")
	err = errors.Errorf("context: %w", err)
	err = errors.Errorf("outermost context: %w", err)
	pprintf("%+v", err)

	// Output: outermost context: context: err message
	// github.com/secureworks/errors_test.ExampleErrorf_appendingDebuggingContext
	// 	/home/testuser/pkgs/errors/examples_test.go:0
	// github.com/secureworks/errors_test.ExampleErrorf_appendingDebuggingContext
	// 	/home/testuser/pkgs/errors/examples_test.go:0
}

func ExampleFramesFrom_appendedFrames() {
	err := errors.New("err message")
	err = errors.Errorf("context: %w", err)
	err = errors.Errorf("outermost context: %w", err)
	frames := errors.FramesFrom(err)
	pprintf("\n%+v", frames)

	// Output:
	// github.com/secureworks/errors_test.ExampleFramesFrom_appendedFrames
	// 	/home/testuser/pkgs/errors/examples_test.go:0
	// github.com/secureworks/errors_test.ExampleFramesFrom_appendedFrames
	// 	/home/testuser/pkgs/errors/examples_test.go:0

}

func ExampleFramesFrom_stackTrace() {
	err := errors.NewWithStackTrace("err message")
	err = errors.Errorf("context: %w", err)
	err = errors.Errorf("outermost context: %w", err)
	frames := errors.FramesFrom(err)
	pprintf("\n%+v", frames)

	// Output:
	// github.com/secureworks/errors_test.ExampleFramesFrom_stackTrace
	// 	/home/testuser/pkgs/errors/examples_test.go:0
	// testing.runExample
	// 	/go/src/testing/run_example.go:0
	// testing.runExamples
	// 	/go/src/testing/example.go:0
	// testing.(*M).Run
	// 	/go/src/testing/testing.go:0
	// main.main
	// 	_testmain.go:0
	// runtime.main
	// 	/go/src/runtime/proc.go:0
}

func ExampleWithMessage() {
	err := errors.New("new err message")
	err = errors.Errorf("context: %w", err)
	err = errors.Errorf("outermost context: %w", err)
	err = errors.WithMessage(err, "new err message")

	fmt.Print(err)

	// Output: new err message
}

func ExampleMask() {
	err := errors.New("new err message")
	err = errors.Errorf("context: %w", err)
	err = errors.Errorf("outermost context: %w", err)
	err = errors.Mask(errors.WithMessage(err, "err"))

	// Should show frames.
	pprintf("%+v", err)

	// Output: err
}

type unknownErrorType struct {
	error       error
	SecretValue string
}

func (e *unknownErrorType) Error() string {
	return e.error.Error()
}

func (e *unknownErrorType) Unwrap() error {
	return e.error
}

func ExampleOpaque() {
	err := errors.New("err message")
	err = errors.Errorf("context: %w", err)
	err = &unknownErrorType{error: err, SecretValue: "secret data we don't want to leak"}
	err = errors.Errorf("outermost context: %w", err)
	err = errors.Opaque(err)

	// Opaque squashes the error chain, removing any outside types that may
	// have snuck in, while retaining all the errors package data we know
	// about.
	var unkErr *unknownErrorType
	if errors.As(err, &unkErr) {
		fmt.Println("leaked data:", unkErr.SecretValue)
	}
	pprintf("%+v", err)

	// Output: outermost context: context: err message
	// github.com/secureworks/errors_test.ExampleOpaque
	// 	/home/testuser/pkgs/errors/examples_test.go:0
	// github.com/secureworks/errors_test.ExampleOpaque
	// 	/home/testuser/pkgs/errors/examples_test.go:0
}

func ExampleNewMultiError() {
	merr := errors.NewMultiError(
		errors.New("err1"),
		errors.New("err2"),
		errors.New("err3"),
	)
	pprint(merr)

	// Output: [err1; err2; err3]
}

func ExampleNewMultiError_isAnError() {
	err := (error)(errors.NewMultiError(
		errors.New("err1"),
		errors.New("err2"),
		errors.New("err3"),
	))
	pprint(err)

	// Output: [err1; err2; err3]
}

func ExampleNewMultiError_flattensMultiErrors() {
	merrInner := errors.NewMultiError(
		errors.New("err1"),
		errors.New("err2"),
	)
	merr := errors.NewMultiError(
		merrInner,
		errors.New("err3"),
	)
	pprint(merr)

	// Output: [err1; err2; err3]
}

func ExampleMultiError_Unwrap() {
	merr := errors.NewMultiError(
		errors.New("err1"),
		errors.New("err2"),
		errors.New("err3"),
	)
	for _, err := range merr.Unwrap() {
		pprint("\n", err)
	}

	// Output:
	// err1
	// err2
	// err3
}

func ExampleMultiError_ErrorOrNil() {
	pprint("\n", errors.NewMultiError().ErrorOrNil())
	pprint("\n", errors.NewMultiError(nil).ErrorOrNil())
	pprint("\n", errors.NewMultiError(errors.New("err")).ErrorOrNil())
	pprint("\n", errors.NewMultiError(errors.New("err"), errors.New("err")).ErrorOrNil())

	// Output:
	// <nil>
	// <nil>
	// err
	// [err; err]
}

func ExampleMultiError_as() {
	err1 := errors.Errorf("context: %w",
		&unknownErrorType{error: errors.New("err"), SecretValue: "secret A"})

	fmt.Println()

	var unkErr *unknownErrorType
	if errors.As(err1, &unkErr) {
		fmt.Printf("basic unwrap found: %s\n", unkErr.SecretValue)
	} else {
		fmt.Println("basic unwrap not found")
	}

	// MultiError implements As by iterating over each error in order,
	// unwrapping the contained values.
	err2 := errors.Errorf("outer context: %w", errors.NewMultiError(
		errors.New("err"),
		err1,
		// Last in order, so not reached.
		&unknownErrorType{error: errors.New("err"), SecretValue: "secret B"},
	))
	if errors.As(err2, &unkErr) {
		fmt.Printf("multi unwrap found: %s\n", unkErr.SecretValue)
	} else {
		fmt.Println("multi unwrap not found")
	}

	// To get all, you must unwrap to MultiError and then unwrap contained values.
	var merr *errors.MultiError
	if errors.As(err2, &merr) {
		for i, err := range merr.Unwrap() {
			if errors.As(err, &unkErr) {
				fmt.Printf("unmerged %d unwrap found: %s\n", i, unkErr.SecretValue)
			} else {
				fmt.Printf("unmerged %d unwrap not found\n", i)
			}
		}
	}

	// Output:
	// basic unwrap found: secret A
	// multi unwrap found: secret A
	// unmerged 0 unwrap not found
	// unmerged 1 unwrap found: secret A
	// unmerged 2 unwrap found: secret B
}

func ExampleMultiError_is() {
	errSentinel := errors.New("sentinel err")
	errA := errors.Errorf("ctx A: %w", errSentinel)
	errB := errors.Errorf("ctx B: %w", errors.New("err"))
	errC := errors.Errorf("ctx C: %w", errSentinel)

	fmt.Println()

	// MultiError implements Is by iterating over each error in order,
	// unwrapping the contained values.
	err := errors.Errorf("outer context: %w", errors.NewMultiError(
		errA,
		errB,
		errC,
	))
	if errors.Is(err, errSentinel) {
		fmt.Printf("multi err sentinel found: %s\n", err)
	} else {
		fmt.Println("multi err sentinel not found")
	}

	// To check all, you must unwrap to MultiError and then check contained
	// values.
	var merr *errors.MultiError
	if errors.As(err, &merr) {
		for i, err := range merr.Unwrap() {
			if errors.Is(err, errSentinel) {
				fmt.Printf("unmerged %d sentinel found: %s\n", i, err)
			} else {
				fmt.Printf("unmerged %d sentinel not found\n", i)
			}
		}
	}

	// Output:
	// multi err sentinel found: outer context: [ctx A: sentinel err; ctx B: err; ctx C: sentinel err]
	// unmerged 0 sentinel found: ctx A: sentinel err
	// unmerged 1 sentinel not found
	// unmerged 2 sentinel found: ctx C: sentinel err
}

func ExampleMultiError_printf() {
	merrEmpty := errors.NewMultiError()
	merrFull := errors.NewMultiError(
		errors.New("err1"),
		errors.NewWithFrame("err2"),
		errors.NewWithStackTrace("err3"),
	)
	merrWrapped := errors.Errorf("context: %w", merrFull)

	fmt.Println()
	pprintf("1. %+v\n", merrEmpty)
	pprintf("2. %+v\n", merrFull)
	pprintf("3. %+v\n", merrWrapped)

	// Output:
	// 1. empty errors: []
	// 2. multiple errors:
	//
	// * error 1 of 3: err1
	//
	// * error 2 of 3: err2
	// github.com/secureworks/errors_test.ExampleMultiError_printf
	// 	/home/testuser/pkgs/errors/examples_test.go:0
	//
	// * error 3 of 3: err3
	// github.com/secureworks/errors_test.ExampleMultiError_printf
	// 	/home/testuser/pkgs/errors/examples_test.go:0
	// testing.runExample
	// 	/go/src/testing/run_example.go:0
	// testing.runExamples
	// 	/go/src/testing/example.go:0
	// testing.(*M).Run
	// 	/go/src/testing/testing.go:0
	// main.main
	// 	_testmain.go:0
	// runtime.main
	// 	/go/src/runtime/proc.go:0
	//
	// 3. context: [err1; err2; err3]
	// github.com/secureworks/errors_test.ExampleMultiError_printf
	// 	/home/testuser/pkgs/errors/examples_test.go:0
}

func ExampleErrorsFrom() {
	err := errors.NewMultiError(
		errors.New("err1"),
		errors.New("err2"),
		errors.New("err3"),
	).ErrorOrNil()

	fmt.Println(err) // Print the multierror for comparison.

	errs := errors.ErrorsFrom(err)
	for _, err := range errs {
		fmt.Println(err)
	}

	// Output: [err1; err2; err3]
	// err1
	// err2
	// err3
}

func ExampleErrorsFrom_singleError() {
	err := errors.New("err")
	err = errors.Errorf("inner context: %w", err)
	err = errors.Errorf("outer context: %w", err)

	errs := errors.ErrorsFrom(err)
	for _, err := range errs { // errs contains the given error.
		fmt.Println(err)
	}

	// Output: outer context: inner context: err
}

func ExampleErrorsFrom_nil() {
	errs := errors.ErrorsFrom(nil)
	for _, err := range errs { // errs has 0 length.
		fmt.Println(err)
	}

	// Output:
}

func ExampleAppend() {
	err := errors.Append(
		nil,
		nil,
	)
	fmt.Printf("\n%v", err)

	err = errors.Append(err, nil)
	fmt.Printf("\n%v", err)

	err = errors.Append(
		err,
		errors.New("err1"),
	)
	fmt.Printf("\n%v", err)

	err = errors.Append(err, nil)
	fmt.Printf("\n%v", err)

	err = errors.Append(
		err,
		errors.New("err2"),
	)
	fmt.Printf("\n%v", err)

	err = errors.Append(err, nil)
	fmt.Printf("\n%v", err)

	err = errors.Append(
		err,
		errors.New("err3"),
	)
	fmt.Printf("\n%v", err)

	// Output:
	// <nil>
	// <nil>
	// err1
	// err1
	// [err1; err2]
	// [err1; err2]
	// [err1; err2; err3]
}

func ExampleAppendInto() {
	var aerr error

	errs := []error{
		nil,
		errors.New("err1"),
		errors.New("err2"),
		errors.New("err3"),
	}
	for _, err := range errs {
		errors.AppendInto(&aerr, err)
		fmt.Printf("\n%s", aerr)
	}

	// Output:
	// %!s(<nil>)
	// err1
	// [err1; err2]
	// [err1; err2; err3]
}

type testErrCloser struct{}

func (_ *testErrCloser) Close() error {
	return errors.New("and a closer error to boot!")
}

func ExampleAppendResult() {
	errFn := func() (err error) {
		closer := &testErrCloser{}
		defer errors.AppendResult(&err, closer.Close)

		err = errors.New("some error we got")
		if err != nil {
			return
		}
		return
	}

	noErrFn := func() (err error) {
		closer := &testCloser{}
		defer errors.AppendResult(&err, closer.Close)

		return
	}

	fmt.Println()

	err := errFn()
	if err != nil {
		fmt.Println(err)
	}

	err = noErrFn()
	if err != nil {
		fmt.Println(err)
	} else {
		fmt.Println("noErrFn returned nil")
	}

	// Output:
	// [some error we got; and a closer error to boot!]
	// noErrFn returned nil
}

type testCloser struct{ err error }

func (t testCloser) Close() error {
	return t.err
}