doc: add Error Handling article

Originally published on The Go Programming Language Blog, July 12, 2011.

http://blog.golang.org/2011/07/error-handling-and-go.html

Update #2547

R=golang-dev, r
CC=golang-dev
https://golang.org/cl/5475060

doc/Makefile

@@ -8,7 +8,14 @@ TARG=tmpltohtml
 GOFILES=\
 	tmpltohtml.go\
 
-all: tmpltohtml go_tutorial.html effective_go.html go1.html articles/defer_panic_recover.html
+HTML=\
+	articles/defer_panic_recover.html\
+	articles/error_handling.html\
+	effective_go.html\
+	go1.html\
+	go_tutorial.html\
+
+all: tmpltohtml $(HTML)
 
 %.html: %.tmpl tmpltohtml
 	./makehtml $*.tmpl

doc/progs/error.go

+// 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.
+
+// This file contains the code snippets included in "Error Handling and Go."
+
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"log"
+	"net"
+	"os"
+	"time"
+)
+
+type File struct{}
+
+func Open(name string) (file *File, err error)
+
+func openFile() { // OMIT
+	f, err := os.Open("filename.ext")
+	if err != nil {
+		log.Fatal(err)
+	}
+	// do something with the open *File f
+	// STOP OMIT
+	_ = f
+}
+
+// errorString is a trivial implementation of error.
+type errorString struct {
+	s string
+}
+
+func (e *errorString) Error() string {
+	return e.s
+}
+// STOP OMIT
+
+// New returns an error that formats as the given text.
+func New(text string) error {
+	return &errorString{text}
+}
+// STOP OMIT
+
+func Sqrt(f float64) (float64, error) {
+	if f < 0 {
+		return 0, errors.New("math: square root of negative number")
+	}
+	// implementation
+	return 0, nil // OMIT
+}
+// STOP OMIT
+
+func printErr() (int, error) { // OMIT
+	f, err := Sqrt(-1)
+	if err != nil {
+		fmt.Println(err)
+	}
+	// STOP OMIT
+	// fmtError OMIT
+	if f < 0 {
+		return 0, fmt.Errorf("math: square root of negative number %g", f)
+	}
+	// STOP OMIT
+	return 0, nil
+}
+
+type NegativeSqrtError float64
+
+func (f NegativeSqrtError) Error() string {
+	return fmt.Sprintf("math: square root of negative number %g", float64(f))
+}
+// STOP OMIT
+
+type SyntaxError struct {
+	msg    string // description of error
+	Offset int64  // error occurred after reading Offset bytes
+}
+
+func (e *SyntaxError) Error() string { return e.msg }
+// STOP OMIT
+
+func decodeError(dec *json.Decoder, val struct{}) error { // OMIT
+	var f os.FileInfo // OMIT
+	if err := dec.Decode(&val); err != nil {
+		if serr, ok := err.(*json.SyntaxError); ok {
+			line, col := findLine(f, serr.Offset)
+			return fmt.Errorf("%s:%d:%d: %v", f.Name(), line, col, err)
+		}
+		return err
+	}
+	// STOP OMIT
+	return nil
+}
+
+func findLine(os.FileInfo, int64) (int, int)
+
+func netError(err error) { // OMIT
+	for { // OMIT
+		if nerr, ok := err.(net.Error); ok && nerr.Temporary() {
+			time.Sleep(1e9)
+			continue
+		}
+		if err != nil {
+			log.Fatal(err)
+		}
+		// STOP OMIT
+	}
+}
+
+func main() {}

doc/progs/error2.go

+// 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.
+
+// This file contains the code snippets included in "Error Handling and Go."
+
+package main
+
+import (
+	"net/http"
+	"text/template"
+)
+
+func init() {
+	http.HandleFunc("/view", viewRecord)
+}
+
+func viewRecord(w http.ResponseWriter, r *http.Request) {
+	c := appengine.NewContext(r)
+	key := datastore.NewKey(c, "Record", r.FormValue("id"), 0, nil)
+	record := new(Record)
+	if err := datastore.Get(c, key, record); err != nil {
+		http.Error(w, err.Error(), 500)
+		return
+	}
+	if err := viewTemplate.Execute(w, record); err != nil {
+		http.Error(w, err.Error(), 500)
+	}
+}
+// STOP OMIT
+
+type ap struct{}
+
+func (ap) NewContext(*http.Request) *ctx { return nil }
+
+type ctx struct{}
+
+func (*ctx) Errorf(string, ...interface{}) {}
+
+var appengine ap
+
+type ds struct{}
+
+func (ds) NewKey(*ctx, string, string, int, *int) string { return "" }
+func (ds) Get(*ctx, string, *Record) error               { return nil }
+
+var datastore ds
+
+type Record struct{}
+
+var viewTemplate *template.Template
+
+func main() {}

doc/progs/error3.go

+// 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.
+
+// This file contains the code snippets included in "Error Handling and Go."
+
+package main
+
+import (
+	"net/http"
+	"text/template"
+)
+
+func init() {
+	http.Handle("/view", appHandler(viewRecord))
+}
+// STOP OMIT
+
+func viewRecord(w http.ResponseWriter, r *http.Request) error {
+	c := appengine.NewContext(r)
+	key := datastore.NewKey(c, "Record", r.FormValue("id"), 0, nil)
+	record := new(Record)
+	if err := datastore.Get(c, key, record); err != nil {
+		return err
+	}
+	return viewTemplate.Execute(w, record)
+}
+// STOP OMIT
+
+type appHandler func(http.ResponseWriter, *http.Request) error
+
+func (fn appHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	if err := fn(w, r); err != nil {
+		http.Error(w, err.Error(), 500)
+	}
+}
+// STOP OMIT
+
+type ap struct{}
+
+func (ap) NewContext(*http.Request) *ctx { return nil }
+
+type ctx struct{}
+
+func (*ctx) Errorf(string, ...interface{}) {}
+
+var appengine ap
+
+type ds struct{}
+
+func (ds) NewKey(*ctx, string, string, int, *int) string { return "" }
+func (ds) Get(*ctx, string, *Record) error               { return nil }
+
+var datastore ds
+
+type Record struct{}
+
+var viewTemplate *template.Template
+
+func main() {}

doc/progs/error4.go

+// 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.
+
+// This file contains the code snippets included in "Error Handling and Go."
+
+package main
+
+import (
+	"net/http"
+	"text/template"
+)
+
+type appError struct {
+	Error   error
+	Message string
+	Code    int
+}
+// STOP OMIT
+
+type appHandler func(http.ResponseWriter, *http.Request) *appError
+
+func (fn appHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	if e := fn(w, r); e != nil { // e is *appError, not os.Error.
+		c := appengine.NewContext(r)
+		c.Errorf("%v", e.Error)
+		http.Error(w, e.Message, e.Code)
+	}
+}
+// STOP OMIT
+
+func viewRecord(w http.ResponseWriter, r *http.Request) *appError {
+	c := appengine.NewContext(r)
+	key := datastore.NewKey(c, "Record", r.FormValue("id"), 0, nil)
+	record := new(Record)
+	if err := datastore.Get(c, key, record); err != nil {
+		return &appError{err, "Record not found", 404}
+	}
+	if err := viewTemplate.Execute(w, record); err != nil {
+		return &appError{err, "Can't display record", 500}
+	}
+	return nil
+}
+// STOP OMIT
+
+func init() {
+	http.Handle("/view", appHandler(viewRecord))
+}
+
+type ap struct{}
+
+func (ap) NewContext(*http.Request) *ctx { return nil }
+
+type ctx struct{}
+
+func (*ctx) Errorf(string, ...interface{}) {}
+
+var appengine ap
+
+type ds struct{}
+
+func (ds) NewKey(*ctx, string, string, int, *int) string { return "" }
+func (ds) Get(*ctx, string, *Record) error               { return nil }
+
+var datastore ds
+
+type Record struct{}
+
+var viewTemplate *template.Template
+
+func main() {}

doc/progs/run

@@ -31,6 +31,13 @@ effective_go="
 	eff_sequence.go
 "
 
+error_handling="
+	error.go
+	error2.go
+	error3.go
+	error4.go
+"
+
 go_tutorial="
 	cat.go 
 	cat_rot13.go 
@@ -52,6 +59,7 @@ go_tutorial="
 for i in \
 	$defer_panic_recover \
 	$effective_go \
+	$error_handling \
 	$go_tutorial \
 	go1.go \
 ; do