errors: add example showing a custom error with Unwrap

Change-Id: I2bddee9b460d3875911859b49528a00d318f37fc
Reviewed-on: https://go-review.googlesource.com/c/go/+/184237
Reviewed-by: Russ Cox <rsc@golang.org>
Reviewed-by: Emmanuel Odeke <emm.odeke@gmail.com>

1 files changed, 56 insertions, 0 deletions

diff --git a/src/errors/example_unwrap_test.go b/src/errors/example_unwrap_test.go
new file mode 100644
index 0000000000..05c9cd466f
--- /dev/null
+++ b/src/errors/example_unwrap_test.go
@@ -0,0 +1,56 @@
+// 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 errors_test
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"time"
+)
+
+// MyError2 is an error implementation that includes a time, a message, and an
+// underlying error.
+type MyError2 struct {
+	When time.Time
+	What string
+	err  error
+}
+
+func (e MyError2) Error() string {
+	return fmt.Sprintf("%v at %v: %v", e.What, e.When, e.err)
+}
+
+// Unwrap returns e's underlying error, or nil if there is none.
+func (e MyError2) Unwrap() error {
+	return e.err
+}
+
+func readConfig() error {
+	if _, err := os.Open("non-existing"); err != nil {
+		return MyError2{
+			time.Date(1989, 3, 15, 22, 30, 0, 0, time.UTC),
+			"reading config file",
+			err,
+		}
+	}
+	return nil
+}
+
+func Example_unwrap() {
+	if err := readConfig(); err != nil {
+		// Display the error.
+		fmt.Println(err)
+		// If we can retrieve the path, try to recover
+		// by taking another action.
+		var pe *os.PathError
+		if errors.As(err, &pe) {
+			restoreFile(pe.Path)
+		}
+	}
+	// Output: reading config file at 1989-03-15 22:30:00 +0000 UTC: open non-existing: no such file or directory
+}
+
+func restoreFile(path string) {}