From: Russ Cox Date: Thu, 8 Mar 2012 13:39:20 +0000 (-0500) Subject: cmd/godoc: add support for serving templates X-Git-Tag: weekly.2012-03-13~88 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=a40065ac6838068f07dcb12084406bab403067f2;p=gostls13.git cmd/godoc: add support for serving templates doc: convert to use godoc built-in templates tmpltohtml is gone, to avoid having a second copy of the code. Instead, godoc -url /doc/go1.html will print the actual HTML served for that URL. "make" will generate files named go1.rawhtml etc, which can be fed through tidy. It can be hard to tell from the codereview diffs, but all the tmpl files have been renamed to be html files and then have "Template": true added. R=golang-dev, adg, r, gri CC=golang-dev https://golang.org/cl/5782046 --- diff --git a/doc/Makefile b/doc/Makefile index ea39d7ab93..60e1ef369c 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -2,21 +2,18 @@ # Use of this source code is governed by a BSD-style # license that can be found in the LICENSE file. -HTML=\ - articles/defer_panic_recover.html\ - articles/error_handling.html\ - articles/slices_usage_and_internals.html\ - articles/laws_of_reflection.html\ - effective_go.html\ - go1.html\ +RAWHTML=\ + articles/defer_panic_recover.rawhtml\ + articles/error_handling.rawhtml\ + articles/slices_usage_and_internals.rawhtml\ + articles/laws_of_reflection.rawhtml\ + effective_go.rawhtml\ + go1.rawhtml\ -all: tmpltohtml $(HTML) +all: $(RAWHTML) -tmpltohtml: tmpltohtml.go - go build tmpltohtml.go - -%.html: %.tmpl tmpltohtml - ./tmpltohtml $*.tmpl > $@ +%.rawhtml: %.html + godoc -url /doc/$* >$@ clean: - rm -f $(HTML) tmpltohtml + rm -f $(RAWHTML) diff --git a/doc/articles/defer_panic_recover.html b/doc/articles/defer_panic_recover.html index be97045dd9..206b836d8a 100644 --- a/doc/articles/defer_panic_recover.html +++ b/doc/articles/defer_panic_recover.html @@ -1,10 +1,7 @@ -

Go has the usual mechanisms for control flow: if, for, switch, goto. It also @@ -23,23 +20,7 @@ For example, let's look at a function that opens two files and copies the contents of one file to the other:

-
func CopyFile(dstName, srcName string) (written int64, err error) {
-    src, err := os.Open(srcName)
-    if err != nil {
-        return
-    }
-
-    dst, err := os.Create(dstName)
-    if err != nil {
-        return
-    }
-
-    written, err = io.Copy(dst, src)
-    dst.Close()
-    src.Close()
-    return
-}
+{{code "/doc/progs/defer.go" `/func CopyFile/` `/STOP/`}}

This works, but there is a bug. If the call to os.Create fails, the @@ -50,22 +31,7 @@ noticed and resolved. By introducing defer statements we can ensure that the files are always closed:

-
func CopyFile(dstName, srcName string) (written int64, err error) {
-    src, err := os.Open(srcName)
-    if err != nil {
-        return
-    }
-    defer src.Close()
-
-    dst, err := os.Create(dstName)
-    if err != nil {
-        return
-    }
-    defer dst.Close()
-
-    return io.Copy(dst, src)
-}
+{{code "/doc/progs/defer2.go" `/func CopyFile/` `/STOP/`}}

Defer statements allow us to think about closing each file right after opening @@ -88,13 +54,7 @@ In this example, the expression "i" is evaluated when the Println call is deferred. The deferred call will print "0" after the function returns.

-
func a() {
-    i := 0
-    defer fmt.Println(i)
-    i++
-    return
-}
+{{code "/doc/progs/defer.go" `/func a/` `/STOP/`}}

2. Deferred function calls are executed in Last In First Out order @@ -105,12 +65,7 @@ deferred. The deferred call will print "0" after the function returns. This function prints "3210":

-
func b() {
-    for i := 0; i < 4; i++ {
-        defer fmt.Print(i)
-    }
-}
+{{code "/doc/progs/defer.go" `/func b/` `/STOP/`}}

3. Deferred functions may read and assign to the returning function's named @@ -122,11 +77,7 @@ In this example, a deferred function increments the return value i after the surrounding function returns. Thus, this function returns 2:

-
func c() (i int) {
-    defer func() { i++ }()
-    return 1
-}
+{{code "/doc/progs/defer.go" `/func c/` `/STOP/`}}

This is convenient for modifying the error return value of a function; we will @@ -156,36 +107,7 @@ to panic and resume normal execution. Here's an example program that demonstrates the mechanics of panic and defer:

-
package main
-
-import "fmt"
-
-func main() {
-    f()
-    fmt.Println("Returned normally from f.")
-}
-
-func f() {
-    defer func() {
-        if r := recover(); r != nil {
-            fmt.Println("Recovered in f", r)
-        }
-    }()
-    fmt.Println("Calling g.")
-    g(0)
-    fmt.Println("Returned normally from g.")
-}
-
-func g(i int) {
-    if i > 3 {
-        fmt.Println("Panicking!")
-        panic(fmt.Sprintf("%v", i))
-    }
-    defer fmt.Println("Defer in g", i)
-    fmt.Println("Printing in g", i)
-    g(i + 1)
-}
+{{code "/doc/progs/defer2.go" `/package main/` `/STOP/`}}

The function g takes the int i, and panics if i is greater than 3, or else it diff --git a/doc/articles/defer_panic_recover.tmpl b/doc/articles/defer_panic_recover.tmpl deleted file mode 100644 index 5f48c6ef48..0000000000 --- a/doc/articles/defer_panic_recover.tmpl +++ /dev/null @@ -1,195 +0,0 @@ - -{{donotedit}} -

-Go has the usual mechanisms for control flow: if, for, switch, goto. It also -has the go statement to run code in a separate goroutine. Here I'd like to -discuss some of the less common ones: defer, panic, and recover. -

- -

-A defer statement pushes a function call onto a list. The list of saved -calls is executed after the surrounding function returns. Defer is commonly -used to simplify functions that perform various clean-up actions. -

- -

-For example, let's look at a function that opens two files and copies the -contents of one file to the other: -

- -{{code "progs/defer.go" `/func CopyFile/` `/STOP/`}} - -

-This works, but there is a bug. If the call to os.Create fails, the -function will return without closing the source file. This can be easily -remedied by putting a call to src.Close() before the second return statement, -but if the function were more complex the problem might not be so easily -noticed and resolved. By introducing defer statements we can ensure that the -files are always closed: -

- -{{code "progs/defer2.go" `/func CopyFile/` `/STOP/`}} - -

-Defer statements allow us to think about closing each file right after opening -it, guaranteeing that, regardless of the number of return statements in the -function, the files will be closed. -

- -

-The behavior of defer statements is straightforward and predictable. There are -three simple rules: -

- -

-1. A deferred function's arguments are evaluated when the defer statement is -evaluated. -

- -

-In this example, the expression "i" is evaluated when the Println call is -deferred. The deferred call will print "0" after the function returns. -

- -{{code "progs/defer.go" `/func a/` `/STOP/`}} - -

-2. Deferred function calls are executed in Last In First Out order -after the surrounding function returns. -

- -

-This function prints "3210": -

- -{{code "progs/defer.go" `/func b/` `/STOP/`}} - -

-3. Deferred functions may read and assign to the returning function's named -return values. -

- -

-In this example, a deferred function increments the return value i after -the surrounding function returns. Thus, this function returns 2: -

- -{{code "progs/defer.go" `/func c/` `/STOP/`}} - -

-This is convenient for modifying the error return value of a function; we will -see an example of this shortly. -

- -

-Panic is a built-in function that stops the ordinary flow of control and -begins panicking. When the function F calls panic, execution of F stops, -any deferred functions in F are executed normally, and then F returns to its -caller. To the caller, F then behaves like a call to panic. The process -continues up the stack until all functions in the current goroutine have -returned, at which point the program crashes. Panics can be initiated by -invoking panic directly. They can also be caused by runtime errors, such as -out-of-bounds array accesses. -

- -

-Recover is a built-in function that regains control of a panicking -goroutine. Recover is only useful inside deferred functions. During normal -execution, a call to recover will return nil and have no other effect. If the -current goroutine is panicking, a call to recover will capture the value given -to panic and resume normal execution. -

- -

-Here's an example program that demonstrates the mechanics of panic and defer: -

- -{{code "progs/defer2.go" `/package main/` `/STOP/`}} - -

-The function g takes the int i, and panics if i is greater than 3, or else it -calls itself with the argument i+1. The function f defers a function that calls -recover and prints the recovered value (if it is non-nil). Try to picture what -the output of this program might be before reading on. -

- -

-The program will output: -

- -
Calling g.
-Printing in g 0
-Printing in g 1
-Printing in g 2
-Printing in g 3
-Panicking!
-Defer in g 3
-Defer in g 2
-Defer in g 1
-Defer in g 0
-Recovered in f 4
-Returned normally from f.
- -

-If we remove the deferred function from f the panic is not recovered and -reaches the top of the goroutine's call stack, terminating the program. This -modified program will output: -

- -
Calling g.
-Printing in g 0
-Printing in g 1
-Printing in g 2
-Printing in g 3
-Panicking!
-Defer in g 3
-Defer in g 2
-Defer in g 1
-Defer in g 0
-panic: 4
- 
-panic PC=0x2a9cd8
-[stack trace omitted]
- -

-For a real-world example of panic and recover, see the -json package from the Go standard library. -It decodes JSON-encoded data with a set of recursive functions. -When malformed JSON is encountered, the parser calls panic to unwind the -stack to the top-level function call, which recovers from the panic and returns -an appropriate error value (see the 'error' and 'unmarshal' functions in -decode.go). -

- -

-The convention in the Go libraries is that even when a package uses panic -internally, its external API still presents explicit error return values. -

- -

-Other uses of defer (beyond the file.Close() example given earlier) -include releasing a mutex: -

- -
mu.Lock()
-defer mu.Unlock()
- -

-printing a footer: -

- -
printHeader()
-defer printFooter()
- -

-and more. -

- -

-In summary, the defer statement (with or without panic and recover) provides an -unusual and powerful mechanism for control flow. It can be used to model a -number of features implemented by special-purpose structures in other -programming languages. Try it out. -

diff --git a/doc/articles/error_handling.html b/doc/articles/error_handling.html index ac33f1dabc..b66033cb74 100644 --- a/doc/articles/error_handling.html +++ b/doc/articles/error_handling.html @@ -1,10 +1,7 @@ -

If you have written any Go code you have probably encountered the built-in @@ -13,20 +10,14 @@ indicate an abnormal state. For example, the os.Open function returns a non-nil error value when it fails to open a file.

-
func Open(name string) (file *File, err error)
+{{code "/doc/progs/error.go" `/func Open/`}}

The following code uses os.Open to open a file. If an error occurs it calls log.Fatal to print the error message and stop.

-
    f, err := os.Open("filename.ext")
-    if err != nil {
-        log.Fatal(err)
-    }
-    // do something with the open *File f
+{{code "/doc/progs/error.go" `/func openFile/` `/STOP/`}}

You can get a lot done in Go knowing just this about the error @@ -59,15 +50,7 @@ The most commonly-used error implementation is the errors package's unexported errorString type.

-
// errorString is a trivial implementation of error.
-type errorString struct {
-    s string
-}
-
-func (e *errorString) Error() string {
-    return e.s
-}
+{{code "/doc/progs/error.go" `/errorString/` `/STOP/`}}

You can construct one of these values with the errors.New @@ -75,23 +58,13 @@ function. It takes a string that it converts to an errors.errorStringerror value.

-
// New returns an error that formats as the given text.
-func New(text string) error {
-    return &errorString{text}
-}
+{{code "/doc/progs/error.go" `/New/` `/STOP/`}}

Here's how you might use errors.New:

-
func Sqrt(f float64) (float64, error) {
-    if f < 0 {
-        return 0, errors.New("math: square root of negative number")
-    }
-    // implementation
-}
+{{code "/doc/progs/error.go" `/func Sqrt/` `/STOP/`}}

A caller passing a negative argument to Sqrt receives a non-nil @@ -101,11 +74,7 @@ A caller passing a negative argument to Sqrt receives a non-nil Error method, or by just printing it:

-
    f, err := Sqrt(-1)
-    if err != nil {
-        fmt.Println(err)
-    }
+{{code "/doc/progs/error.go" `/func printErr/` `/STOP/`}}

The fmt package formats an error value @@ -126,10 +95,7 @@ rules and returns it as an error created by errors.New.

-
    if f < 0 {
-        return 0, fmt.Errorf("math: square root of negative number %g", f)
-    }
+{{code "/doc/progs/error.go" `/fmtError/` `/STOP/`}}

In many cases fmt.Errorf is good enough, but since @@ -143,12 +109,7 @@ argument passed to Sqrt. We can enable that by defining a new error implementation instead of using errors.errorString:

-
type NegativeSqrtError float64
-
-func (f NegativeSqrtError) Error() string {
-    return fmt.Sprintf("math: square root of negative number %g", float64(f))
-}
+{{code "/doc/progs/error.go" `/type NegativeSqrtError/` `/STOP/`}}

A sophisticated caller can then use a @@ -164,13 +125,7 @@ As another example, the json package specifies returns when it encounters a syntax error parsing a JSON blob.

-
type SyntaxError struct {
-    msg    string // description of error
-    Offset int64  // error occurred after reading Offset bytes
-}
-
-func (e *SyntaxError) Error() string { return e.msg }
+{{code "/doc/progs/error.go" `/type SyntaxError/` `/STOP/`}}

The Offset field isn't even shown in the default formatting of the @@ -178,14 +133,7 @@ error, but callers can use it to add file and line information to their error messages:

-
    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
-    }
+{{code "/doc/progs/error.go" `/func decodeError/` `/STOP/`}}

(This is a slightly simplified version of some @@ -217,14 +165,7 @@ web crawler might sleep and retry when it encounters a temporary error and give up otherwise.

-
        if nerr, ok := err.(net.Error); ok && nerr.Temporary() {
-            time.Sleep(1e9)
-            continue
-        }
-        if err != nil {
-            log.Fatal(err)
-        }
+{{code "/doc/progs/error.go" `/func netError/` `/STOP/`}}

Simplifying repetitive error handling @@ -244,23 +185,7 @@ application with an HTTP handler that retrieves a record from the datastore and formats it with a 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)
-    }
-}
+{{code "/doc/progs/error2.go" `/func init/` `/STOP/`}}

This function handles errors returned by the datastore.Get @@ -276,23 +201,13 @@ To reduce the repetition we can define our own HTTP appHandler type that includes an error return value:

-
type appHandler func(http.ResponseWriter, *http.Request) error
+{{code "/doc/progs/error3.go" `/type appHandler/`}}

Then we can change our viewRecord function to return errors:

-
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)
-}
+{{code "/doc/progs/error3.go" `/func viewRecord/` `/STOP/`}}

This is simpler than the original version, but the http.Handler interface's ServeHTTP method on appHandler:

-
func (fn appHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
-    if err := fn(w, r); err != nil {
-        http.Error(w, err.Error(), 500)
-    }
-}
+{{code "/doc/progs/error3.go" `/ServeHTTP/` `/STOP/`}}

The ServeHTTP method calls the appHandler function @@ -323,10 +233,7 @@ Now when registering viewRecord with the http package we use the http.HandlerFunc).

-
func init() {
-    http.Handle("/view", appHandler(viewRecord))
-}
+{{code "/doc/progs/error3.go" `/func init/` `/STOP/`}}

With this basic error handling infrastructure in place, we can make it more @@ -341,19 +248,13 @@ To do this we create an appError struct containing an error and some other fields:

-
type appError struct {
-    Error   error
-    Message string
-    Code    int
-}
+{{code "/doc/progs/error4.go" `/type appError/` `/STOP/`}}

Next we modify the appHandler type to return *appError values:

-
type appHandler func(http.ResponseWriter, *http.Request) *appError
+{{code "/doc/progs/error4.go" `/type appHandler/`}}

(It's usually a mistake to pass back the concrete type of an error rather than @@ -369,33 +270,14 @@ status Code and log the full Error to the developer console:

-
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)
-    }
-}
+{{code "/doc/progs/error4.go" `/ServeHTTP/` `/STOP/`}}

Finally, we update viewRecord to the new function signature and have it return more context when it encounters an error:

-
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
-}
+{{code "/doc/progs/error4.go" `/func viewRecord/` `/STOP/`}}

This version of viewRecord is the same length as the original, but diff --git a/doc/articles/error_handling.tmpl b/doc/articles/error_handling.tmpl deleted file mode 100644 index 56b7fb309d..0000000000 --- a/doc/articles/error_handling.tmpl +++ /dev/null @@ -1,314 +0,0 @@ - -{{donotedit}} -

-If you have written any Go code you have probably encountered the built-in -error type. Go code uses error values to -indicate an abnormal state. For example, the os.Open function -returns a non-nil error value when it fails to open a file. -

- -{{code "progs/error.go" `/func Open/`}} - -

-The following code uses os.Open to open a file. If an error -occurs it calls log.Fatal to print the error message and stop. -

- -{{code "progs/error.go" `/func openFile/` `/STOP/`}} - -

-You can get a lot done in Go knowing just this about the error -type, but in this article we'll take a closer look at error and -discuss some good practices for error handling in Go. -

- -

-The error type -

- -

-The error type is an interface type. An error -variable represents any value that can describe itself as a string. Here is the -interface's declaration: -

- -
type error interface {
-    Error() string
-}
- -

-The error type, as with all built in types, is -predeclared in the -universe block. -

- -

-The most commonly-used error implementation is the -errors package's unexported errorString type. -

- -{{code "progs/error.go" `/errorString/` `/STOP/`}} - -

-You can construct one of these values with the errors.New -function. It takes a string that it converts to an errors.errorString -and returns as an error value. -

- -{{code "progs/error.go" `/New/` `/STOP/`}} - -

-Here's how you might use errors.New: -

- -{{code "progs/error.go" `/func Sqrt/` `/STOP/`}} - -

-A caller passing a negative argument to Sqrt receives a non-nil -error value (whose concrete representation is an -errors.errorString value). The caller can access the error string -("math: square root of...") by calling the error's -Error method, or by just printing it: -

- -{{code "progs/error.go" `/func printErr/` `/STOP/`}} - -

-The fmt package formats an error value -by calling its Error() string method. -

- -

-It is the error implementation's responsibility to summarize the context. -The error returned by os.Open formats as "open /etc/passwd: -permission denied," not just "permission denied." The error returned by our -Sqrt is missing information about the invalid argument. -

- -

-To add that information, a useful function is the fmt package's -Errorf. It formats a string according to Printf's -rules and returns it as an error created by -errors.New. -

- -{{code "progs/error.go" `/fmtError/` `/STOP/`}} - -

-In many cases fmt.Errorf is good enough, but since -error is an interface, you can use arbitrary data structures as -error values, to allow callers to inspect the details of the error. -

- -

-For instance, our hypothetical callers might want to recover the invalid -argument passed to Sqrt. We can enable that by defining a new -error implementation instead of using errors.errorString: -

- -{{code "progs/error.go" `/type NegativeSqrtError/` `/STOP/`}} - -

-A sophisticated caller can then use a -type assertion to check for a -NegativeSqrtError and handle it specially, while callers that just -pass the error to fmt.Println or log.Fatal will see -no change in behavior. -

- -

-As another example, the json package specifies a -SyntaxError type that the json.Decode function -returns when it encounters a syntax error parsing a JSON blob. -

- -{{code "progs/error.go" `/type SyntaxError/` `/STOP/`}} - -

-The Offset field isn't even shown in the default formatting of the -error, but callers can use it to add file and line information to their error -messages: -

- -{{code "progs/error.go" `/func decodeError/` `/STOP/`}} - -

-(This is a slightly simplified version of some -actual code -from the Camlistore project.) -

- -

-The error interface requires only a Error method; -specific error implementations might have additional methods. For instance, the -net package returns errors of type -error, following the usual convention, but some of the error -implementations have additional methods defined by the net.Error -interface: -

- -
package net
-
-type Error interface {
-    error
-    Timeout() bool   // Is the error a timeout?
-    Temporary() bool // Is the error temporary?
-}
- -

-Client code can test for a net.Error with a type assertion and -then distinguish transient network errors from permanent ones. For instance, a -web crawler might sleep and retry when it encounters a temporary error and give -up otherwise. -

- -{{code "progs/error.go" `/func netError/` `/STOP/`}} - -

-Simplifying repetitive error handling -

- -

-In Go, error handling is important. The language's design and conventions -encourage you to explicitly check for errors where they occur (as distinct from -the convention in other languages of throwing exceptions and sometimes catching -them). In some cases this makes Go code verbose, but fortunately there are some -techniques you can use to minimize repetitive error handling. -

- -

-Consider an App Engine -application with an HTTP handler that retrieves a record from the datastore and -formats it with a template. -

- -{{code "progs/error2.go" `/func init/` `/STOP/`}} - -

-This function handles errors returned by the datastore.Get -function and viewTemplate's Execute method. In both -cases, it presents a simple error message to the user with the HTTP status code -500 ("Internal Server Error"). This looks like a manageable amount of code, but -add some more HTTP handlers and you quickly end up with many copies of -identical error handling code. -

- -

-To reduce the repetition we can define our own HTTP appHandler -type that includes an error return value: -

- -{{code "progs/error3.go" `/type appHandler/`}} - -

-Then we can change our viewRecord function to return errors: -

- -{{code "progs/error3.go" `/func viewRecord/` `/STOP/`}} - -

-This is simpler than the original version, but the http package doesn't understand functions that return -error. -To fix this we can implement the http.Handler interface's -ServeHTTP method on appHandler: -

- -{{code "progs/error3.go" `/ServeHTTP/` `/STOP/`}} - -

-The ServeHTTP method calls the appHandler function -and displays the returned error (if any) to the user. Notice that the method's -receiver, fn, is a function. (Go can do that!) The method invokes -the function by calling the receiver in the expression fn(w, r). -

- -

-Now when registering viewRecord with the http package we use the -Handle function (instead of HandleFunc) as -appHandler is an http.Handler (not an -http.HandlerFunc). -

- -{{code "progs/error3.go" `/func init/` `/STOP/`}} - -

-With this basic error handling infrastructure in place, we can make it more -user friendly. Rather than just displaying the error string, it would be better -to give the user a simple error message with an appropriate HTTP status code, -while logging the full error to the App Engine developer console for debugging -purposes. -

- -

-To do this we create an appError struct containing an -error and some other fields: -

- -{{code "progs/error4.go" `/type appError/` `/STOP/`}} - -

-Next we modify the appHandler type to return *appError values: -

- -{{code "progs/error4.go" `/type appHandler/`}} - -

-(It's usually a mistake to pass back the concrete type of an error rather than -error, for reasons to be discussed in another article, but -it's the right thing to do here because ServeHTTP is the only -place that sees the value and uses its contents.) -

- -

-And make appHandler's ServeHTTP method display the -appError's Message to the user with the correct HTTP -status Code and log the full Error to the developer -console: -

- -{{code "progs/error4.go" `/ServeHTTP/` `/STOP/`}} - -

-Finally, we update viewRecord to the new function signature and -have it return more context when it encounters an error: -

- -{{code "progs/error4.go" `/func viewRecord/` `/STOP/`}} - -

-This version of viewRecord is the same length as the original, but -now each of those lines has specific meaning and we are providing a friendlier -user experience. -

- -

-It doesn't end there; we can further improve the error handling in our -application. Some ideas: -

- -
    -
  • give the error handler a pretty HTML template, -
  • make debugging easier by writing the stack trace to the HTTP response when -the user is an administrator, -
  • write a constructor function for appError that stores the -stack trace for easier debugging, -
  • recover from panics inside the appHandler, logging the error -to the console as "Critical," while telling the user "a serious error -has occurred." This is a nice touch to avoid exposing the user to inscrutable -error messages caused by programming errors. -See the Defer, Panic, and Recover -article for more details. -
- -

-Conclusion -

- -

-Proper error handling is an essential requirement of good software. By -employing the techniques described in this post you should be able to write -more reliable and succinct Go code. -

diff --git a/doc/articles/laws_of_reflection.html b/doc/articles/laws_of_reflection.html index 37eb96bb6b..ca729508bb 100644 --- a/doc/articles/laws_of_reflection.html +++ b/doc/articles/laws_of_reflection.html @@ -1,11 +1,7 @@ - -

Reflection in computing is the @@ -36,11 +32,7 @@ exactly one type known and fixed at compile time: int, and so on. If we declare

-
type MyInt int
-
-var i int
-var j MyInt
+{{code "/doc/progs/interface.go" `/type MyInt/` `/STOP/`}}

then i has type int and j @@ -60,16 +52,7 @@ interface's methods. A well-known pair of examples is "http://golang.org/pkg/io/">io package:

-
// Reader is the interface that wraps the basic Read method.
-type Reader interface {
-    Read(p []byte) (n int, err error)
-}
-
-// Writer is the interface that wraps the basic Write method.
-type Writer interface {
-    Write(p []byte) (n int, err error)
-}
+{{code "/doc/progs/interface.go" `/// Reader/` `/STOP/`}}

Any type that implements a Read (or @@ -80,12 +63,7 @@ purposes of this discussion, that means that a variable of type Read method:

-
    var r io.Reader
-    r = os.Stdin
-    r = bufio.NewReader(r)
-    r = new(bytes.Buffer)
-    // and so on
+{{code "/doc/progs/interface.go" `/func readers/` `/STOP/`}}

It's important to be clear that whatever concrete value @@ -138,13 +116,7 @@ that implements the interface and the type describes the full type of that item. For instance, after

-
    var r io.Reader
-    tty, err := os.OpenFile("/dev/tty", os.O_RDWR, 0)
-    if err != nil {
-        return nil, err
-    }
-    r = tty
+{{code "/doc/progs/interface.go" `/func typeAssertions/` `/STOP/`}}

r contains, schematically, the (value, type) pair, @@ -156,9 +128,7 @@ the type information about that value. That's why we can do things like this:

-
    var w io.Writer
-    w = r.(io.Writer)
+{{code "/doc/progs/interface.go" `/var w io.Writer/` `/STOP/`}}

The expression in this assignment is a type assertion; what it @@ -176,9 +146,7 @@ methods. Continuing, we can do this:

-
    var empty interface{}
-    empty = w
+{{code "/doc/progs/interface.go" `/var empty interface{}/` `/STOP/`}}

and our empty interface value e will again contain @@ -232,18 +200,7 @@ now.) Let's start with TypeOf:

-
package main
-
-import (
-    "fmt"
-    "reflect"
-)
-
-func main() {
-    var x float64 = 3.4
-    fmt.Println("type:", reflect.TypeOf(x))
-}
+{{code "/doc/progs/interface2.go" `/package main/` `/STOP main/`}}

This program prints @@ -281,9 +238,7 @@ value (from here on we'll elide the boilerplate and focus just on the executable code):

-
    var x float64 = 3.4
-    fmt.Println("type:", reflect.TypeOf(x))
+{{code "/doc/progs/interface2.go" `/var x/` `/STOP/`}}

prints @@ -307,12 +262,7 @@ on. Also methods on Value with names like int64 and float64) stored inside:

-
    var x float64 = 3.4
-    v := reflect.ValueOf(x)
-    fmt.Println("type:", v.Type())
-    fmt.Println("kind is float64:", v.Kind() == reflect.Float64)
-    fmt.Println("value:", v.Float())
+{{code "/doc/progs/interface2.go" `/START f1/` `/STOP/`}}

prints @@ -342,12 +292,7 @@ instance. That is, the Int method of necessary to convert to the actual type involved:

-
    var x uint8 = 'x'
-    v := reflect.ValueOf(x)
-    fmt.Println("type:", v.Type())                            // uint8.
-    fmt.Println("kind is uint8: ", v.Kind() == reflect.Uint8) // true.
-    x = uint8(v.Uint())                                       // v.Uint returns a uint64.
+{{code "/doc/progs/interface2.go" `/START f2/` `/STOP/`}}

The second property is that the Kind of a reflection @@ -356,10 +301,7 @@ reflection object contains a value of a user-defined integer type, as in

-
    type MyInt int
-    var x MyInt = 7
-    v := reflect.ValueOf(x)
+{{code "/doc/progs/interface2.go" `/START f3/` `/STOP/`}}

the Kind of v is still @@ -395,9 +337,7 @@ func (v Value) Interface() interface{} As a consequence we can say

-
    y := v.Interface().(float64) // y will have type float64.
-    fmt.Println(y)
+{{code "/doc/progs/interface2.go" `/START f3b/` `/STOP/`}}

to print the float64 value represented by the @@ -415,8 +355,7 @@ the Interface method to the formatted print routine:

-
    fmt.Println(v.Interface())
+{{code "/doc/progs/interface2.go" `/START f3c/` `/STOP/`}}

(Why not fmt.Println(v)? Because v is a @@ -425,8 +364,7 @@ Since our value is a float64, we can even use a floating-point format if we want:

-
    fmt.Printf("value is %7.1e\n", v.Interface())
+{{code "/doc/progs/interface2.go" `/START f3d/` `/STOP/`}}

and get in this case @@ -467,10 +405,7 @@ enough to understand if we start from first principles. Here is some code that does not work, but is worth studying.

-
    var x float64 = 3.4
-    v := reflect.ValueOf(x)
-    v.SetFloat(7.1) // Error: will panic.
+{{code "/doc/progs/interface2.go" `/START f4/` `/STOP/`}}

If you run this code, it will panic with the cryptic message @@ -492,10 +427,7 @@ The CanSet method of Value reports the settability of a Value; in our case,

-
    var x float64 = 3.4
-    v := reflect.ValueOf(x)
-    fmt.Println("settability of v:", v.CanSet())
+{{code "/doc/progs/interface2.go" `/START f5/` `/STOP/`}}

prints @@ -518,9 +450,7 @@ determined by whether the reflection object holds the original item. When we say

-
    var x float64 = 3.4
-    v := reflect.ValueOf(x)
+{{code "/doc/progs/interface2.go" `/START f6/` `/STOP/`}}

we pass a copy of x to @@ -530,8 +460,7 @@ argument to reflect.ValueOf is a copy of statement

-
    v.SetFloat(7.1)
+{{code "/doc/progs/interface2.go" `/START f6b/` `/STOP/`}}

were allowed to succeed, it would not update x, even @@ -577,11 +506,7 @@ and then create a reflection value that points to it, called p.

-
    var x float64 = 3.4
-    p := reflect.ValueOf(&x) // Note: take the address of x.
-    fmt.Println("type of p:", p.Type())
-    fmt.Println("settability of p:", p.CanSet())
+{{code "/doc/progs/interface2.go" `/START f7/` `/STOP/`}}

The output so far is @@ -601,9 +526,7 @@ and save the result in a reflection Value called v:

-
    v := p.Elem()
-    fmt.Println("settability of v:", v.CanSet())
+{{code "/doc/progs/interface2.go" `/START f7b/` `/STOP/`}}

Now v is a settable reflection object, as the output @@ -620,10 +543,7 @@ and since it represents x, we are finally able to use x:

-
    v.SetFloat(7.1)
-    fmt.Println(v.Interface())
-    fmt.Println(x)
+{{code "/doc/progs/interface2.go" `/START f7c/` `/STOP/`}}

The output, as expected, is @@ -664,19 +584,7 @@ but the fields themselves are regular reflect.Value objects.

-
    type T struct {
-        A int
-        B string
-    }
-    t := T{23, "skidoo"}
-    s := reflect.ValueOf(&t).Elem()
-    typeOfT := s.Type()
-    for i := 0; i < s.NumField(); i++ {
-        f := s.Field(i)
-        fmt.Printf("%d: %s %s = %v\n", i,
-            typeOfT.Field(i).Name, f.Type(), f.Interface())
-    }
+{{code "/doc/progs/interface2.go" `/START f8/` `/STOP/`}}

The output of this program is @@ -699,10 +607,7 @@ Because s contains a settable reflection object, we can modify the fields of the structure.

-
    s.Field(0).SetInt(77)
-    s.Field(1).SetString("Sunset Strip")
-    fmt.Println("t is now", t)
+{{code "/doc/progs/interface2.go" `/START f8b/` `/STOP/`}}

And here's the result: @@ -746,4 +651,4 @@ sending and receiving on channels, allocating memory, using slices and maps, calling methods and functions — but this post is long enough. We'll cover some of those topics in a later article. -

\ No newline at end of file +

diff --git a/doc/articles/laws_of_reflection.tmpl b/doc/articles/laws_of_reflection.tmpl deleted file mode 100644 index d89566f622..0000000000 --- a/doc/articles/laws_of_reflection.tmpl +++ /dev/null @@ -1,654 +0,0 @@ - -{{donotedit}} - -

-Reflection in computing is the -ability of a program to examine its own structure, particularly -through types; it's a form of metaprogramming. It's also a great -source of confusion. -

- -

-In this article we attempt to clarify things by explaining how -reflection works in Go. Each language's reflection model is -different (and many languages don't support it at all), but -this article is about Go, so for the rest of this article the word -"reflection" should be taken to mean "reflection in Go". -

- -

Types and interfaces

- -

-Because reflection builds on the type system, let's start with a -refresher about types in Go. -

- -

-Go is statically typed. Every variable has a static type, that is, -exactly one type known and fixed at compile time: int, -float32, *MyType, []byte, -and so on. If we declare -

- -{{code "progs/interface.go" `/type MyInt/` `/STOP/`}} - -

-then i has type int and j -has type MyInt. The variables i and -j have distinct static types and, although they have -the same underlying type, they cannot be assigned to one another -without a conversion. -

- -

-One important category of type is interface types, which represent -fixed sets of methods. An interface variable can store any concrete -(non-interface) value as long as that value implements the -interface's methods. A well-known pair of examples is -io.Reader and io.Writer, the types -Reader and Writer from the io package: -

- -{{code "progs/interface.go" `/// Reader/` `/STOP/`}} - -

-Any type that implements a Read (or -Write) method with this signature is said to implement -io.Reader (or io.Writer). For the -purposes of this discussion, that means that a variable of type -io.Reader can hold any value whose type has a -Read method: -

- -{{code "progs/interface.go" `/func readers/` `/STOP/`}} - -

-It's important to be clear that whatever concrete value -r may hold, r's type is always -io.Reader: Go is statically typed and the static type -of r is io.Reader.

- -

-An extremely important example of an interface type is the empty -interface: -

- -
-interface{}
-
- -

-It represents the empty set of methods and is satisfied by any -value at all, since any value has zero or more methods. -

- -

-Some people say that Go's interfaces are dynamically typed, but -that is misleading. They are statically typed: a variable of -interface type always has the same static type, and even though at -run time the value stored in the interface variable may change -type, that value will always satisfy the interface. -

- -

-We need to be precise about all this because reflection and -interfaces are closely related. -

- -

The representation of an interface

- -

-Russ Cox has written a -detailed blog post about the representation of interface values -in Go. It's not necessary to repeat the full story here, but a -simplified summary is in order. -

- -

-A variable of interface type stores a pair: the concrete value -assigned to the variable, and that value's type descriptor. -To be more precise, the value is the underlying concrete data item -that implements the interface and the type describes the full type -of that item. For instance, after -

- -{{code "progs/interface.go" `/func typeAssertions/` `/STOP/`}} - -

-r contains, schematically, the (value, type) pair, -(tty, *os.File). Notice that the type -*os.File implements methods other than -Read; even though the interface value provides access -only to the Read method, the value inside carries all -the type information about that value. That's why we can do things -like this: -

- -{{code "progs/interface.go" `/var w io.Writer/` `/STOP/`}} - -

-The expression in this assignment is a type assertion; what it -asserts is that the item inside r also implements -io.Writer, and so we can assign it to w. -After the assignment, w will contain the pair -(tty, *os.File). That's the same pair as -was held in r. The static type of the interface -determines what methods may be invoked with an interface variable, -even though the concrete value inside may have a larger set of -methods. -

- -

-Continuing, we can do this: -

- -{{code "progs/interface.go" `/var empty interface{}/` `/STOP/`}} - -

-and our empty interface value e will again contain -that same pair, (tty, *os.File). That's -handy: an empty interface can hold any value and contains all the -information we could ever need about that value. -

- -

-(We don't need a type assertion here because it's known statically -that w satisfies the empty interface. In the example -where we moved a value from a Reader to a -Writer, we needed to be explicit and use a type -assertion because Writer's methods are not a -subset of Reader's.) -

- -

-One important detail is that the pair inside an interface always -has the form (value, concrete type) and cannot have the form -(value, interface type). Interfaces do not hold interface -values. -

- -

-Now we're ready to reflect. -

- -

The first law of reflection

- -

1. Reflection goes from interface value to reflection object.

- -

-At the basic level, reflection is just a mechanism to examine the -type and value pair stored inside an interface variable. To get -started, there are two types we need to know about in -package reflect: -Type and -Value. Those two types -give access to the contents of an interface variable, and two -simple functions, called reflect.TypeOf and -reflect.ValueOf, retrieve reflect.Type -and reflect.Value pieces out of an interface value. -(Also, from the reflect.Value it's easy to get -to the reflect.Type, but let's keep the -Value and Type concepts separate for -now.) -

- -

-Let's start with TypeOf: -

- -{{code "progs/interface2.go" `/package main/` `/STOP main/`}} - -

-This program prints -

- -
-type: float64
-
- -

-You might be wondering where the interface is here, since the -program looks like it's passing the float64 -variable x, not an interface value, to -reflect.TypeOf. But it's there; as godoc reports, the -signature of reflect.TypeOf includes an empty -interface: -

- -
-// TypeOf returns the reflection Type of the value in the interface{}.
-func TypeOf(i interface{}) Type
-
- -

-When we call reflect.TypeOf(x), x is -first stored in an empty interface, which is then passed as the -argument; reflect.TypeOf unpacks that empty interface -to recover the type information. -

- -

-The reflect.ValueOf function, of course, recovers the -value (from here on we'll elide the boilerplate and focus just on -the executable code): -

- -{{code "progs/interface2.go" `/var x/` `/STOP/`}} - -

-prints -

- -
-value: <float64 Value>
-
- -

-Both reflect.Type and reflect.Value have -lots of methods to let us examine and manipulate them. One -important example is that Value has a -Type method that returns the Type of a -reflect.Value. Another is that both Type -and Value have a Kind method that returns -a constant indicating what sort of item is stored: -Uint, Float64, Slice, and so -on. Also methods on Value with names like -Int and Float let us grab values (as -int64 and float64) stored inside: -

- -{{code "progs/interface2.go" `/START f1/` `/STOP/`}} - -

-prints -

- -
-type: float64
-kind is float64: true
-value: 3.4
-
- -

-There are also methods like SetInt and -SetFloat but to use them we need to understand -settability, the subject of the third law of reflection, discussed -below. -

- -

-The reflection library has a couple of properties worth singling -out. First, to keep the API simple, the "getter" and "setter" -methods of Value operate on the largest type that can -hold the value: int64 for all the signed integers, for -instance. That is, the Int method of -Value returns an int64 and the -SetInt value takes an int64; it may be -necessary to convert to the actual type involved: -

- -{{code "progs/interface2.go" `/START f2/` `/STOP/`}} - -

-The second property is that the Kind of a reflection -object describes the underlying type, not the static type. If a -reflection object contains a value of a user-defined integer type, -as in -

- -{{code "progs/interface2.go" `/START f3/` `/STOP/`}} - -

-the Kind of v is still -reflect.Int, even though the static type of -x is MyInt, not int. In -other words, the Kind cannot discriminate an int from -a MyInt even though the Type can. -

- -

The second law of reflection

- -

2. Reflection goes from reflection object to interface -value.

- -

-Like physical reflection, reflection in Go generates its own -inverse. -

- -

-Given a reflect.Value we can recover an interface -value using the Interface method; in effect the method -packs the type and value information back into an interface -representation and returns the result: -

- -
-// Interface returns v's value as an interface{}.
-func (v Value) Interface() interface{}
-
- -

-As a consequence we can say -

- -{{code "progs/interface2.go" `/START f3b/` `/STOP/`}} - -

-to print the float64 value represented by the -reflection object v. -

- -

-We can do even better, though. The arguments to -fmt.Println, fmt.Printf and so on are all -passed as empty interface values, which are then unpacked by the -fmt package internally just as we have been doing in -the previous examples. Therefore all it takes to print the contents -of a reflect.Value correctly is to pass the result of -the Interface method to the formatted print -routine: -

- -{{code "progs/interface2.go" `/START f3c/` `/STOP/`}} - -

-(Why not fmt.Println(v)? Because v is a -reflect.Value; we want the concrete value it holds.) -Since our value is a float64, we can even use a -floating-point format if we want: -

- -{{code "progs/interface2.go" `/START f3d/` `/STOP/`}} - -

-and get in this case -

- -
-3.4e+00
-
- -

-Again, there's no need to type-assert the result of -v.Interface() to float64; the empty -interface value has the concrete value's type information inside -and Printf will recover it. -

- -

-In short, the Interface method is the inverse of the -ValueOf function, except that its result is always of -static type interface{}. -

- -

-Reiterating: Reflection goes from interface values to reflection -objects and back again. -

- -

The third law of reflection

- -

3. To modify a reflection object, the value must be settable.

- -

-The third law is the most subtle and confusing, but it's easy -enough to understand if we start from first principles. -

- -

-Here is some code that does not work, but is worth studying. -

- -{{code "progs/interface2.go" `/START f4/` `/STOP/`}} - -

-If you run this code, it will panic with the cryptic message -

- -
-panic: reflect.Value.SetFloat using unaddressable value
-
- -

-The problem is not that the value 7.1 is not -addressable; it's that v is not settable. Settability -is a property of a reflection Value, and not all -reflection Values have it. -

- -

-The CanSet method of Value reports the -settability of a Value; in our case, -

- -{{code "progs/interface2.go" `/START f5/` `/STOP/`}} - -

-prints -

- -
-settability of v: false
-
- -

-It is an error to call a Set method on an non-settable -Value. But what is settability? -

- -

-Settability is a bit like addressability, but stricter. It's the -property that a reflection object can modify the actual storage -that was used to create the reflection object. Settability is -determined by whether the reflection object holds the original -item. When we say -

- -{{code "progs/interface2.go" `/START f6/` `/STOP/`}} - -

-we pass a copy of x to -reflect.ValueOf, so the interface value created as the -argument to reflect.ValueOf is a copy of -x, not x itself. Thus, if the -statement -

- -{{code "progs/interface2.go" `/START f6b/` `/STOP/`}} - -

-were allowed to succeed, it would not update x, even -though v looks like it was created from -x. Instead, it would update the copy of x -stored inside the reflection value and x itself would -be unaffected. That would be confusing and useless, so it is -illegal, and settability is the property used to avoid this -issue. -

- -

-If this seems bizarre, it's not. It's actually a familiar situation -in unusual garb. Think of passing x to a -function: -

- -
-f(x)
-
- -

-We would not expect f to be able to modify -x because we passed a copy of x's value, -not x itself. If we want f to modify -x directly we must pass our function the address of -x (that is, a pointer to x):

- -

-f(&x) -

- -

-This is straightforward and familiar, and reflection works the same -way. If we want to modify x by reflection, we must -give the reflection library a pointer to the value we want to -modify. -

- -

-Let's do that. First we initialize x as usual -and then create a reflection value that points to it, called -p. -

- -{{code "progs/interface2.go" `/START f7/` `/STOP/`}} - -

-The output so far is -

- -
-type of p: *float64
-settability of p: false
-
- -

-The reflection object p isn't settable, but it's not -p we want to set, it's (in effect) *p. To -get to what p points to, we call the Elem -method of Value, which indirects through the pointer, -and save the result in a reflection Value called -v: -

- -{{code "progs/interface2.go" `/START f7b/` `/STOP/`}} - -

-Now v is a settable reflection object, as the output -demonstrates, -

- -
-settability of v: true
-
- -

-and since it represents x, we are finally able to use -v.SetFloat to modify the value of -x: -

- -{{code "progs/interface2.go" `/START f7c/` `/STOP/`}} - -

-The output, as expected, is -

- -
-7.1
-7.1
-
- -

-Reflection can be hard to understand but it's doing exactly what -the language does, albeit through reflection Types and -Values that can disguise what's going on. Just keep in -mind that reflection Values need the address of something in order -to modify what they represent. -

- -

Structs

- -

-In our previous example v wasn't a pointer itself, it -was just derived from one. A common way for this situation to arise -is when using reflection to modify the fields of a structure. As -long as we have the address of the structure, we can modify its -fields. -

- -

-Here's a simple example that analyzes a struct value, -t. We create the reflection object with the address of -the struct because we'll want to modify it later. Then we set -typeOfT to its type and iterate over the fields using -straightforward method calls (see -package reflect for details). -Note that we extract the names of the fields from the struct type, -but the fields themselves are regular reflect.Value -objects. -

- -{{code "progs/interface2.go" `/START f8/` `/STOP/`}} - -

-The output of this program is -

- -
-0: A int = 23
-1: B string = skidoo
-
- -

-There's one more point about settability introduced in -passing here: the field names of T are upper case -(exported) because only exported fields of a struct are -settable. -

- -

-Because s contains a settable reflection object, we -can modify the fields of the structure. -

- -{{code "progs/interface2.go" `/START f8b/` `/STOP/`}} - -

-And here's the result: -

- -
-t is now {77 Sunset Strip}
-
- -

-If we modified the program so that s was created from -t, not &t, the calls to -SetInt and SetString would fail as the -fields of t would not be settable. -

- -

Conclusion

- -

-Here again are the laws of reflection: -

- -
    -
  1. Reflection goes from interface value to reflection -object.
    2. -
  2. Reflection goes from reflection object to interface -value.
    3. -
  3. To modify a reflection object, the value must be settable.
    4. -
- -

-Once you understand these laws reflection in Go becomes much easier -to use, although it remains subtle. It's a powerful tool that -should be used with care and avoided unless strictly -necessary. -

- -

-There's plenty more to reflection that we haven't covered — -sending and receiving on channels, allocating memory, using slices -and maps, calling methods and functions — but this post is -long enough. We'll cover some of those topics in a later -article. -

\ No newline at end of file diff --git a/doc/articles/slices_usage_and_internals.html b/doc/articles/slices_usage_and_internals.html index c10dfe0cad..810b0a41f8 100644 --- a/doc/articles/slices_usage_and_internals.html +++ b/doc/articles/slices_usage_and_internals.html @@ -1,11 +1,7 @@ - -

Go's slice type provides a convenient and efficient means of working with @@ -326,20 +322,7 @@ appends byte elements to a slice of bytes, growing the slice if necessary, and returns the updated slice value:

-
func AppendByte(slice []byte, data ...byte) []byte {
-    m := len(slice)
-    n := m + len(data)
-    if n > cap(slice) { // if necessary, reallocate
-        // allocate double what's needed, for future growth.
-        newSlice := make([]byte, (n+1)*2)
-        copy(newSlice, slice)
-        slice = newSlice
-    }
-    slice = slice[0:n]
-    copy(slice[m:n], data)
-    return slice
-}
+{{code "/doc/progs/slices.go" `/AppendByte/` `/STOP/`}}

One could use AppendByte like this: @@ -398,18 +381,7 @@ Since the zero value of a slice (nil) acts like a zero-length slice, you can declare a slice variable and then append to it in a loop:

-
// Filter returns a new slice holding only
-// the elements of s that satisfy f()
-func Filter(s []int, fn func(int) bool) []int {
-    var p []int // == nil
-    for _, i := range s {
-        if fn(i) {
-            p = append(p, i)
-        }
-    }
-    return p
-}
+{{code "/doc/progs/slices.go" `/Filter/` `/STOP/`}}

A possible "gotcha" @@ -428,13 +400,7 @@ searches it for the first group of consecutive numeric digits, returning them as a new slice.

-
var digitRegexp = regexp.MustCompile("[0-9]+")
-
-func FindDigits(filename string) []byte {
-    b, _ := ioutil.ReadFile(filename)
-    return digitRegexp.Find(b)
-}
+{{code "/doc/progs/slices.go" `/digit/` `/STOP/`}}

This code behaves as advertised, but the returned []byte points @@ -449,14 +415,7 @@ To fix this problem one can copy the interesting data to a new slice before returning it:

-
func CopyDigits(filename string) []byte {
-    b, _ := ioutil.ReadFile(filename)
-    b = digitRegexp.Find(b)
-    c := make([]byte, len(b))
-    copy(c, b)
-    return c
-}
+{{code "/doc/progs/slices.go" `/CopyDigits/` `/STOP/`}}

A more concise version of this function could be constructed by using diff --git a/doc/articles/slices_usage_and_internals.tmpl b/doc/articles/slices_usage_and_internals.tmpl deleted file mode 100644 index d2f8fb7f58..0000000000 --- a/doc/articles/slices_usage_and_internals.tmpl +++ /dev/null @@ -1,438 +0,0 @@ - -{{donotedit}} - -

-Go's slice type provides a convenient and efficient means of working with -sequences of typed data. Slices are analogous to arrays in other languages, but -have some unusual properties. This article will look at what slices are and how -they are used. -

- -

-Arrays -

- -

-The slice type is an abstraction built on top of Go's array type, and so to -understand slices we must first understand arrays. -

- -

-An array type definition specifies a length and an element type. For example, -the type [4]int represents an array of four integers. An array's -size is fixed; its length is part of its type ([4]int and -[5]int are distinct, incompatible types). Arrays can be indexed in -the usual way, so the expression s[n] accesses the nth -element: -

- -
-var a [4]int
-a[0] = 1
-i := a[0]
-// i == 1
-
- -

-Arrays do not need to be initialized explicitly; the zero value of an array is -a ready-to-use array whose elements are themselves zeroed: -

- -
-// a[2] == 0, the zero value of the int type
-
- -

-The in-memory representation of [4]int is just four integer values laid out sequentially: -

- -

- -

- -

-Go's arrays are values. An array variable denotes the entire array; it is not a -pointer to the first array element (as would be the case in C). This means -that when you assign or pass around an array value you will make a copy of its -contents. (To avoid the copy you could pass a pointer to the array, but -then that's a pointer to an array, not an array.) One way to think about arrays -is as a sort of struct but with indexed rather than named fields: a fixed-size -composite value. -

- -

-An array literal can be specified like so: -

- -
-b := [2]string{"Penn", "Teller"}
-
- -

-Or, you can have the compiler count the array elements for you: -

- -
-b := [...]string{"Penn", "Teller"}
-
- -

-In both cases, the type of b is [2]string. -

- -

-Slices -

- -

-Arrays have their place, but they're a bit inflexible, so you don't see them -too often in Go code. Slices, though, are everywhere. They build on arrays to -provide great power and convenience. -

- -

-The type specification for a slice is []T, where T is -the type of the elements of the slice. Unlike an array type, a slice type has -no specified length. -

- -

-A slice literal is declared just like an array literal, except you leave out -the element count: -

- -
-letters := []string{"a", "b", "c", "d"}
-
- -

-A slice can be created with the built-in function called make, -which has the signature, -

- -
-func make([]T, len, cap) []T
-
- -

-where T stands for the element type of the slice to be created. The -make function takes a type, a length, and an optional capacity. -When called, make allocates an array and returns a slice that -refers to that array. -

- -
-var s []byte
-s = make([]byte, 5, 5)
-// s == []byte{0, 0, 0, 0, 0}
-
- -

-When the capacity argument is omitted, it defaults to the specified length. -Here's a more succinct version of the same code: -

- -
-s := make([]byte, 5)
-
- -

-The length and capacity of a slice can be inspected using the built-in -len and cap functions. -

- -
-len(s) == 5
-cap(s) == 5
-
- -

-The next two sections discuss the relationship between length and capacity. -

- -

-The zero value of a slice is nil. The len and -cap functions will both return 0 for a nil slice. -

- -

-A slice can also be formed by "slicing" an existing slice or array. Slicing is -done by specifying a half-open range with two indices separated by a colon. For -example, the expression b[1:4] creates a slice including elements -1 through 3 of b (the indices of the resulting slice will be 0 -through 2). -

- -
-b := []byte{'g', 'o', 'l', 'a', 'n', 'g'}
-// b[1:4] == []byte{'o', 'l', 'a'}, sharing the same storage as b
-
- -

-The start and end indices of a slice expression are optional; they default to zero and the slice's length respectively: -

- -
-// b[:2] == []byte{'g', 'o'}
-// b[2:] == []byte{'l', 'a', 'n', 'g'}
-// b[:] == b
-
- -

-This is also the syntax to create a slice given an array: -

- -
-x := [3]string{"Лайка", "Белка", "Стрелка"}
-s := x[:] // a slice referencing the storage of x
-
- -

-Slice internals -

- -

-A slice is a descriptor of an array segment. It consists of a pointer to the -array, the length of the segment, and its capacity (the maximum length of the -segment). -

- -

- -

- -

-Our variable s, created earlier by make([]byte, 5), -is structured like this: -

- -

- -

- -

-The length is the number of elements referred to by the slice. The capacity is -the number of elements in the underlying array (beginning at the element -referred to by the slice pointer). The distinction between length and capacity -will be made clear as we walk through the next few examples. -

- -

-As we slice s, observe the changes in the slice data structure and -their relation to the underlying array: -

- -
-s = s[2:4]
-
- -

- -

- -

-Slicing does not copy the slice's data. It creates a new slice value that -points to the original array. This makes slice operations as efficient as -manipulating array indices. Therefore, modifying the elements (not the -slice itself) of a re-slice modifies the elements of the original slice: -

- -
-d := []byte{'r', 'o', 'a', 'd'}
-e := d[2:] 
-// e == []byte{'a', 'd'}
-e[1] == 'm'
-// e == []byte{'a', 'm'}
-// d == []byte{'r', 'o', 'a', 'm'}
-
- -

-Earlier we sliced s to a length shorter than its capacity. We can -grow s to its capacity by slicing it again: -

- -
-s = s[:cap(s)]
-
- -

- -

- -

-A slice cannot be grown beyond its capacity. Attempting to do so will cause a -runtime panic, just as when indexing outside the bounds of a slice or array. -Similarly, slices cannot be re-sliced below zero to access earlier elements in -the array. -

- -

-Growing slices (the copy and append functions) -

- -

-To increase the capacity of a slice one must create a new, larger slice and -copy the contents of the original slice into it. This technique is how dynamic -array implementations from other languages work behind the scenes. The next -example doubles the capacity of s by making a new slice, -t, copying the contents of s into t, and -then assigning the slice value t to s: -

- -
-t := make([]byte, len(s), (cap(s)+1)*2) // +1 in case cap(s) == 0
-for i := range s {
-        t[i] = s[i]
-}
-s = t
-
- -

-The looping piece of this common operation is made easier by the built-in copy -function. As the name suggests, copy copies data from a source slice to a -destination slice. It returns the number of elements copied. -

- -
-func copy(dst, src []T) int
-
- -

-The copy function supports copying between slices of different -lengths (it will copy only up to the smaller number of elements). In addition, -copy can handle source and destination slices that share the same -underlying array, handling overlapping slices correctly. -

- -

-Using copy, we can simplify the code snippet above: -

- -
-t := make([]byte, len(s), (cap(s)+1)*2)
-copy(t, s)
-s = t
-
- -

-A common operation is to append data to the end of a slice. This function -appends byte elements to a slice of bytes, growing the slice if necessary, and -returns the updated slice value: -

- -{{code "progs/slices.go" `/AppendByte/` `/STOP/`}} - -

-One could use AppendByte like this: -

- -
-p := []byte{2, 3, 5}
-p = AppendByte(p, 7, 11, 13)
-// p == []byte{2, 3, 5, 7, 11, 13}
-
- -

-Functions like AppendByte are useful because they offer complete -control over the way the slice is grown. Depending on the characteristics of -the program, it may be desirable to allocate in smaller or larger chunks, or to -put a ceiling on the size of a reallocation. -

- -

-But most programs don't need complete control, so Go provides a built-in -append function that's good for most purposes; it has the -signature -

- -
-func append(s []T, x ...T) []T 
-
- -

-The append function appends the elements x to the end -of the slice s, and grows the slice if a greater capacity is -needed. -

- -
-a := make([]int, 1)
-// a == []int{0}
-a = append(a, 1, 2, 3)
-// a == []int{0, 1, 2, 3}
-
- -

-To append one slice to another, use ... to expand the second -argument to a list of arguments. -

- -
-a := []string{"John", "Paul"}
-b := []string{"George", "Ringo", "Pete"}
-a = append(a, b...) // equivalent to "append(a, b[0], b[1], b[2])"
-// a == []string{"John", "Paul", "George", "Ringo", "Pete"}
-
- -

-Since the zero value of a slice (nil) acts like a zero-length -slice, you can declare a slice variable and then append to it in a loop: -

- -{{code "progs/slices.go" `/Filter/` `/STOP/`}} - -

-A possible "gotcha" -

- -

-As mentioned earlier, re-slicing a slice doesn't make a copy of the underlying -array. The full array will be kept in memory until it is no longer referenced. -Occasionally this can cause the program to hold all the data in memory when -only a small piece of it is needed. -

- -

-For example, this FindDigits function loads a file into memory and -searches it for the first group of consecutive numeric digits, returning them -as a new slice. -

- -{{code "progs/slices.go" `/digit/` `/STOP/`}} - -

-This code behaves as advertised, but the returned []byte points -into an array containing the entire file. Since the slice references the -original array, as long as the slice is kept around the garbage collector can't -release the array; the few useful bytes of the file keep the entire contents in -memory. -

- -

-To fix this problem one can copy the interesting data to a new slice before -returning it: -

- -{{code "progs/slices.go" `/CopyDigits/` `/STOP/`}} - -

-A more concise version of this function could be constructed by using -append. This is left as an exercise for the reader. -

- -

-Further Reading -

- -

-Effective Go contains an -in-depth treatment of slices -and arrays, -and the Go language specification -defines slices and their -associated -helper -functions. -

diff --git a/doc/effective_go.html b/doc/effective_go.html index acca1e5e0d..3203a31dfa 100644 --- a/doc/effective_go.html +++ b/doc/effective_go.html @@ -1,11 +1,7 @@ - -

Introduction

@@ -1693,47 +1689,13 @@ enumerator. Since iota can be part of an expression and expressions can be implicitly repeated, it is easy to build intricate sets of values.

-
type ByteSize float64
-
-const (
-    _           = iota // ignore first value by assigning to blank identifier
-    KB ByteSize = 1 << (10 * iota)
-    MB
-    GB
-    TB
-    PB
-    EB
-    ZB
-    YB
-)
+{{code "/doc/progs/eff_bytesize.go" `/^type ByteSize/` `/^\)/`}}

The ability to attach a method such as String to a type makes it possible for such values to format themselves automatically for printing, even as part of a general type.

-
func (b ByteSize) String() string {
-    switch {
-    case b >= YB:
-        return fmt.Sprintf("%.2fYB", float64(b/YB))
-    case b >= ZB:
-        return fmt.Sprintf("%.2fZB", float64(b/ZB))
-    case b >= EB:
-        return fmt.Sprintf("%.2fEB", float64(b/EB))
-    case b >= PB:
-        return fmt.Sprintf("%.2fPB", float64(b/PB))
-    case b >= TB:
-        return fmt.Sprintf("%.2fTB", float64(b/TB))
-    case b >= GB:
-        return fmt.Sprintf("%.2fGB", float64(b/GB))
-    case b >= MB:
-        return fmt.Sprintf("%.2fMB", float64(b/MB))
-    case b >= KB:
-        return fmt.Sprintf("%.2fKB", float64(b/KB))
-    }
-    return fmt.Sprintf("%.2fB", float64(b))
-}
+{{code "/doc/progs/eff_bytesize.go" `/^func.*ByteSize.*String/` `/^}/`}}

(The float64 conversions prevent Sprintf from recurring back through the String method for @@ -1879,32 +1841,7 @@ by the routines in package sort if it implements and it could also have a custom formatter. In this contrived example Sequence satisfies both.

-
type Sequence []int
-
-// Methods required by sort.Interface.
-func (s Sequence) Len() int {
-    return len(s)
-}
-func (s Sequence) Less(i, j int) bool {
-    return s[i] < s[j]
-}
-func (s Sequence) Swap(i, j int) {
-    s[i], s[j] = s[j], s[i]
-}
-
-// Method for printing - sorts the elements before printing.
-func (s Sequence) String() string {
-    sort.Sort(s)
-    str := "["
-    for i, elem := range s {
-        if i > 0 {
-            str += " "
-        }
-        str += fmt.Sprint(elem)
-    }
-    return str + "]"
-}
+{{code "/doc/progs/eff_sequence.go" `/^type/` "$"}}

Conversions

@@ -3010,53 +2947,7 @@ for instance, a URL, saving you typing the URL into the phone's tiny keyboard. Here's the complete program. An explanation follows.

-
package main
-
-import (
-    "flag"
-    "log"
-    "net/http"
-    "text/template"
-)
-
-var addr = flag.String("addr", ":1718", "http service address") // Q=17, R=18
-
-var templ = template.Must(template.New("qr").Parse(templateStr))
-
-func main() {
-    flag.Parse()
-    http.Handle("/", http.HandlerFunc(QR))
-    err := http.ListenAndServe(*addr, nil)
-    if err != nil {
-        log.Fatal("ListenAndServe:", err)
-    }
-}
-
-func QR(w http.ResponseWriter, req *http.Request) {
-    templ.Execute(w, req.FormValue("s"))
-}
-
-const templateStr = `
-<html>
-<head>
-<title>QR Link Generator</title>
-</head>
-<body>
-{{if .}}
-<img src="http://chart.apis.google.com/chart?chs=300x300&cht=qr&choe=UTF-8&chl={{urlquery .}}" />
-<br>
-{{html .}}
-<br>
-<br>
-{{end}}
-<form action="/" name=f method="GET"><input maxLength=1024 size=70
-name=s value="" title="Text to QR Encode"><input type=submit
-value="Show QR" name=qr>
-</form>
-</body>
-</html>
-`
+{{code "/doc/progs/eff_qr.go"}}

The pieces up to main should be easy to follow. The one flag sets a default HTTP port for our server. The template @@ -3082,13 +2973,13 @@ from data items passed to templ.Execute, in this case the form value. Within the template text (templateStr), double-brace-delimited pieces denote template actions. -The piece from {{if .}} -to {{end}} executes only if the value of the current data item, called . (dot), +The piece from {{html "{{if .}}"}} +to {{html "{{end}}"}} executes only if the value of the current data item, called . (dot), is non-empty. That is, when the string is empty, this piece of the template is suppressed.

-The snippet {{urlquery .}} says to process the data with the function +The snippet {{html "{{urlquery .}}"}} says to process the data with the function urlquery, which sanitizes the query string for safe display on the web page.

diff --git a/doc/effective_go.tmpl b/doc/effective_go.tmpl deleted file mode 100644 index 92620b9c98..0000000000 --- a/doc/effective_go.tmpl +++ /dev/null @@ -1,3008 +0,0 @@ - -{{donotedit}} - -

Introduction

- -

-Go is a new language. Although it borrows ideas from -existing languages, -it has unusual properties that make effective Go programs -different in character from programs written in its relatives. -A straightforward translation of a C++ or Java program into Go -is unlikely to produce a satisfactory result—Java programs -are written in Java, not Go. -On the other hand, thinking about the problem from a Go -perspective could produce a successful but quite different -program. -In other words, -to write Go well, it's important to understand its properties -and idioms. -It's also important to know the established conventions for -programming in Go, such as naming, formatting, program -construction, and so on, so that programs you write -will be easy for other Go programmers to understand. -

- -

-This document gives tips for writing clear, idiomatic Go code. -It augments the language specification, -the Tour of Go, -and How to Write Go Code, -all of which you -should read first. -

- -

Examples

- -

-The Go package sources -are intended to serve not -only as the core library but also as examples of how to -use the language. -If you have a question about how to approach a problem or how something -might be implemented, they can provide answers, ideas and -background. -

- - -

Formatting

- -

-Formatting issues are the most contentious -but the least consequential. -People can adapt to different formatting styles -but it's better if they don't have to, and -less time is devoted to the topic -if everyone adheres to the same style. -The problem is how to approach this Utopia without a long -prescriptive style guide. -

- -

-With Go we take an unusual -approach and let the machine -take care of most formatting issues. -The gofmt program -(also available as go fmt, which -operates at the package level rather than source file level) -reads a Go program -and emits the source in a standard style of indentation -and vertical alignment, retaining and if necessary -reformatting comments. -If you want to know how to handle some new layout -situation, run gofmt; if the answer doesn't -seem right, rearrange your program (or file a bug about gofmt), -don't work around it. -

- -

-As an example, there's no need to spend time lining up -the comments on the fields of a structure. -Gofmt will do that for you. Given the -declaration -

- -
-type T struct {
-    name string // name of the object
-    value int // its value
-}
-
- -

-gofmt will line up the columns: -

- -
-type T struct {
-    name    string // name of the object
-    value   int    // its value
-}
-
- -

-All Go code in the standard packages has been formatted with gofmt. -

- - -

-Some formatting details remain. Very briefly, -

- -
-
Indentation
-
We use tabs for indentation and gofmt emits them by default. - Use spaces only if you must. -
-
Line length
-
- Go has no line length limit. Don't worry about overflowing a punched card. - If a line feels too long, wrap it and indent with an extra tab. -
-
Parentheses
-
- Go needs fewer parentheses: control structures (if, - for, switch) do not have parentheses in - their syntax. - Also, the operator precedence hierarchy is shorter and clearer, so -
-x<<8 + y<<16
-
- means what the spacing implies. -
-
- -

Commentary

- -

-Go provides C-style /* */ block comments -and C++-style // line comments. -Line comments are the norm; -block comments appear mostly as package comments and -are also useful to disable large swaths of code. -

- -

-The program—and web server—godoc processes -Go source files to extract documentation about the contents of the -package. -Comments that appear before top-level declarations, with no intervening newlines, -are extracted along with the declaration to serve as explanatory text for the item. -The nature and style of these comments determines the -quality of the documentation godoc produces. -

- -

-Every package should have a package comment, a block -comment preceding the package clause. -For multi-file packages, the package comment only needs to be -present in one file, and any one will do. -The package comment should introduce the package and -provide information relevant to the package as a whole. -It will appear first on the godoc page and -should set up the detailed documentation that follows. -

- -
-/*
-    Package regexp implements a simple library for
-    regular expressions.
-
-    The syntax of the regular expressions accepted is:
-
-    regexp:
-        concatenation { '|' concatenation }
-    concatenation:
-        { closure }
-    closure:
-        term [ '*' | '+' | '?' ]
-    term:
-        '^'
-        '$'
-        '.'
-        character
-        '[' [ '^' ] character-ranges ']'
-        '(' regexp ')'
-*/
-package regexp
-
- -

-If the package is simple, the package comment can be brief. -

- -
-// Package path implements utility routines for
-// manipulating slash-separated filename paths.
-
- -

-Comments do not need extra formatting such as banners of stars. -The generated output may not even be presented in a fixed-width font, so don't depend -on spacing for alignment—godoc, like gofmt, -takes care of that. -The comments are uninterpreted plain text, so HTML and other -annotations such as _this_ will reproduce verbatim and should -not be used. -Depending on the context, godoc might not even -reformat comments, so make sure they look good straight up: -use correct spelling, punctuation, and sentence structure, -fold long lines, and so on. -

- -

-Inside a package, any comment immediately preceding a top-level declaration -serves as a doc comment for that declaration. -Every exported (capitalized) name in a program should -have a doc comment. -

- -

-Doc comments work best as complete sentences, which allow -a wide variety of automated presentations. -The first sentence should be a one-sentence summary that -starts with the name being declared. -

- -
-// Compile parses a regular expression and returns, if successful, a Regexp
-// object that can be used to match against text.
-func Compile(str string) (regexp *Regexp, err error) {
-
- -

-Go's declaration syntax allows grouping of declarations. -A single doc comment can introduce a group of related constants or variables. -Since the whole declaration is presented, such a comment can often be perfunctory. -

- -
-// Error codes returned by failures to parse an expression.
-var (
-    ErrInternal      = errors.New("regexp: internal error")
-    ErrUnmatchedLpar = errors.New("regexp: unmatched '('")
-    ErrUnmatchedRpar = errors.New("regexp: unmatched ')'")
-    ...
-)
-
- -

-Even for private names, grouping can also indicate relationships between items, -such as the fact that a set of variables is protected by a mutex. -

- -
-var (
-    countLock   sync.Mutex
-    inputCount  uint32
-    outputCount uint32
-    errorCount  uint32
-)
-
- -

Names

- -

-Names are as important in Go as in any other language. -In some cases they even have semantic effect: for instance, -the visibility of a name outside a package is determined by whether its -first character is upper case. -It's therefore worth spending a little time talking about naming conventions -in Go programs. -

- - -

Package names

- -

-When a package is imported, the package name becomes an accessor for the -contents. After -

- -
-import "bytes"
-
- -

-the importing package can talk about bytes.Buffer. It's -helpful if everyone using the package can use the same name to refer to -its contents, which implies that the package name should be good: -short, concise, evocative. By convention, packages are given -lower case, single-word names; there should be no need for underscores -or mixedCaps. -Err on the side of brevity, since everyone using your -package will be typing that name. -And don't worry about collisions a priori. -The package name is only the default name for imports; it need not be unique -across all source code, and in the rare case of a collision the -importing package can choose a different name to use locally. -In any case, confusion is rare because the file name in the import -determines just which package is being used. -

- -

-Another convention is that the package name is the base name of -its source directory; -the package in src/pkg/encoding/base64 -is imported as "encoding/base64" but has name base64, -not encoding_base64 and not encodingBase64. -

- -

-The importer of a package will use the name to refer to its contents -(the import . notation is intended mostly for tests and other -unusual situations and should be avoided unless necessary), -so exported names in the package can use that fact -to avoid stutter. -For instance, the buffered reader type in the bufio package is called Reader, -not BufReader, because users see it as bufio.Reader, -which is a clear, concise name. -Moreover, -because imported entities are always addressed with their package name, bufio.Reader -does not conflict with io.Reader. -Similarly, the function to make new instances of ring.Ring—which -is the definition of a constructor in Go—would -normally be called NewRing, but since -Ring is the only type exported by the package, and since the -package is called ring, it's called just New, -which clients of the package see as ring.New. -Use the package structure to help you choose good names. -

- -

-Another short example is once.Do; -once.Do(setup) reads well and would not be improved by -writing once.DoOrWaitUntilDone(setup). -Long names don't automatically make things more readable. -If the name represents something intricate or subtle, it's usually better -to write a helpful doc comment than to attempt to put all the information -into the name. -

- -

Getters

- -

-Go doesn't provide automatic support for getters and setters. -There's nothing wrong with providing getters and setters yourself, -and it's often appropriate to do so, but it's neither idiomatic nor necessary -to put Get into the getter's name. If you have a field called -owner (lower case, unexported), the getter method should be -called Owner (upper case, exported), not GetOwner. -The use of upper-case names for export provides the hook to discriminate -the field from the method. -A setter function, if needed, will likely be called SetOwner. -Both names read well in practice: -

-
-owner := obj.Owner()
-if owner != user {
-    obj.SetOwner(user)
-}
-
- -

Interface names

- -

-By convention, one-method interfaces are named by -the method name plus the -er suffix: Reader, -Writer, Formatter etc. -

- -

-There are a number of such names and it's productive to honor them and the function -names they capture. -Read, Write, Close, Flush, -String and so on have -canonical signatures and meanings. To avoid confusion, -don't give your method one of those names unless it -has the same signature and meaning. -Conversely, if your type implements a method with the -same meaning as a method on a well-known type, -give it the same name and signature; -call your string-converter method String not ToString. -

- -

MixedCaps

- -

-Finally, the convention in Go is to use MixedCaps -or mixedCaps rather than underscores to write -multiword names. -

- -

Semicolons

- -

-Like C, Go's formal grammar uses semicolons to terminate statements; -unlike C, those semicolons do not appear in the source. -Instead the lexer uses a simple rule to insert semicolons automatically -as it scans, so the input text is mostly free of them. -

- -

-The rule is this. If the last token before a newline is an identifier -(which includes words like int and float64), -a basic literal such as a number or string constant, or one of the -tokens -

-
-break continue fallthrough return ++ -- ) }
-
-

-the lexer always inserts a semicolon after the token. -This could be summarized as, “if the newline comes -after a token that could end a statement, insert a semicolon”. -

- -

-A semicolon can also be omitted immediately before a closing brace, -so a statement such as -

-
-    go func() { for { dst <- <-src } }()
-
-

-needs no semicolons. -Idiomatic Go programs have semicolons only in places such as -for loop clauses, to separate the initializer, condition, and -continuation elements. They are also necessary to separate multiple -statements on a line, should you write code that way. -

- -

-One caveat. You should never put the opening brace of a -control structure (if, for, switch, -or select) on the next line. If you do, a semicolon -will be inserted before the brace, which could cause unwanted -effects. Write them like this -

- -
-if i < f() {
-    g()
-}
-
-

-not like this -

-
-if i < f()  // wrong!
-{           // wrong!
-    g()
-}
-
- - -

Control structures

- -

-The control structures of Go are related to those of C but differ -in important ways. -There is no do or while loop, only a -slightly generalized -for; -switch is more flexible; -if and switch accept an optional -initialization statement like that of for; -and there are new control structures including a type switch and a -multiway communications multiplexer, select. -The syntax is also slightly different: -there are no parentheses -and the bodies must always be brace-delimited. -

- -

If

- -

-In Go a simple if looks like this: -

-
-if x > 0 {
-    return y
-}
-
- -

-Mandatory braces encourage writing simple if statements -on multiple lines. It's good style to do so anyway, -especially when the body contains a control statement such as a -return or break. -

- -

-Since if and switch accept an initialization -statement, it's common to see one used to set up a local variable. -

- -
-if err := file.Chmod(0664); err != nil {
-    log.Print(err)
-    return err
-}
-
- -

-In the Go libraries, you'll find that -when an if statement doesn't flow into the next statement—that is, -the body ends in break, continue, -goto, or return—the unnecessary -else is omitted. -

- -
-f, err := os.Open(name)
-if err != nil {
-    return err
-}
-codeUsing(f)
-
- -

-This is an example of a common situation where code must guard against a -sequence of error conditions. The code reads well if the -successful flow of control runs down the page, eliminating error cases -as they arise. Since error cases tend to end in return -statements, the resulting code needs no else statements. -

- -
-f, err := os.Open(name)
-if err != nil {
-    return err
-}
-d, err := f.Stat()
-if err != nil {
-    f.Close()
-    return err
-}
-codeUsing(f, d)
-
- - -

Redeclaration

- -

-An aside: The last example in the previous section demonstrates a detail of how the -:= short declaration form works. -The declaration that calls os.Open reads, -

- -
-f, err := os.Open(name)
-
- -

-This statement declares two variables, f and err. -A few lines later, the call to f.Stat reads, -

- -
-d, err := f.Stat()
-
- -

-which looks as if it declares d and err. -Notice, though, that err appears in both statements. -This duplication is legal: err is declared by the first statement, -but only re-assigned in the second. -This means that the call to f.Stat uses the existing -err variable declared above, and just gives it a new value. -

- -

-In a := declaration a variable v may appear even -if it has already been declared, provided: -

- -
    -
  • this declaration is in the same scope as the existing declaration of v -(if v is already declared in an outer scope, the declaration will create a new variable),
    • -
  • the corresponding value in the initialization is assignable to v, and
    • -
  • there is at least one other variable in the declaration that is being declared anew.
    • -
- -

-This unusual property is pure pragmatism, -making it easy to use a single err value, for example, -in a long if-else chain. -You'll see it used often. -

- -

For

- -

-The Go for loop is similar to—but not the same as—C's. -It unifies for -and while and there is no do-while. -There are three forms, only one of which has semicolons. -

-
-// Like a C for
-for init; condition; post { }
-
-// Like a C while
-for condition { }
-
-// Like a C for(;;)
-for { }
-
- -

-Short declarations make it easy to declare the index variable right in the loop. -

-
-sum := 0
-for i := 0; i < 10; i++ {
-    sum += i
-}
-
- -

-If you're looping over an array, slice, string, or map, -or reading from a channel, a range clause can -manage the loop. -

-
-var m map[string]int
-sum := 0
-for _, value := range m {  // key is unused
-    sum += value
-}
-
- -

-For strings, the range does more work for you, breaking out individual -Unicode characters by parsing the UTF-8. -Erroneous encodings consume one byte and produce the -replacement rune U+FFFD. The loop -

-
-for pos, char := range "日本語" {
-    fmt.Printf("character %c starts at byte position %d\n", char, pos)
-}
-
-

-prints -

-
-character 日 starts at byte position 0
-character 本 starts at byte position 3
-character 語 starts at byte position 6
-
- -

-Finally, Go has no comma operator and ++ and -- -are statements not expressions. -Thus if you want to run multiple variables in a for -you should use parallel assignment. -

-
-// Reverse a
-for i, j := 0, len(a)-1; i < j; i, j = i+1, j-1 {
-    a[i], a[j] = a[j], a[i]
-}
-
- -

Switch

- -

-Go's switch is more general than C's. -The expressions need not be constants or even integers, -the cases are evaluated top to bottom until a match is found, -and if the switch has no expression it switches on -true. -It's therefore possible—and idiomatic—to write an -if-else-if-else -chain as a switch. -

- -
-func unhex(c byte) byte {
-    switch {
-    case '0' <= c && c <= '9':
-        return c - '0'
-    case 'a' <= c && c <= 'f':
-        return c - 'a' + 10
-    case 'A' <= c && c <= 'F':
-        return c - 'A' + 10
-    }
-    return 0
-}
-
- -

-There is no automatic fall through, but cases can be presented -in comma-separated lists. -

-func shouldEscape(c byte) bool {
-    switch c {
-    case ' ', '?', '&', '=', '#', '+', '%':
-        return true
-    }
-    return false
-}
-
- -

-Here's a comparison routine for byte arrays that uses two -switch statements: -

-// Compare returns an integer comparing the two byte arrays
-// lexicographically.
-// The result will be 0 if a == b, -1 if a < b, and +1 if a > b
-func Compare(a, b []byte) int {
-    for i := 0; i < len(a) && i < len(b); i++ {
-        switch {
-        case a[i] > b[i]:
-            return 1
-        case a[i] < b[i]:
-            return -1
-        }
-    }
-    switch {
-    case len(a) < len(b):
-        return -1
-    case len(a) > len(b):
-        return 1
-    }
-    return 0
-}
-
- -

-A switch can also be used to discover the dynamic type of an interface -variable. Such a type switch uses the syntax of a type -assertion with the keyword type inside the parentheses. -If the switch declares a variable in the expression, the variable will -have the corresponding type in each clause. -

-
-switch t := interfaceValue.(type) {
-default:
-    fmt.Printf("unexpected type %T", t)  // %T prints type
-case bool:
-    fmt.Printf("boolean %t\n", t)
-case int:
-    fmt.Printf("integer %d\n", t)
-case *bool:
-    fmt.Printf("pointer to boolean %t\n", *t)
-case *int:
-    fmt.Printf("pointer to integer %d\n", *t)
-}
-
- -

Functions

- -

Multiple return values

- -

-One of Go's unusual features is that functions and methods -can return multiple values. This form can be used to -improve on a couple of clumsy idioms in C programs: in-band -error returns (such as -1 for EOF) -and modifying an argument. -

- -

-In C, a write error is signaled by a negative count with the -error code secreted away in a volatile location. -In Go, Write -can return a count and an error: “Yes, you wrote some -bytes but not all of them because you filled the device”. -The signature of *File.Write in package os is: -

- -
-func (file *File) Write(b []byte) (n int, err error)
-
- -

-and as the documentation says, it returns the number of bytes -written and a non-nil error when n -!= len(b). -This is a common style; see the section on error handling for more examples. -

- -

-A similar approach obviates the need to pass a pointer to a return -value to simulate a reference parameter. -Here's a simple-minded function to -grab a number from a position in a byte array, returning the number -and the next position. -

- -
-func nextInt(b []byte, i int) (int, int) {
-    for ; i < len(b) && !isDigit(b[i]); i++ {
-    }
-    x := 0
-    for ; i < len(b) && isDigit(b[i]); i++ {
-        x = x*10 + int(b[i])-'0'
-    }
-    return x, i
-}
-
- -

-You could use it to scan the numbers in an input array a like this: -

- -
-    for i := 0; i < len(a); {
-        x, i = nextInt(a, i)
-        fmt.Println(x)
-    }
-
- -

Named result parameters

- -

-The return or result "parameters" of a Go function can be given names and -used as regular variables, just like the incoming parameters. -When named, they are initialized to the zero values for their types when -the function begins; if the function executes a return statement -with no arguments, the current values of the result parameters are -used as the returned values. -

- -

-The names are not mandatory but they can make code shorter and clearer: -they're documentation. -If we name the results of nextInt it becomes -obvious which returned int -is which. -

- -
-func nextInt(b []byte, pos int) (value, nextPos int) {
-
- -

-Because named results are initialized and tied to an unadorned return, they can simplify -as well as clarify. Here's a version -of io.ReadFull that uses them well: -

- -
-func ReadFull(r Reader, buf []byte) (n int, err error) {
-    for len(buf) > 0 && err == nil {
-        var nr int
-        nr, err = r.Read(buf)
-        n += nr
-        buf = buf[nr:]
-    }
-    return
-}
-
- -

Defer

- -

-Go's defer statement schedules a function call (the -deferred function) to be run immediately before the function -executing the defer returns. It's an unusual but -effective way to deal with situations such as resources that must be -released regardless of which path a function takes to return. The -canonical examples are unlocking a mutex or closing a file. -

- -
-// Contents returns the file's contents as a string.
-func Contents(filename string) (string, error) {
-    f, err := os.Open(filename)
-    if err != nil {
-        return "", err
-    }
-    defer f.Close()  // f.Close will run when we're finished.
-
-    var result []byte
-    buf := make([]byte, 100)
-    for {
-        n, err := f.Read(buf[0:])
-        result = append(result, buf[0:n]...) // append is discussed later.
-        if err != nil {
-            if err == io.EOF {
-                break
-            }
-            return "", err  // f will be closed if we return here.
-        }
-    }
-    return string(result), nil // f will be closed if we return here.
-}
-
- -

-Deferring a call to a function such as Close has two advantages. First, it -guarantees that you will never forget to close the file, a mistake -that's easy to make if you later edit the function to add a new return -path. Second, it means that the close sits near the open, -which is much clearer than placing it at the end of the function. -

- -

-The arguments to the deferred function (which include the receiver if -the function is a method) are evaluated when the defer -executes, not when the call executes. Besides avoiding worries -about variables changing values as the function executes, this means -that a single deferred call site can defer multiple function -executions. Here's a silly example. -

- -
-for i := 0; i < 5; i++ {
-    defer fmt.Printf("%d ", i)
-}
-
- -

-Deferred functions are executed in LIFO order, so this code will cause -4 3 2 1 0 to be printed when the function returns. A -more plausible example is a simple way to trace function execution -through the program. We could write a couple of simple tracing -routines like this: -

- -
-func trace(s string)   { fmt.Println("entering:", s) }
-func untrace(s string) { fmt.Println("leaving:", s) }
-
-// Use them like this:
-func a() {
-    trace("a")
-    defer untrace("a")
-    // do something....
-}
-
- -

-We can do better by exploiting the fact that arguments to deferred -functions are evaluated when the defer executes. The -tracing routine can set up the argument to the untracing routine. -This example: -

- -
-func trace(s string) string {
-    fmt.Println("entering:", s)
-    return s
-}
-
-func un(s string) {
-    fmt.Println("leaving:", s)
-}
-
-func a() {
-    defer un(trace("a"))
-    fmt.Println("in a")
-}
-
-func b() {
-    defer un(trace("b"))
-    fmt.Println("in b")
-    a()
-}
-
-func main() {
-    b()
-}
-
- -

-prints -

- -
-entering: b
-in b
-entering: a
-in a
-leaving: a
-leaving: b
-
- -

-For programmers accustomed to block-level resource management from -other languages, defer may seem peculiar, but its most -interesting and powerful applications come precisely from the fact -that it's not block-based but function-based. In the section on -panic and recover we'll see another -example of its possibilities. -

- -

Data

- -

Allocation with new

- -

-Go has two allocation primitives, the built-in functions -new and make. -They do different things and apply to different types, which can be confusing, -but the rules are simple. -Let's talk about new first. -It's a built-in function that allocates memory, but unlike its namesakes -in some other languages it does not initialize the memory, -it only zeroes it. -That is, -new(T) allocates zeroed storage for a new item of type -T and returns its address, a value of type *T. -In Go terminology, it returns a pointer to a newly allocated zero value of type -T. -

- -

-Since the memory returned by new is zeroed, it's helpful to arrange -when designing your data structures that the -zero value of each type can be used without further initialization. This means a user of -the data structure can create one with new and get right to -work. -For example, the documentation for bytes.Buffer states that -"the zero value for Buffer is an empty buffer ready to use." -Similarly, sync.Mutex does not -have an explicit constructor or Init method. -Instead, the zero value for a sync.Mutex -is defined to be an unlocked mutex. -

- -

-The zero-value-is-useful property works transitively. Consider this type declaration. -

- -
-type SyncedBuffer struct {
-    lock    sync.Mutex
-    buffer  bytes.Buffer
-}
-
- -

-Values of type SyncedBuffer are also ready to use immediately upon allocation -or just declaration. In the next snippet, both p and v will work -correctly without further arrangement. -

- -
-p := new(SyncedBuffer)  // type *SyncedBuffer
-var v SyncedBuffer      // type  SyncedBuffer
-
- -

Constructors and composite literals

- -

-Sometimes the zero value isn't good enough and an initializing -constructor is necessary, as in this example derived from -package os. -

- -
-func NewFile(fd int, name string) *File {
-    if fd < 0 {
-        return nil
-    }
-    f := new(File)
-    f.fd = fd
-    f.name = name
-    f.dirinfo = nil
-    f.nepipe = 0
-    return f
-}
-
- -

-There's a lot of boiler plate in there. We can simplify it -using a composite literal, which is -an expression that creates a -new instance each time it is evaluated. -

- -
-func NewFile(fd int, name string) *File {
-    if fd < 0 {
-        return nil
-    }
-    f := File{fd, name, nil, 0}
-    return &f
-}
-
- -

-Note that, unlike in C, it's perfectly OK to return the address of a local variable; -the storage associated with the variable survives after the function -returns. -In fact, taking the address of a composite literal -allocates a fresh instance each time it is evaluated, -so we can combine these last two lines. -

- -
-    return &File{fd, name, nil, 0}
-
- -

-The fields of a composite literal are laid out in order and must all be present. -However, by labeling the elements explicitly as field:value -pairs, the initializers can appear in any -order, with the missing ones left as their respective zero values. Thus we could say -

- -
-    return &File{fd: fd, name: name}
-
- -

-As a limiting case, if a composite literal contains no fields at all, it creates -a zero value for the type. The expressions new(File) and &File{} are equivalent. -

- -

-Composite literals can also be created for arrays, slices, and maps, -with the field labels being indices or map keys as appropriate. -In these examples, the initializations work regardless of the values of Enone, -Eio, and Einval, as long as they are distinct. -

- -
-a := [...]string   {Enone: "no error", Eio: "Eio", Einval: "invalid argument"}
-s := []string      {Enone: "no error", Eio: "Eio", Einval: "invalid argument"}
-m := map[int]string{Enone: "no error", Eio: "Eio", Einval: "invalid argument"}
-
- -

Allocation with make

- -

-Back to allocation. -The built-in function make(T, args) serves -a purpose different from new(T). -It creates slices, maps, and channels only, and it returns an initialized -(not zeroed) -value of type T (not *T). -The reason for the distinction -is that these three types are, under the covers, references to data structures that -must be initialized before use. -A slice, for example, is a three-item descriptor -containing a pointer to the data (inside an array), the length, and the -capacity, and until those items are initialized, the slice is nil. -For slices, maps, and channels, -make initializes the internal data structure and prepares -the value for use. -For instance, -

- -
-make([]int, 10, 100)
-
- -

-allocates an array of 100 ints and then creates a slice -structure with length 10 and a capacity of 100 pointing at the first -10 elements of the array. -(When making a slice, the capacity can be omitted; see the section on slices -for more information.) -In contrast, new([]int) returns a pointer to a newly allocated, zeroed slice -structure, that is, a pointer to a nil slice value. - -

-These examples illustrate the difference between new and -make. -

- -
-var p *[]int = new([]int)       // allocates slice structure; *p == nil; rarely useful
-var v  []int = make([]int, 100) // the slice v now refers to a new array of 100 ints
-
-// Unnecessarily complex:
-var p *[]int = new([]int)
-*p = make([]int, 100, 100)
-
-// Idiomatic:
-v := make([]int, 100)
-
- -

-Remember that make applies only to maps, slices and channels -and does not return a pointer. -To obtain an explicit pointer allocate with new. -

- -

Arrays

- -

-Arrays are useful when planning the detailed layout of memory and sometimes -can help avoid allocation, but primarily -they are a building block for slices, the subject of the next section. -To lay the foundation for that topic, here are a few words about arrays. -

- -

-There are major differences between the ways arrays work in Go and C. -In Go, -

-
    -
  • -Arrays are values. Assigning one array to another copies all the elements. -
    • -
  • -In particular, if you pass an array to a function, it -will receive a copy of the array, not a pointer to it. -
  • -The size of an array is part of its type. The types [10]int -and [20]int are distinct. -
    • -
- -

-The value property can be useful but also expensive; if you want C-like behavior and efficiency, -you can pass a pointer to the array. -

- -
-func Sum(a *[3]float64) (sum float64) {
-    for _, v := range *a {
-        sum += v
-    }
-    return
-}
-
-array := [...]float64{7.0, 8.5, 9.1}
-x := Sum(&array)  // Note the explicit address-of operator
-
- -

-But even this style isn't idiomatic Go. Slices are. -

- -

Slices

- -

-Slices wrap arrays to give a more general, powerful, and convenient -interface to sequences of data. Except for items with explicit -dimension such as transformation matrices, most array programming in -Go is done with slices rather than simple arrays. -

-

-Slices are reference types, which means that if you assign one -slice to another, both refer to the same underlying array. For -instance, if a function takes a slice argument, changes it makes to -the elements of the slice will be visible to the caller, analogous to -passing a pointer to the underlying array. A Read -function can therefore accept a slice argument rather than a pointer -and a count; the length within the slice sets an upper -limit of how much data to read. Here is the signature of the -Read method of the File type in package -os: -

-
-func (file *File) Read(buf []byte) (n int, err error)
-
-

-The method returns the number of bytes read and an error value, if -any. To read into the first 32 bytes of a larger buffer -b, slice (here used as a verb) the buffer. -

-
-    n, err := f.Read(buf[0:32])
-
-

-Such slicing is common and efficient. In fact, leaving efficiency aside for -the moment, this snippet would also read the first 32 bytes of the buffer. -

-
-    var n int
-    var err error
-    for i := 0; i < 32; i++ {
-        nbytes, e := f.Read(buf[i:i+1])  // Read one byte.
-        if nbytes == 0 || e != nil {
-            err = e
-            break
-        }
-        n += nbytes
-    }
-
-

-The length of a slice may be changed as long as it still fits within -the limits of the underlying array; just assign it to a slice of -itself. The capacity of a slice, accessible by the built-in -function cap, reports the maximum length the slice may -assume. Here is a function to append data to a slice. If the data -exceeds the capacity, the slice is reallocated. The -resulting slice is returned. The function uses the fact that -len and cap are legal when applied to the -nil slice, and return 0. -

-
-func Append(slice, data[]byte) []byte {
-    l := len(slice)
-    if l + len(data) > cap(slice) {  // reallocate
-        // Allocate double what's needed, for future growth.
-        newSlice := make([]byte, (l+len(data))*2)
-        // The copy function is predeclared and works for any slice type.
-        copy(newSlice, slice)
-        slice = newSlice
-    }
-    slice = slice[0:l+len(data)]
-    for i, c := range data {
-        slice[l+i] = c
-    }
-    return slice
-}
-
-

-We must return the slice afterwards because, although Append -can modify the elements of slice, the slice itself (the run-time data -structure holding the pointer, length, and capacity) is passed by value. -

-The idea of appending to a slice is so useful it's captured by the -append built-in function. To understand that function's -design, though, we need a little more information, so we'll return -to it later. -

- - -

Maps

- -

-Maps are a convenient and powerful built-in data structure to associate -values of different types. -The key can be of any type for which the equality operator is defined, -such as integers, -floating point and complex numbers, -strings, pointers, and interfaces (as long as the dynamic type -supports equality). Structs, arrays and slices cannot be used as map keys, -because equality is not defined on those types. -Like slices, maps are a reference type. If you pass a map to a function -that changes the contents of the map, the changes will be visible -in the caller. -

-

-Maps can be constructed using the usual composite literal syntax -with colon-separated key-value pairs, -so it's easy to build them during initialization. -

-
-var timeZone = map[string] int {
-    "UTC":  0*60*60,
-    "EST": -5*60*60,
-    "CST": -6*60*60,
-    "MST": -7*60*60,
-    "PST": -8*60*60,
-}
-
-

-Assigning and fetching map values looks syntactically just like -doing the same for arrays except that the index doesn't need to -be an integer. -

-
-offset := timeZone["EST"]
-
-

-An attempt to fetch a map value with a key that -is not present in the map will return the zero value for the type -of the entries -in the map. For instance, if the map contains integers, looking -up a non-existent key will return 0. -A set can be implemented as a map with value type bool. -Set the map entry to true to put the value in the set, and then -test it by simple indexing. -

-
-attended := map[string] bool {
-    "Ann": true,
-    "Joe": true,
-    ...
-}
-
-if attended[person] { // will be false if person is not in the map
-    fmt.Println(person, "was at the meeting")
-}
-
-

-Sometimes you need to distinguish a missing entry from -a zero value. Is there an entry for "UTC" -or is that zero value because it's not in the map at all? -You can discriminate with a form of multiple assignment. -

-
-var seconds int
-var ok bool
-seconds, ok = timeZone[tz]
-
-

-For obvious reasons this is called the “comma ok” idiom. -In this example, if tz is present, seconds -will be set appropriately and ok will be true; if not, -seconds will be set to zero and ok will -be false. -Here's a function that puts it together with a nice error report: -

-
-func offset(tz string) int {
-    if seconds, ok := timeZone[tz]; ok {
-        return seconds
-    }
-    log.Println("unknown time zone:", tz)
-    return 0
-}
-
-

-To test for presence in the map without worrying about the actual value, -you can use the blank identifier, a simple underscore (_). -The blank identifier can be assigned or declared with any value of any type, with the -value discarded harmlessly. For testing just presence in a map, use the blank -identifier in place of the usual variable for the value. -

-
-_, present := timeZone[tz]
-
-

-To delete a map entry, use the delete -built-in function, whose arguments are the map and the key to be deleted. -It's safe to do this this even if the key is already absent -from the map. -

-
-delete(timeZone, "PDT")  // Now on Standard Time
-
- -

Printing

- -

-Formatted printing in Go uses a style similar to C's printf -family but is richer and more general. The functions live in the fmt -package and have capitalized names: fmt.Printf, fmt.Fprintf, -fmt.Sprintf and so on. The string functions (Sprintf etc.) -return a string rather than filling in a provided buffer. -

-

-You don't need to provide a format string. For each of Printf, -Fprintf and Sprintf there is another pair -of functions, for instance Print and Println. -These functions do not take a format string but instead generate a default -format for each argument. The Println versions also insert a blank -between arguments and append a newline to the output while -the Print versions add blanks only if the operand on neither side is a string. -In this example each line produces the same output. -

-
-fmt.Printf("Hello %d\n", 23)
-fmt.Fprint(os.Stdout, "Hello ", 23, "\n")
-fmt.Println("Hello", 23)
-fmt.Println(fmt.Sprint("Hello ", 23))
-
-

-As mentioned in -the Tour, fmt.Fprint -and friends take as a first argument any object -that implements the io.Writer interface; the variables os.Stdout -and os.Stderr are familiar instances. -

-

-Here things start to diverge from C. First, the numeric formats such as %d -do not take flags for signedness or size; instead, the printing routines use the -type of the argument to decide these properties. -

-
-var x uint64 = 1<<64 - 1
-fmt.Printf("%d %x; %d %x\n", x, x, int64(x), int64(x))
-
-

-prints -

-
-18446744073709551615 ffffffffffffffff; -1 -1
-
-

-If you just want the default conversion, such as decimal for integers, you can use -the catchall format %v (for “value”); the result is exactly -what Print and Println would produce. -Moreover, that format can print any value, even arrays, structs, and -maps. Here is a print statement for the time zone map defined in the previous section. -

-
-fmt.Printf("%v\n", timeZone)  // or just fmt.Println(timeZone)
-
-

-which gives output -

-
-map[CST:-21600 PST:-28800 EST:-18000 UTC:0 MST:-25200]
-
-

-For maps the keys may be output in any order, of course. -When printing a struct, the modified format %+v annotates the -fields of the structure with their names, and for any value the alternate -format %#v prints the value in full Go syntax. -

-
-type T struct {
-    a int
-    b float64
-    c string
-}
-t := &T{ 7, -2.35, "abc\tdef" }
-fmt.Printf("%v\n", t)
-fmt.Printf("%+v\n", t)
-fmt.Printf("%#v\n", t)
-fmt.Printf("%#v\n", timeZone)
-
-

-prints -

-
-&{7 -2.35 abc   def}
-&{a:7 b:-2.35 c:abc     def}
-&main.T{a:7, b:-2.35, c:"abc\tdef"}
-map[string] int{"CST":-21600, "PST":-28800, "EST":-18000, "UTC":0, "MST":-25200}
-
-

-(Note the ampersands.) -That quoted string format is also available through %q when -applied to a value of type string or []byte; -the alternate format %#q will use backquotes instead if possible. -Also, %x works on strings and arrays of bytes as well as on integers, -generating a long hexadecimal string, and with -a space in the format (% x) it puts spaces between the bytes. -

-

-Another handy format is %T, which prints the type of a value. -

-fmt.Printf("%T\n", timeZone)
-
-

-prints -

-
-map[string] int
-
-

-If you want to control the default format for a custom type, all that's required is to define -a method with the signature String() string on the type. -For our simple type T, that might look like this. -

-
-func (t *T) String() string {
-    return fmt.Sprintf("%d/%g/%q", t.a, t.b, t.c)
-}
-fmt.Printf("%v\n", t)
-
-

-to print in the format -

-
-7/-2.35/"abc\tdef"
-
-

-(If you need to print values of type T as well as pointers to T, -the receiver for String must be of value type; this example used a pointer because -that's more efficient and idiomatic for struct types. -See the section below on pointers vs. value receivers for more information.) -

-

-Our String method is able to call Sprintf because the -print routines are fully reentrant and can be used recursively. -We can even go one step further and pass a print routine's arguments directly to another such routine. -The signature of Printf uses the type ...interface{} -for its final argument to specify that an arbitrary number of parameters (of arbitrary type) -can appear after the format. -

-
-func Printf(format string, v ...interface{}) (n int, err error) {
-
-

-Within the function Printf, v acts like a variable of type -[]interface{} but if it is passed to another variadic function, it acts like -a regular list of arguments. -Here is the implementation of the -function log.Println we used above. It passes its arguments directly to -fmt.Sprintln for the actual formatting. -

-
-// Println prints to the standard logger in the manner of fmt.Println.
-func Println(v ...interface{}) {
-    std.Output(2, fmt.Sprintln(v...))  // Output takes parameters (int, string)
-}
-
-

-We write ... after v in the nested call to Sprintln to tell the -compiler to treat v as a list of arguments; otherwise it would just pass -v as a single slice argument. -

-There's even more to printing than we've covered here. See the godoc documentation -for package fmt for the details. -

-

-By the way, a ... parameter can be of a specific type, for instance ...int -for a min function that chooses the least of a list of integers: -

-
-func Min(a ...int) int {
-    min := int(^uint(0) >> 1)  // largest int
-    for _, i := range a {
-        if i < min {
-            min = i
-        }
-    }
-    return min
-}
-
- -

Append

-

-Now we have the missing piece we needed to explain the design of -the append built-in function. The signature of append -is different from our custom Append function above. -Schematically, it's like this: -

-
-func append(slice []T, elements...T) []T
-
-

-where T is a placeholder for any given type. You can't -actually write a function in Go where the type T -is determined by the caller. -That's why append is built in: it needs support from the -compiler. -

-

-What append does is append the elements to the end of -the slice and return the result. The result needs to be returned -because, as with our hand-written Append, the underlying -array may change. This simple example -

-
-x := []int{1,2,3}
-x = append(x, 4, 5, 6)
-fmt.Println(x)
-
-

-prints [1 2 3 4 5 6]. So append works a -little like Printf, collecting an arbitrary number of -arguments. -

-

-But what if we wanted to do what our Append does and -append a slice to a slice? Easy: use ... at the call -site, just as we did in the call to Output above. This -snippet produces identical output to the one above. -

-
-x := []int{1,2,3}
-y := []int{4,5,6}
-x = append(x, y...)
-fmt.Println(x)
-
-

-Without that ..., it wouldn't compile because the types -would be wrong; y is not of type int. -

- -

Initialization

- -

-Although it doesn't look superficially very different from -initialization in C or C++, initialization in Go is more powerful. -Complex structures can be built during initialization and the ordering -issues between initialized objects in different packages are handled -correctly. -

- -

Constants

- -

-Constants in Go are just that—constant. -They are created at compile time, even when defined as -locals in functions, -and can only be numbers, strings or booleans. -Because of the compile-time restriction, the expressions -that define them must be constant expressions, -evaluatable by the compiler. For instance, -1<<3 is a constant expression, while -math.Sin(math.Pi/4) is not because -the function call to math.Sin needs -to happen at run time. -

- -

-In Go, enumerated constants are created using the iota -enumerator. Since iota can be part of an expression and -expressions can be implicitly repeated, it is easy to build intricate -sets of values. -

-{{code "progs/eff_bytesize.go" `/^type ByteSize/` `/^\)/`}} -

-The ability to attach a method such as String to a -type makes it possible for such values to format themselves -automatically for printing, even as part of a general type. -

-{{code "progs/eff_bytesize.go" `/^func.*ByteSize.*String/` `/^}/`}} -

-(The float64 conversions prevent Sprintf -from recurring back through the String method for -ByteSize.) -The expression YB prints as 1.00YB, -while ByteSize(1e13) prints as 9.09TB. -

- -

Variables

- -

-Variables can be initialized just like constants but the -initializer can be a general expression computed at run time. -

-
-var (
-    HOME = os.Getenv("HOME")
-    USER = os.Getenv("USER")
-    GOROOT = os.Getenv("GOROOT")
-)
-
- -

The init function

- -

-Finally, each source file can define its own niladic init function to -set up whatever state is required. (Actually each file can have multiple -init functions.) -And finally means finally: init is called after all the -variable declarations in the package have evaluated their initializers, -and those are evaluated only after all the imported packages have been -initialized. -

-

-Besides initializations that cannot be expressed as declarations, -a common use of init functions is to verify or repair -correctness of the program state before real execution begins. -

- -
-func init() {
-    if USER == "" {
-        log.Fatal("$USER not set")
-    }
-    if HOME == "" {
-        HOME = "/usr/" + USER
-    }
-    if GOROOT == "" {
-        GOROOT = HOME + "/go"
-    }
-    // GOROOT may be overridden by --goroot flag on command line.
-    flag.StringVar(&GOROOT, "goroot", GOROOT, "Go root directory")
-}
-
- -

Methods

- -

Pointers vs. Values

-

-Methods can be defined for any named type that is not a pointer or an interface; -the receiver does not have to be a struct. -

-In the discussion of slices above, we wrote an Append -function. We can define it as a method on slices instead. To do -this, we first declare a named type to which we can bind the method, and -then make the receiver for the method a value of that type. -

-
-type ByteSlice []byte
-
-func (slice ByteSlice) Append(data []byte) []byte {
-    // Body exactly the same as above
-}
-
-

-This still requires the method to return the updated slice. We can -eliminate that clumsiness by redefining the method to take a -pointer to a ByteSlice as its receiver, so the -method can overwrite the caller's slice. -

-
-func (p *ByteSlice) Append(data []byte) {
-    slice := *p
-    // Body as above, without the return.
-    *p = slice
-}
-
-

-In fact, we can do even better. If we modify our function so it looks -like a standard Write method, like this, -

-
-func (p *ByteSlice) Write(data []byte) (n int, err error) {
-    slice := *p
-    // Again as above.
-    *p = slice
-    return len(data), nil
-}
-
-

-then the type *ByteSlice satisfies the standard interface -io.Writer, which is handy. For instance, we can -print into one. -

-
-    var b ByteSlice
-    fmt.Fprintf(&b, "This hour has %d days\n", 7)
-
-

-We pass the address of a ByteSlice -because only *ByteSlice satisfies io.Writer. -The rule about pointers vs. values for receivers is that value methods -can be invoked on pointers and values, but pointer methods can only be -invoked on pointers. This is because pointer methods can modify the -receiver; invoking them on a copy of the value would cause those -modifications to be discarded. -

-

-By the way, the idea of using Write on a slice of bytes -is implemented by bytes.Buffer. -

- -

Interfaces and other types

- -

Interfaces

-

-Interfaces in Go provide a way to specify the behavior of an -object: if something can do this, then it can be used -here. We've seen a couple of simple examples already; -custom printers can be implemented by a String method -while Fprintf can generate output to anything -with a Write method. -Interfaces with only one or two methods are common in Go code, and are -usually given a name derived from the method, such as io.Writer -for something that implements Write. -

-

-A type can implement multiple interfaces. -For instance, a collection can be sorted -by the routines in package sort if it implements -sort.Interface, which contains Len(), -Less(i, j int) bool, and Swap(i, j int), -and it could also have a custom formatter. -In this contrived example Sequence satisfies both. -

-{{code "progs/eff_sequence.go" `/^type/` "$"}} - -

Conversions

- -

-The String method of Sequence is recreating the -work that Sprint already does for slices. We can share the -effort if we convert the Sequence to a plain -[]int before calling Sprint. -

-
-func (s Sequence) String() string {
-    sort.Sort(s)
-    return fmt.Sprint([]int(s))
-}
-
-

-The conversion causes s to be treated as an ordinary slice -and therefore receive the default formatting. -Without the conversion, Sprint would find the -String method of Sequence and recur indefinitely. -Because the two types (Sequence and []int) -are the same if we ignore the type name, it's legal to convert between them. -The conversion doesn't create a new value, it just temporarily acts -as though the existing value has a new type. -(There are other legal conversions, such as from integer to floating point, that -do create a new value.) -

-

-It's an idiom in Go programs to convert the -type of an expression to access a different -set of methods. As an example, we could use the existing -type sort.IntSlice to reduce the entire example -to this: -

-
-type Sequence []int
-
-// Method for printing - sorts the elements before printing
-func (s Sequence) String() string {
-    sort.IntSlice(s).Sort()
-    return fmt.Sprint([]int(s))
-}
-
-

-Now, instead of having Sequence implement multiple -interfaces (sorting and printing), we're using the ability of a data item to be -converted to multiple types (Sequence, sort.IntSlice -and []int), each of which does some part of the job. -That's more unusual in practice but can be effective. -

- -

Generality

-

-If a type exists only to implement an interface -and has no exported methods beyond that interface, -there is no need to export the type itself. -Exporting just the interface makes it clear that -it's the behavior that matters, not the implementation, -and that other implementations with different properties -can mirror the behavior of the original type. -It also avoids the need to repeat the documentation -on every instance of a common method. -

-

-In such cases, the constructor should return an interface value -rather than the implementing type. -As an example, in the hash libraries -both crc32.NewIEEE and adler32.New -return the interface type hash.Hash32. -Substituting the CRC-32 algorithm for Adler-32 in a Go program -requires only changing the constructor call; -the rest of the code is unaffected by the change of algorithm. -

-

-A similar approach allows the streaming cipher algorithms -in the various crypto packages to be -separated from the block ciphers they chain together. -The Block interface -in the crypto/cipherpackage specifies the -behavior of a block cipher, which provides encryption -of a single block of data. -Then, by analogy with the bufio package, -cipher packages that implement this interface -can be used to construct streaming ciphers, represented -by the Stream interface, without -knowing the details of the block encryption. -

-

-The crypto/cipher interfaces look like this: -

-
-type Block interface {
-    BlockSize() int
-    Encrypt(src, dst []byte)
-    Decrypt(src, dst []byte)
-}
-
-type Stream interface {
-    XORKeyStream(dst, src []byte)
-}
-
- -

-Here's the definition of the counter mode (CTR) stream, -which turns a block cipher into a streaming cipher; notice -that the block cipher's details are abstracted away: -

- -
-// NewCTR returns a Stream that encrypts/decrypts using the given Block in
-// counter mode. The length of iv must be the same as the Block's block size.
-func NewCTR(block Block, iv []byte) Stream
-
-

-NewCTR applies not -just to one specific encryption algorithm and data source but to any -implementation of the Block interface and any -Stream. Because they return -interface values, replacing CTR -encryption with other encryption modes is a localized change. The constructor -calls must be edited, but because the surrounding code must treat the result only -as a Stream, it won't notice the difference. -

- -

Interfaces and methods

-

-Since almost anything can have methods attached, almost anything can -satisfy an interface. One illustrative example is in the http -package, which defines the Handler interface. Any object -that implements Handler can serve HTTP requests. -

-
-type Handler interface {
-    ServeHTTP(ResponseWriter, *Request)
-}
-
-

-ResponseWriter is itself an interface that provides access -to the methods needed to return the response to the client. -Those methods include the standard Write method, so an -http.ResponseWriter can be used wherever an io.Writer -can be used. -Request is a struct containing a parsed representation -of the request from the client. -

-For brevity, let's ignore POSTs and assume HTTP requests are always -GETs; that simplification does not affect the way the handlers are -set up. Here's a trivial but complete implementation of a handler to -count the number of times the -page is visited. -

-
-// Simple counter server.
-type Counter struct {
-    n int
-}
-
-func (ctr *Counter) ServeHTTP(w http.ResponseWriter, req *http.Request) {
-    ctr.n++
-    fmt.Fprintf(w, "counter = %d\n", ctr.n)
-}
-
-

-(Keeping with our theme, note how Fprintf can print to an -http.ResponseWriter.) -For reference, here's how to attach such a server to a node on the URL tree. -

-import "net/http"
-...
-ctr := new(Counter)
-http.Handle("/counter", ctr)
-
-

-But why make Counter a struct? An integer is all that's needed. -(The receiver needs to be a pointer so the increment is visible to the caller.) -

-
-// Simpler counter server.
-type Counter int
-
-func (ctr *Counter) ServeHTTP(w http.ResponseWriter, req *http.Request) {
-    *ctr++
-    fmt.Fprintf(w, "counter = %d\n", *ctr)
-}
-
-

-What if your program has some internal state that needs to be notified that a page -has been visited? Tie a channel to the web page. -

-
-// A channel that sends a notification on each visit.
-// (Probably want the channel to be buffered.)
-type Chan chan *http.Request
-
-func (ch Chan) ServeHTTP(w http.ResponseWriter, req *http.Request) {
-    ch <- req
-    fmt.Fprint(w, "notification sent")
-}
-
-

-Finally, let's say we wanted to present on /args the arguments -used when invoking the server binary. -It's easy to write a function to print the arguments. -

-
-func ArgServer() {
-    for _, s := range os.Args {
-        fmt.Println(s)
-    }
-}
-
-

-How do we turn that into an HTTP server? We could make ArgServer -a method of some type whose value we ignore, but there's a cleaner way. -Since we can define a method for any type except pointers and interfaces, -we can write a method for a function. -The http package contains this code: -

-
-// The HandlerFunc type is an adapter to allow the use of
-// ordinary functions as HTTP handlers.  If f is a function
-// with the appropriate signature, HandlerFunc(f) is a
-// Handler object that calls f.
-type HandlerFunc func(ResponseWriter, *Request)
-
-// ServeHTTP calls f(c, req).
-func (f HandlerFunc) ServeHTTP(w ResponseWriter, req *Request) {
-    f(w, req)
-}
-
-

-HandlerFunc is a type with a method, ServeHTTP, -so values of that type can serve HTTP requests. Look at the implementation -of the method: the receiver is a function, f, and the method -calls f. That may seem odd but it's not that different from, say, -the receiver being a channel and the method sending on the channel. -

-

-To make ArgServer into an HTTP server, we first modify it -to have the right signature. -

-
-// Argument server.
-func ArgServer(w http.ResponseWriter, req *http.Request) {
-    for _, s := range os.Args {
-        fmt.Fprintln(w, s)
-    }
-}
-
-

-ArgServer now has same signature as HandlerFunc, -so it can be converted to that type to access its methods, -just as we converted Sequence to IntSlice -to access IntSlice.Sort. -The code to set it up is concise: -

-
-http.Handle("/args", http.HandlerFunc(ArgServer))
-
-

-When someone visits the page /args, -the handler installed at that page has value ArgServer -and type HandlerFunc. -The HTTP server will invoke the method ServeHTTP -of that type, with ArgServer as the receiver, which will in turn call -ArgServer (via the invocation f(c, req) -inside HandlerFunc.ServeHTTP). -The arguments will then be displayed. -

-

-In this section we have made an HTTP server from a struct, an integer, -a channel, and a function, all because interfaces are just sets of -methods, which can be defined for (almost) any type. -

- -

Embedding

- -

-Go does not provide the typical, type-driven notion of subclassing, -but it does have the ability to “borrow” pieces of an -implementation by embedding types within a struct or -interface. -

-

-Interface embedding is very simple. -We've mentioned the io.Reader and io.Writer interfaces before; -here are their definitions. -

-
-type Reader interface {
-    Read(p []byte) (n int, err error)
-}
-
-type Writer interface {
-    Write(p []byte) (n int, err error)
-}
-
-

-The io package also exports several other interfaces -that specify objects that can implement several such methods. -For instance, there is io.ReadWriter, an interface -containing both Read and Write. -We could specify io.ReadWriter by listing the -two methods explicitly, but it's easier and more evocative -to embed the two interfaces to form the new one, like this: -

-
-// ReadWriter is the interface that combines the Reader and Writer interfaces.
-type ReadWriter interface {
-    Reader
-    Writer
-}
-
-

-This says just what it looks like: A ReadWriter can do -what a Reader does and what a Writer -does; it is a union of the embedded interfaces (which must be disjoint -sets of methods). -Only interfaces can be embedded within interfaces. -

-The same basic idea applies to structs, but with more far-reaching -implications. The bufio package has two struct types, -bufio.Reader and bufio.Writer, each of -which of course implements the analogous interfaces from package -io. -And bufio also implements a buffered reader/writer, -which it does by combining a reader and a writer into one struct -using embedding: it lists the types within the struct -but does not give them field names. -

-
-// ReadWriter stores pointers to a Reader and a Writer.
-// It implements io.ReadWriter.
-type ReadWriter struct {
-    *Reader  // *bufio.Reader
-    *Writer  // *bufio.Writer
-}
-
-

-The embedded elements are pointers to structs and of course -must be initialized to point to valid structs before they -can be used. -The ReadWriter struct could be written as -

-
-type ReadWriter struct {
-    reader *Reader
-    writer *Writer
-}
-
-

-but then to promote the methods of the fields and to -satisfy the io interfaces, we would also need -to provide forwarding methods, like this: -

-
-func (rw *ReadWriter) Read(p []byte) (n int, err error) {
-    return rw.reader.Read(p)
-}
-
-

-By embedding the structs directly, we avoid this bookkeeping. -The methods of embedded types come along for free, which means that bufio.ReadWriter -not only has the methods of bufio.Reader and bufio.Writer, -it also satisfies all three interfaces: -io.Reader, -io.Writer, and -io.ReadWriter. -

-

-There's an important way in which embedding differs from subclassing. When we embed a type, -the methods of that type become methods of the outer type, -but when they are invoked the receiver of the method is the inner type, not the outer one. -In our example, when the Read method of a bufio.ReadWriter is -invoked, it has exactly the same effect as the forwarding method written out above; -the receiver is the reader field of the ReadWriter, not the -ReadWriter itself. -

-

-Embedding can also be a simple convenience. -This example shows an embedded field alongside a regular, named field. -

-
-type Job struct {
-    Command string
-    *log.Logger
-}
-
-

-The Job type now has the Log, Logf -and other -methods of *log.Logger. We could have given the Logger -a field name, of course, but it's not necessary to do so. And now, once -initialized, we can -log to the Job: -

-
-job.Log("starting now...")
-
-

-The Logger is a regular field of the struct and we can initialize -it in the usual way with a constructor, -

-
-func NewJob(command string, logger *log.Logger) *Job {
-    return &Job{command, logger}
-}
-
-

-or with a composite literal, -

-
-job := &Job{command, log.New(os.Stderr, "Job: ", log.Ldate)}
-
-

-If we need to refer to an embedded field directly, the type name of the field, -ignoring the package qualifier, serves as a field name. If we needed to access the -*log.Logger of a Job variable job, -we would write job.Logger. -This would be useful if we wanted to refine the methods of Logger. -

-
-func (job *Job) Logf(format string, args ...interface{}) {
-    job.Logger.Logf("%q: %s", job.Command, fmt.Sprintf(format, args))
-}
-
-

-Embedding types introduces the problem of name conflicts but the rules to resolve -them are simple. -First, a field or method X hides any other item X in a more deeply -nested part of the type. -If log.Logger contained a field or method called Command, the Command field -of Job would dominate it. -

-

-Second, if the same name appears at the same nesting level, it is usually an error; -it would be erroneous to embed log.Logger if the Job struct -contained another field or method called Logger. -However, if the duplicate name is never mentioned in the program outside the type definition, it is OK. -This qualification provides some protection against changes made to types embedded from outside; there -is no problem if a field is added that conflicts with another field in another subtype if neither field -is ever used. -

- - -

Concurrency

- -

Share by communicating

- -

-Concurrent programming is a large topic and there is space only for some -Go-specific highlights here. -

-

-Concurrent programming in many environments is made difficult by the -subtleties required to implement correct access to shared variables. Go encourages -a different approach in which shared values are passed around on channels -and, in fact, never actively shared by separate threads of execution. -Only one goroutine has access to the value at any given time. -Data races cannot occur, by design. -To encourage this way of thinking we have reduced it to a slogan: -

-
-Do not communicate by sharing memory; -instead, share memory by communicating. -
-

-This approach can be taken too far. Reference counts may be best done -by putting a mutex around an integer variable, for instance. But as a -high-level approach, using channels to control access makes it easier -to write clear, correct programs. -

-

-One way to think about this model is to consider a typical single-threaded -program running on one CPU. It has no need for synchronization primitives. -Now run another such instance; it too needs no synchronization. Now let those -two communicate; if the communication is the synchronizer, there's still no need -for other synchronization. Unix pipelines, for example, fit this model -perfectly. Although Go's approach to concurrency originates in Hoare's -Communicating Sequential Processes (CSP), -it can also be seen as a type-safe generalization of Unix pipes. -

- -

Goroutines

- -

-They're called goroutines because the existing -terms—threads, coroutines, processes, and so on—convey -inaccurate connotations. A goroutine has a simple model: it is a -function executing in parallel with other goroutines in the same -address space. It is lightweight, costing little more than the -allocation of stack space. -And the stacks start small, so they are cheap, and grow -by allocating (and freeing) heap storage as required. -

-

-Goroutines are multiplexed onto multiple OS threads so if one should -block, such as while waiting for I/O, others continue to run. Their -design hides many of the complexities of thread creation and -management. -

-

-Prefix a function or method call with the go -keyword to run the call in a new goroutine. -When the call completes, the goroutine -exits, silently. (The effect is similar to the Unix shell's -& notation for running a command in the -background.) -

-
-go list.Sort()  // run list.Sort in parallel; don't wait for it. 
-
-

-A function literal can be handy in a goroutine invocation. -

-func Announce(message string, delay int64) {
-    go func() {
-        time.Sleep(delay)
-        fmt.Println(message)
-    }()  // Note the parentheses - must call the function.
-}
-
-

-In Go, function literals are closures: the implementation makes -sure the variables referred to by the function survive as long as they are active. -

-These examples aren't too practical because the functions have no way of signaling -completion. For that, we need channels. -

- -

Channels

- -

-Like maps, channels are a reference type and are allocated with make. -If an optional integer parameter is provided, it sets the buffer size for the channel. -The default is zero, for an unbuffered or synchronous channel. -

-
-ci := make(chan int)            // unbuffered channel of integers
-cj := make(chan int, 0)         // unbuffered channel of integers
-cs := make(chan *os.File, 100)  // buffered channel of pointers to Files
-
-

-Channels combine communication—the exchange of a value—with -synchronization—guaranteeing that two calculations (goroutines) are in -a known state. -

-

-There are lots of nice idioms using channels. Here's one to get us started. -In the previous section we launched a sort in the background. A channel -can allow the launching goroutine to wait for the sort to complete. -

-
-c := make(chan int)  // Allocate a channel.
-// Start the sort in a goroutine; when it completes, signal on the channel.
-go func() {
-    list.Sort()
-    c <- 1  // Send a signal; value does not matter. 
-}()
-doSomethingForAWhile()
-<-c   // Wait for sort to finish; discard sent value.
-
-

-Receivers always block until there is data to receive. -If the channel is unbuffered, the sender blocks until the receiver has -received the value. -If the channel has a buffer, the sender blocks only until the -value has been copied to the buffer; if the buffer is full, this -means waiting until some receiver has retrieved a value. -

-

-A buffered channel can be used like a semaphore, for instance to -limit throughput. In this example, incoming requests are passed -to handle, which sends a value into the channel, processes -the request, and then receives a value from the channel. -The capacity of the channel buffer limits the number of -simultaneous calls to process. -

-
-var sem = make(chan int, MaxOutstanding)
-
-func handle(r *Request) {
-    sem <- 1    // Wait for active queue to drain.
-    process(r)  // May take a long time.
-    <-sem       // Done; enable next request to run.
-}
-
-func Serve(queue chan *Request) {
-    for {
-        req := <-queue
-        go handle(req)  // Don't wait for handle to finish.
-    }
-}
-
-

-Here's the same idea implemented by starting a fixed -number of handle goroutines all reading from the request -channel. -The number of goroutines limits the number of simultaneous -calls to process. -This Serve function also accepts a channel on which -it will be told to exit; after launching the goroutines it blocks -receiving from that channel. -

-
-func handle(queue chan *Request) {
-    for r := range queue {
-        process(r)
-    }
-}
-
-func Serve(clientRequests chan *clientRequests, quit chan bool) {
-    // Start handlers
-    for i := 0; i < MaxOutstanding; i++ {
-        go handle(clientRequests)
-    }
-    <-quit  // Wait to be told to exit.
-}
-
- -

Channels of channels

-

-One of the most important properties of Go is that -a channel is a first-class value that can be allocated and passed -around like any other. A common use of this property is -to implement safe, parallel demultiplexing. -

-In the example in the previous section, handle was -an idealized handler for a request but we didn't define the -type it was handling. If that type includes a channel on which -to reply, each client can provide its own path for the answer. -Here's a schematic definition of type Request. -

-
-type Request struct {
-    args        []int
-    f           func([]int) int
-    resultChan  chan int
-}
-
-

-The client provides a function and its arguments, as well as -a channel inside the request object on which to receive the answer. -

-
-func sum(a []int) (s int) {
-    for _, v := range a {
-        s += v
-    }
-    return
-}
-
-request := &Request{[]int{3, 4, 5}, sum, make(chan int)}
-// Send request
-clientRequests <- request
-// Wait for response.
-fmt.Printf("answer: %d\n", <-request.resultChan)
-
-

-On the server side, the handler function is the only thing that changes. -

-
-func handle(queue chan *Request) {
-    for req := range queue {
-        req.resultChan <- req.f(req.args)
-    }
-}
-
-

-There's clearly a lot more to do to make it realistic, but this -code is a framework for a rate-limited, parallel, non-blocking RPC -system, and there's not a mutex in sight. -

- -

Parallelization

-

-Another application of these ideas is to parallelize a calculation -across multiple CPU cores. If the calculation can be broken into -separate pieces, it can be parallelized, with a channel to signal -when each piece completes. -

-

-Let's say we have an expensive operation to perform on a vector of items, -and that the value of the operation on each item is independent, -as in this idealized example. -

-
-type Vector []float64
-
-// Apply the operation to v[i], v[i+1] ... up to v[n-1].
-func (v Vector) DoSome(i, n int, u Vector, c chan int) {
-    for ; i < n; i++ {
-        v[i] += u.Op(v[i])
-    }
-    c <- 1    // signal that this piece is done
-}
-
-

-We launch the pieces independently in a loop, one per CPU. -They can complete in any order but it doesn't matter; we just -count the completion signals by draining the channel after -launching all the goroutines. -

-
-const NCPU = 4  // number of CPU cores
-
-func (v Vector) DoAll(u Vector) {
-    c := make(chan int, NCPU)  // Buffering optional but sensible.
-    for i := 0; i < NCPU; i++ {
-        go v.DoSome(i*len(v)/NCPU, (i+1)*len(v)/NCPU, u, c)
-    }
-    // Drain the channel.
-    for i := 0; i < NCPU; i++ {
-        <-c    // wait for one task to complete
-    }
-    // All done.
-}
-
-
- -

-The current implementation of gc (6g, etc.) -will not parallelize this code by default. -It dedicates only a single core to user-level processing. An -arbitrary number of goroutines can be blocked in system calls, but -by default only one can be executing user-level code at any time. -It should be smarter and one day it will be smarter, but until it -is if you want CPU parallelism you must tell the run-time -how many goroutines you want executing code simultaneously. There -are two related ways to do this. Either run your job with environment -variable GOMAXPROCS set to the number of cores to use -or import the runtime package and call -runtime.GOMAXPROCS(NCPU). -A helpful value might be runtime.NumCPU(), which reports the number -of logical CPUs on the local machine. -Again, this requirement is expected to be retired as the scheduling and run-time improve. -

- -

A leaky buffer

- -

-The tools of concurrent programming can even make non-concurrent -ideas easier to express. Here's an example abstracted from an RPC -package. The client goroutine loops receiving data from some source, -perhaps a network. To avoid allocating and freeing buffers, it keeps -a free list, and uses a buffered channel to represent it. If the -channel is empty, a new buffer gets allocated. -Once the message buffer is ready, it's sent to the server on -serverChan. -

-
-var freeList = make(chan *Buffer, 100)
-var serverChan = make(chan *Buffer)
-
-func client() {
-    for {
-        var b *Buffer
-        // Grab a buffer if available; allocate if not.
-        select {
-        case b = <-freeList:
-            // Got one; nothing more to do.
-        default:
-            // None free, so allocate a new one.
-            b = new(Buffer)
-        }
-        load(b)              // Read next message from the net.
-        serverChan <- b      // Send to server.
-    }
-}
-
-

-The server loop receives each message from the client, processes it, -and returns the buffer to the free list. -

-
-func server() {
-    for {
-        b := <-serverChan    // Wait for work.
-        process(b)
-        // Reuse buffer if there's room.
-        select {
-        case freeList <- b:
-            // Buffer on free list; nothing more to do.
-        default:
-            // Free list full, just carry on.
-        }
-    }
-}
-
-

-The client attempts to retrieve a buffer from freeList; -if none is available, it allocates a fresh one. -The server's send to freeList puts b back -on the free list unless the list is full, in which case the -buffer is dropped on the floor to be reclaimed by -the garbage collector. -(The default clauses in the select -statements execute when no other case is ready, -meaning that the selects never block.) -This implementation builds a leaky bucket free list -in just a few lines, relying on the buffered channel and -the garbage collector for bookkeeping. -

- -

Errors

- -

-Library routines must often return some sort of error indication to -the caller. As mentioned earlier, Go's multivalue return makes it -easy to return a detailed error description alongside the normal -return value. By convention, errors have type error, -a simple built-in interface. -

-
-type error interface {
-    Error() string
-}
-
-

-A library writer is free to implement this interface with a -richer model under the covers, making it possible not only -to see the error but also to provide some context. -For example, os.Open returns an os.PathError. -

-
-// PathError records an error and the operation and
-// file path that caused it.
-type PathError struct {
-    Op string    // "open", "unlink", etc.
-    Path string  // The associated file.
-    Err error    // Returned by the system call.
-}
-
-func (e *PathError) Error() string {
-    return e.Op + " " + e.Path + ": " + e.Err.Error()
-}
-
-

-PathError's Error generates -a string like this: -

-
-open /etc/passwx: no such file or directory
-
-

-Such an error, which includes the problematic file name, the -operation, and the operating system error it triggered, is useful even -if printed far from the call that caused it; -it is much more informative than the plain -"no such file or directory". -

- -

-When feasible, error strings should identify their origin, such as by having -a prefix naming the package that generated the error. For example, in package -image, the string representation for a decoding error due to an unknown format -is "image: unknown format". -

- -

-Callers that care about the precise error details can -use a type switch or a type assertion to look for specific -errors and extract details. For PathErrors -this might include examining the internal Err -field for recoverable failures. -

- -
-for try := 0; try < 2; try++ {
-    file, err = os.Open(filename)
-    if err == nil {
-        return
-    }
-    if e, ok := err.(*os.PathError); ok && e.Err == os.ENOSPC {
-        deleteTempFiles()  // Recover some space.
-        continue
-    }
-    return
-}
-
- -

-The second if statement here is idiomatic Go. -The type assertion err.(*os.PathError) is -checked with the "comma ok" idiom (mentioned earlier -in the context of examining maps). -If the type assertion fails, ok will be false, and e -will be nil. -If it succeeds, ok will be true, which means the -error was of type *os.PathError, and then so is e, -which we can examine for more information about the error. -

- -

Panic

- -

-The usual way to report an error to a caller is to return an -error as an extra return value. The canonical -Read method is a well-known instance; it returns a byte -count and an error. But what if the error is -unrecoverable? Sometimes the program simply cannot continue. -

- -

-For this purpose, there is a built-in function panic -that in effect creates a run-time error that will stop the program -(but see the next section). The function takes a single argument -of arbitrary type—often a string—to be printed as the -program dies. It's also a way to indicate that something impossible has -happened, such as exiting an infinite loop. In fact, the compiler -recognizes a panic at the end of a function and -suppresses the usual check for a return statement. -

- - -
-// A toy implementation of cube root using Newton's method.
-func CubeRoot(x float64) float64 {
-    z := x/3   // Arbitrary initial value
-    for i := 0; i < 1e6; i++ {
-        prevz := z
-        z -= (z*z*z-x) / (3*z*z)
-        if veryClose(z, prevz) {
-            return z
-        }
-    }
-    // A million iterations has not converged; something is wrong.
-    panic(fmt.Sprintf("CubeRoot(%g) did not converge", x))
-}
-
- -

-This is only an example but real library functions should -avoid panic. If the problem can be masked or worked -around, it's always better to let things continue to run rather -than taking down the whole program. One possible counterexample -is during initialization: if the library truly cannot set itself up, -it might be reasonable to panic, so to speak. -

- -
-var user = os.Getenv("USER")
-
-func init() {
-    if user == "" {
-        panic("no value for $USER")
-    }
-}
-
- -

Recover

- -

-When panic is called, including implicitly for run-time -errors such as indexing an array out of bounds or failing a type -assertion, it immediately stops execution of the current function -and begins unwinding the stack of the goroutine, running any deferred -functions along the way. If that unwinding reaches the top of the -goroutine's stack, the program dies. However, it is possible to -use the built-in function recover to regain control -of the goroutine and resume normal execution. -

- -

-A call to recover stops the unwinding and returns the -argument passed to panic. Because the only code that -runs while unwinding is inside deferred functions, recover -is only useful inside deferred functions. -

- -

-One application of recover is to shut down a failing goroutine -inside a server without killing the other executing goroutines. -

- -
-func server(workChan <-chan *Work) {
-    for work := range workChan {
-        go safelyDo(work)
-    }
-}
-
-func safelyDo(work *Work) {
-    defer func() {
-        if err := recover(); err != nil {
-            log.Println("work failed:", err)
-        }
-    }()
-    do(work)
-}
-
- -

-In this example, if do(work) panics, the result will be -logged and the goroutine will exit cleanly without disturbing the -others. There's no need to do anything else in the deferred closure; -calling recover handles the condition completely. -

- -

-Because recover always returns nil unless called directly -from a deferred function, deferred code can call library routines that themselves -use panic and recover without failing. As an example, -the deferred function in safelyDo might call a logging function before -calling recover, and that logging code would run unaffected -by the panicking state. -

- -

-With our recovery pattern in place, the do -function (and anything it calls) can get out of any bad situation -cleanly by calling panic. We can use that idea to -simplify error handling in complex software. Let's look at an -idealized excerpt from the regexp package, which reports -parsing errors by calling panic with a local -error type. Here's the definition of Error, -an error method, and the Compile function. -

- -
-// Error is the type of a parse error; it satisfies the error interface.
-type Error string
-func (e Error) Error() string {
-    return string(e)
-}
-
-// error is a method of *Regexp that reports parsing errors by
-// panicking with an Error.
-func (regexp *Regexp) error(err string) {
-    panic(Error(err))
-}
-
-// Compile returns a parsed representation of the regular expression.
-func Compile(str string) (regexp *Regexp, err error) {
-    regexp = new(Regexp)
-    // doParse will panic if there is a parse error.
-    defer func() {
-        if e := recover(); e != nil {
-            regexp = nil    // Clear return value.
-            err = e.(Error) // Will re-panic if not a parse error.
-        }
-    }()
-    return regexp.doParse(str), nil
-}
-
- -

-If doParse panics, the recovery block will set the -return value to nil—deferred functions can modify -named return values. It then will then check, in the assignment -to err, that the problem was a parse error by asserting -that it has the local type Error. -If it does not, the type assertion will fail, causing a run-time error -that continues the stack unwinding as though nothing had interrupted -it. This check means that if something unexpected happens, such -as an array index out of bounds, the code will fail even though we -are using panic and recover to handle -user-triggered errors. -

- -

-With error handling in place, the error method -makes it easy to report parse errors without worrying about unwinding -the parse stack by hand. -

- -

-Useful though this pattern is, it should be used only within a package. -Parse turns its internal panic calls into -error values; it does not expose panics -to its client. That is a good rule to follow. -

- -

-By the way, this re-panic idiom changes the panic value if an actual -error occurs. However, both the original and new failures will be -presented in the crash report, so the root cause of the problem will -still be visible. Thus this simple re-panic approach is usually -sufficient—it's a crash after all—but if you want to -display only the original value, you can write a little more code to -filter unexpected problems and re-panic with the original error. -That's left as an exercise for the reader. -

- - -

A web server

- -

-Let's finish with a complete Go program, a web server. -This one is actually a kind of web re-server. -Google provides a service at -http://chart.apis.google.com -that does automatic formatting of data into charts and graphs. -It's hard to use interactively, though, -because you need to put the data into the URL as a query. -The program here provides a nicer interface to one form of data: given a short piece of text, -it calls on the chart server to produce a QR code, a matrix of boxes that encode the -text. -That image can be grabbed with your cell phone's camera and interpreted as, -for instance, a URL, saving you typing the URL into the phone's tiny keyboard. -

-

-Here's the complete program. -An explanation follows. -

-{{code "progs/eff_qr.go"}} -

-The pieces up to main should be easy to follow. -The one flag sets a default HTTP port for our server. The template -variable templ is where the fun happens. It builds an HTML template -that will be executed by the server to display the page; more about -that in a moment. -

-

-The main function parses the flags and, using the mechanism -we talked about above, binds the function QR to the root path -for the server. Then http.ListenAndServe is called to start the -server; it blocks while the server runs. -

-

-QR just receives the request, which contains form data, and -executes the template on the data in the form value named s. -

-

-The template package is powerful; -this program just touches on its capabilities. -In essence, it rewrites a piece of text on the fly by substituting elements derived -from data items passed to templ.Execute, in this case the -form value. -Within the template text (templateStr), -double-brace-delimited pieces denote template actions. -The piece from {{html "{{if .}}"}} -to {{html "{{end}}"}} executes only if the value of the current data item, called . (dot), -is non-empty. -That is, when the string is empty, this piece of the template is suppressed. -

-

-The snippet {{html "{{urlquery .}}"}} says to process the data with the function -urlquery, which sanitizes the query string -for safe display on the web page. -

-

-The rest of the template string is just the HTML to show when the page loads. -If this is too quick an explanation, see the documentation -for the template package for a more thorough discussion. -

-

-And there you have it: a useful webserver in a few lines of code plus some -data-driven HTML text. -Go is powerful enough to make a lot happen in a few lines. -

- - - diff --git a/doc/go1.html b/doc/go1.html index 6d71037f2e..dcc3300d32 100644 --- a/doc/go1.html +++ b/doc/go1.html @@ -1,11 +1,7 @@ - -

Introduction to Go 1

@@ -64,9 +60,7 @@ However, append did not provide a way to append a string to a -
    greeting := []byte{}
-    greeting = append(greeting, []byte("hello ")...)
+{{code "/doc/progs/go1.go" `/greeting := ..byte/` `/append.*hello/`}}

By analogy with the similar property of copy, Go 1 @@ -75,8 +69,7 @@ slice, reducing the friction between strings and byte slices. The conversion is no longer necessary:

-
    greeting = append(greeting, "world"...)
+{{code "/doc/progs/go1.go" `/append.*world/`}}

Updating: @@ -126,35 +119,7 @@ type specification for the elements' initializers if they are of pointer type. All four of the initializations in this example are legal; the last one was illegal before Go 1.

-
    type Date struct {
-        month string
-        day   int
-    }
-    // Struct values, fully qualified; always legal.
-    holiday1 := []Date{
-        Date{"Feb", 14},
-        Date{"Nov", 11},
-        Date{"Dec", 25},
-    }
-    // Struct values, type name elided; always legal.
-    holiday2 := []Date{
-        {"Feb", 14},
-        {"Nov", 11},
-        {"Dec", 25},
-    }
-    // Pointers, fully qualified, always legal.
-    holiday3 := []*Date{
-        &Date{"Feb", 14},
-        &Date{"Nov", 11},
-        &Date{"Dec", 25},
-    }
-    // Pointers, type name elided; legal in Go 1.
-    holiday4 := []*Date{
-        {"Feb", 14},
-        {"Nov", 11},
-        {"Dec", 25},
-    }
+{{code "/doc/progs/go1.go" `/type Date struct/` `/STOP/`}}

Updating: @@ -183,14 +148,7 @@ In Go 1, code that uses goroutines can be called from without introducing a deadlock.

-
var PackageGlobal int
-
-func init() {
-    c := make(chan int)
-    go initializationFunction(c)
-    PackageGlobal = <-c
-}
+{{code "/doc/progs/go1.go" `/PackageGlobal/` `/^}/`}}

Updating: @@ -231,14 +189,7 @@ when appropriate. For instance, the functions unicode.ToLower and relatives now take and return a rune.

-
    delta := 'δ' // delta has type rune.
-    var DELTA rune
-    DELTA = unicode.ToUpper(delta)
-    epsilon := unicode.ToLower(DELTA + 1)
-    if epsilon != 'δ'+1 {
-        log.Fatal("inconsistent casing for Greek")
-    }
+{{code "/doc/progs/go1.go" `/STARTRUNE/` `/ENDRUNE/`}}

Updating: @@ -287,8 +238,7 @@ In Go 1, that syntax has gone; instead there is a new built-in function, delete. The call

-
    delete(m, k)
+{{code "/doc/progs/go1.go" `/delete\(m, k\)/`}}

will delete the map entry retrieved by the expression m[k]. @@ -327,12 +277,7 @@ This change means that code that depends on iteration order is very likely to br Just as important, it allows the map implementation to ensure better map balancing even when programs are using range loops to select an element from a map.

-
    m := map[string]int{"Sunday": 0, "Monday": 1}
-    for name, value := range m {
-        // This loop should not assume Sunday will be visited first.
-        f(name, value)
-    }
+{{code "/doc/progs/go1.go" `/Sunday/` `/^ }/`}}

Updating: @@ -367,17 +312,7 @@ proceed in left-to-right order. These examples illustrate the behavior.

-
    sa := []int{1, 2, 3}
-    i := 0
-    i, sa[i] = 1, 2 // sets i = 1, sa[0] = 2
-
-    sb := []int{1, 2, 3}
-    j := 0
-    sb[j], j = 2, 1 // sets sb[0] = 2, j = 1
-
-    sc := []int{1, 2, 3}
-    sc[0], sc[0] = 1, 2 // sets sc[0] = 1, then sc[0] = 2 (so sc[0] = 2 at end)
+{{code "/doc/progs/go1.go" `/sa :=/` `/then sc.0. = 2/`}}

Updating: @@ -504,18 +439,7 @@ provided they are composed from elements for which equality is also defined, using element-wise comparison.

-
    type Day struct {
-        long  string
-        short string
-    }
-    Christmas := Day{"Christmas", "XMas"}
-    Thanksgiving := Day{"Thanksgiving", "Turkey"}
-    holiday := map[Day]bool{
-        Christmas:    true,
-        Thanksgiving: true,
-    }
-    fmt.Printf("Christmas is a holiday: %t\n", holiday[Christmas])
+{{code "/doc/progs/go1.go" `/type Day struct/` `/Printf/`}}

Second, Go 1 removes the definition of equality for function values, @@ -831,16 +755,7 @@ The fmt library automatically invokes Error, as it alr does for String, for easy printing of error values.

-
type SyntaxError struct {
-    File    string
-    Line    int
-    Message string
-}
-
-func (se *SyntaxError) Error() string {
-    return fmt.Sprintf("%s:%d: %s", se.File, se.Line, se.Message)
-}
+{{code "/doc/progs/go1.go" `/START ERROR EXAMPLE/` `/END ERROR EXAMPLE/`}}

All standard packages have been updated to use the new interface; the old os.Error is gone. @@ -858,8 +773,7 @@ func New(text string) error to turn a string into an error. It replaces the old os.NewError.

-
    var ErrSyntax = errors.New("syntax error")
+{{code "/doc/progs/go1.go" `/ErrSyntax/`}}

Updating: @@ -949,17 +863,7 @@ returns a time.Time value rather than, in the old API, an integer nanosecond count since the Unix epoch.

-
// sleepUntil sleeps until the specified time. It returns immediately if it's too late.
-func sleepUntil(wakeup time.Time) {
-    now := time.Now() // A Time.
-    if !wakeup.After(now) {
-        return
-    }
-    delta := wakeup.Sub(now) // A Duration.
-    fmt.Printf("Sleeping for %.3fs\n", delta.Seconds())
-    time.Sleep(delta)
-}
+{{code "/doc/progs/go1.go" `/sleepUntil/` `/^}/`}}

The new types, methods, and constants have been propagated through @@ -1196,8 +1100,7 @@ Values for such flags must be given units, just as time.Duration formats them: 10s, 1h30m, etc.

-
var timeout = flag.Duration("timeout", 30*time.Second, "how long to wait for completion")
+{{code "/doc/progs/go1.go" `/timeout/`}}

Updating: @@ -1711,11 +1614,7 @@ and IsPermission.

-
    f, err := os.OpenFile(name, os.O_RDWR|os.O_CREATE|os.O_EXCL, 0600)
-    if os.IsExist(err) {
-        log.Printf("%s already exists", name)
-    }
+{{code "/doc/progs/go1.go" `/os\.Open/` `/}/`}}

Updating: @@ -1781,21 +1680,7 @@ If a directory's contents are to be skipped, the function should return the value filepath.SkipDir

-
    markFn := func(path string, info os.FileInfo, err error) error {
-        if path == "pictures" { // Will skip walking of directory pictures and its contents.
-            return filepath.SkipDir
-        }
-        if err != nil {
-            return err
-        }
-        log.Println(path)
-        return nil
-    }
-    err := filepath.Walk(".", markFn)
-    if err != nil {
-        log.Fatal(err)
-    }
+{{code "/doc/progs/go1.go" `/STARTWALK/` `/ENDWALK/`}}

Updating: @@ -1993,20 +1878,7 @@ In Go 1, B has new methods, analogous to those of T, e logging and failure reporting.

-
func BenchmarkSprintf(b *testing.B) {
-    // Verify correctness before running benchmark.
-    b.StopTimer()
-    got := fmt.Sprintf("%x", 23)
-    const expect = "17"
-    if expect != got {
-        b.Fatalf("expected %q; got %q", expect, got)
-    }
-    b.StartTimer()
-    for i := 0; i < b.N; i++ {
-        fmt.Sprintf("%x", 23)
-    }
-}
+{{code "/doc/progs/go1.go" `/func.*Benchmark/` `/^}/`}}

Updating: diff --git a/doc/go1.tmpl b/doc/go1.tmpl deleted file mode 100644 index ae9f81a639..0000000000 --- a/doc/go1.tmpl +++ /dev/null @@ -1,2029 +0,0 @@ - -{{donotedit}} - -

Introduction to Go 1

- -

-Go version 1, Go 1 for short, defines a language and a set of core libraries -that provide a stable foundation for creating reliable products, projects, and -publications. -

- -

-The driving motivation for Go 1 is stability for its users. People should be able to -write Go programs and expect that they will continue to compile and run without -change, on a time scale of years, including in production environments such as -Google App Engine. Similarly, people should be able to write books about Go, be -able to say which version of Go the book is describing, and have that version -number still be meaningful much later. -

- -

-Code that compiles in Go 1 should, with few exceptions, continue to compile and -run throughout the lifetime of that version, even as we issue updates and bug -fixes such as Go version 1.1, 1.2, and so on. Other than critical fixes, changes -made to the language and library for subsequent releases of Go 1 may -add functionality but will not break existing Go 1 programs. -The Go 1 compatibility document -explains the compatibility guidelines in more detail. -

- -

-Go 1 is a representation of Go as it used today, not a wholesale rethinking of -the language. We avoided designing new features and instead focused on cleaning -up problems and inconsistencies and improving portability. There are a number -changes to the Go language and packages that we had considered for some time and -prototyped but not released primarily because they are significant and -backwards-incompatible. Go 1 was an opportunity to get them out, which is -helpful for the long term, but also means that Go 1 introduces incompatibilities -for old programs. Fortunately, the go fix tool can -automate much of the work needed to bring programs up to the Go 1 standard. -

- -

-This document outlines the major changes in Go 1 that will affect programmers -updating existing code; its reference point is the prior release, r60 (tagged as -r60.3). It also explains how to update code from r60 to run under Go 1. -

- -

Changes to the language

- -

Append

- -

-The append predeclared variadic function makes it easy to grow a slice -by adding elements to the end. -A common use is to add bytes to the end of a byte slice when generating output. -However, append did not provide a way to append a string to a []byte, -which is another common case. -

- -{{code "progs/go1.go" `/greeting := ..byte/` `/append.*hello/`}} - -

-By analogy with the similar property of copy, Go 1 -permits a string to be appended (byte-wise) directly to a byte -slice, reducing the friction between strings and byte slices. -The conversion is no longer necessary: -

- -{{code "progs/go1.go" `/append.*world/`}} - -

-Updating: -This is a new feature, so existing code needs no changes. -

- -

Close

- -

-The close predeclared function provides a mechanism -for a sender to signal that no more values will be sent. -It is important to the implementation of for range -loops over channels and is helpful in other situations. -Partly by design and partly because of race conditions that can occur otherwise, -it is intended for use only by the goroutine sending on the channel, -not by the goroutine receiving data. -However, before Go 1 there was no compile-time checking that close -was being used correctly. -

- -

-To close this gap, at least in part, Go 1 disallows close on receive-only channels. -Attempting to close such a channel is a compile-time error. -

- -
-    var c chan int
-    var csend chan<- int = c
-    var crecv <-chan int = c
-    close(c)     // legal
-    close(csend) // legal
-    close(crecv) // illegal
-
- -

-Updating: -Existing code that attempts to close a receive-only channel was -erroneous even before Go 1 and should be fixed. The compiler will -now reject such code. -

- -

Composite literals

- -

-In Go 1, a composite literal of array, slice, or map type can elide the -type specification for the elements' initializers if they are of pointer type. -All four of the initializations in this example are legal; the last one was illegal before Go 1. -

- -{{code "progs/go1.go" `/type Date struct/` `/STOP/`}} - -

-Updating: -This change has no effect on existing code, but the command -gofmt -s applied to existing source -will, among other things, elide explicit element types wherever permitted. -

- - -

Goroutines during init

- -

-The old language defined that go statements executed during initialization created goroutines but that they did not begin to run until initialization of the entire program was complete. -This introduced clumsiness in many places and, in effect, limited the utility -of the init construct: -if it was possible for another package to use the library during initialization, the library -was forced to avoid goroutines. -This design was done for reasons of simplicity and safety but, -as our confidence in the language grew, it seemed unnecessary. -Running goroutines during initialization is no more complex or unsafe than running them during normal execution. -

- -

-In Go 1, code that uses goroutines can be called from -init routines and global initialization expressions -without introducing a deadlock. -

- -{{code "progs/go1.go" `/PackageGlobal/` `/^}/`}} - -

-Updating: -This is a new feature, so existing code needs no changes, -although it's possible that code that depends on goroutines not starting before main will break. -There was no such code in the standard repository. -

- -

The rune type

- -

-The language spec allows the int type to be 32 or 64 bits wide, but current implementations set int to 32 bits even on 64-bit platforms. -It would be preferable to have int be 64 bits on 64-bit platforms. -(There are important consequences for indexing large slices.) -However, this change would waste space when processing Unicode characters with -the old language because the int type was also used to hold Unicode code points: each code point would waste an extra 32 bits of storage if int grew from 32 bits to 64. -

- -

-To make changing to 64-bit int feasible, -Go 1 introduces a new basic type, rune, to represent -individual Unicode code points. -It is an alias for int32, analogous to byte -as an alias for uint8. -

- -

-Character literals such as 'a', '語', and '\u0345' -now have default type rune, -analogous to 1.0 having default type float64. -A variable initialized to a character constant will therefore -have type rune unless otherwise specified. -

- -

-Libraries have been updated to use rune rather than int -when appropriate. For instance, the functions unicode.ToLower and -relatives now take and return a rune. -

- -{{code "progs/go1.go" `/STARTRUNE/` `/ENDRUNE/`}} - -

-Updating: -Most source code will be unaffected by this because the type inference from -:= initializers introduces the new type silently, and it propagates -from there. -Some code may get type errors that a trivial conversion will resolve. -

- -

The error type

- -

-Go 1 introduces a new built-in type, error, which has the following definition: -

- -
-    type error interface {
-        Error() string
-    }
-
- -

-Since the consequences of this type are all in the package library, -it is discussed below. -

- -

Deleting from maps

- -

-In the old language, to delete the entry with key k from map m, one wrote the statement, -

- -
-    m[k] = value, false
-
- -

-This syntax was a peculiar special case, the only two-to-one assignment. -It required passing a value (usually ignored) that is evaluated but discarded, -plus a boolean that was nearly always the constant false. -It did the job but was odd and a point of contention. -

- -

-In Go 1, that syntax has gone; instead there is a new built-in -function, delete. The call -

- -{{code "progs/go1.go" `/delete\(m, k\)/`}} - -

-will delete the map entry retrieved by the expression m[k]. -There is no return value. Deleting a non-existent entry is a no-op. -

- -

-Updating: -Running go fix will convert expressions of the form m[k] = value, -false into delete(m, k) when it is clear that -the ignored value can be safely discarded from the program and -false refers to the predefined boolean constant. -The fix tool -will flag other uses of the syntax for inspection by the programmer. -

- -

Iterating in maps

- -

-The old language specification did not define the order of iteration for maps, -and in practice it differed across hardware platforms. -This caused tests that iterated over maps to be fragile and non-portable, with the -unpleasant property that a test might always pass on one machine but break on another. -

- -

-In Go 1, the order in which elements are visited when iterating -over a map using a for range statement -is defined to be unpredictable, even if the same loop is run multiple -times with the same map. -Code should not assume that the elements are visited in any particular order. -

- -

-This change means that code that depends on iteration order is very likely to break early and be fixed long before it becomes a problem. -Just as important, it allows the map implementation to ensure better map balancing even when programs are using range loops to select an element from a map. -

- -{{code "progs/go1.go" `/Sunday/` `/^ }/`}} - -

-Updating: -This is one change where tools cannot help. Most existing code -will be unaffected, but some programs may break or misbehave; we -recommend manual checking of all range statements over maps to -verify they do not depend on iteration order. There were a few such -examples in the standard repository; they have been fixed. -Note that it was already incorrect to depend on the iteration order, which -was unspecified. This change codifies the unpredictability. -

- -

Multiple assignment

- -

-The language specification has long guaranteed that in assignments -the right-hand-side expressions are all evaluated before any left-hand-side expressions are assigned. -To guarantee predictable behavior, -Go 1 refines the specification further. -

- -

-If the left-hand side of the assignment -statement contains expressions that require evaluation, such as -function calls or array indexing operations, these will all be done -using the usual left-to-right rule before any variables are assigned -their value. Once everything is evaluated, the actual assignments -proceed in left-to-right order. -

- -

-These examples illustrate the behavior. -

- -{{code "progs/go1.go" `/sa :=/` `/then sc.0. = 2/`}} - -

-Updating: -This is one change where tools cannot help, but breakage is unlikely. -No code in the standard repository was broken by this change, and code -that depended on the previous unspecified behavior was already incorrect. -

- -

Returns and shadowed variables

- -

-A common mistake is to use return (without arguments) after an assignment to a variable that has the same name as a result variable but is not the same variable. -This situation is called shadowing: the result variable has been shadowed by another variable with the same name declared in an inner scope. -

- -

-In functions with named return values, -the Go 1 compilers disallow return statements without arguments if any of the named return values is shadowed at the point of the return statement. -(It isn't part of the specification, because this is one area we are still exploring; -the situation is analogous to the compilers rejecting functions that do not end with an explicit return statement.) -

- -

-This function implicitly returns a shadowed return value and will be rejected by the compiler: -

- -
-    func Bug() (i, j, k int) {
-        for i = 0; i < 5; i++ {
-            for j := 0; j < 5; j++ { // Redeclares j.
-                k += i*j
-                if k > 100 {
-                    return // Rejected: j is shadowed here.
-                }
-            }
-        }
-        return // OK: j is not shadowed here.
-    }
-
- -

-Updating: -Code that shadows return values in this way will be rejected by the compiler and will need to be fixed by hand. -The few cases that arose in the standard repository were mostly bugs. -

- -

Copying structs with unexported fields

- -

-The old language did not allow a package to make a copy of a struct value containing unexported fields belonging to a different package. -There was, however, a required exception for a method receiver; -also, the implementations of copy and append have never honored the restriction. -

- -

-Go 1 will allow packages to copy struct values containing unexported fields from other packages. -Besides resolving the inconsistency, -this change admits a new kind of API: a package can return an opaque value without resorting to a pointer or interface. -The new implementations of time.Time and -reflect.Value are examples of types taking advantage of this new property. -

- -

-As an example, if package p includes the definitions, -

- -
-    type Struct struct {
-        Public int
-        secret int
-    }
-    func NewStruct(a int) Struct {  // Note: not a pointer.
-        return Struct{a, f(a)}
-    }
-    func (s Struct) String() string {
-        return fmt.Sprintf("{%d (secret %d)}", s.Public, s.secret)
-    }
-
- -

-a package that imports p can assign and copy values of type -p.Struct at will. -Behind the scenes the unexported fields will be assigned and copied just -as if they were exported, -but the client code will never be aware of them. The code -

- -
-    import "p"
-
-    myStruct := p.NewStruct(23)
-    copyOfMyStruct := myStruct
-    fmt.Println(myStruct, copyOfMyStruct)
-
- -

-will show that the secret field of the struct has been copied to the new value. -

- -

-Updating: -This is a new feature, so existing code needs no changes. -

- -

Equality

- -

-Before Go 1, the language did not define equality on struct and array values. -This meant, -among other things, that structs and arrays could not be used as map keys. -On the other hand, Go did define equality on function and map values. -Function equality was problematic in the presence of closures -(when are two closures equal?) -while map equality compared pointers, not the maps' content, which was usually -not what the user would want. -

- -

-Go 1 addressed these issues. -First, structs and arrays can be compared for equality and inequality -(== and !=), -and therefore be used as map keys, -provided they are composed from elements for which equality is also defined, -using element-wise comparison. -

- -{{code "progs/go1.go" `/type Day struct/` `/Printf/`}} - -

-Second, Go 1 removes the definition of equality for function values, -except for comparison with nil. -Finally, map equality is gone too, also except for comparison with nil. -

- -

-Note that equality is still undefined for slices, for which the -calculation is in general infeasible. Also note that the ordered -comparison operators (< <= -> >=) are still undefined for -structs and arrays. - -

-Updating: -Struct and array equality is a new feature, so existing code needs no changes. -Existing code that depends on function or map equality will be -rejected by the compiler and will need to be fixed by hand. -Few programs will be affected, but the fix may require some -redesign. -

- -

The package hierarchy

- -

-Go 1 addresses many deficiencies in the old standard library and -cleans up a number of packages, making them more internally consistent -and portable. -

- -

-This section describes how the packages have been rearranged in Go 1. -Some have moved, some have been renamed, some have been deleted. -New packages are described in later sections. -

- -

The package hierarchy

- -

-Go 1 has a rearranged package hierarchy that groups related items -into subdirectories. For instance, utf8 and -utf16 now occupy subdirectories of unicode. -Also, some packages have moved into -subrepositories of -code.google.com/p/go -while others have been deleted outright. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Old pathNew path
asn1 encoding/asn1
csv encoding/csv
gob encoding/gob
json encoding/json
xml encoding/xml
exp/template/html html/template
big math/big
cmath math/cmplx
rand math/rand
http net/http
http/cgi net/http/cgi
http/fcgi net/http/fcgi
http/httptest net/http/httptest
http/pprof net/http/pprof
mail net/mail
rpc net/rpc
rpc/jsonrpc net/rpc/jsonrpc
smtp net/smtp
url net/url
exec os/exec
scanner text/scanner
tabwriter text/tabwriter
template text/template
template/parse text/template/parse
utf8 unicode/utf8
utf16 unicode/utf16
- -

-Note that the package names for the old cmath and -exp/template/html packages have changed to cmplx -and template. -

- -

-Updating: -Running go fix will update all imports and package renames for packages that -remain inside the standard repository. Programs that import packages -that are no longer in the standard repository will need to be edited -by hand. -

- -

The package tree exp

- -

-Because they are not standardized, the packages under the exp directory will not be available in the -standard Go 1 release distributions, although they will be available in source code form -in the repository for -developers who wish to use them. -

- -

-Several packages have moved under exp at the time of Go 1's release: -

- -
    -
  • ebnf
    • -
  • html†
    • -
  • go/types
    • -
- -

-(†The EscapeString and UnescapeString types remain -in package html.) -

- -

-All these packages are available under the same names, with the prefix exp/: exp/ebnf etc. -

- -

-Also, the utf8.String type has been moved to its own package, exp/utf8string. -

- -

-Finally, the gotype command now resides in exp/gotype, while -ebnflint is now in exp/ebnflint. -If they are installed, they now reside in $GOROOT/bin/tool. -

- -

-Updating: -Code that uses packages in exp will need to be updated by hand, -or else compiled from an installation that has exp available. -The go fix tool or the compiler will complain about such uses. -

- -

The package tree old

- -

-Because they are deprecated, the packages under the old directory will not be available in the -standard Go 1 release distributions, although they will be available in source code form for -developers who wish to use them. -

- -

-The packages in their new locations are: -

- -
    -
  • old/netchan
    • -
  • old/regexp
    • -
  • old/template
    • -
- -

-Updating: -Code that uses packages now in old will need to be updated by hand, -or else compiled from an installation that has old available. -The go fix tool will warn about such uses. -

- -

Deleted packages

- -

-Go 1 deletes several packages outright: -

- -
    -
  • container/vector
    • -
  • exp/datafmt
    • -
  • go/typechecker
    • -
  • try
    • -
- -

-and also the command gotry. -

- -

-Updating: -Code that uses container/vector should be updated to use -slices directly. See -the Go -Language Community Wiki for some suggestions. -Code that uses the other packages (there should be almost zero) will need to be rethought. -

- -

Packages moving to subrepositories

- -

-Go 1 has moved a number of packages into other repositories, usually sub-repositories of -the main Go repository. -This table lists the old and new import paths: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
OldNew
crypto/bcrypt code.google.com/p/go.crypto/bcrypt
crypto/blowfish code.google.com/p/go.crypto/blowfish
crypto/cast5 code.google.com/p/go.crypto/cast5
crypto/md4 code.google.com/p/go.crypto/md4
crypto/ocsp code.google.com/p/go.crypto/ocsp
crypto/openpgp code.google.com/p/go.crypto/openpgp
crypto/openpgp/armor code.google.com/p/go.crypto/openpgp/armor
crypto/openpgp/elgamal code.google.com/p/go.crypto/openpgp/elgamal
crypto/openpgp/errors code.google.com/p/go.crypto/openpgp/errors
crypto/openpgp/packet code.google.com/p/go.crypto/openpgp/packet
crypto/openpgp/s2k code.google.com/p/go.crypto/openpgp/s2k
crypto/ripemd160 code.google.com/p/go.crypto/ripemd160
crypto/twofish code.google.com/p/go.crypto/twofish
crypto/xtea code.google.com/p/go.crypto/xtea
exp/ssh code.google.com/p/go.crypto/ssh
image/bmp code.google.com/p/go.image/bmp
image/tiff code.google.com/p/go.image/tiff
net/dict code.google.com/p/go.net/dict
net/websocket code.google.com/p/go.net/websocket
exp/spdy code.google.com/p/go.net/spdy
encoding/git85 code.google.com/p/go.codereview/git85
patch code.google.com/p/go.codereview/patch
exp/wingui code.google.com/p/gowingui
- -

-Updating: -Running go fix will update imports of these packages to use the new import paths. -Installations that depend on these packages will need to install them using -a go install command. -

- -

Major changes to the library

- -

-This section describes significant changes to the core libraries, the ones that -affect the most programs. -

- -

The error type and errors package

- -

-The placement of os.Error in package os is mostly historical: errors first came up when implementing package os, and they seemed system-related at the time. -Since then it has become clear that errors are more fundamental than the operating system. For example, it would be nice to use Errors in packages that os depends on, like syscall. -Also, having Error in os introduces many dependencies on os that would otherwise not exist. -

- -

-Go 1 solves these problems by introducing a built-in error interface type and a separate errors package (analogous to bytes and strings) that contains utility functions. -It replaces os.NewError with -errors.New, -giving errors a more central place in the environment. -

- -

-So the widely-used String method does not cause accidental satisfaction -of the error interface, the error interface uses instead -the name Error for that method: -

- -
-    type error interface {
-        Error() string
-    }
-
- -

-The fmt library automatically invokes Error, as it already -does for String, for easy printing of error values. -

- -{{code "progs/go1.go" `/START ERROR EXAMPLE/` `/END ERROR EXAMPLE/`}} - -

-All standard packages have been updated to use the new interface; the old os.Error is gone. -

- -

-A new package, errors, contains the function -

- -
-func New(text string) error
-
- -

-to turn a string into an error. It replaces the old os.NewError. -

- -{{code "progs/go1.go" `/ErrSyntax/`}} - -

-Updating: -Running go fix will update almost all code affected by the change. -Code that defines error types with a String method will need to be updated -by hand to rename the methods to Error. -

- -

System call errors

- -

-The old syscall package, which predated os.Error -(and just about everything else), -returned errors as int values. -In turn, the os package forwarded many of these errors, such -as EINVAL, but using a different set of errors on each platform. -This behavior was unpleasant and unportable. -

- -

-In Go 1, the -syscall -package instead returns an error for system call errors. -On Unix, the implementation is done by a -syscall.Errno type -that satisfies error and replaces the old os.Errno. -

- -

-The changes affecting os.EINVAL and relatives are -described elsewhere. - -

-Updating: -Running go fix will update almost all code affected by the change. -Regardless, most code should use the os package -rather than syscall and so will be unaffected. -

- -

Time

- -

-Time is always a challenge to support well in a programming language. -The old Go time package had int64 units, no -real type safety, -and no distinction between absolute times and durations. -

- -

-One of the most sweeping changes in the Go 1 library is therefore a -complete redesign of the -time package. -Instead of an integer number of nanoseconds as an int64, -and a separate *time.Time type to deal with human -units such as hours and years, -there are now two fundamental types: -time.Time -(a value, so the * is gone), which represents a moment in time; -and time.Duration, -which represents an interval. -Both have nanosecond resolution. -A Time can represent any time into the ancient -past and remote future, while a Duration can -span plus or minus only about 290 years. -There are methods on these types, plus a number of helpful -predefined constant durations such as time.Second. -

- -

-Among the new methods are things like -Time.Add, -which adds a Duration to a Time, and -Time.Sub, -which subtracts two Times to yield a Duration. -

- -

-The most important semantic change is that the Unix epoch (Jan 1, 1970) is now -relevant only for those functions and methods that mention Unix: -time.Unix -and the Unix -and UnixNano methods -of the Time type. -In particular, -time.Now -returns a time.Time value rather than, in the old -API, an integer nanosecond count since the Unix epoch. -

- -{{code "progs/go1.go" `/sleepUntil/` `/^}/`}} - -

-The new types, methods, and constants have been propagated through -all the standard packages that use time, such as os and -its representation of file time stamps. -

- -

-Updating: -The go fix tool will update many uses of the old time package to use the new -types and methods, although it does not replace values such as 1e9 -representing nanoseconds per second. -Also, because of type changes in some of the values that arise, -some of the expressions rewritten by the fix tool may require -further hand editing; in such cases the rewrite will include -the correct function or method for the old functionality, but -may have the wrong type or require further analysis. -

- -

Minor changes to the library

- -

-This section describes smaller changes, such as those to less commonly -used packages or that affect -few programs beyond the need to run go fix. -This category includes packages that are new in Go 1. -Collectively they improve portability, regularize behavior, and -make the interfaces more modern and Go-like. -

- -

The archive/zip package

- -

-In Go 1, *zip.Writer no -longer has a Write method. Its presence was a mistake. -

- -

-Updating: -What little code is affected will be caught by the compiler and must be updated by hand. -

- -

The bufio package

- -

-In Go 1, bufio.NewReaderSize -and -bufio.NewWriterSize -functions no longer return an error for invalid sizes. -If the argument size is too small or invalid, it is adjusted. -

- -

-Updating: -Running go fix will update calls that assign the error to _. -Calls that aren't fixed will be caught by the compiler and must be updated by hand. -

- -

The compress/flate, compress/gzip and compress/zlib packages

- -

-In Go 1, the NewWriterXxx functions in -compress/flate, -compress/gzip and -compress/zlib -all return (*Writer, error) if they take a compression level, -and *Writer otherwise. Package gzip's -Compressor and Decompressor types have been renamed -to Writer and Reader. Package flate's -WrongValueError type has been removed. -

- -

-Updating -Running go fix will update old names and calls that assign the error to _. -Calls that aren't fixed will be caught by the compiler and must be updated by hand. -

- -

The crypto/aes and crypto/des packages

- -

-In Go 1, the Reset method has been removed. Go does not guarantee -that memory is not copied and therefore this method was misleading. -

- -

-The cipher-specific types *aes.Cipher, *des.Cipher, -and *des.TripleDESCipher have been removed in favor of -cipher.Block. -

- -

-Updating: -Remove the calls to Reset. Replace uses of the specific cipher types with -cipher.Block. -

- -

The crypto/elliptic package

- -

-In Go 1, elliptic.Curve -has been made an interface to permit alternative implementations. The curve -parameters have been moved to the -elliptic.CurveParams -structure. -

- -

-Updating: -Existing users of *elliptic.Curve will need to change to -simply elliptic.Curve. Calls to Marshal, -Unmarshal and GenerateKey are now functions -in crypto/elliptic that take an elliptic.Curve -as their first argument. -

- -

The crypto/hmac package

- -

-In Go 1, the hash-specific functions, such as hmac.NewMD5, have -been removed from crypto/hmac. Instead, hmac.New takes -a function that returns a hash.Hash, such as md5.New. -

- -

-Updating: -Running go fix will perform the needed changes. -

- -

The crypto/x509 package

- -

-In Go 1, the -CreateCertificate -and -CreateCRL -functions in crypto/x509 have been altered to take an -interface{} where they previously took a *rsa.PublicKey -or *rsa.PrivateKey. This will allow other public key algorithms -to be implemented in the future. -

- -

-Updating: -No changes will be needed. -

- -

The encoding/binary package

- -

-In Go 1, the binary.TotalSize function has been replaced by -Size, -which takes an interface{} argument rather than -a reflect.Value. -

- -

-Updating: -What little code is affected will be caught by the compiler and must be updated by hand. -

- -

The encoding/xml package

- -

-In Go 1, the xml package -has been brought closer in design to the other marshaling packages such -as encoding/gob. -

- -

-The old Parser type is renamed -Decoder and has a new -Decode method. An -Encoder type was also introduced. -

- -

-The functions Marshal -and Unmarshal -work with []byte values now. To work with streams, -use the new Encoder -and Decoder types. -

- -

-When marshaling or unmarshaling values, the format of supported flags in -field tags has changed to be closer to the -json package -(`xml:"name,flag"`). The matching done between field tags, field -names, and the XML attribute and element names is now case-sensitive. -The XMLName field tag, if present, must also match the name -of the XML element being marshaled. -

- -

-Updating: -Running go fix will update most uses of the package except for some calls to -Unmarshal. Special care must be taken with field tags, -since the fix tool will not update them and if not fixed by hand they will -misbehave silently in some cases. For example, the old -"attr" is now written ",attr" while plain -"attr" remains valid but with a different meaning. -

- -

The expvar package

- -

-In Go 1, the RemoveAll function has been removed. -The Iter function and Iter method on *Map have -been replaced by -Do -and -(*Map).Do. -

- -

-Updating: -Most code using expvar will not need changing. The rare code that used -Iter can be updated to pass a closure to Do to achieve the same effect. -

- -

The flag package

- -

-In Go 1, the interface flag.Value has changed slightly. -The Set method now returns an error instead of -a bool to indicate success or failure. -

- -

-There is also a new kind of flag, Duration, to support argument -values specifying time intervals. -Values for such flags must be given units, just as time.Duration -formats them: 10s, 1h30m, etc. -

- -{{code "progs/go1.go" `/timeout/`}} - -

-Updating: -Programs that implement their own flags will need minor manual fixes to update their -Set methods. -The Duration flag is new and affects no existing code. -

- - -

The go/* packages

- -

-Several packages under go have slightly revised APIs. -

- -

-A concrete Mode type was introduced for configuration mode flags -in the packages -go/scanner, -go/parser, -go/printer, and -go/doc. -

- -

-The modes AllowIllegalChars and InsertSemis have been removed -from the go/scanner package. They were mostly -useful for scanning text other then Go source files. Instead, the -text/scanner package should be used -for that purpose. -

- -

-The ErrorHandler provided -to the scanner's Init method is -now simply a function rather than an interface. The ErrorVector type has -been removed in favor of the (existing) ErrorList -type, and the ErrorVector methods have been migrated. Instead of embedding -an ErrorVector in a client of the scanner, now a client should maintain -an ErrorList. -

- -

-The set of parse functions provided by the go/parser -package has been reduced to the primary parse function -ParseFile, and a couple of -convenience functions ParseDir -and ParseExpr. -

- -

-The go/printer package supports an additional -configuration mode SourcePos; -if set, the printer will emit //line comments such that the generated -output contains the original source code position information. The new type -CommentedNode can be -used to provide comments associated with an arbitrary -ast.Node (until now only -ast.File carried comment information). -

- -

-The type names of the go/doc package have been -streamlined by removing the Doc suffix: PackageDoc -is now Package, ValueDoc is Value, etc. -Also, all types now consistently have a Name field (or Names, -in the case of type Value) and Type.Factories has become -Type.Funcs. -Instead of calling doc.NewPackageDoc(pkg, importpath), -documentation for a package is created with: -

- -
-    doc.New(pkg, importpath, mode)
-
- -

-where the new mode parameter specifies the operation mode: -if set to AllDecls, all declarations -(not just exported ones) are considered. -The function NewFileDoc was removed, and the function -CommentText has become the method -Text of -ast.CommentGroup. -

- -

-In package go/token, the -token.FileSet method Files -(which originally returned a channel of *token.Files) has been replaced -with the iterator Iterate that -accepts a function argument instead. -

- -

-In package go/build, the API -has been nearly completely replaced. -The package still computes Go package information -but it does not run the build: the Cmd and Script -types are gone. -(To build code, use the new -go command instead.) -The DirInfo type is now named -Package. -FindTree and ScanDir are replaced by -Import -and -ImportDir. -

- -

-Updating: -Code that uses packages in go will have to be updated by hand; the -compiler will reject incorrect uses. Templates used in conjunction with any of the -go/doc types may need manual fixes; the renamed fields will lead -to run-time errors. -

- -

The hash package

- -

-In Go 1, the definition of hash.Hash includes -a new method, BlockSize. This new method is used primarily in the -cryptographic libraries. -

- -

-The Sum method of the -hash.Hash interface now takes a -[]byte argument, to which the hash value will be appended. -The previous behavior can be recreated by adding a nil argument to the call. -

- -

-Updating: -Existing implementations of hash.Hash will need to add a -BlockSize method. Hashes that process the input one byte at -a time can implement BlockSize to return 1. -Running go fix will update calls to the Sum methods of the various -implementations of hash.Hash. -

- -

-Updating: -Since the package's functionality is new, no updating is necessary. -

- -

The http package

- -

-In Go 1 the http package is refactored, -putting some of the utilities into a -httputil subdirectory. -These pieces are only rarely needed by HTTP clients. -The affected items are: -

- -
    -
  • ClientConn
    • -
  • DumpRequest
    • -
  • DumpRequest
    • -
  • DumpRequestOut
    • -
  • DumpResponse
    • -
  • NewChunkedReader
    • -
  • NewChunkedWriter
    • -
  • NewClientConn
    • -
  • NewProxyClientConn
    • -
  • NewServerConn
    • -
  • NewSingleHostReverseProxy
    • -
  • ReverseProxy
    • -
  • ServerConn
    • -
- -

-The Request.RawURL field has been removed; it was a -historical artifact. -

- -

-The Handle and HandleFunc -functions, and the similarly-named methods of ServeMux, -now panic if an attempt is made to register the same pattern twice. -

- -

-Updating: -Running go fix will update the few programs that are affected except for -uses of RawURL, which must be fixed by hand. -

- -

The image package

- -

-The image package has had a number of -minor changes, rearrangements and renamings. -

- -

-Most of the color handling code has been moved into its own package, -image/color. -For the elements that moved, a symmetry arises; for instance, -each pixel of an -image.RGBA -is a -color.RGBA. -

- -

-The old image/ycbcr package has been folded, with some -renamings, into the -image -and -image/color -packages. -

- -

-The old image.ColorImage type is still in the image -package but has been renamed -image.Uniform, -while image.Tiled has been removed. -

- -

-This table lists the renamings. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
OldNew
image.Color color.Color
image.ColorModel color.Model
image.ColorModelFunc color.ModelFunc
image.PalettedColorModel color.Palette
image.RGBAColor color.RGBA
image.RGBA64Color color.RGBA64
image.NRGBAColor color.NRGBA
image.NRGBA64Color color.NRGBA64
image.AlphaColor color.Alpha
image.Alpha16Color color.Alpha16
image.GrayColor color.Gray
image.Gray16Color color.Gray16
image.RGBAColorModel color.RGBAModel
image.RGBA64ColorModel color.RGBA64Model
image.NRGBAColorModel color.NRGBAModel
image.NRGBA64ColorModel color.NRGBA64Model
image.AlphaColorModel color.AlphaModel
image.Alpha16ColorModel color.Alpha16Model
image.GrayColorModel color.GrayModel
image.Gray16ColorModel color.Gray16Model
ycbcr.RGBToYCbCr color.RGBToYCbCr
ycbcr.YCbCrToRGB color.YCbCrToRGB
ycbcr.YCbCrColorModel color.YCbCrModel
ycbcr.YCbCrColor color.YCbCr
ycbcr.YCbCr image.YCbCr
ycbcr.SubsampleRatio444 image.YCbCrSubsampleRatio444
ycbcr.SubsampleRatio422 image.YCbCrSubsampleRatio422
ycbcr.SubsampleRatio420 image.YCbCrSubsampleRatio420
image.ColorImage image.Uniform
- -

-The image package's New functions -(NewRGBA, -NewRGBA64, etc.) -take an image.Rectangle as an argument -instead of four integers. -

- -

-Finally, there are new predefined color.Color variables -color.Black, -color.White, -color.Opaque -and -color.Transparent. -

- -

-Updating: -Running go fix will update almost all code affected by the change. -

- -

The log/syslog package

- -

-In Go 1, the syslog.NewLogger -function returns an error as well as a log.Logger. -

- -

-Updating: -What little code is affected will be caught by the compiler and must be updated by hand. -

- -

The mime package

- -

-In Go 1, the FormatMediaType function -of the mime package has been simplified to make it -consistent with -ParseMediaType. -It now takes "text/html" rather than "text" and "html". -

- -

-Updating: -What little code is affected will be caught by the compiler and must be updated by hand. -

- -

The net package

- -

-In Go 1, the various SetTimeout, -SetReadTimeout, and SetWriteTimeout methods -have been replaced with -SetDeadline, -SetReadDeadline, and -SetWriteDeadline, -respectively. Rather than taking a timeout value in nanoseconds that -apply to any activity on the connection, the new methods set an -absolute deadline (as a time.Time value) after which -reads and writes will time out and no longer block. -

- -

-There are also new functions -net.DialTimeout -to simplify timing out dialing a network address and -net.ListenMulticastUDP -to allow multicast UDP to listen concurrently across multiple listeners. -The net.ListenMulticastUDP function replaces the old -JoinGroup and LeaveGroup methods. -

- -

-Updating: -Code that uses the old methods will fail to compile and must be updated by hand. -The semantic change makes it difficult for the fix tool to update automatically. -

- -

The os package

- -

-The Time function has been removed; callers should use -the Time type from the -time package. -

- -

-The Exec function has been removed; callers should use -Exec from the syscall package, where available. -

- -

-The ShellExpand function has been renamed to ExpandEnv. -

- -

-The NewFile function -now takes a uintptr fd, instead of an int. -The Fd method on files now -also returns a uintptr. -

- -

-There are no longer error constants such as EINVAL -in the os package, since the set of values varied with -the underlying operating system. There are new portable functions like -IsPermission -to test common error properties, plus a few new error values -with more Go-like names, such as -ErrPermission -and -ErrNoEnv. -

- -

-The Getenverror function has been removed. To distinguish -between a non-existent environment variable and an empty string, -use os.Environ or -syscall.Getenv. -

- - -

-The Process.Wait method has -dropped its option argument and the associated constants are gone -from the package. -Also, the function Wait is gone; only the method of -the Process type persists. -

- -

-The Waitmsg type returned by -Process.Wait -has been replaced with a more portable -ProcessState -type with accessor methods to recover information about the -process. -Because of changes to Wait, the ProcessState -value always describes an exited process. -Portability concerns simplified the interface in other ways, but the values returned by the -ProcessState.Sys and -ProcessState.SysUsage -methods can be type-asserted to underlying system-specific data structures such as -syscall.WaitStatus and -syscall.Rusage on Unix. -

- -

-Updating: -Running go fix will drop a zero argument to Process.Wait. -All other changes will be caught by the compiler and must be updated by hand. -

- -

The os.FileInfo type

- -

-Go 1 redefines the os.FileInfo type, -changing it from a struct to an interface: -

- -
-    type FileInfo interface {
-        Name() string       // base name of the file
-        Size() int64        // length in bytes
-        Mode() FileMode     // file mode bits
-        ModTime() time.Time // modification time
-        IsDir() bool        // abbreviation for Mode().IsDir()
-        Sys() interface{}   // underlying data source (can return nil)
-    }
-
- -

-The file mode information has been moved into a subtype called -os.FileMode, -a simple integer type with IsDir, Perm, and String -methods. -

- -

-The system-specific details of file modes and properties such as (on Unix) -i-number have been removed from FileInfo altogether. -Instead, each operating system's os package provides an -implementation of the FileInfo interface, which -has a Sys method that returns the -system-specific representation of file metadata. -For instance, to discover the i-number of a file on a Unix system, unpack -the FileInfo like this: -

- -
-    fi, err := os.Stat("hello.go")
-    if err != nil {
-        log.Fatal(err)
-    }
-    // Check that it's a Unix file.
-    unixStat, ok := fi.Sys().(*syscall.Stat_t)
-    if !ok {
-        log.Fatal("hello.go: not a Unix file")
-    }
-    fmt.Printf("file i-number: %d\n", unixStat.Ino)
-
- -

-Assuming (which is unwise) that "hello.go" is a Unix file, -the i-number expression could be contracted to -

- -
-    fi.Sys().(*syscall.Stat_t).Ino
-
- -

-The vast majority of uses of FileInfo need only the methods -of the standard interface. -

- -

-The os package no longer contains wrappers for the POSIX errors -such as ENOENT. -For the few programs that need to verify particular error conditions, there are -now the boolean functions -IsExist, -IsNotExist -and -IsPermission. -

- -{{code "progs/go1.go" `/os\.Open/` `/}/`}} - -

-Updating: -Running go fix will update code that uses the old equivalent of the current os.FileInfo -and os.FileMode API. -Code that needs system-specific file details will need to be updated by hand. -Code that uses the old POSIX error values from the os package -will fail to compile and will also need to be updated by hand. -

- -

The os/signal package

- -

-The os/signal package in Go 1 replaces the -Incoming function, which returned a channel -that received all incoming signals, -with the selective Notify function, which asks -for delivery of specific signals on an existing channel. -

- -

-Updating: -Code must be updated by hand. -A literal translation of -

-
-c := signal.Incoming()
-
-

-is -

-
-c := make(chan os.Signal)
-signal.Notify(c) // ask for all signals
-
-

-but most code should list the specific signals it wants to handle instead: -

-
-c := make(chan os.Signal)
-signal.Notify(c, syscall.SIGHUP, syscall.SIGQUIT)
-
- -

The path/filepath package

- -

-In Go 1, the Walk function of the -path/filepath package -has been changed to take a function value of type -WalkFunc -instead of a Visitor interface value. -WalkFunc unifies the handling of both files and directories. -

- -
-    type WalkFunc func(path string, info os.FileInfo, err error) error
-
- -

-The WalkFunc function will be called even for files or directories that could not be opened; -in such cases the error argument will describe the failure. -If a directory's contents are to be skipped, -the function should return the value filepath.SkipDir -

- -{{code "progs/go1.go" `/STARTWALK/` `/ENDWALK/`}} - -

-Updating: -The change simplifies most code but has subtle consequences, so affected programs -will need to be updated by hand. -The compiler will catch code using the old interface. -

- -

The regexp package

- -

-The regexp package has been rewritten. -It has the same interface but the specification of the regular expressions -it supports has changed from the old "egrep" form to that of -RE2. -

- -

-Updating: -Code that uses the package should have its regular expressions checked by hand. -

- -

The runtime package

- -

-In Go 1, much of the API exported by package -runtime has been removed in favor of -functionality provided by other packages. -Code using the runtime.Type interface -or its specific concrete type implementations should -now use package reflect. -Code using runtime.Semacquire or runtime.Semrelease -should use channels or the abstractions in package sync. -The runtime.Alloc, runtime.Free, -and runtime.Lookup functions, an unsafe API created for -debugging the memory allocator, have no replacement. -

- -

-Before, runtime.MemStats was a global variable holding -statistics about memory allocation, and calls to runtime.UpdateMemStats -ensured that it was up to date. -In Go 1, runtime.MemStats is a struct type, and code should use -runtime.ReadMemStats -to obtain the current statistics. -

- -

-The package adds a new function, -runtime.NumCPU, that returns the number of CPUs available -for parallel execution, as reported by the operating system kernel. -Its value can inform the setting of GOMAXPROCS. -The runtime.Cgocalls and runtime.Goroutines functions -have been renamed to runtime.NumCgoCall and runtime.NumGoroutine. -

- -

-Updating: -Running go fix will update code for the function renamings. -Other code will need to be updated by hand. -

- -

The strconv package

- -

-In Go 1, the -strconv -package has been significantly reworked to make it more Go-like and less C-like, -although Atoi lives on (it's similar to -int(ParseInt(x, 10, 0)), as does -Itoa(x) (FormatInt(int64(x), 10)). -There are also new variants of some of the functions that append to byte slices rather than -return strings, to allow control over allocation. -

- -

-This table summarizes the renamings; see the -package documentation -for full details. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Old callNew call
Atob(x) ParseBool(x)
Atof32(x) ParseFloat(x, 32)§
Atof64(x) ParseFloat(x, 64)
AtofN(x, n) ParseFloat(x, n)
Atoi(x) Atoi(x)
Atoi(x) ParseInt(x, 10, 0)§
Atoi64(x) ParseInt(x, 10, 64)
Atoui(x) ParseUint(x, 10, 0)§
Atoi64(x) ParseInt(x, 10, 64)
Btoi64(x, b) ParseInt(x, b, 64)
Btoui64(x, b) ParseUint(x, b, 64)
Btoa(x) FormatBool(x)
Ftoa32(x, f, p) FormatFloat(float64(x), f, p, 32)
Ftoa64(x, f, p) FormatFloat(x, f, p, 64)
FtoaN(x, f, p, n) FormatFloat(x, f, p, n)
Itoa(x) Itoa(x)
Itoa(x) FormatInt(int64(x), 10)
Itoa64(x) FormatInt(x, 10)
Itob(x, b) FormatInt(int64(x), b)
Itob64(x, b) FormatInt(x, b)
Uitoa(x) FormatUint(uint64(x), 10)
Uitoa64(x) FormatUint(x, 10)
Uitob(x, b) FormatUint(uint64(x), b)
Uitob64(x, b) FormatUint(x, b)
- -

-Updating: -Running go fix will update almost all code affected by the change. -
-§ Atoi persists but Atoui and Atof32 do not, so -they may require -a cast that must be added by hand; the go fix tool will warn about it. -

- - -

The template packages

- -

-The template and exp/template/html packages have moved to -text/template and -html/template. -More significant, the interface to these packages has been simplified. -The template language is the same, but the concept of "template set" is gone -and the functions and methods of the packages have changed accordingly, -often by elimination. -

- -

-Instead of sets, a Template object -may contain multiple named template definitions, -in effect constructing -name spaces for template invocation. -A template can invoke any other template associated with it, but only those -templates associated with it. -The simplest way to associate templates is to parse them together, something -made easier with the new structure of the packages. -

- -

-Updating: -The imports will be updated by fix tool. -Single-template uses will be otherwise be largely unaffected. -Code that uses multiple templates in concert will need to be updated by hand. -The examples in -the documentation for text/template can provide guidance. -

- -

The testing package

- -

-The testing package has a type, B, passed as an argument to benchmark functions. -In Go 1, B has new methods, analogous to those of T, enabling -logging and failure reporting. -

- -{{code "progs/go1.go" `/func.*Benchmark/` `/^}/`}} - -

-Updating: -Existing code is unaffected, although benchmarks that use println -or panic should be updated to use the new methods. -

- -

The testing/script package

- -

-The testing/script package has been deleted. It was a dreg. -

- -

-Updating: -No code is likely to be affected. -

- -

The unsafe package

- -

-In Go 1, the functions -unsafe.Typeof, unsafe.Reflect, -unsafe.Unreflect, unsafe.New, and -unsafe.NewArray have been removed; -they duplicated safer functionality provided by -package reflect. -

- -

-Updating: -Code using these functions must be rewritten to use -package reflect. -The changes to encoding/gob and the protocol buffer library -may be helpful as examples. -

- -

The url package

- -

-In Go 1 several fields from the url.URL type -were removed or replaced. -

- -

-The String method now -predictably rebuilds an encoded URL string using all of URL's -fields as necessary. The resulting string will also no longer have -passwords escaped. -

- -

-The Raw field has been removed. In most cases the String -method may be used in its place. -

- -

-The old RawUserinfo field is replaced by the User -field, of type *net.Userinfo. -Values of this type may be created using the new net.User -and net.UserPassword -functions. The EscapeUserinfo and UnescapeUserinfo -functions are also gone. -

- -

-The RawAuthority field has been removed. The same information is -available in the Host and User fields. -

- -

-The RawPath field and the EncodedPath method have -been removed. The path information in rooted URLs (with a slash following the -schema) is now available only in decoded form in the Path field. -Occasionally, the encoded data may be required to obtain information that -was lost in the decoding process. These cases must be handled by accessing -the data the URL was built from. -

- -

-URLs with non-rooted paths, such as "mailto:dev@golang.org?subject=Hi", -are also handled differently. The OpaquePath boolean field has been -removed and a new Opaque string field introduced to hold the encoded -path for such URLs. In Go 1, the cited URL parses as: -

- -
-    URL{
-        Scheme: "mailto",
-        Opaque: "dev@golang.org",
-        RawQuery: "subject=Hi",
-    }
-
- -

-A new RequestURI method was -added to URL. -

- -

-The ParseWithReference function has been renamed to ParseWithFragment. -

- -

-Updating: -Code that uses the old fields will fail to compile and must be updated by hand. -The semantic changes make it difficult for the fix tool to update automatically. -

- -

The go command

- -

-Go 1 introduces the go command, a tool for fetching, -building, and installing Go packages and commands. The go command -does away with makefiles, instead using Go source code to find dependencies and -determine build conditions. Most existing Go programs will no longer require -makefiles to be built. -

- -

-See How to Write Go Code for a primer on the -go command and the go command documentation -for the full details. -

- -

-Updating: -Projects that depend on the Go project's old makefile-based build -infrastructure (Make.pkg, Make.cmd, and so on) should -switch to using the go command for building Go code and, if -necessary, rewrite their makefiles to perform any auxiliary build tasks. -

- -

The cgo command

- -

-In Go 1, the cgo command -uses a different _cgo_export.h -file, which is generated for packages containing //export lines. -The _cgo_export.h file now begins with the C preamble comment, -so that exported function definitions can use types defined there. -This has the effect of compiling the preamble multiple times, so a -package using //export must not put function definitions -or variable initializations in the C preamble. -

- -

Packaged releases

- diff --git a/src/cmd/godoc/doc.go b/src/cmd/godoc/doc.go index 32c046a3bb..4c83e2529b 100644 --- a/src/cmd/godoc/doc.go +++ b/src/cmd/godoc/doc.go @@ -87,6 +87,9 @@ The flags are: directory containing alternate template files; if set, the directory may provide alternative template files for the files in $GOROOT/lib/godoc + -url=path + print to standard output the data that would be served by + an HTTP request for path -zip="" zip file providing the file system to serve; disabled if empty diff --git a/src/cmd/godoc/godoc.go b/src/cmd/godoc/godoc.go index 01b609b055..3a35073937 100644 --- a/src/cmd/godoc/godoc.go +++ b/src/cmd/godoc/godoc.go @@ -605,6 +605,23 @@ func serveHTMLDoc(w http.ResponseWriter, r *http.Request, abspath, relpath strin log.Printf("decoding metadata %s: %v", relpath, err) } + // evaluate as template if indicated + if meta.Template { + tmpl, err := template.New("main").Funcs(templateFuncs).Parse(string(src)) + if err != nil { + log.Printf("parsing template %s: %v", relpath, err) + serveError(w, r, relpath, err) + return + } + var buf bytes.Buffer + if err := tmpl.Execute(&buf, nil); err != nil { + log.Printf("executing template %s: %v", relpath, err) + serveError(w, r, relpath, err) + return + } + src = buf.Bytes() + } + // if it's the language spec, add tags to EBNF productions if strings.HasSuffix(abspath, "go_spec.html") { var buf bytes.Buffer @@ -1177,6 +1194,7 @@ func search(w http.ResponseWriter, r *http.Request) { type Metadata struct { Title string Subtitle string + Template bool // execute as template Path string // canonical path for this page filePath string // filesystem path relative to goroot } diff --git a/src/cmd/godoc/main.go b/src/cmd/godoc/main.go index 893f611e76..a1470204f9 100644 --- a/src/cmd/godoc/main.go +++ b/src/cmd/godoc/main.go @@ -38,6 +38,7 @@ import ( "log" "net/http" _ "net/http/pprof" // to serve /debug/pprof/* + "net/url" "os" pathpkg "path" "path/filepath" @@ -69,6 +70,7 @@ var ( // layout control html = flag.Bool("html", false, "print HTML in command-line mode") srcMode = flag.Bool("src", false, "print (exported) source in command-line mode") + urlFlag = flag.String("url", "", "print HTML for named URL") // command-line searches query = flag.Bool("q", false, "arguments are considered search queries") @@ -225,7 +227,7 @@ func main() { flag.Parse() // Check usage: either server and no args, command line and args, or index creation mode - if (*httpAddr != "") != (flag.NArg() == 0) && !*writeIndex { + if (*httpAddr != "" || *urlFlag != "") != (flag.NArg() == 0) && !*writeIndex { usage() } @@ -286,6 +288,44 @@ func main() { return } + // Print content that would be served at the URL *urlFlag. + if *urlFlag != "" { + registerPublicHandlers(http.DefaultServeMux) + // Try up to 10 fetches, following redirects. + urlstr := *urlFlag + for i := 0; i < 10; i++ { + // Prepare request. + u, err := url.Parse(urlstr) + if err != nil { + log.Fatal(err) + } + req := &http.Request{ + URL: u, + } + + // Invoke default HTTP handler to serve request + // to our buffering httpWriter. + w := &httpWriter{h: http.Header{}, code: 200} + http.DefaultServeMux.ServeHTTP(w, req) + + // Return data, error, or follow redirect. + switch w.code { + case 200: // ok + os.Stdout.Write(w.Bytes()) + return + case 301, 302, 303, 307: // redirect + redirect := w.h.Get("Location") + if redirect == "" { + log.Fatalf("HTTP %d without Location header", w.code) + } + urlstr = redirect + default: + log.Fatalf("HTTP error %d", w.code) + } + } + log.Fatalf("too many redirects") + } + if *httpAddr != "" { // HTTP server mode. var handler http.Handler = http.DefaultServeMux @@ -494,3 +534,13 @@ func main() { log.Printf("packageText.Execute: %s", err) } } + +// An httpWriter is an http.ResponseWriter writing to a bytes.Buffer. +type httpWriter struct { + bytes.Buffer + h http.Header + code int +} + +func (w *httpWriter) Header() http.Header { return w.h } +func (w *httpWriter) WriteHeader(code int) { w.code = code } diff --git a/doc/tmpltohtml.go b/src/cmd/godoc/template.go similarity index 77% rename from doc/tmpltohtml.go rename to src/cmd/godoc/template.go index 70745f4ddd..51b63a804f 100644 --- a/doc/tmpltohtml.go +++ b/src/cmd/godoc/template.go @@ -2,6 +2,12 @@ // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file. +// Template support for writing HTML documents. +// Documents that include Template: true in their +// metadata are executed as input to text/template. +// +// This file defines functions for those templates to invoke. + // The template uses the function "code" to inject program // source into the output by extracting code from files and // injecting them as HTML-escaped 
 blocks.
@@ -26,52 +32,26 @@
 package main
 
 import (
-	"flag"
 	"fmt"
-	"io/ioutil"
 	"log"
-	"os"
-	"path/filepath"
 	"regexp"
 	"strings"
 	"text/template"
 )
 
-func Usage() {
-	fmt.Fprintf(os.Stderr, "usage: tmpltohtml file\n")
-	os.Exit(2)
-}
+// Functions in this file panic on error, but the panic is recovered
+// to an error by 'code'.
 
 var templateFuncs = template.FuncMap{
-	"code":      code,
-	"donotedit": donotedit,
-}
-
-func main() {
-	flag.Usage = Usage
-	flag.Parse()
-	if len(flag.Args()) != 1 {
-		Usage()
-	}
-
-	// Read and parse the input.
-	name := flag.Arg(0)
-	tmpl := template.New(filepath.Base(name)).Funcs(templateFuncs)
-	if _, err := tmpl.ParseFiles(name); err != nil {
-		log.Fatal(err)
-	}
-
-	// Execute the template.
-	if err := tmpl.Execute(os.Stdout, 0); err != nil {
-		log.Fatal(err)
-	}
+	"code": code,
 }
 
-// contents reads a file by name and returns its contents as a string.
+// contents reads and returns the content of the named file
+// (from the virtual file system, so for example /doc refers to $GOROOT/doc).
 func contents(name string) string {
-	file, err := ioutil.ReadFile(name)
+	file, err := ReadFile(fs, name)
 	if err != nil {
-		log.Fatal(err)
+		log.Panic(err)
 	}
 	return string(file)
 }
@@ -87,17 +67,18 @@ func format(arg interface{}) string {
 		}
 		return fmt.Sprintf("%q", arg)
 	default:
-		log.Fatalf("unrecognized argument: %v type %T", arg, arg)
+		log.Panicf("unrecognized argument: %v type %T", arg, arg)
 	}
 	return ""
 }
 
-func donotedit() string {
-	// No editing please.
-	return fmt.Sprintf("\n", flag.Args()[0])
-}
+func code(file string, arg ...interface{}) (s string, err error) {
+	defer func() {
+		if r := recover(); r != nil {
+			err = fmt.Errorf("%v", r)
+		}
+	}()
 
-func code(file string, arg ...interface{}) (string, error) {
 	text := contents(file)
 	var command string
 	switch len(arg) {
@@ -129,13 +110,13 @@ func parseArg(arg interface{}, file string, max int) (ival int, sval string, isI
 	switch n := arg.(type) {
 	case int:
 		if n <= 0 || n > max {
-			log.Fatalf("%q:%d is out of range", file, n)
+			log.Panicf("%q:%d is out of range", file, n)
 		}
 		return n, "", true
 	case string:
 		return 0, n, false
 	}
-	log.Fatalf("unrecognized argument %v type %T", arg, arg)
+	log.Panicf("unrecognized argument %v type %T", arg, arg)
 	return
 }
 
@@ -160,7 +141,7 @@ func multipleLines(file, text string, arg1, arg2 interface{}) string {
 	if !isInt2 {
 		line2 = match(file, line1, lines, pattern2)
 	} else if line2 < line1 {
-		log.Fatalf("lines out of order for %q: %d %d", text, line1, line2)
+		log.Panicf("lines out of order for %q: %d %d", text, line1, line2)
 	}
 	for k := line1 - 1; k < line2; k++ {
 		if strings.HasSuffix(lines[k], "OMIT\n") {
@@ -177,7 +158,7 @@ func match(file string, start int, lines []string, pattern string) int {
 	// $ matches the end of the file.
 	if pattern == "$" {
 		if len(lines) == 0 {
-			log.Fatalf("%q: empty file", file)
+			log.Panicf("%q: empty file", file)
 		}
 		return len(lines)
 	}
@@ -185,15 +166,15 @@ func match(file string, start int, lines []string, pattern string) int {
 	if len(pattern) > 2 && pattern[0] == '/' && pattern[len(pattern)-1] == '/' {
 		re, err := regexp.Compile(pattern[1 : len(pattern)-1])
 		if err != nil {
-			log.Fatal(err)
+			log.Panic(err)
 		}
 		for i := start; i < len(lines); i++ {
 			if re.MatchString(lines[i]) {
 				return i + 1
 			}
 		}
-		log.Fatalf("%s: no match for %#q", file, pattern)
+		log.Panicf("%s: no match for %#q", file, pattern)
 	}
-	log.Fatalf("unrecognized pattern: %q", pattern)
+	log.Panicf("unrecognized pattern: %q", pattern)
 	return 0
 }