Skip to content

G
go
Commit a40065ac authored by Russ Cox's avatar Russ Cox
Browse files
Options

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
parent e38c5fb2
Hide whitespace changes
Inline Side-by-side
Showing with 199 additions and 7357 deletions
doc/Makefile
View file @ a40065ac
......@@ -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)
doc/articles/defer_panic_recover.html
View file @ a40065ac
<!--{
"Title": "Defer, Panic, and Recover"
"Title": "Defer, Panic, and Recover",
"Template": true
}-->
<!--
DO NOT EDIT: created by
tmpltohtml articles/defer_panic_recover.tmpl
-->
<p>
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:
</p>
<pre><!--{{code "progs/defer.go" `/func CopyFile/` `/STOP/`}}
-->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
}</pre>
{{code "/doc/progs/defer.go" `/func CopyFile/` `/STOP/`}}
<p>
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:
</p>
<pre><!--{{code "progs/defer2.go" `/func CopyFile/` `/STOP/`}}
-->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)
}</pre>
{{code "/doc/progs/defer2.go" `/func CopyFile/` `/STOP/`}}
<p>
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.
</p>
<pre><!--{{code "progs/defer.go" `/func a/` `/STOP/`}}
-->func a() {
i := 0
defer fmt.Println(i)
i++
return
}</pre>
{{code "/doc/progs/defer.go" `/func a/` `/STOP/`}}
<p>
2. <i>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":
</p>
<pre><!--{{code "progs/defer.go" `/func b/` `/STOP/`}}
-->func b() {
for i := 0; i &lt; 4; i++ {
defer fmt.Print(i)
}
}</pre>
{{code "/doc/progs/defer.go" `/func b/` `/STOP/`}}
<p>
3. <i>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 <i>after</i>
the surrounding function returns. Thus, this function returns 2:
</p>
<pre><!--{{code "progs/defer.go" `/func c/` `/STOP/`}}
-->func c() (i int) {
defer func() { i++ }()
return 1
}</pre>
{{code "/doc/progs/defer.go" `/func c/` `/STOP/`}}
<p>
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:
</p>
<pre><!--{{code "progs/defer2.go" `/package main/` `/STOP/`}}
-->package main
import &#34;fmt&#34;
func main() {
f()
fmt.Println(&#34;Returned normally from f.&#34;)
}
func f() {
defer func() {
if r := recover(); r != nil {
fmt.Println(&#34;Recovered in f&#34;, r)
}
}()
fmt.Println(&#34;Calling g.&#34;)
g(0)
fmt.Println(&#34;Returned normally from g.&#34;)
}
func g(i int) {
if i &gt; 3 {
fmt.Println(&#34;Panicking!&#34;)
panic(fmt.Sprintf(&#34;%v&#34;, i))
}
defer fmt.Println(&#34;Defer in g&#34;, i)
fmt.Println(&#34;Printing in g&#34;, i)
g(i + 1)
}</pre>
{{code "/doc/progs/defer2.go" `/package main/` `/STOP/`}}
<p>
The function g takes the int i, and panics if i is greater than 3, or else it
......
doc/articles/defer_panic_recover.tmpl deleted 100644 → 0
View file @ e38c5fb2
<!--{
"Title": "Defer, Panic, and Recover"
}-->
{{donotedit}}
<p>
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.
</p>
<p>
A <b>defer statement</b> 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.
</p>
<p>
For example, let's look at a function that opens two files and copies the
contents of one file to the other:
</p>
{{code "progs/defer.go" `/func CopyFile/` `/STOP/`}}
<p>
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:
</p>
{{code "progs/defer2.go" `/func CopyFile/` `/STOP/`}}
<p>
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 <i>will</i> be closed.
</p>
<p>
The behavior of defer statements is straightforward and predictable. There are
three simple rules:
</p>
<p>
1. <i>A deferred function's arguments are evaluated when the defer statement is
evaluated.</i>
</p>
<p>
In this example, the expression "i" is evaluated when the Println call is
deferred. The deferred call will print "0" after the function returns.
</p>
{{code "progs/defer.go" `/func a/` `/STOP/`}}
<p>
2. <i>Deferred function calls are executed in Last In First Out order
</i>after<i> the surrounding function returns.</i>
</p>
<p>
This function prints "3210":
</p>
{{code "progs/defer.go" `/func b/` `/STOP/`}}
<p>
3. <i>Deferred functions may read and assign to the returning function's named
return values.</i>
</p>
<p>
In this example, a deferred function increments the return value i <i>after</i>
the surrounding function returns. Thus, this function returns 2:
</p>
{{code "progs/defer.go" `/func c/` `/STOP/`}}
<p>
This is convenient for modifying the error return value of a function; we will
see an example of this shortly.
</p>
<p>
<b>Panic</b> is a built-in function that stops the ordinary flow of control and
begins <i>panicking</i>. 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.
</p>
<p>
<b>Recover</b> 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.
</p>
<p>
Here's an example program that demonstrates the mechanics of panic and defer:
</p>
{{code "progs/defer2.go" `/package main/` `/STOP/`}}
<p>
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.
</p>
<p>
The program will output:
</p>
<pre>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.</pre>
<p>
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:
</p>
<pre>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]</pre>
<p>
For a real-world example of <b>panic</b> and <b>recover</b>, see the
<a href="/pkg/encoding/json/">json package</a> 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
<a href="/src/pkg/encoding/json/decode.go">decode.go</a>).
</p>
<p>
The convention in the Go libraries is that even when a package uses panic
internally, its external API still presents explicit error return values.
</p>
<p>
Other uses of <b>defer</b> (beyond the file.Close() example given earlier)
include releasing a mutex:
</p>
<pre>mu.Lock()
defer mu.Unlock()</pre>
<p>
printing a footer:
</p>
<pre>printHeader()
defer printFooter()</pre>
<p>
and more.
</p>
<p>
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.
</p>
doc/articles/error_handling.html
View file @ a40065ac
<!--{
"Title": "Error Handling and Go"
"Title": "Error Handling and Go",
"Template": true
}-->
<!--
DO NOT EDIT: created by
tmpltohtml articles/error_handling.tmpl
-->
<p>
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 <code>os.Open</code> function
returns a non-nil <code>error</code> value when it fails to open a file.
</p>
<pre><!--{{code "progs/error.go" `/func Open/`}}
-->func Open(name string) (file *File, err error)</pre>
{{code "/doc/progs/error.go" `/func Open/`}}
<p>
The following code uses <code>os.Open</code> to open a file. If an error
occurs it calls <code>log.Fatal</code> to print the error message and stop.
</p>
<pre><!--{{code "progs/error.go" `/func openFile/` `/STOP/`}}
--> f, err := os.Open(&#34;filename.ext&#34;)
if err != nil {
log.Fatal(err)
}
// do something with the open *File f</pre>
{{code "/doc/progs/error.go" `/func openFile/` `/STOP/`}}
<p>
You can get a lot done in Go knowing just this about the <code>error</code>
......@@ -59,15 +50,7 @@ The most commonly-used <code>error</code> implementation is the
<a href="/pkg/errors/">errors</a> package's unexported <code>errorString</code> type.
</p>
<pre><!--{{code "progs/error.go" `/errorString/` `/STOP/`}}
-->// errorString is a trivial implementation of error.
type errorString struct {
s string
}
func (e *errorString) Error() string {
return e.s
}</pre>
{{code "/doc/progs/error.go" `/errorString/` `/STOP/`}}
<p>
You can construct one of these values with the <code>errors.New</code>
......@@ -75,23 +58,13 @@ function. It takes a string that it converts to an <code>errors.errorString</cod
and returns as an <code>error</code> value.
</p>
<pre><!--{{code "progs/error.go" `/New/` `/STOP/`}}
-->// New returns an error that formats as the given text.
func New(text string) error {
return &amp;errorString{text}
}</pre>
{{code "/doc/progs/error.go" `/New/` `/STOP/`}}
<p>
Here's how you might use <code>errors.New</code>:
</p>
<pre><!--{{code "progs/error.go" `/func Sqrt/` `/STOP/`}}
-->func Sqrt(f float64) (float64, error) {
if f &lt; 0 {
return 0, errors.New(&#34;math: square root of negative number&#34;)
}
// implementation
}</pre>
{{code "/doc/progs/error.go" `/func Sqrt/` `/STOP/`}}
<p>
A caller passing a negative argument to <code>Sqrt</code> receives a non-nil
......@@ -101,11 +74,7 @@ A caller passing a negative argument to <code>Sqrt</code> receives a non-nil
<code>Error</code> method, or by just printing it:
</p>
<pre><!--{{code "progs/error.go" `/func printErr/` `/STOP/`}}
--> f, err := Sqrt(-1)
if err != nil {
fmt.Println(err)
}</pre>
{{code "/doc/progs/error.go" `/func printErr/` `/STOP/`}}
<p>
The <a href="/pkg/fmt/">fmt</a> package formats an <code>error</code> value
......@@ -126,10 +95,7 @@ rules and returns it as an <code>error</code> created by
<code>errors.New</code>.
</p>
<pre><!--{{code "progs/error.go" `/fmtError/` `/STOP/`}}
--> if f &lt; 0 {
return 0, fmt.Errorf(&#34;math: square root of negative number %g&#34;, f)
}</pre>
{{code "/doc/progs/error.go" `/fmtError/` `/STOP/`}}
<p>
In many cases <code>fmt.Errorf</code> is good enough, but since
......@@ -143,12 +109,7 @@ argument passed to <code>Sqrt</code>. We can enable that by defining a new
error implementation instead of using <code>errors.errorString</code>:
</p>
<pre><!--{{code "progs/error.go" `/type NegativeSqrtError/` `/STOP/`}}
-->type NegativeSqrtError float64
func (f NegativeSqrtError) Error() string {
return fmt.Sprintf(&#34;math: square root of negative number %g&#34;, float64(f))
}</pre>
{{code "/doc/progs/error.go" `/type NegativeSqrtError/` `/STOP/`}}
<p>
A sophisticated caller can then use a
......@@ -164,13 +125,7 @@ As another example, the <a href="/pkg/encoding/json/">json</a> package specifies
returns when it encounters a syntax error parsing a JSON blob.
</p>
<pre><!--{{code "progs/error.go" `/type SyntaxError/` `/STOP/`}}
-->type SyntaxError struct {
msg string // description of error
Offset int64 // error occurred after reading Offset bytes
}
func (e *SyntaxError) Error() string { return e.msg }</pre>
{{code "/doc/progs/error.go" `/type SyntaxError/` `/STOP/`}}
<p>
The <code>Offset</code> 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:
</p>
<pre><!--{{code "progs/error.go" `/func decodeError/` `/STOP/`}}
--> if err := dec.Decode(&amp;val); err != nil {
if serr, ok := err.(*json.SyntaxError); ok {
line, col := findLine(f, serr.Offset)
return fmt.Errorf(&#34;%s:%d:%d: %v&#34;, f.Name(), line, col, err)
}
return err
}</pre>
{{code "/doc/progs/error.go" `/func decodeError/` `/STOP/`}}
<p>
(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.
</p>
<pre><!--{{code "progs/error.go" `/func netError/` `/STOP/`}}
--> if nerr, ok := err.(net.Error); ok &amp;&amp; nerr.Temporary() {
time.Sleep(1e9)
continue
}
if err != nil {
log.Fatal(err)
}</pre>
{{code "/doc/progs/error.go" `/func netError/` `/STOP/`}}
<p>
<b>Simplifying repetitive error handling</b>
......@@ -244,23 +185,7 @@ application with an HTTP handler that retrieves a record from the datastore and
formats it with a template.
</p>
<pre><!--{{code "progs/error2.go" `/func init/` `/STOP/`}}
-->func init() {
http.HandleFunc(&#34;/view&#34;, viewRecord)
}
func viewRecord(w http.ResponseWriter, r *http.Request) {
c := appengine.NewContext(r)
key := datastore.NewKey(c, &#34;Record&#34;, r.FormValue(&#34;id&#34;), 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)
}
}</pre>
{{code "/doc/progs/error2.go" `/func init/` `/STOP/`}}
<p>
This function handles errors returned by the <code>datastore.Get</code>
......@@ -276,23 +201,13 @@ To reduce the repetition we can define our own HTTP <code>appHandler</code>
type that includes an <code>error</code> return value:
</p>
<pre><!--{{code "progs/error3.go" `/type appHandler/`}}
-->type appHandler func(http.ResponseWriter, *http.Request) error</pre>
{{code "/doc/progs/error3.go" `/type appHandler/`}}
<p>
Then we can change our <code>viewRecord</code> function to return errors:
</p>
<pre><!--{{code "progs/error3.go" `/func viewRecord/` `/STOP/`}}
-->func viewRecord(w http.ResponseWriter, r *http.Request) error {
c := appengine.NewContext(r)
key := datastore.NewKey(c, &#34;Record&#34;, r.FormValue(&#34;id&#34;), 0, nil)
record := new(Record)
if err := datastore.Get(c, key, record); err != nil {
return err
}
return viewTemplate.Execute(w, record)
}</pre>
{{code "/doc/progs/error3.go" `/func viewRecord/` `/STOP/`}}
<p>
This is simpler than the original version, but the <a
......@@ -302,12 +217,7 @@ To fix this we can implement the <code>http.Handler</code> interface's
<code>ServeHTTP</code> method on <code>appHandler</code>:
</p>
<pre><!--{{code "progs/error3.go" `/ServeHTTP/` `/STOP/`}}
-->func (fn appHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
if err := fn(w, r); err != nil {
http.Error(w, err.Error(), 500)
}
}</pre>
{{code "/doc/progs/error3.go" `/ServeHTTP/` `/STOP/`}}
<p>
The <code>ServeHTTP</code> method calls the <code>appHandler</code> function
......@@ -323,10 +233,7 @@ Now when registering <code>viewRecord</code> with the http package we use the
<code>http.HandlerFunc</code>).
</p>
<pre><!--{{code "progs/error3.go" `/func init/` `/STOP/`}}
-->func init() {
http.Handle(&#34;/view&#34;, appHandler(viewRecord))
}</pre>
{{code "/doc/progs/error3.go" `/func init/` `/STOP/`}}
<p>
With this basic error handling infrastructure in place, we can make it more
......@@ -341,19 +248,13 @@ To do this we create an <code>appError</code> struct containing an
<code>error</code> and some other fields:
</p>
<pre><!--{{code "progs/error4.go" `/type appError/` `/STOP/`}}
-->type appError struct {
Error error
Message string
Code int
}</pre>
{{code "/doc/progs/error4.go" `/type appError/` `/STOP/`}}
<p>
Next we modify the appHandler type to return <code>*appError</code> values:
</p>
<pre><!--{{code "progs/error4.go" `/type appHandler/`}}
-->type appHandler func(http.ResponseWriter, *http.Request) *appError</pre>
{{code "/doc/progs/error4.go" `/type appHandler/`}}
<p>
(It's usually a mistake to pass back the concrete type of an error rather than
......@@ -369,33 +270,14 @@ status <code>Code</code> and log the full <code>Error</code> to the developer
console:
</p>
<pre><!--{{code "progs/error4.go" `/ServeHTTP/` `/STOP/`}}
-->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(&#34;%v&#34;, e.Error)
http.Error(w, e.Message, e.Code)
}
}</pre>
{{code "/doc/progs/error4.go" `/ServeHTTP/` `/STOP/`}}
<p>
Finally, we update <code>viewRecord</code> to the new function signature and
have it return more context when it encounters an error:
</p>
<pre><!--{{code "progs/error4.go" `/func viewRecord/` `/STOP/`}}
-->func viewRecord(w http.ResponseWriter, r *http.Request) *appError {
c := appengine.NewContext(r)
key := datastore.NewKey(c, &#34;Record&#34;, r.FormValue(&#34;id&#34;), 0, nil)
record := new(Record)
if err := datastore.Get(c, key, record); err != nil {
return &amp;appError{err, &#34;Record not found&#34;, 404}
}
if err := viewTemplate.Execute(w, record); err != nil {
return &amp;appError{err, &#34;Can&#39;t display record&#34;, 500}
}
return nil
}</pre>
{{code "/doc/progs/error4.go" `/func viewRecord/` `/STOP/`}}
<p>
This version of <code>viewRecord</code> is the same length as the original, but
......
doc/articles/error_handling.tmpl deleted 100644 → 0
View file @ e38c5fb2
<!--{
"Title": "Error Handling and Go"
}-->
{{donotedit}}
<p>
If you have written any Go code you have probably encountered the built-in
<code>error</code> type. Go code uses <code>error</code> values to
indicate an abnormal state. For example, the <code>os.Open</code> function
returns a non-nil <code>error</code> value when it fails to open a file.
</p>
{{code "progs/error.go" `/func Open/`}}
<p>
The following code uses <code>os.Open</code> to open a file. If an error
occurs it calls <code>log.Fatal</code> to print the error message and stop.
</p>
{{code "progs/error.go" `/func openFile/` `/STOP/`}}
<p>
You can get a lot done in Go knowing just this about the <code>error</code>
type, but in this article we'll take a closer look at <code>error</code> and
discuss some good practices for error handling in Go.
</p>
<p>
<b>The error type</b>
</p>
<p>
The <code>error</code> type is an interface type. An <code>error</code>
variable represents any value that can describe itself as a string. Here is the
interface's declaration:
</p>
<pre>type error interface {
Error() string
}</pre>
<p>
The <code>error</code> type, as with all built in types, is
<a href="/doc/go_spec.html#Predeclared_identifiers">predeclared</a> in the
<a href="/doc/go_spec.html#Blocks">universe block</a>.
</p>
<p>
The most commonly-used <code>error</code> implementation is the
<a href="/pkg/errors/">errors</a> package's unexported <code>errorString</code> type.
</p>
{{code "progs/error.go" `/errorString/` `/STOP/`}}
<p>
You can construct one of these values with the <code>errors.New</code>
function. It takes a string that it converts to an <code>errors.errorString</code>
and returns as an <code>error</code> value.
</p>
{{code "progs/error.go" `/New/` `/STOP/`}}
<p>
Here's how you might use <code>errors.New</code>:
</p>
{{code "progs/error.go" `/func Sqrt/` `/STOP/`}}
<p>
A caller passing a negative argument to <code>Sqrt</code> receives a non-nil
<code>error</code> value (whose concrete representation is an
<code>errors.errorString</code> value). The caller can access the error string
("math: square root of...") by calling the <code>error</code>'s
<code>Error</code> method, or by just printing it:
</p>
{{code "progs/error.go" `/func printErr/` `/STOP/`}}
<p>
The <a href="/pkg/fmt/">fmt</a> package formats an <code>error</code> value
by calling its <code>Error() string</code> method.
</p>
<p>
It is the error implementation's responsibility to summarize the context.
The error returned by <code>os.Open</code> formats as "open /etc/passwd:
permission denied," not just "permission denied." The error returned by our
<code>Sqrt</code> is missing information about the invalid argument.
</p>
<p>
To add that information, a useful function is the <code>fmt</code> package's
<code>Errorf</code>. It formats a string according to <code>Printf</code>'s
rules and returns it as an <code>error</code> created by
<code>errors.New</code>.
</p>
{{code "progs/error.go" `/fmtError/` `/STOP/`}}
<p>
In many cases <code>fmt.Errorf</code> is good enough, but since
<code>error</code> is an interface, you can use arbitrary data structures as
error values, to allow callers to inspect the details of the error.
</p>
<p>
For instance, our hypothetical callers might want to recover the invalid
argument passed to <code>Sqrt</code>. We can enable that by defining a new
error implementation instead of using <code>errors.errorString</code>:
</p>
{{code "progs/error.go" `/type NegativeSqrtError/` `/STOP/`}}
<p>
A sophisticated caller can then use a
<a href="/doc/go_spec.html#Type_assertions">type assertion</a> to check for a
<code>NegativeSqrtError</code> and handle it specially, while callers that just
pass the error to <code>fmt.Println</code> or <code>log.Fatal</code> will see
no change in behavior.
</p>
<p>
As another example, the <a href="/pkg/encoding/json/">json</a> package specifies a
<code>SyntaxError</code> type that the <code>json.Decode</code> function
returns when it encounters a syntax error parsing a JSON blob.
</p>
{{code "progs/error.go" `/type SyntaxError/` `/STOP/`}}
<p>
The <code>Offset</code> 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:
</p>
{{code "progs/error.go" `/func decodeError/` `/STOP/`}}
<p>
(This is a slightly simplified version of some
<a href="http://camlistore.org/code/?p=camlistore.git;a=blob;f=lib/go/camli/jsonconfig/eval.go#l68">actual code</a>
from the <a href="http://camlistore.org">Camlistore</a> project.)
</p>
<p>
The <code>error</code> interface requires only a <code>Error</code> method;
specific error implementations might have additional methods. For instance, the
<a href="/pkg/net/">net</a> package returns errors of type
<code>error</code>, following the usual convention, but some of the error
implementations have additional methods defined by the <code>net.Error</code>
interface:
</p>
<pre>package net
type Error interface {
error
Timeout() bool // Is the error a timeout?
Temporary() bool // Is the error temporary?
}</pre>
<p>
Client code can test for a <code>net.Error</code> 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.
</p>
{{code "progs/error.go" `/func netError/` `/STOP/`}}
<p>
<b>Simplifying repetitive error handling</b>
</p>
<p>
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.
</p>
<p>
Consider an <a href="http://code.google.com/appengine/docs/go/">App Engine</a>
application with an HTTP handler that retrieves a record from the datastore and
formats it with a template.
</p>
{{code "progs/error2.go" `/func init/` `/STOP/`}}
<p>
This function handles errors returned by the <code>datastore.Get</code>
function and <code>viewTemplate</code>'s <code>Execute</code> 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.
</p>
<p>
To reduce the repetition we can define our own HTTP <code>appHandler</code>
type that includes an <code>error</code> return value:
</p>
{{code "progs/error3.go" `/type appHandler/`}}
<p>
Then we can change our <code>viewRecord</code> function to return errors:
</p>
{{code "progs/error3.go" `/func viewRecord/` `/STOP/`}}
<p>
This is simpler than the original version, but the <a
href="/pkg/net/http/">http</a> package doesn't understand functions that return
<code>error</code>.
To fix this we can implement the <code>http.Handler</code> interface's
<code>ServeHTTP</code> method on <code>appHandler</code>:
</p>
{{code "progs/error3.go" `/ServeHTTP/` `/STOP/`}}
<p>
The <code>ServeHTTP</code> method calls the <code>appHandler</code> function
and displays the returned error (if any) to the user. Notice that the method's
receiver, <code>fn</code>, is a function. (Go can do that!) The method invokes
the function by calling the receiver in the expression <code>fn(w, r)</code>.
</p>
<p>
Now when registering <code>viewRecord</code> with the http package we use the
<code>Handle</code> function (instead of <code>HandleFunc</code>) as
<code>appHandler</code> is an <code>http.Handler</code> (not an
<code>http.HandlerFunc</code>).
</p>
{{code "progs/error3.go" `/func init/` `/STOP/`}}
<p>
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.
</p>
<p>
To do this we create an <code>appError</code> struct containing an
<code>error</code> and some other fields:
</p>
{{code "progs/error4.go" `/type appError/` `/STOP/`}}
<p>
Next we modify the appHandler type to return <code>*appError</code> values:
</p>
{{code "progs/error4.go" `/type appHandler/`}}
<p>
(It's usually a mistake to pass back the concrete type of an error rather than
<code>error</code>, for reasons to be discussed in another article, but
it's the right thing to do here because <code>ServeHTTP</code> is the only
place that sees the value and uses its contents.)
</p>
<p>
And make <code>appHandler</code>'s <code>ServeHTTP</code> method display the
<code>appError</code>'s <code>Message</code> to the user with the correct HTTP
status <code>Code</code> and log the full <code>Error</code> to the developer
console:
</p>
{{code "progs/error4.go" `/ServeHTTP/` `/STOP/`}}
<p>
Finally, we update <code>viewRecord</code> to the new function signature and
have it return more context when it encounters an error:
</p>
{{code "progs/error4.go" `/func viewRecord/` `/STOP/`}}
<p>
This version of <code>viewRecord</code> is the same length as the original, but
now each of those lines has specific meaning and we are providing a friendlier
user experience.
</p>
<p>
It doesn't end there; we can further improve the error handling in our
application. Some ideas:
</p>
<ul>
<li>give the error handler a pretty HTML template,
<li>make debugging easier by writing the stack trace to the HTTP response when
the user is an administrator,
<li>write a constructor function for <code>appError</code> that stores the
stack trace for easier debugging,
<li>recover from panics inside the <code>appHandler</code>, 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 <a href="defer_panic_recover.html">Defer, Panic, and Recover</a>
article for more details.
</ul>
<p>
<b>Conclusion</b>
</p>
<p>
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.
</p>
doc/articles/laws_of_reflection.html
View file @ a40065ac
<!--{
"Title": "The Laws of Reflection"
"Title": "The Laws of Reflection",
"Template": true
}-->
<!--
DO NOT EDIT: created by
tmpltohtml articles/laws_of_reflection.tmpl
-->
<p>
Reflection in computing is the
......@@ -36,11 +32,7 @@ exactly one type known and fixed at compile time: <code>int</code>,
and so on. If we declare
</p>
<pre><!--{{code "progs/interface.go" `/type MyInt/` `/STOP/`}}
-->type MyInt int
var i int
var j MyInt</pre>
{{code "/doc/progs/interface.go" `/type MyInt/` `/STOP/`}}
<p>
then <code>i</code> has type <code>int</code> and <code>j</code>
......@@ -60,16 +52,7 @@ interface's methods. A well-known pair of examples is
"http://golang.org/pkg/io/">io package</a>:
</p>
<pre><!--{{code "progs/interface.go" `/// Reader/` `/STOP/`}}
-->// 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)
}</pre>
{{code "/doc/progs/interface.go" `/// Reader/` `/STOP/`}}
<p>
Any type that implements a <code>Read</code> (or
......@@ -80,12 +63,7 @@ purposes of this discussion, that means that a variable of type
<code>Read</code> method:
</p>
<pre><!--{{code "progs/interface.go" `/func readers/` `/STOP/`}}
--> var r io.Reader
r = os.Stdin
r = bufio.NewReader(r)
r = new(bytes.Buffer)
// and so on</pre>
{{code "/doc/progs/interface.go" `/func readers/` `/STOP/`}}
<p>
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
</p>
<pre><!--{{code "progs/interface.go" `/func typeAssertions/` `/STOP/`}}
--> var r io.Reader
tty, err := os.OpenFile(&#34;/dev/tty&#34;, os.O_RDWR, 0)
if err != nil {
return nil, err
}
r = tty</pre>
{{code "/doc/progs/interface.go" `/func typeAssertions/` `/STOP/`}}
<p>
<code>r</code> 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:
</p>
<pre><!--{{code "progs/interface.go" `/var w io.Writer/` `/STOP/`}}
--> var w io.Writer
w = r.(io.Writer)</pre>
{{code "/doc/progs/interface.go" `/var w io.Writer/` `/STOP/`}}
<p>
The expression in this assignment is a type assertion; what it
......@@ -176,9 +146,7 @@ methods.
Continuing, we can do this:
</p>
<pre><!--{{code "progs/interface.go" `/var empty interface{}/` `/STOP/`}}
--> var empty interface{}
empty = w</pre>
{{code "/doc/progs/interface.go" `/var empty interface{}/` `/STOP/`}}
<p>
and our empty interface value <code>e</code> will again contain
......@@ -232,18 +200,7 @@ now.)
Let's start with <code>TypeOf</code>:
</p>
<pre><!--{{code "progs/interface2.go" `/package main/` `/STOP main/`}}
-->package main
import (
&#34;fmt&#34;
&#34;reflect&#34;
)
func main() {
var x float64 = 3.4
fmt.Println(&#34;type:&#34;, reflect.TypeOf(x))
}</pre>
{{code "/doc/progs/interface2.go" `/package main/` `/STOP main/`}}
<p>
This program prints
......@@ -281,9 +238,7 @@ value (from here on we'll elide the boilerplate and focus just on
the executable code):
</p>
<pre><!--{{code "progs/interface2.go" `/var x/` `/STOP/`}}
--> var x float64 = 3.4
fmt.Println(&#34;type:&#34;, reflect.TypeOf(x))</pre>
{{code "/doc/progs/interface2.go" `/var x/` `/STOP/`}}
<p>
prints
......@@ -307,12 +262,7 @@ on. Also methods on <code>Value</code> with names like
<code>int64</code> and <code>float64</code>) stored inside:
</p>
<pre><!--{{code "progs/interface2.go" `/START f1/` `/STOP/`}}
--> var x float64 = 3.4
v := reflect.ValueOf(x)
fmt.Println(&#34;type:&#34;, v.Type())
fmt.Println(&#34;kind is float64:&#34;, v.Kind() == reflect.Float64)
fmt.Println(&#34;value:&#34;, v.Float())</pre>
{{code "/doc/progs/interface2.go" `/START f1/` `/STOP/`}}
<p>
prints
......@@ -342,12 +292,7 @@ instance. That is, the <code>Int</code> method of
necessary to convert to the actual type involved:
</p>
<pre><!--{{code "progs/interface2.go" `/START f2/` `/STOP/`}}
--> var x uint8 = &#39;x&#39;
v := reflect.ValueOf(x)
fmt.Println(&#34;type:&#34;, v.Type()) // uint8.
fmt.Println(&#34;kind is uint8: &#34;, v.Kind() == reflect.Uint8) // true.
x = uint8(v.Uint()) // v.Uint returns a uint64.</pre>
{{code "/doc/progs/interface2.go" `/START f2/` `/STOP/`}}
<p>
The second property is that the <code>Kind</code> of a reflection
......@@ -356,10 +301,7 @@ reflection object contains a value of a user-defined integer type,
as in
</p>
<pre><!--{{code "progs/interface2.go" `/START f3/` `/STOP/`}}
--> type MyInt int
var x MyInt = 7
v := reflect.ValueOf(x)</pre>
{{code "/doc/progs/interface2.go" `/START f3/` `/STOP/`}}
<p>
the <code>Kind</code> of <code>v</code> is still
......@@ -395,9 +337,7 @@ func (v Value) Interface() interface{}
As a consequence we can say
</p>
<pre><!--{{code "progs/interface2.go" `/START f3b/` `/STOP/`}}
--> y := v.Interface().(float64) // y will have type float64.
fmt.Println(y)</pre>
{{code "/doc/progs/interface2.go" `/START f3b/` `/STOP/`}}
<p>
to print the <code>float64</code> value represented by the
......@@ -415,8 +355,7 @@ the <code>Interface</code> method to the formatted print
routine:
</p>
<pre><!--{{code "progs/interface2.go" `/START f3c/` `/STOP/`}}
--> fmt.Println(v.Interface())</pre>
{{code "/doc/progs/interface2.go" `/START f3c/` `/STOP/`}}
<p>
(Why not <code>fmt.Println(v)</code>? Because <code>v</code> is a
......@@ -425,8 +364,7 @@ Since our value is a <code>float64</code>, we can even use a
floating-point format if we want:
</p>
<pre><!--{{code "progs/interface2.go" `/START f3d/` `/STOP/`}}
--> fmt.Printf(&#34;value is %7.1e\n&#34;, v.Interface())</pre>
{{code "/doc/progs/interface2.go" `/START f3d/` `/STOP/`}}
<p>
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.
</p>
<pre><!--{{code "progs/interface2.go" `/START f4/` `/STOP/`}}
--> var x float64 = 3.4
v := reflect.ValueOf(x)
v.SetFloat(7.1) // Error: will panic.</pre>
{{code "/doc/progs/interface2.go" `/START f4/` `/STOP/`}}
<p>
If you run this code, it will panic with the cryptic message
......@@ -492,10 +427,7 @@ The <code>CanSet</code> method of <code>Value</code> reports the
settability of a <code>Value</code>; in our case,
</p>
<pre><!--{{code "progs/interface2.go" `/START f5/` `/STOP/`}}
--> var x float64 = 3.4
v := reflect.ValueOf(x)
fmt.Println(&#34;settability of v:&#34;, v.CanSet())</pre>
{{code "/doc/progs/interface2.go" `/START f5/` `/STOP/`}}
<p>
prints
......@@ -518,9 +450,7 @@ determined by whether the reflection object holds the original
item. When we say
</p>
<pre><!--{{code "progs/interface2.go" `/START f6/` `/STOP/`}}
--> var x float64 = 3.4
v := reflect.ValueOf(x)</pre>
{{code "/doc/progs/interface2.go" `/START f6/` `/STOP/`}}
<p>
we pass a <em>copy</em> of <code>x</code> to
......@@ -530,8 +460,7 @@ argument to <code>reflect.ValueOf</code> is a <em>copy</em> of
statement
</p>
<pre><!--{{code "progs/interface2.go" `/START f6b/` `/STOP/`}}
--> v.SetFloat(7.1)</pre>
{{code "/doc/progs/interface2.go" `/START f6b/` `/STOP/`}}
<p>
were allowed to succeed, it would not update <code>x</code>, even
......@@ -577,11 +506,7 @@ and then create a reflection value that points to it, called
<code>p</code>.
</p>
<pre><!--{{code "progs/interface2.go" `/START f7/` `/STOP/`}}
--> var x float64 = 3.4
p := reflect.ValueOf(&amp;x) // Note: take the address of x.
fmt.Println(&#34;type of p:&#34;, p.Type())
fmt.Println(&#34;settability of p:&#34;, p.CanSet())</pre>
{{code "/doc/progs/interface2.go" `/START f7/` `/STOP/`}}
<p>
The output so far is
......@@ -601,9 +526,7 @@ and save the result in a reflection <code>Value</code> called
<code>v</code>:
</p>
<pre><!--{{code "progs/interface2.go" `/START f7b/` `/STOP/`}}
--> v := p.Elem()
fmt.Println(&#34;settability of v:&#34;, v.CanSet())</pre>
{{code "/doc/progs/interface2.go" `/START f7b/` `/STOP/`}}
<p>
Now <code>v</code> is a settable reflection object, as the output
......@@ -620,10 +543,7 @@ and since it represents <code>x</code>, we are finally able to use
<code>x</code>:
</p>
<pre><!--{{code "progs/interface2.go" `/START f7c/` `/STOP/`}}
--> v.SetFloat(7.1)
fmt.Println(v.Interface())
fmt.Println(x)</pre>
{{code "/doc/progs/interface2.go" `/START f7c/` `/STOP/`}}
<p>
The output, as expected, is
......@@ -664,19 +584,7 @@ but the fields themselves are regular <code>reflect.Value</code>
objects.
</p>
<pre><!--{{code "progs/interface2.go" `/START f8/` `/STOP/`}}
--> type T struct {
A int
B string
}
t := T{23, &#34;skidoo&#34;}
s := reflect.ValueOf(&amp;t).Elem()
typeOfT := s.Type()
for i := 0; i &lt; s.NumField(); i++ {
f := s.Field(i)
fmt.Printf(&#34;%d: %s %s = %v\n&#34;, i,
typeOfT.Field(i).Name, f.Type(), f.Interface())
}</pre>
{{code "/doc/progs/interface2.go" `/START f8/` `/STOP/`}}
<p>
The output of this program is
......@@ -699,10 +607,7 @@ Because <code>s</code> contains a settable reflection object, we
can modify the fields of the structure.
</p>
<pre><!--{{code "progs/interface2.go" `/START f8b/` `/STOP/`}}
--> s.Field(0).SetInt(77)
s.Field(1).SetString(&#34;Sunset Strip&#34;)
fmt.Println(&#34;t is now&#34;, t)</pre>
{{code "/doc/progs/interface2.go" `/START f8b/` `/STOP/`}}
<p>
And here's the result:
......@@ -746,4 +651,4 @@ sending and receiving on channels, allocating memory, using slices
and maps, calling methods and functions &mdash; but this post is
long enough. We'll cover some of those topics in a later
article.
</p>
\ No newline at end of file
</p>
doc/articles/laws_of_reflection.tmpl deleted 100644 → 0
View file @ e38c5fb2
<!--{
"Title": "The Laws of Reflection"
}-->
{{donotedit}}
<p>
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.
</p>
<p>
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".
</p>
<p><b>Types and interfaces</b></p>
<p>
Because reflection builds on the type system, let's start with a
refresher about types in Go.
</p>
<p>
Go is statically typed. Every variable has a static type, that is,
exactly one type known and fixed at compile time: <code>int</code>,
<code>float32</code>, <code>*MyType</code>, <code>[]byte</code>,
and so on. If we declare
</p>
{{code "progs/interface.go" `/type MyInt/` `/STOP/`}}
<p>
then <code>i</code> has type <code>int</code> and <code>j</code>
has type <code>MyInt</code>. The variables <code>i</code> and
<code>j</code> have distinct static types and, although they have
the same underlying type, they cannot be assigned to one another
without a conversion.
</p>
<p>
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
<code>io.Reader</code> and <code>io.Writer</code>, the types
<code>Reader</code> and <code>Writer</code> from the <a href=
"http://golang.org/pkg/io/">io package</a>:
</p>
{{code "progs/interface.go" `/// Reader/` `/STOP/`}}
<p>
Any type that implements a <code>Read</code> (or
<code>Write</code>) method with this signature is said to implement
<code>io.Reader</code> (or <code>io.Writer</code>). For the
purposes of this discussion, that means that a variable of type
<code>io.Reader</code> can hold any value whose type has a
<code>Read</code> method:
</p>
{{code "progs/interface.go" `/func readers/` `/STOP/`}}
<p>
It's important to be clear that whatever concrete value
<code>r</code> may hold, <code>r</code>'s type is always
<code>io.Reader</code>: Go is statically typed and the static type
of <code>r</code> is <code>io.Reader</code>.</p>
<p>
An extremely important example of an interface type is the empty
interface:
</p>
<pre>
interface{}
</pre>
<p>
It represents the empty set of methods and is satisfied by any
value at all, since any value has zero or more methods.
</p>
<p>
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.
</p>
<p>
We need to be precise about all this because reflection and
interfaces are closely related.
</p>
<p><b>The representation of an interface</b></p>
<p>
Russ Cox has written a <a href=
"http://research.swtch.com/2009/12/go-data-structures-interfaces.html">
detailed blog post</a> 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.
</p>
<p>
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
</p>
{{code "progs/interface.go" `/func typeAssertions/` `/STOP/`}}
<p>
<code>r</code> contains, schematically, the (value, type) pair,
(<code>tty</code>, <code>*os.File</code>). Notice that the type
<code>*os.File</code> implements methods other than
<code>Read</code>; even though the interface value provides access
only to the <code>Read</code> method, the value inside carries all
the type information about that value. That's why we can do things
like this:
</p>
{{code "progs/interface.go" `/var w io.Writer/` `/STOP/`}}
<p>
The expression in this assignment is a type assertion; what it
asserts is that the item inside <code>r</code> also implements
<code>io.Writer</code>, and so we can assign it to <code>w</code>.
After the assignment, <code>w</code> will contain the pair
(<code>tty</code>, <code>*os.File</code>). That's the same pair as
was held in <code>r</code>. 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.
</p>
<p>
Continuing, we can do this:
</p>
{{code "progs/interface.go" `/var empty interface{}/` `/STOP/`}}
<p>
and our empty interface value <code>e</code> will again contain
that same pair, (<code>tty</code>, <code>*os.File</code>). That's
handy: an empty interface can hold any value and contains all the
information we could ever need about that value.
</p>
<p>
(We don't need a type assertion here because it's known statically
that <code>w</code> satisfies the empty interface. In the example
where we moved a value from a <code>Reader</code> to a
<code>Writer</code>, we needed to be explicit and use a type
assertion because <code>Writer</code>'s methods are not a
subset of <code>Reader</code>'s.)
</p>
<p>
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.
</p>
<p>
Now we're ready to reflect.
</p>
<p><b>The first law of reflection</b></p>
<p><b>1. Reflection goes from interface value to reflection object.</b></p>
<p>
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
<a href="http://golang.org/pkg/reflect">package reflect</a>:
<a href="http://golang.org/pkg/reflect/#Type">Type</a> and
<a href="http://golang.org/pkg/reflect/#Value">Value</a>. Those two types
give access to the contents of an interface variable, and two
simple functions, called <code>reflect.TypeOf</code> and
<code>reflect.ValueOf</code>, retrieve <code>reflect.Type</code>
and <code>reflect.Value</code> pieces out of an interface value.
(Also, from the <code>reflect.Value</code> it's easy to get
to the <code>reflect.Type</code>, but let's keep the
<code>Value</code> and <code>Type</code> concepts separate for
now.)
</p>
<p>
Let's start with <code>TypeOf</code>:
</p>
{{code "progs/interface2.go" `/package main/` `/STOP main/`}}
<p>
This program prints
</p>
<pre>
type: float64
</pre>
<p>
You might be wondering where the interface is here, since the
program looks like it's passing the <code>float64</code>
variable <code>x</code>, not an interface value, to
<code>reflect.TypeOf</code>. But it's there; as <a href=
"http://golang.org/pkg/reflect/#Type.TypeOf">godoc reports</a>, the
signature of <code>reflect.TypeOf</code> includes an empty
interface:
</p>
<pre>
// TypeOf returns the reflection Type of the value in the interface{}.
func TypeOf(i interface{}) Type
</pre>
<p>
When we call <code>reflect.TypeOf(x)</code>, <code>x</code> is
first stored in an empty interface, which is then passed as the
argument; <code>reflect.TypeOf</code> unpacks that empty interface
to recover the type information.
</p>
<p>
The <code>reflect.ValueOf</code> function, of course, recovers the
value (from here on we'll elide the boilerplate and focus just on
the executable code):
</p>
{{code "progs/interface2.go" `/var x/` `/STOP/`}}
<p>
prints
</p>
<pre>
value: &lt;float64 Value&gt;
</pre>
<p>
Both <code>reflect.Type</code> and <code>reflect.Value</code> have
lots of methods to let us examine and manipulate them. One
important example is that <code>Value</code> has a
<code>Type</code> method that returns the <code>Type</code> of a
<code>reflect.Value</code>. Another is that both <code>Type</code>
and <code>Value</code> have a <code>Kind</code> method that returns
a constant indicating what sort of item is stored:
<code>Uint</code>, <code>Float64</code>, <code>Slice</code>, and so
on. Also methods on <code>Value</code> with names like
<code>Int</code> and <code>Float</code> let us grab values (as
<code>int64</code> and <code>float64</code>) stored inside:
</p>
{{code "progs/interface2.go" `/START f1/` `/STOP/`}}
<p>
prints
</p>
<pre>
type: float64
kind is float64: true
value: 3.4
</pre>
<p>
There are also methods like <code>SetInt</code> and
<code>SetFloat</code> but to use them we need to understand
settability, the subject of the third law of reflection, discussed
below.
</p>
<p>
The reflection library has a couple of properties worth singling
out. First, to keep the API simple, the "getter" and "setter"
methods of <code>Value</code> operate on the largest type that can
hold the value: <code>int64</code> for all the signed integers, for
instance. That is, the <code>Int</code> method of
<code>Value</code> returns an <code>int64</code> and the
<code>SetInt</code> value takes an <code>int64</code>; it may be
necessary to convert to the actual type involved:
</p>
{{code "progs/interface2.go" `/START f2/` `/STOP/`}}
<p>
The second property is that the <code>Kind</code> 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
</p>
{{code "progs/interface2.go" `/START f3/` `/STOP/`}}
<p>
the <code>Kind</code> of <code>v</code> is still
<code>reflect.Int</code>, even though the static type of
<code>x</code> is <code>MyInt</code>, not <code>int</code>. In
other words, the <code>Kind</code> cannot discriminate an int from
a <code>MyInt</code> even though the <code>Type</code> can.
</p>
<p><b>The second law of reflection</b></p>
<p><b>2. Reflection goes from reflection object to interface
value.</b></p>
<p>
Like physical reflection, reflection in Go generates its own
inverse.
</p>
<p>
Given a <code>reflect.Value</code> we can recover an interface
value using the <code>Interface</code> method; in effect the method
packs the type and value information back into an interface
representation and returns the result:
</p>
<pre>
// Interface returns v's value as an interface{}.
func (v Value) Interface() interface{}
</pre>
<p>
As a consequence we can say
</p>
{{code "progs/interface2.go" `/START f3b/` `/STOP/`}}
<p>
to print the <code>float64</code> value represented by the
reflection object <code>v</code>.
</p>
<p>
We can do even better, though. The arguments to
<code>fmt.Println</code>, <code>fmt.Printf</code> and so on are all
passed as empty interface values, which are then unpacked by the
<code>fmt</code> package internally just as we have been doing in
the previous examples. Therefore all it takes to print the contents
of a <code>reflect.Value</code> correctly is to pass the result of
the <code>Interface</code> method to the formatted print
routine:
</p>
{{code "progs/interface2.go" `/START f3c/` `/STOP/`}}
<p>
(Why not <code>fmt.Println(v)</code>? Because <code>v</code> is a
<code>reflect.Value</code>; we want the concrete value it holds.)
Since our value is a <code>float64</code>, we can even use a
floating-point format if we want:
</p>
{{code "progs/interface2.go" `/START f3d/` `/STOP/`}}
<p>
and get in this case
</p>
<pre>
3.4e+00
</pre>
<p>
Again, there's no need to type-assert the result of
<code>v.Interface()</code> to <code>float64</code>; the empty
interface value has the concrete value's type information inside
and <code>Printf</code> will recover it.
</p>
<p>
In short, the <code>Interface</code> method is the inverse of the
<code>ValueOf</code> function, except that its result is always of
static type <code>interface{}</code>.
</p>
<p>
Reiterating: Reflection goes from interface values to reflection
objects and back again.
</p>
<p><b>The third law of reflection</b></p>
<p><b>3. To modify a reflection object, the value must be settable.</b></p>
<p>
The third law is the most subtle and confusing, but it's easy
enough to understand if we start from first principles.
</p>
<p>
Here is some code that does not work, but is worth studying.
</p>
{{code "progs/interface2.go" `/START f4/` `/STOP/`}}
<p>
If you run this code, it will panic with the cryptic message
</p>
<pre>
panic: reflect.Value.SetFloat using unaddressable value
</pre>
<p>
The problem is not that the value <code>7.1</code> is not
addressable; it's that <code>v</code> is not settable. Settability
is a property of a reflection <code>Value</code>, and not all
reflection <code>Values</code> have it.
</p>
<p>
The <code>CanSet</code> method of <code>Value</code> reports the
settability of a <code>Value</code>; in our case,
</p>
{{code "progs/interface2.go" `/START f5/` `/STOP/`}}
<p>
prints
</p>
<pre>
settability of v: false
</pre>
<p>
It is an error to call a <code>Set</code> method on an non-settable
<code>Value</code>. But what is settability?
</p>
<p>
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
</p>
{{code "progs/interface2.go" `/START f6/` `/STOP/`}}
<p>
we pass a <em>copy</em> of <code>x</code> to
<code>reflect.ValueOf</code>, so the interface value created as the
argument to <code>reflect.ValueOf</code> is a <em>copy</em> of
<code>x</code>, not <code>x</code> itself. Thus, if the
statement
</p>
{{code "progs/interface2.go" `/START f6b/` `/STOP/`}}
<p>
were allowed to succeed, it would not update <code>x</code>, even
though <code>v</code> looks like it was created from
<code>x</code>. Instead, it would update the copy of <code>x</code>
stored inside the reflection value and <code>x</code> itself would
be unaffected. That would be confusing and useless, so it is
illegal, and settability is the property used to avoid this
issue.
</p>
<p>
If this seems bizarre, it's not. It's actually a familiar situation
in unusual garb. Think of passing <code>x</code> to a
function:
</p>
<pre>
f(x)
</pre>
<p>
We would not expect <code>f</code> to be able to modify
<code>x</code> because we passed a copy of <code>x</code>'s value,
not <code>x</code> itself. If we want <code>f</code> to modify
<code>x</code> directly we must pass our function the address of
<code>x</code> (that is, a pointer to <code>x</code>):</p>
<p>
<code>f(&amp;x)</code>
</p>
<p>
This is straightforward and familiar, and reflection works the same
way. If we want to modify <code>x</code> by reflection, we must
give the reflection library a pointer to the value we want to
modify.
</p>
<p>
Let's do that. First we initialize <code>x</code> as usual
and then create a reflection value that points to it, called
<code>p</code>.
</p>
{{code "progs/interface2.go" `/START f7/` `/STOP/`}}
<p>
The output so far is
</p>
<pre>
type of p: *float64
settability of p: false
</pre>
<p>
The reflection object <code>p</code> isn't settable, but it's not
<code>p</code> we want to set, it's (in effect) <code>*p</code>. To
get to what <code>p</code> points to, we call the <code>Elem</code>
method of <code>Value</code>, which indirects through the pointer,
and save the result in a reflection <code>Value</code> called
<code>v</code>:
</p>
{{code "progs/interface2.go" `/START f7b/` `/STOP/`}}
<p>
Now <code>v</code> is a settable reflection object, as the output
demonstrates,
</p>
<pre>
settability of v: true
</pre>
<p>
and since it represents <code>x</code>, we are finally able to use
<code>v.SetFloat</code> to modify the value of
<code>x</code>:
</p>
{{code "progs/interface2.go" `/START f7c/` `/STOP/`}}
<p>
The output, as expected, is
</p>
<pre>
7.1
7.1
</pre>
<p>
Reflection can be hard to understand but it's doing exactly what
the language does, albeit through reflection <code>Types</code> and
<code>Values</code> 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.
</p>
<p><b>Structs</b></p>
<p>
In our previous example <code>v</code> 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.
</p>
<p>
Here's a simple example that analyzes a struct value,
<code>t</code>. We create the reflection object with the address of
the struct because we'll want to modify it later. Then we set
<code>typeOfT</code> to its type and iterate over the fields using
straightforward method calls (see
<a href="http://golang.org/pkg/reflect/">package reflect</a> for details).
Note that we extract the names of the fields from the struct type,
but the fields themselves are regular <code>reflect.Value</code>
objects.
</p>
{{code "progs/interface2.go" `/START f8/` `/STOP/`}}
<p>
The output of this program is
</p>
<pre>
0: A int = 23
1: B string = skidoo
</pre>
<p>
There's one more point about settability introduced in
passing here: the field names of <code>T</code> are upper case
(exported) because only exported fields of a struct are
settable.
</p>
<p>
Because <code>s</code> contains a settable reflection object, we
can modify the fields of the structure.
</p>
{{code "progs/interface2.go" `/START f8b/` `/STOP/`}}
<p>
And here's the result:
</p>
<pre>
t is now {77 Sunset Strip}
</pre>
<p>
If we modified the program so that <code>s</code> was created from
<code>t</code>, not <code>&amp;t</code>, the calls to
<code>SetInt</code> and <code>SetString</code> would fail as the
fields of <code>t</code> would not be settable.
</p>
<p><b>Conclusion</b></p>
<p>
Here again are the laws of reflection:
</p>
<ol>
<li>Reflection goes from interface value to reflection
object.</li>
<li>Reflection goes from reflection object to interface
value.</li>
<li>To modify a reflection object, the value must be settable.</li>
</ol>
<p>
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.
</p>
<p>
There's plenty more to reflection that we haven't covered &mdash;
sending and receiving on channels, allocating memory, using slices
and maps, calling methods and functions &mdash; but this post is
long enough. We'll cover some of those topics in a later
article.
</p>
\ No newline at end of file
doc/articles/slices_usage_and_internals.html
View file @ a40065ac
<!--{
"Title": "Slices: usage and internals"
"Title": "Slices: usage and internals",
"Template": true
}-->
<!--
DO NOT EDIT: created by
tmpltohtml articles/slices_usage_and_internals.tmpl
-->
<p>
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:
</p>
<pre><!--{{code "progs/slices.go" `/AppendByte/` `/STOP/`}}
-->func AppendByte(slice []byte, data ...byte) []byte {
m := len(slice)
n := m + len(data)
if n &gt; cap(slice) { // if necessary, reallocate
// allocate double what&#39;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
}</pre>
{{code "/doc/progs/slices.go" `/AppendByte/` `/STOP/`}}
<p>
One could use <code>AppendByte</code> like this:
......@@ -398,18 +381,7 @@ Since the zero value of a slice (<code>nil</code>) acts like a zero-length
slice, you can declare a slice variable and then append to it in a loop:
</p>
<pre><!--{{code "progs/slices.go" `/Filter/` `/STOP/`}}
-->// 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
}</pre>
{{code "/doc/progs/slices.go" `/Filter/` `/STOP/`}}
<p>
<b>A possible "gotcha"</b>
......@@ -428,13 +400,7 @@ searches it for the first group of consecutive numeric digits, returning them
as a new slice.
</p>
<pre><!--{{code "progs/slices.go" `/digit/` `/STOP/`}}
-->var digitRegexp = regexp.MustCompile(&#34;[0-9]+&#34;)
func FindDigits(filename string) []byte {
b, _ := ioutil.ReadFile(filename)
return digitRegexp.Find(b)
}</pre>
{{code "/doc/progs/slices.go" `/digit/` `/STOP/`}}
<p>
This code behaves as advertised, but the returned <code>[]byte</code> points
......@@ -449,14 +415,7 @@ To fix this problem one can copy the interesting data to a new slice before
returning it:
</p>
<pre><!--{{code "progs/slices.go" `/CopyDigits/` `/STOP/`}}
-->func CopyDigits(filename string) []byte {
b, _ := ioutil.ReadFile(filename)
b = digitRegexp.Find(b)
c := make([]byte, len(b))
copy(c, b)
return c
}</pre>
{{code "/doc/progs/slices.go" `/CopyDigits/` `/STOP/`}}
<p>
A more concise version of this function could be constructed by using
......
doc/articles/slices_usage_and_internals.tmpl deleted 100644 → 0
View file @ e38c5fb2
<!--{
"Title": "Slices: usage and internals"
}-->
{{donotedit}}
<p>
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.
</p>
<p>
<b>Arrays</b>
</p>
<p>
The slice type is an abstraction built on top of Go's array type, and so to
understand slices we must first understand arrays.
</p>
<p>
An array type definition specifies a length and an element type. For example,
the type <code>[4]int</code> represents an array of four integers. An array's
size is fixed; its length is part of its type (<code>[4]int</code> and
<code>[5]int</code> are distinct, incompatible types). Arrays can be indexed in
the usual way, so the expression <code>s[n]</code> accesses the <i>n</i>th
element:
</p>
<pre>
var a [4]int
a[0] = 1
i := a[0]
// i == 1
</pre>
<p>
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:
</p>
<pre>
// a[2] == 0, the zero value of the int type
</pre>
<p>
The in-memory representation of <code>[4]int</code> is just four integer values laid out sequentially:
</p>
<p>
<img src="slice-array.png">
</p>
<p>
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 <i>pointer</i> 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.
</p>
<p>
An array literal can be specified like so:
</p>
<pre>
b := [2]string{"Penn", "Teller"}
</pre>
<p>
Or, you can have the compiler count the array elements for you:
</p>
<pre>
b := [...]string{"Penn", "Teller"}
</pre>
<p>
In both cases, the type of <code>b</code> is <code>[2]string</code>.
</p>
<p>
<b>Slices</b>
</p>
<p>
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.
</p>
<p>
The type specification for a slice is <code>[]T</code>, where <code>T</code> is
the type of the elements of the slice. Unlike an array type, a slice type has
no specified length.
</p>
<p>
A slice literal is declared just like an array literal, except you leave out
the element count:
</p>
<pre>
letters := []string{"a", "b", "c", "d"}
</pre>
<p>
A slice can be created with the built-in function called <code>make</code>,
which has the signature,
</p>
<pre>
func make([]T, len, cap) []T
</pre>
<p>
where T stands for the element type of the slice to be created. The
<code>make</code> function takes a type, a length, and an optional capacity.
When called, <code>make</code> allocates an array and returns a slice that
refers to that array.
</p>
<pre>
var s []byte
s = make([]byte, 5, 5)
// s == []byte{0, 0, 0, 0, 0}
</pre>
<p>
When the capacity argument is omitted, it defaults to the specified length.
Here's a more succinct version of the same code:
</p>
<pre>
s := make([]byte, 5)
</pre>
<p>
The length and capacity of a slice can be inspected using the built-in
<code>len</code> and <code>cap</code> functions.
</p>
<pre>
len(s) == 5
cap(s) == 5
</pre>
<p>
The next two sections discuss the relationship between length and capacity.
</p>
<p>
The zero value of a slice is <code>nil</code>. The <code>len</code> and
<code>cap</code> functions will both return 0 for a nil slice.
</p>
<p>
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 <code>b[1:4]</code> creates a slice including elements
1 through 3 of <code>b</code> (the indices of the resulting slice will be 0
through 2).
</p>
<pre>
b := []byte{'g', 'o', 'l', 'a', 'n', 'g'}
// b[1:4] == []byte{'o', 'l', 'a'}, sharing the same storage as b
</pre>
<p>
The start and end indices of a slice expression are optional; they default to zero and the slice's length respectively:
</p>
<pre>
// b[:2] == []byte{'g', 'o'}
// b[2:] == []byte{'l', 'a', 'n', 'g'}
// b[:] == b
</pre>
<p>
This is also the syntax to create a slice given an array:
</p>
<pre>
x := [3]string{"Лайка", "Белка", "Стрелка"}
s := x[:] // a slice referencing the storage of x
</pre>
<p>
<b>Slice internals</b>
</p>
<p>
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).
</p>
<p>
<img src="slice-struct.png">
</p>
<p>
Our variable <code>s</code>, created earlier by <code>make([]byte, 5)</code>,
is structured like this:
</p>
<p>
<img src="slice-1.png">
</p>
<p>
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.
</p>
<p>
As we slice <code>s</code>, observe the changes in the slice data structure and
their relation to the underlying array:
</p>
<pre>
s = s[2:4]
</pre>
<p>
<img src="slice-2.png">
</p>
<p>
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 <i>elements</i> (not the
slice itself) of a re-slice modifies the elements of the original slice:
</p>
<pre>
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'}
</pre>
<p>
Earlier we sliced <code>s</code> to a length shorter than its capacity. We can
grow s to its capacity by slicing it again:
</p>
<pre>
s = s[:cap(s)]
</pre>
<p>
<img src="slice-3.png">
</p>
<p>
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.
</p>
<p>
<b>Growing slices (the copy and append functions)</b>
</p>
<p>
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 <code>s</code> by making a new slice,
<code>t</code>, copying the contents of <code>s</code> into <code>t</code>, and
then assigning the slice value <code>t</code> to <code>s</code>:
</p>
<pre>
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
</pre>
<p>
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.
</p>
<pre>
func copy(dst, src []T) int
</pre>
<p>
The <code>copy</code> function supports copying between slices of different
lengths (it will copy only up to the smaller number of elements). In addition,
<code>copy</code> can handle source and destination slices that share the same
underlying array, handling overlapping slices correctly.
</p>
<p>
Using <code>copy</code>, we can simplify the code snippet above:
</p>
<pre>
t := make([]byte, len(s), (cap(s)+1)*2)
copy(t, s)
s = t
</pre>
<p>
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:
</p>
{{code "progs/slices.go" `/AppendByte/` `/STOP/`}}
<p>
One could use <code>AppendByte</code> like this:
</p>
<pre>
p := []byte{2, 3, 5}
p = AppendByte(p, 7, 11, 13)
// p == []byte{2, 3, 5, 7, 11, 13}
</pre>
<p>
Functions like <code>AppendByte</code> 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.
</p>
<p>
But most programs don't need complete control, so Go provides a built-in
<code>append</code> function that's good for most purposes; it has the
signature
</p>
<pre>
func append(s []T, x ...T) []T
</pre>
<p>
The <code>append</code> function appends the elements <code>x</code> to the end
of the slice <code>s</code>, and grows the slice if a greater capacity is
needed.
</p>
<pre>
a := make([]int, 1)
// a == []int{0}
a = append(a, 1, 2, 3)
// a == []int{0, 1, 2, 3}
</pre>
<p>
To append one slice to another, use <code>...</code> to expand the second
argument to a list of arguments.
</p>
<pre>
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"}
</pre>
<p>
Since the zero value of a slice (<code>nil</code>) acts like a zero-length
slice, you can declare a slice variable and then append to it in a loop:
</p>
{{code "progs/slices.go" `/Filter/` `/STOP/`}}
<p>
<b>A possible "gotcha"</b>
</p>
<p>
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.
</p>
<p>
For example, this <code>FindDigits</code> function loads a file into memory and
searches it for the first group of consecutive numeric digits, returning them
as a new slice.
</p>
{{code "progs/slices.go" `/digit/` `/STOP/`}}
<p>
This code behaves as advertised, but the returned <code>[]byte</code> 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.
</p>
<p>
To fix this problem one can copy the interesting data to a new slice before
returning it:
</p>
{{code "progs/slices.go" `/CopyDigits/` `/STOP/`}}
<p>
A more concise version of this function could be constructed by using
<code>append</code>. This is left as an exercise for the reader.
</p>
<p>
<b>Further Reading</b>
</p>
<p>
<a href="/doc/effective_go.html">Effective Go</a> contains an
in-depth treatment of <a href="/doc/effective_go.html#slices">slices</a>
and <a href="/doc/effective_go.html#arrays">arrays</a>,
and the Go <a href="/doc/go_spec.html">language specification</a>
defines <a href="/doc/go_spec.html#Slice_types">slices</a> and their
<a href="/doc/go_spec.html#Length_and_capacity">associated</a>
<a href="/doc/go_spec.html#Making_slices_maps_and_channels">helper</a>
<a href="/doc/go_spec.html#Appending_and_copying_slices">functions</a>.
</p>
doc/effective_go.html
View file @ a40065ac
<!--{
"Title": "Effective Go"
"Title": "Effective Go",
"Template": true
}-->
<!--
DO NOT EDIT: created by
tmpltohtml effective_go.tmpl
-->
<h2 id="introduction">Introduction</h2>
......@@ -1693,47 +1689,13 @@ enumerator. Since <code>iota</code> can be part of an expression and
expressions can be implicitly repeated, it is easy to build intricate
sets of values.
</p>
<pre><!--{{code "progs/eff_bytesize.go" `/^type ByteSize/` `/^\)/`}}
-->type ByteSize float64
const (
_ = iota // ignore first value by assigning to blank identifier
KB ByteSize = 1 &lt;&lt; (10 * iota)
MB
GB
TB
PB
EB
ZB
YB
)</pre>
{{code "/doc/progs/eff_bytesize.go" `/^type ByteSize/` `/^\)/`}}
<p>
The ability to attach a method such as <code>String</code> to a
type makes it possible for such values to format themselves
automatically for printing, even as part of a general type.
</p>
<pre><!--{{code "progs/eff_bytesize.go" `/^func.*ByteSize.*String/` `/^}/`}}
-->func (b ByteSize) String() string {
switch {
case b &gt;= YB:
return fmt.Sprintf(&#34;%.2fYB&#34;, float64(b/YB))
case b &gt;= ZB:
return fmt.Sprintf(&#34;%.2fZB&#34;, float64(b/ZB))
case b &gt;= EB:
return fmt.Sprintf(&#34;%.2fEB&#34;, float64(b/EB))
case b &gt;= PB:
return fmt.Sprintf(&#34;%.2fPB&#34;, float64(b/PB))
case b &gt;= TB:
return fmt.Sprintf(&#34;%.2fTB&#34;, float64(b/TB))
case b &gt;= GB:
return fmt.Sprintf(&#34;%.2fGB&#34;, float64(b/GB))
case b &gt;= MB:
return fmt.Sprintf(&#34;%.2fMB&#34;, float64(b/MB))
case b &gt;= KB:
return fmt.Sprintf(&#34;%.2fKB&#34;, float64(b/KB))
}
return fmt.Sprintf(&#34;%.2fB&#34;, float64(b))
}</pre>
{{code "/doc/progs/eff_bytesize.go" `/^func.*ByteSize.*String/` `/^}/`}}
<p>
(The <code>float64</code> conversions prevent <code>Sprintf</code>
from recurring back through the <code>String</code> method for
......@@ -1879,32 +1841,7 @@ by the routines in package <code>sort</code> if it implements
and it could also have a custom formatter.
In this contrived example <code>Sequence</code> satisfies both.
</p>
<pre><!--{{code "progs/eff_sequence.go" `/^type/` "$"}}
-->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] &lt; 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 := &#34;[&#34;
for i, elem := range s {
if i &gt; 0 {
str += &#34; &#34;
}
str += fmt.Sprint(elem)
}
return str + &#34;]&#34;
}</pre>
{{code "/doc/progs/eff_sequence.go" `/^type/` "$"}}
<h3 id="conversions">Conversions</h3>
......@@ -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.
</p>
<pre><!--{{code "progs/eff_qr.go"}}
-->package main
import (
&#34;flag&#34;
&#34;log&#34;
&#34;net/http&#34;
&#34;text/template&#34;
)
var addr = flag.String(&#34;addr&#34;, &#34;:1718&#34;, &#34;http service address&#34;) // Q=17, R=18
var templ = template.Must(template.New(&#34;qr&#34;).Parse(templateStr))
func main() {
flag.Parse()
http.Handle(&#34;/&#34;, http.HandlerFunc(QR))
err := http.ListenAndServe(*addr, nil)
if err != nil {
log.Fatal(&#34;ListenAndServe:&#34;, err)
}
}
func QR(w http.ResponseWriter, req *http.Request) {
templ.Execute(w, req.FormValue(&#34;s&#34;))
}
const templateStr = `
&lt;html&gt;
&lt;head&gt;
&lt;title&gt;QR Link Generator&lt;/title&gt;
&lt;/head&gt;
&lt;body&gt;
{{if .}}
&lt;img src=&#34;http://chart.apis.google.com/chart?chs=300x300&amp;cht=qr&amp;choe=UTF-8&amp;chl={{urlquery .}}&#34; /&gt;
&lt;br&gt;
{{html .}}
&lt;br&gt;
&lt;br&gt;
{{end}}
&lt;form action=&#34;/&#34; name=f method=&#34;GET&#34;&gt;&lt;input maxLength=1024 size=70
name=s value=&#34;&#34; title=&#34;Text to QR Encode&#34;&gt;&lt;input type=submit
value=&#34;Show QR&#34; name=qr&gt;
&lt;/form&gt;
&lt;/body&gt;
&lt;/html&gt;
`</pre>
{{code "/doc/progs/eff_qr.go"}}
<p>
The pieces up to <code>main</code> 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 <code>templ.Execute</code>, in this case the
form value.
Within the template text (<code>templateStr</code>),
double-brace-delimited pieces denote template actions.
The piece from <code>{{if .}}</code>
to <code>{{end}}</code> executes only if the value of the current data item, called <code>.</code> (dot),
The piece from <code>{{html "{{if .}}"}}</code>
to <code>{{html "{{end}}"}}</code> executes only if the value of the current data item, called <code>.</code> (dot),
is non-empty.
That is, when the string is empty, this piece of the template is suppressed.
</p>
<p>
The snippet <code>{{urlquery .}}</code> says to process the data with the function
The snippet <code>{{html "{{urlquery .}}"}}</code> says to process the data with the function
<code>urlquery</code>, which sanitizes the query string
for safe display on the web page.
</p>
......
doc/effective_go.tmpl deleted 100644 → 0
View file @ e38c5fb2
<!--{
"Title": "Effective Go"
}-->
{{donotedit}}
<h2 id="introduction">Introduction</h2>
<p>
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&mdash;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.
</p>
<p>
This document gives tips for writing clear, idiomatic Go code.
It augments the <a href="/ref/spec">language specification</a>,
the <a href="http://tour.golang.org/">Tour of Go</a>,
and <a href="/doc/code.html">How to Write Go Code</a>,
all of which you
should read first.
</p>
<h3 id="examples">Examples</h3>
<p>
The <a href="/src/pkg/">Go package sources</a>
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.
</p>
<h2 id="formatting">Formatting</h2>
<p>
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.
</p>
<p>
With Go we take an unusual
approach and let the machine
take care of most formatting issues.
The <code>gofmt</code> program
(also available as <code>go fmt</code>, 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 <code>gofmt</code>; if the answer doesn't
seem right, rearrange your program (or file a bug about <code>gofmt</code>),
don't work around it.
</p>
<p>
As an example, there's no need to spend time lining up
the comments on the fields of a structure.
<code>Gofmt</code> will do that for you. Given the
declaration
</p>
<pre>
type T struct {
name string // name of the object
value int // its value
}
</pre>
<p>
<code>gofmt</code> will line up the columns:
</p>
<pre>
type T struct {
name string // name of the object
value int // its value
}
</pre>
<p>
All Go code in the standard packages has been formatted with <code>gofmt</code>.
</p>
<p>
Some formatting details remain. Very briefly,
</p>
<dl>
<dt>Indentation</dt>
<dd>We use tabs for indentation and <code>gofmt</code> emits them by default.
Use spaces only if you must.
</dd>
<dt>Line length</dt>
<dd>
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.
</dd>
<dt>Parentheses</dt>
<dd>
Go needs fewer parentheses: control structures (<code>if</code>,
<code>for</code>, <code>switch</code>) do not have parentheses in
their syntax.
Also, the operator precedence hierarchy is shorter and clearer, so
<pre>
x&lt;&lt;8 + y&lt;&lt;16
</pre>
means what the spacing implies.
</dd>
</dl>
<h2 id="commentary">Commentary</h2>
<p>
Go provides C-style <code>/* */</code> block comments
and C++-style <code>//</code> line comments.
Line comments are the norm;
block comments appear mostly as package comments and
are also useful to disable large swaths of code.
</p>
<p>
The program—and web server—<code>godoc</code> 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 <code>godoc</code> produces.
</p>
<p>
Every package should have a <i>package comment</i>, 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 <code>godoc</code> page and
should set up the detailed documentation that follows.
</p>
<pre>
/*
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
</pre>
<p>
If the package is simple, the package comment can be brief.
</p>
<pre>
// Package path implements utility routines for
// manipulating slash-separated filename paths.
</pre>
<p>
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&mdash;<code>godoc</code>, like <code>gofmt</code>,
takes care of that.
The comments are uninterpreted plain text, so HTML and other
annotations such as <code>_this_</code> will reproduce <i>verbatim</i> and should
not be used.
Depending on the context, <code>godoc</code> 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.
</p>
<p>
Inside a package, any comment immediately preceding a top-level declaration
serves as a <i>doc comment</i> for that declaration.
Every exported (capitalized) name in a program should
have a doc comment.
</p>
<p>
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.
</p>
<pre>
// 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) {
</pre>
<p>
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.
</p>
<pre>
// 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 ')'")
...
)
</pre>
<p>
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.
</p>
<pre>
var (
countLock sync.Mutex
inputCount uint32
outputCount uint32
errorCount uint32
)
</pre>
<h2 id="names">Names</h2>
<p>
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.
</p>
<h3 id="package-names">Package names</h3>
<p>
When a package is imported, the package name becomes an accessor for the
contents. After
</p>
<pre>
import "bytes"
</pre>
<p>
the importing package can talk about <code>bytes.Buffer</code>. 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 <i>a priori</i>.
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.
</p>
<p>
Another convention is that the package name is the base name of
its source directory;
the package in <code>src/pkg/encoding/base64</code>
is imported as <code>"encoding/base64"</code> but has name <code>base64</code>,
not <code>encoding_base64</code> and not <code>encodingBase64</code>.
</p>
<p>
The importer of a package will use the name to refer to its contents
(the <code>import .</code> 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 <code>bufio</code> package is called <code>Reader</code>,
not <code>BufReader</code>, because users see it as <code>bufio.Reader</code>,
which is a clear, concise name.
Moreover,
because imported entities are always addressed with their package name, <code>bufio.Reader</code>
does not conflict with <code>io.Reader</code>.
Similarly, the function to make new instances of <code>ring.Ring</code>&mdash;which
is the definition of a <em>constructor</em> in Go&mdash;would
normally be called <code>NewRing</code>, but since
<code>Ring</code> is the only type exported by the package, and since the
package is called <code>ring</code>, it's called just <code>New</code>,
which clients of the package see as <code>ring.New</code>.
Use the package structure to help you choose good names.
</p>
<p>
Another short example is <code>once.Do</code>;
<code>once.Do(setup)</code> reads well and would not be improved by
writing <code>once.DoOrWaitUntilDone(setup)</code>.
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.
</p>
<h3 id="Getters">Getters</h3>
<p>
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 <code>Get</code> into the getter's name. If you have a field called
<code>owner</code> (lower case, unexported), the getter method should be
called <code>Owner</code> (upper case, exported), not <code>GetOwner</code>.
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 <code>SetOwner</code>.
Both names read well in practice:
</p>
<pre>
owner := obj.Owner()
if owner != user {
obj.SetOwner(user)
}
</pre>
<h3 id="interface-names">Interface names</h3>
<p>
By convention, one-method interfaces are named by
the method name plus the -er suffix: <code>Reader</code>,
<code>Writer</code>, <code>Formatter</code> etc.
</p>
<p>
There are a number of such names and it's productive to honor them and the function
names they capture.
<code>Read</code>, <code>Write</code>, <code>Close</code>, <code>Flush</code>,
<code>String</code> 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 <code>String</code> not <code>ToString</code>.
</p>
<h3 id="mixed-caps">MixedCaps</h3>
<p>
Finally, the convention in Go is to use <code>MixedCaps</code>
or <code>mixedCaps</code> rather than underscores to write
multiword names.
</p>
<h2 id="semicolons">Semicolons</h2>
<p>
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.
</p>
<p>
The rule is this. If the last token before a newline is an identifier
(which includes words like <code>int</code> and <code>float64</code>),
a basic literal such as a number or string constant, or one of the
tokens
</p>
<pre>
break continue fallthrough return ++ -- ) }
</pre>
<p>
the lexer always inserts a semicolon after the token.
This could be summarized as, &ldquo;if the newline comes
after a token that could end a statement, insert a semicolon&rdquo;.
</p>
<p>
A semicolon can also be omitted immediately before a closing brace,
so a statement such as
</p>
<pre>
go func() { for { dst &lt;- &lt;-src } }()
</pre>
<p>
needs no semicolons.
Idiomatic Go programs have semicolons only in places such as
<code>for</code> 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.
</p>
<p>
One caveat. You should never put the opening brace of a
control structure (<code>if</code>, <code>for</code>, <code>switch</code>,
or <code>select</code>) on the next line. If you do, a semicolon
will be inserted before the brace, which could cause unwanted
effects. Write them like this
</p>
<pre>
if i &lt; f() {
g()
}
</pre>
<p>
not like this
</p>
<pre>
if i &lt; f() // wrong!
{ // wrong!
g()
}
</pre>
<h2 id="control-structures">Control structures</h2>
<p>
The control structures of Go are related to those of C but differ
in important ways.
There is no <code>do</code> or <code>while</code> loop, only a
slightly generalized
<code>for</code>;
<code>switch</code> is more flexible;
<code>if</code> and <code>switch</code> accept an optional
initialization statement like that of <code>for</code>;
and there are new control structures including a type switch and a
multiway communications multiplexer, <code>select</code>.
The syntax is also slightly different:
there are no parentheses
and the bodies must always be brace-delimited.
</p>
<h3 id="if">If</h3>
<p>
In Go a simple <code>if</code> looks like this:
</p>
<pre>
if x &gt; 0 {
return y
}
</pre>
<p>
Mandatory braces encourage writing simple <code>if</code> statements
on multiple lines. It's good style to do so anyway,
especially when the body contains a control statement such as a
<code>return</code> or <code>break</code>.
</p>
<p>
Since <code>if</code> and <code>switch</code> accept an initialization
statement, it's common to see one used to set up a local variable.
</p>
<pre>
if err := file.Chmod(0664); err != nil {
log.Print(err)
return err
}
</pre>
<p id="else">
In the Go libraries, you'll find that
when an <code>if</code> statement doesn't flow into the next statement—that is,
the body ends in <code>break</code>, <code>continue</code>,
<code>goto</code>, or <code>return</code>—the unnecessary
<code>else</code> is omitted.
</p>
<pre>
f, err := os.Open(name)
if err != nil {
return err
}
codeUsing(f)
</pre>
<p>
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 <code>return</code>
statements, the resulting code needs no <code>else</code> statements.
</p>
<pre>
f, err := os.Open(name)
if err != nil {
return err
}
d, err := f.Stat()
if err != nil {
f.Close()
return err
}
codeUsing(f, d)
</pre>
<h3 id="redeclaration">Redeclaration</h3>
<p>
An aside: The last example in the previous section demonstrates a detail of how the
<code>:=</code> short declaration form works.
The declaration that calls <code>os.Open</code> reads,
</p>
<pre>
f, err := os.Open(name)
</pre>
<p>
This statement declares two variables, <code>f</code> and <code>err</code>.
A few lines later, the call to <code>f.Stat</code> reads,
</p>
<pre>
d, err := f.Stat()
</pre>
<p>
which looks as if it declares <code>d</code> and <code>err</code>.
Notice, though, that <code>err</code> appears in both statements.
This duplication is legal: <code>err</code> is declared by the first statement,
but only <em>re-assigned</em> in the second.
This means that the call to <code>f.Stat</code> uses the existing
<code>err</code> variable declared above, and just gives it a new value.
</p>
<p>
In a <code>:=</code> declaration a variable <code>v</code> may appear even
if it has already been declared, provided:
</p>
<ul>
<li>this declaration is in the same scope as the existing declaration of <code>v</code>
(if <code>v</code> is already declared in an outer scope, the declaration will create a new variable),</li>
<li>the corresponding value in the initialization is assignable to <code>v</code>, and</li>
<li>there is at least one other variable in the declaration that is being declared anew.</li>
</ul>
<p>
This unusual property is pure pragmatism,
making it easy to use a single <code>err</code> value, for example,
in a long <code>if-else</code> chain.
You'll see it used often.
</p>
<h3 id="for">For</h3>
<p>
The Go <code>for</code> loop is similar to&mdash;but not the same as&mdash;C's.
It unifies <code>for</code>
and <code>while</code> and there is no <code>do-while</code>.
There are three forms, only one of which has semicolons.
</p>
<pre>
// Like a C for
for init; condition; post { }
// Like a C while
for condition { }
// Like a C for(;;)
for { }
</pre>
<p>
Short declarations make it easy to declare the index variable right in the loop.
</p>
<pre>
sum := 0
for i := 0; i &lt; 10; i++ {
sum += i
}
</pre>
<p>
If you're looping over an array, slice, string, or map,
or reading from a channel, a <code>range</code> clause can
manage the loop.
</p>
<pre>
var m map[string]int
sum := 0
for _, value := range m { // key is unused
sum += value
}
</pre>
<p>
For strings, the <code>range</code> 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
</p>
<pre>
for pos, char := range "日本語" {
fmt.Printf("character %c starts at byte position %d\n", char, pos)
}
</pre>
<p>
prints
</p>
<pre>
character 日 starts at byte position 0
character 本 starts at byte position 3
character 語 starts at byte position 6
</pre>
<p>
Finally, Go has no comma operator and <code>++</code> and <code>--</code>
are statements not expressions.
Thus if you want to run multiple variables in a <code>for</code>
you should use parallel assignment.
</p>
<pre>
// Reverse a
for i, j := 0, len(a)-1; i &lt; j; i, j = i+1, j-1 {
a[i], a[j] = a[j], a[i]
}
</pre>
<h3 id="switch">Switch</h3>
<p>
Go's <code>switch</code> 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 <code>switch</code> has no expression it switches on
<code>true</code>.
It's therefore possible&mdash;and idiomatic&mdash;to write an
<code>if</code>-<code>else</code>-<code>if</code>-<code>else</code>
chain as a <code>switch</code>.
</p>
<pre>
func unhex(c byte) byte {
switch {
case '0' &lt;= c &amp;&amp; c &lt;= '9':
return c - '0'
case 'a' &lt;= c &amp;&amp; c &lt;= 'f':
return c - 'a' + 10
case 'A' &lt;= c &amp;&amp; c &lt;= 'F':
return c - 'A' + 10
}
return 0
}
</pre>
<p>
There is no automatic fall through, but cases can be presented
in comma-separated lists.
<pre>
func shouldEscape(c byte) bool {
switch c {
case ' ', '?', '&amp;', '=', '#', '+', '%':
return true
}
return false
}
</pre>
<p>
Here's a comparison routine for byte arrays that uses two
<code>switch</code> statements:
<pre>
// Compare returns an integer comparing the two byte arrays
// lexicographically.
// The result will be 0 if a == b, -1 if a &lt; b, and +1 if a &gt; b
func Compare(a, b []byte) int {
for i := 0; i &lt; len(a) &amp;&amp; i &lt; len(b); i++ {
switch {
case a[i] &gt; b[i]:
return 1
case a[i] &lt; b[i]:
return -1
}
}
switch {
case len(a) &lt; len(b):
return -1
case len(a) &gt; len(b):
return 1
}
return 0
}
</pre>
<p>
A switch can also be used to discover the dynamic type of an interface
variable. Such a <em>type switch</em> uses the syntax of a type
assertion with the keyword <code>type</code> inside the parentheses.
If the switch declares a variable in the expression, the variable will
have the corresponding type in each clause.
</p>
<pre>
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)
}
</pre>
<h2 id="functions">Functions</h2>
<h3 id="multiple-returns">Multiple return values</h3>
<p>
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 <code>-1</code> for <code>EOF</code>)
and modifying an argument.
</p>
<p>
In C, a write error is signaled by a negative count with the
error code secreted away in a volatile location.
In Go, <code>Write</code>
can return a count <i>and</i> an error: &ldquo;Yes, you wrote some
bytes but not all of them because you filled the device&rdquo;.
The signature of <code>*File.Write</code> in package <code>os</code> is:
</p>
<pre>
func (file *File) Write(b []byte) (n int, err error)
</pre>
<p>
and as the documentation says, it returns the number of bytes
written and a non-nil <code>error</code> when <code>n</code>
<code>!=</code> <code>len(b)</code>.
This is a common style; see the section on error handling for more examples.
</p>
<p>
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.
</p>
<pre>
func nextInt(b []byte, i int) (int, int) {
for ; i &lt; len(b) &amp;&amp; !isDigit(b[i]); i++ {
}
x := 0
for ; i &lt; len(b) &amp;&amp; isDigit(b[i]); i++ {
x = x*10 + int(b[i])-'0'
}
return x, i
}
</pre>
<p>
You could use it to scan the numbers in an input array <code>a</code> like this:
</p>
<pre>
for i := 0; i &lt; len(a); {
x, i = nextInt(a, i)
fmt.Println(x)
}
</pre>
<h3 id="named-results">Named result parameters</h3>
<p>
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 <code>return</code> statement
with no arguments, the current values of the result parameters are
used as the returned values.
</p>
<p>
The names are not mandatory but they can make code shorter and clearer:
they're documentation.
If we name the results of <code>nextInt</code> it becomes
obvious which returned <code>int</code>
is which.
</p>
<pre>
func nextInt(b []byte, pos int) (value, nextPos int) {
</pre>
<p>
Because named results are initialized and tied to an unadorned return, they can simplify
as well as clarify. Here's a version
of <code>io.ReadFull</code> that uses them well:
</p>
<pre>
func ReadFull(r Reader, buf []byte) (n int, err error) {
for len(buf) &gt; 0 &amp;&amp; err == nil {
var nr int
nr, err = r.Read(buf)
n += nr
buf = buf[nr:]
}
return
}
</pre>
<h3 id="defer">Defer</h3>
<p>
Go's <code>defer</code> statement schedules a function call (the
<i>deferred</i> function) to be run immediately before the function
executing the <code>defer</code> 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.
</p>
<pre>
// 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.
}
</pre>
<p>
Deferring a call to a function such as <code>Close</code> 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.
</p>
<p>
The arguments to the deferred function (which include the receiver if
the function is a method) are evaluated when the <i>defer</i>
executes, not when the <i>call</i> 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.
</p>
<pre>
for i := 0; i &lt; 5; i++ {
defer fmt.Printf("%d ", i)
}
</pre>
<p>
Deferred functions are executed in LIFO order, so this code will cause
<code>4 3 2 1 0</code> 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:
</p>
<pre>
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....
}
</pre>
<p>
We can do better by exploiting the fact that arguments to deferred
functions are evaluated when the <code>defer</code> executes. The
tracing routine can set up the argument to the untracing routine.
This example:
</p>
<pre>
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()
}
</pre>
<p>
prints
</p>
<pre>
entering: b
in b
entering: a
in a
leaving: a
leaving: b
</pre>
<p>
For programmers accustomed to block-level resource management from
other languages, <code>defer</code> 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
<code>panic</code> and <code>recover</code> we'll see another
example of its possibilities.
</p>
<h2 id="data">Data</h2>
<h3 id="allocation_new">Allocation with <code>new</code></h3>
<p>
Go has two allocation primitives, the built-in functions
<code>new</code> and <code>make</code>.
They do different things and apply to different types, which can be confusing,
but the rules are simple.
Let's talk about <code>new</code> first.
It's a built-in function that allocates memory, but unlike its namesakes
in some other languages it does not <em>initialize</em> the memory,
it only <em>zeroes</em> it.
That is,
<code>new(T)</code> allocates zeroed storage for a new item of type
<code>T</code> and returns its address, a value of type <code>*T</code>.
In Go terminology, it returns a pointer to a newly allocated zero value of type
<code>T</code>.
</p>
<p>
Since the memory returned by <code>new</code> 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 <code>new</code> and get right to
work.
For example, the documentation for <code>bytes.Buffer</code> states that
"the zero value for <code>Buffer</code> is an empty buffer ready to use."
Similarly, <code>sync.Mutex</code> does not
have an explicit constructor or <code>Init</code> method.
Instead, the zero value for a <code>sync.Mutex</code>
is defined to be an unlocked mutex.
</p>
<p>
The zero-value-is-useful property works transitively. Consider this type declaration.
</p>
<pre>
type SyncedBuffer struct {
lock sync.Mutex
buffer bytes.Buffer
}
</pre>
<p>
Values of type <code>SyncedBuffer</code> are also ready to use immediately upon allocation
or just declaration. In the next snippet, both <code>p</code> and <code>v</code> will work
correctly without further arrangement.
</p>
<pre>
p := new(SyncedBuffer) // type *SyncedBuffer
var v SyncedBuffer // type SyncedBuffer
</pre>
<h3 id="composite_literals">Constructors and composite literals</h3>
<p>
Sometimes the zero value isn't good enough and an initializing
constructor is necessary, as in this example derived from
package <code>os</code>.
</p>
<pre>
func NewFile(fd int, name string) *File {
if fd &lt; 0 {
return nil
}
f := new(File)
f.fd = fd
f.name = name
f.dirinfo = nil
f.nepipe = 0
return f
}
</pre>
<p>
There's a lot of boiler plate in there. We can simplify it
using a <i>composite literal</i>, which is
an expression that creates a
new instance each time it is evaluated.
</p>
<pre>
func NewFile(fd int, name string) *File {
if fd &lt; 0 {
return nil
}
f := File{fd, name, nil, 0}
return &amp;f
}
</pre>
<p>
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.
</p>
<pre>
return &amp;File{fd, name, nil, 0}
</pre>
<p>
The fields of a composite literal are laid out in order and must all be present.
However, by labeling the elements explicitly as <i>field</i><code>:</code><i>value</i>
pairs, the initializers can appear in any
order, with the missing ones left as their respective zero values. Thus we could say
</p>
<pre>
return &amp;File{fd: fd, name: name}
</pre>
<p>
As a limiting case, if a composite literal contains no fields at all, it creates
a zero value for the type. The expressions <code>new(File)</code> and <code>&amp;File{}</code> are equivalent.
</p>
<p>
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 <code>Enone</code>,
<code>Eio</code>, and <code>Einval</code>, as long as they are distinct.
</p>
<pre>
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"}
</pre>
<h3 id="allocation_make">Allocation with <code>make</code></h3>
<p>
Back to allocation.
The built-in function <code>make(T, </code><i>args</i><code>)</code> serves
a purpose different from <code>new(T)</code>.
It creates slices, maps, and channels only, and it returns an <em>initialized</em>
(not <em>zeroed</em>)
value of type <code>T</code> (not <code>*T</code>).
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 <code>nil</code>.
For slices, maps, and channels,
<code>make</code> initializes the internal data structure and prepares
the value for use.
For instance,
</p>
<pre>
make([]int, 10, 100)
</pre>
<p>
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, <code>new([]int)</code> returns a pointer to a newly allocated, zeroed slice
structure, that is, a pointer to a <code>nil</code> slice value.
<p>
These examples illustrate the difference between <code>new</code> and
<code>make</code>.
</p>
<pre>
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)
</pre>
<p>
Remember that <code>make</code> applies only to maps, slices and channels
and does not return a pointer.
To obtain an explicit pointer allocate with <code>new</code>.
</p>
<h3 id="arrays">Arrays</h3>
<p>
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.
</p>
<p>
There are major differences between the ways arrays work in Go and C.
In Go,
</p>
<ul>
<li>
Arrays are values. Assigning one array to another copies all the elements.
</li>
<li>
In particular, if you pass an array to a function, it
will receive a <i>copy</i> of the array, not a pointer to it.
<li>
The size of an array is part of its type. The types <code>[10]int</code>
and <code>[20]int</code> are distinct.
</li>
</ul>
<p>
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.
</p>
<pre>
func Sum(a *[3]float64) (sum float64) {
for _, v := range *a {
sum += v
}
return
}
array := [...]float64{7.0, 8.5, 9.1}
x := Sum(&amp;array) // Note the explicit address-of operator
</pre>
<p>
But even this style isn't idiomatic Go. Slices are.
</p>
<h3 id="slices">Slices</h3>
<p>
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.
</p>
<p>
Slices are <i>reference types</i>, 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 <code>Read</code>
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
<code>Read</code> method of the <code>File</code> type in package
<code>os</code>:
</p>
<pre>
func (file *File) Read(buf []byte) (n int, err error)
</pre>
<p>
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
<code>b</code>, <i>slice</i> (here used as a verb) the buffer.
</p>
<pre>
n, err := f.Read(buf[0:32])
</pre>
<p>
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.
</p>
<pre>
var n int
var err error
for i := 0; i &lt; 32; i++ {
nbytes, e := f.Read(buf[i:i+1]) // Read one byte.
if nbytes == 0 || e != nil {
err = e
break
}
n += nbytes
}
</pre>
<p>
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 <i>capacity</i> of a slice, accessible by the built-in
function <code>cap</code>, 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
<code>len</code> and <code>cap</code> are legal when applied to the
<code>nil</code> slice, and return 0.
</p>
<pre>
func Append(slice, data[]byte) []byte {
l := len(slice)
if l + len(data) &gt; 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
}
</pre>
<p>
We must return the slice afterwards because, although <code>Append</code>
can modify the elements of <code>slice</code>, the slice itself (the run-time data
structure holding the pointer, length, and capacity) is passed by value.
<p>
The idea of appending to a slice is so useful it's captured by the
<code>append</code> built-in function. To understand that function's
design, though, we need a little more information, so we'll return
to it later.
</p>
<h3 id="maps">Maps</h3>
<p>
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.
</p>
<p>
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.
</p>
<pre>
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,
}
</pre>
<p>
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.
</p>
<pre>
offset := timeZone["EST"]
</pre>
<p>
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 <code>0</code>.
A set can be implemented as a map with value type <code>bool</code>.
Set the map entry to <code>true</code> to put the value in the set, and then
test it by simple indexing.
</p>
<pre>
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")
}
</pre>
<p>
Sometimes you need to distinguish a missing entry from
a zero value. Is there an entry for <code>"UTC"</code>
or is that zero value because it's not in the map at all?
You can discriminate with a form of multiple assignment.
</p>
<pre>
var seconds int
var ok bool
seconds, ok = timeZone[tz]
</pre>
<p>
For obvious reasons this is called the &ldquo;comma ok&rdquo; idiom.
In this example, if <code>tz</code> is present, <code>seconds</code>
will be set appropriately and <code>ok</code> will be true; if not,
<code>seconds</code> will be set to zero and <code>ok</code> will
be false.
Here's a function that puts it together with a nice error report:
</p>
<pre>
func offset(tz string) int {
if seconds, ok := timeZone[tz]; ok {
return seconds
}
log.Println("unknown time zone:", tz)
return 0
}
</pre>
<p>
To test for presence in the map without worrying about the actual value,
you can use the <em>blank identifier</em>, a simple underscore (<code>_</code>).
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.
</p>
<pre>
_, present := timeZone[tz]
</pre>
<p>
To delete a map entry, use the <code>delete</code>
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.
</p>
<pre>
delete(timeZone, "PDT") // Now on Standard Time
</pre>
<h3 id="printing">Printing</h3>
<p>
Formatted printing in Go uses a style similar to C's <code>printf</code>
family but is richer and more general. The functions live in the <code>fmt</code>
package and have capitalized names: <code>fmt.Printf</code>, <code>fmt.Fprintf</code>,
<code>fmt.Sprintf</code> and so on. The string functions (<code>Sprintf</code> etc.)
return a string rather than filling in a provided buffer.
</p>
<p>
You don't need to provide a format string. For each of <code>Printf</code>,
<code>Fprintf</code> and <code>Sprintf</code> there is another pair
of functions, for instance <code>Print</code> and <code>Println</code>.
These functions do not take a format string but instead generate a default
format for each argument. The <code>Println</code> versions also insert a blank
between arguments and append a newline to the output while
the <code>Print</code> versions add blanks only if the operand on neither side is a string.
In this example each line produces the same output.
</p>
<pre>
fmt.Printf("Hello %d\n", 23)
fmt.Fprint(os.Stdout, "Hello ", 23, "\n")
fmt.Println("Hello", 23)
fmt.Println(fmt.Sprint("Hello ", 23))
</pre>
<p>
As mentioned in
the <a href="http://code.google.com/p/go-tour/">Tour</a>, <code>fmt.Fprint</code>
and friends take as a first argument any object
that implements the <code>io.Writer</code> interface; the variables <code>os.Stdout</code>
and <code>os.Stderr</code> are familiar instances.
</p>
<p>
Here things start to diverge from C. First, the numeric formats such as <code>%d</code>
do not take flags for signedness or size; instead, the printing routines use the
type of the argument to decide these properties.
</p>
<pre>
var x uint64 = 1&lt;&lt;64 - 1
fmt.Printf("%d %x; %d %x\n", x, x, int64(x), int64(x))
</pre>
<p>
prints
</p>
<pre>
18446744073709551615 ffffffffffffffff; -1 -1
</pre>
<p>
If you just want the default conversion, such as decimal for integers, you can use
the catchall format <code>%v</code> (for &ldquo;value&rdquo;); the result is exactly
what <code>Print</code> and <code>Println</code> would produce.
Moreover, that format can print <em>any</em> value, even arrays, structs, and
maps. Here is a print statement for the time zone map defined in the previous section.
</p>
<pre>
fmt.Printf("%v\n", timeZone) // or just fmt.Println(timeZone)
</pre>
<p>
which gives output
</p>
<pre>
map[CST:-21600 PST:-28800 EST:-18000 UTC:0 MST:-25200]
</pre>
<p>
For maps the keys may be output in any order, of course.
When printing a struct, the modified format <code>%+v</code> annotates the
fields of the structure with their names, and for any value the alternate
format <code>%#v</code> prints the value in full Go syntax.
</p>
<pre>
type T struct {
a int
b float64
c string
}
t := &amp;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)
</pre>
<p>
prints
</p>
<pre>
&amp;{7 -2.35 abc def}
&amp;{a:7 b:-2.35 c:abc def}
&amp;main.T{a:7, b:-2.35, c:"abc\tdef"}
map[string] int{"CST":-21600, "PST":-28800, "EST":-18000, "UTC":0, "MST":-25200}
</pre>
<p>
(Note the ampersands.)
That quoted string format is also available through <code>%q</code> when
applied to a value of type <code>string</code> or <code>[]byte</code>;
the alternate format <code>%#q</code> will use backquotes instead if possible.
Also, <code>%x</code> works on strings and arrays of bytes as well as on integers,
generating a long hexadecimal string, and with
a space in the format (<code>%&nbsp;x</code>) it puts spaces between the bytes.
</p>
<p>
Another handy format is <code>%T</code>, which prints the <em>type</em> of a value.
<pre>
fmt.Printf(&quot;%T\n&quot;, timeZone)
</pre>
<p>
prints
</p>
<pre>
map[string] int
</pre>
<p>
If you want to control the default format for a custom type, all that's required is to define
a method with the signature <code>String() string</code> on the type.
For our simple type <code>T</code>, that might look like this.
</p>
<pre>
func (t *T) String() string {
return fmt.Sprintf("%d/%g/%q", t.a, t.b, t.c)
}
fmt.Printf("%v\n", t)
</pre>
<p>
to print in the format
</p>
<pre>
7/-2.35/"abc\tdef"
</pre>
<p>
(If you need to print <em>values</em> of type <code>T</code> as well as pointers to <code>T</code>,
the receiver for <code>String</code> 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 <a href="#pointers_vs_values">pointers vs. value receivers</a> for more information.)
</p>
<p>
Our <code>String</code> method is able to call <code>Sprintf</code> 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 <code>Printf</code> uses the type <code>...interface{}</code>
for its final argument to specify that an arbitrary number of parameters (of arbitrary type)
can appear after the format.
</p>
<pre>
func Printf(format string, v ...interface{}) (n int, err error) {
</pre>
<p>
Within the function <code>Printf</code>, <code>v</code> acts like a variable of type
<code>[]interface{}</code> but if it is passed to another variadic function, it acts like
a regular list of arguments.
Here is the implementation of the
function <code>log.Println</code> we used above. It passes its arguments directly to
<code>fmt.Sprintln</code> for the actual formatting.
</p>
<pre>
// 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)
}
</pre>
<p>
We write <code>...</code> after <code>v</code> in the nested call to <code>Sprintln</code> to tell the
compiler to treat <code>v</code> as a list of arguments; otherwise it would just pass
<code>v</code> as a single slice argument.
<p>
There's even more to printing than we've covered here. See the <code>godoc</code> documentation
for package <code>fmt</code> for the details.
</p>
<p>
By the way, a <code>...</code> parameter can be of a specific type, for instance <code>...int</code>
for a min function that chooses the least of a list of integers:
</p>
<pre>
func Min(a ...int) int {
min := int(^uint(0) >> 1) // largest int
for _, i := range a {
if i &lt; min {
min = i
}
}
return min
}
</pre>
<h3 id="append">Append</h3>
<p>
Now we have the missing piece we needed to explain the design of
the <code>append</code> built-in function. The signature of <code>append</code>
is different from our custom <code>Append</code> function above.
Schematically, it's like this:
</p>
<pre>
func append(slice []<i>T</i>, elements...T) []<i>T</i>
</pre>
<p>
where <i>T</i> is a placeholder for any given type. You can't
actually write a function in Go where the type <code>T</code>
is determined by the caller.
That's why <code>append</code> is built in: it needs support from the
compiler.
</p>
<p>
What <code>append</code> 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 <code>Append</code>, the underlying
array may change. This simple example
</p>
<pre>
x := []int{1,2,3}
x = append(x, 4, 5, 6)
fmt.Println(x)
</pre>
<p>
prints <code>[1 2 3 4 5 6]</code>. So <code>append</code> works a
little like <code>Printf</code>, collecting an arbitrary number of
arguments.
</p>
<p>
But what if we wanted to do what our <code>Append</code> does and
append a slice to a slice? Easy: use <code>...</code> at the call
site, just as we did in the call to <code>Output</code> above. This
snippet produces identical output to the one above.
</p>
<pre>
x := []int{1,2,3}
y := []int{4,5,6}
x = append(x, y...)
fmt.Println(x)
</pre>
<p>
Without that <code>...</code>, it wouldn't compile because the types
would be wrong; <code>y</code> is not of type <code>int</code>.
</p>
<h2 id="initialization">Initialization</h2>
<p>
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.
</p>
<h3 id="constants">Constants</h3>
<p>
Constants in Go are just that&mdash;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,
<code>1&lt;&lt;3</code> is a constant expression, while
<code>math.Sin(math.Pi/4)</code> is not because
the function call to <code>math.Sin</code> needs
to happen at run time.
</p>
<p>
In Go, enumerated constants are created using the <code>iota</code>
enumerator. Since <code>iota</code> can be part of an expression and
expressions can be implicitly repeated, it is easy to build intricate
sets of values.
</p>
{{code "progs/eff_bytesize.go" `/^type ByteSize/` `/^\)/`}}
<p>
The ability to attach a method such as <code>String</code> to a
type makes it possible for such values to format themselves
automatically for printing, even as part of a general type.
</p>
{{code "progs/eff_bytesize.go" `/^func.*ByteSize.*String/` `/^}/`}}
<p>
(The <code>float64</code> conversions prevent <code>Sprintf</code>
from recurring back through the <code>String</code> method for
<code>ByteSize</code>.)
The expression <code>YB</code> prints as <code>1.00YB</code>,
while <code>ByteSize(1e13)</code> prints as <code>9.09TB</code>.
</p>
<h3 id="variables">Variables</h3>
<p>
Variables can be initialized just like constants but the
initializer can be a general expression computed at run time.
</p>
<pre>
var (
HOME = os.Getenv("HOME")
USER = os.Getenv("USER")
GOROOT = os.Getenv("GOROOT")
)
</pre>
<h3 id="init">The init function</h3>
<p>
Finally, each source file can define its own niladic <code>init</code> function to
set up whatever state is required. (Actually each file can have multiple
<code>init</code> functions.)
And finally means finally: <code>init</code> 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.
</p>
<p>
Besides initializations that cannot be expressed as declarations,
a common use of <code>init</code> functions is to verify or repair
correctness of the program state before real execution begins.
</p>
<pre>
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(&amp;GOROOT, "goroot", GOROOT, "Go root directory")
}
</pre>
<h2 id="methods">Methods</h2>
<h3 id="pointers_vs_values">Pointers vs. Values</h3>
<p>
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.
<p>
In the discussion of slices above, we wrote an <code>Append</code>
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.
</p>
<pre>
type ByteSlice []byte
func (slice ByteSlice) Append(data []byte) []byte {
// Body exactly the same as above
}
</pre>
<p>
This still requires the method to return the updated slice. We can
eliminate that clumsiness by redefining the method to take a
<i>pointer</i> to a <code>ByteSlice</code> as its receiver, so the
method can overwrite the caller's slice.
</p>
<pre>
func (p *ByteSlice) Append(data []byte) {
slice := *p
// Body as above, without the return.
*p = slice
}
</pre>
<p>
In fact, we can do even better. If we modify our function so it looks
like a standard <code>Write</code> method, like this,
</p>
<pre>
func (p *ByteSlice) Write(data []byte) (n int, err error) {
slice := *p
// Again as above.
*p = slice
return len(data), nil
}
</pre>
<p>
then the type <code>*ByteSlice</code> satisfies the standard interface
<code>io.Writer</code>, which is handy. For instance, we can
print into one.
</p>
<pre>
var b ByteSlice
fmt.Fprintf(&amp;b, "This hour has %d days\n", 7)
</pre>
<p>
We pass the address of a <code>ByteSlice</code>
because only <code>*ByteSlice</code> satisfies <code>io.Writer</code>.
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.
</p>
<p>
By the way, the idea of using <code>Write</code> on a slice of bytes
is implemented by <code>bytes.Buffer</code>.
</p>
<h2 id="interfaces_and_types">Interfaces and other types</h2>
<h3 id="interfaces">Interfaces</h3>
<p>
Interfaces in Go provide a way to specify the behavior of an
object: if something can do <em>this</em>, then it can be used
<em>here</em>. We've seen a couple of simple examples already;
custom printers can be implemented by a <code>String</code> method
while <code>Fprintf</code> can generate output to anything
with a <code>Write</code> 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 <code>io.Writer</code>
for something that implements <code>Write</code>.
</p>
<p>
A type can implement multiple interfaces.
For instance, a collection can be sorted
by the routines in package <code>sort</code> if it implements
<code>sort.Interface</code>, which contains <code>Len()</code>,
<code>Less(i, j int) bool</code>, and <code>Swap(i, j int)</code>,
and it could also have a custom formatter.
In this contrived example <code>Sequence</code> satisfies both.
</p>
{{code "progs/eff_sequence.go" `/^type/` "$"}}
<h3 id="conversions">Conversions</h3>
<p>
The <code>String</code> method of <code>Sequence</code> is recreating the
work that <code>Sprint</code> already does for slices. We can share the
effort if we convert the <code>Sequence</code> to a plain
<code>[]int</code> before calling <code>Sprint</code>.
</p>
<pre>
func (s Sequence) String() string {
sort.Sort(s)
return fmt.Sprint([]int(s))
}
</pre>
<p>
The conversion causes <code>s</code> to be treated as an ordinary slice
and therefore receive the default formatting.
Without the conversion, <code>Sprint</code> would find the
<code>String</code> method of <code>Sequence</code> and recur indefinitely.
Because the two types (<code>Sequence</code> and <code>[]int</code>)
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.)
</p>
<p>
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 <code>sort.IntSlice</code> to reduce the entire example
to this:
</p>
<pre>
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))
}
</pre>
<p>
Now, instead of having <code>Sequence</code> implement multiple
interfaces (sorting and printing), we're using the ability of a data item to be
converted to multiple types (<code>Sequence</code>, <code>sort.IntSlice</code>
and <code>[]int</code>), each of which does some part of the job.
That's more unusual in practice but can be effective.
</p>
<h3 id="generality">Generality</h3>
<p>
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.
</p>
<p>
In such cases, the constructor should return an interface value
rather than the implementing type.
As an example, in the hash libraries
both <code>crc32.NewIEEE</code> and <code>adler32.New</code>
return the interface type <code>hash.Hash32</code>.
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.
</p>
<p>
A similar approach allows the streaming cipher algorithms
in the various <code>crypto</code> packages to be
separated from the block ciphers they chain together.
The <code>Block</code> interface
in the <code>crypto/cipher</code>package specifies the
behavior of a block cipher, which provides encryption
of a single block of data.
Then, by analogy with the <code>bufio</code> package,
cipher packages that implement this interface
can be used to construct streaming ciphers, represented
by the <code>Stream</code> interface, without
knowing the details of the block encryption.
</p>
<p>
The <code>crypto/cipher</code> interfaces look like this:
</p>
<pre>
type Block interface {
BlockSize() int
Encrypt(src, dst []byte)
Decrypt(src, dst []byte)
}
type Stream interface {
XORKeyStream(dst, src []byte)
}
</pre>
<p>
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:
</p>
<pre>
// 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
</pre>
<p>
<code>NewCTR</code> applies not
just to one specific encryption algorithm and data source but to any
implementation of the <code>Block</code> interface and any
<code>Stream</code>. 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 <code>Stream</code>, it won't notice the difference.
</p>
<h3 id="interface_methods">Interfaces and methods</h3>
<p>
Since almost anything can have methods attached, almost anything can
satisfy an interface. One illustrative example is in the <code>http</code>
package, which defines the <code>Handler</code> interface. Any object
that implements <code>Handler</code> can serve HTTP requests.
</p>
<pre>
type Handler interface {
ServeHTTP(ResponseWriter, *Request)
}
</pre>
<p>
<code>ResponseWriter</code> is itself an interface that provides access
to the methods needed to return the response to the client.
Those methods include the standard <code>Write</code> method, so an
<code>http.ResponseWriter</code> can be used wherever an <code>io.Writer</code>
can be used.
<code>Request</code> is a struct containing a parsed representation
of the request from the client.
<p>
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.
</p>
<pre>
// 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)
}
</pre>
<p>
(Keeping with our theme, note how <code>Fprintf</code> can print to an
<code>http.ResponseWriter</code>.)
For reference, here's how to attach such a server to a node on the URL tree.
<pre>
import "net/http"
...
ctr := new(Counter)
http.Handle("/counter", ctr)
</pre>
<p>
But why make <code>Counter</code> a struct? An integer is all that's needed.
(The receiver needs to be a pointer so the increment is visible to the caller.)
</p>
<pre>
// Simpler counter server.
type Counter int
func (ctr *Counter) ServeHTTP(w http.ResponseWriter, req *http.Request) {
*ctr++
fmt.Fprintf(w, "counter = %d\n", *ctr)
}
</pre>
<p>
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.
</p>
<pre>
// 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 &lt;- req
fmt.Fprint(w, "notification sent")
}
</pre>
<p>
Finally, let's say we wanted to present on <code>/args</code> the arguments
used when invoking the server binary.
It's easy to write a function to print the arguments.
</p>
<pre>
func ArgServer() {
for _, s := range os.Args {
fmt.Println(s)
}
}
</pre>
<p>
How do we turn that into an HTTP server? We could make <code>ArgServer</code>
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 <code>http</code> package contains this code:
</p>
<pre>
// 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)
}
</pre>
<p>
<code>HandlerFunc</code> is a type with a method, <code>ServeHTTP</code>,
so values of that type can serve HTTP requests. Look at the implementation
of the method: the receiver is a function, <code>f</code>, and the method
calls <code>f</code>. That may seem odd but it's not that different from, say,
the receiver being a channel and the method sending on the channel.
</p>
<p>
To make <code>ArgServer</code> into an HTTP server, we first modify it
to have the right signature.
</p>
<pre>
// Argument server.
func ArgServer(w http.ResponseWriter, req *http.Request) {
for _, s := range os.Args {
fmt.Fprintln(w, s)
}
}
</pre>
<p>
<code>ArgServer</code> now has same signature as <code>HandlerFunc</code>,
so it can be converted to that type to access its methods,
just as we converted <code>Sequence</code> to <code>IntSlice</code>
to access <code>IntSlice.Sort</code>.
The code to set it up is concise:
</p>
<pre>
http.Handle("/args", http.HandlerFunc(ArgServer))
</pre>
<p>
When someone visits the page <code>/args</code>,
the handler installed at that page has value <code>ArgServer</code>
and type <code>HandlerFunc</code>.
The HTTP server will invoke the method <code>ServeHTTP</code>
of that type, with <code>ArgServer</code> as the receiver, which will in turn call
<code>ArgServer</code> (via the invocation <code>f(c, req)</code>
inside <code>HandlerFunc.ServeHTTP</code>).
The arguments will then be displayed.
</p>
<p>
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.
</p>
<h2 id="embedding">Embedding</h2>
<p>
Go does not provide the typical, type-driven notion of subclassing,
but it does have the ability to &ldquo;borrow&rdquo; pieces of an
implementation by <em>embedding</em> types within a struct or
interface.
</p>
<p>
Interface embedding is very simple.
We've mentioned the <code>io.Reader</code> and <code>io.Writer</code> interfaces before;
here are their definitions.
</p>
<pre>
type Reader interface {
Read(p []byte) (n int, err error)
}
type Writer interface {
Write(p []byte) (n int, err error)
}
</pre>
<p>
The <code>io</code> package also exports several other interfaces
that specify objects that can implement several such methods.
For instance, there is <code>io.ReadWriter</code>, an interface
containing both <code>Read</code> and <code>Write</code>.
We could specify <code>io.ReadWriter</code> 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:
</p>
<pre>
// ReadWriter is the interface that combines the Reader and Writer interfaces.
type ReadWriter interface {
Reader
Writer
}
</pre>
<p>
This says just what it looks like: A <code>ReadWriter</code> can do
what a <code>Reader</code> does <em>and</em> what a <code>Writer</code>
does; it is a union of the embedded interfaces (which must be disjoint
sets of methods).
Only interfaces can be embedded within interfaces.
<p>
The same basic idea applies to structs, but with more far-reaching
implications. The <code>bufio</code> package has two struct types,
<code>bufio.Reader</code> and <code>bufio.Writer</code>, each of
which of course implements the analogous interfaces from package
<code>io</code>.
And <code>bufio</code> 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.
</p>
<pre>
// ReadWriter stores pointers to a Reader and a Writer.
// It implements io.ReadWriter.
type ReadWriter struct {
*Reader // *bufio.Reader
*Writer // *bufio.Writer
}
</pre>
<p>
The embedded elements are pointers to structs and of course
must be initialized to point to valid structs before they
can be used.
The <code>ReadWriter</code> struct could be written as
</p>
<pre>
type ReadWriter struct {
reader *Reader
writer *Writer
}
</pre>
<p>
but then to promote the methods of the fields and to
satisfy the <code>io</code> interfaces, we would also need
to provide forwarding methods, like this:
</p>
<pre>
func (rw *ReadWriter) Read(p []byte) (n int, err error) {
return rw.reader.Read(p)
}
</pre>
<p>
By embedding the structs directly, we avoid this bookkeeping.
The methods of embedded types come along for free, which means that <code>bufio.ReadWriter</code>
not only has the methods of <code>bufio.Reader</code> and <code>bufio.Writer</code>,
it also satisfies all three interfaces:
<code>io.Reader</code>,
<code>io.Writer</code>, and
<code>io.ReadWriter</code>.
</p>
<p>
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 <code>Read</code> method of a <code>bufio.ReadWriter</code> is
invoked, it has exactly the same effect as the forwarding method written out above;
the receiver is the <code>reader</code> field of the <code>ReadWriter</code>, not the
<code>ReadWriter</code> itself.
</p>
<p>
Embedding can also be a simple convenience.
This example shows an embedded field alongside a regular, named field.
</p>
<pre>
type Job struct {
Command string
*log.Logger
}
</pre>
<p>
The <code>Job</code> type now has the <code>Log</code>, <code>Logf</code>
and other
methods of <code>*log.Logger</code>. We could have given the <code>Logger</code>
a field name, of course, but it's not necessary to do so. And now, once
initialized, we can
log to the <code>Job</code>:
</p>
<pre>
job.Log("starting now...")
</pre>
<p>
The <code>Logger</code> is a regular field of the struct and we can initialize
it in the usual way with a constructor,
</p>
<pre>
func NewJob(command string, logger *log.Logger) *Job {
return &amp;Job{command, logger}
}
</pre>
<p>
or with a composite literal,
</p>
<pre>
job := &amp;Job{command, log.New(os.Stderr, "Job: ", log.Ldate)}
</pre>
<p>
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
<code>*log.Logger</code> of a <code>Job</code> variable <code>job</code>,
we would write <code>job.Logger</code>.
This would be useful if we wanted to refine the methods of <code>Logger</code>.
</p>
<pre>
func (job *Job) Logf(format string, args ...interface{}) {
job.Logger.Logf("%q: %s", job.Command, fmt.Sprintf(format, args))
}
</pre>
<p>
Embedding types introduces the problem of name conflicts but the rules to resolve
them are simple.
First, a field or method <code>X</code> hides any other item <code>X</code> in a more deeply
nested part of the type.
If <code>log.Logger</code> contained a field or method called <code>Command</code>, the <code>Command</code> field
of <code>Job</code> would dominate it.
</p>
<p>
Second, if the same name appears at the same nesting level, it is usually an error;
it would be erroneous to embed <code>log.Logger</code> if the <code>Job</code> struct
contained another field or method called <code>Logger</code>.
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.
</p>
<h2 id="concurrency">Concurrency</h2>
<h3 id="sharing">Share by communicating</h3>
<p>
Concurrent programming is a large topic and there is space only for some
Go-specific highlights here.
</p>
<p>
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:
</p>
<blockquote>
Do not communicate by sharing memory;
instead, share memory by communicating.
</blockquote>
<p>
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.
</p>
<p>
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.
</p>
<h3 id="goroutines">Goroutines</h3>
<p>
They're called <em>goroutines</em> because the existing
terms&mdash;threads, coroutines, processes, and so on&mdash;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.
</p>
<p>
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.
</p>
<p>
Prefix a function or method call with the <code>go</code>
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
<code>&amp;</code> notation for running a command in the
background.)
</p>
<pre>
go list.Sort() // run list.Sort in parallel; don't wait for it.
</pre>
<p>
A function literal can be handy in a goroutine invocation.
<pre>
func Announce(message string, delay int64) {
go func() {
time.Sleep(delay)
fmt.Println(message)
}() // Note the parentheses - must call the function.
}
</pre>
<p>
In Go, function literals are closures: the implementation makes
sure the variables referred to by the function survive as long as they are active.
<p>
These examples aren't too practical because the functions have no way of signaling
completion. For that, we need channels.
</p>
<h3 id="channels">Channels</h3>
<p>
Like maps, channels are a reference type and are allocated with <code>make</code>.
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.
</p>
<pre>
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
</pre>
<p>
Channels combine communication&mdash;the exchange of a value&mdash;with
synchronization&mdash;guaranteeing that two calculations (goroutines) are in
a known state.
</p>
<p>
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.
</p>
<pre>
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 &lt;- 1 // Send a signal; value does not matter.
}()
doSomethingForAWhile()
&lt;-c // Wait for sort to finish; discard sent value.
</pre>
<p>
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.
</p>
<p>
A buffered channel can be used like a semaphore, for instance to
limit throughput. In this example, incoming requests are passed
to <code>handle</code>, 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 <code>process</code>.
</p>
<pre>
var sem = make(chan int, MaxOutstanding)
func handle(r *Request) {
sem &lt;- 1 // Wait for active queue to drain.
process(r) // May take a long time.
&lt;-sem // Done; enable next request to run.
}
func Serve(queue chan *Request) {
for {
req := &lt;-queue
go handle(req) // Don't wait for handle to finish.
}
}
</pre>
<p>
Here's the same idea implemented by starting a fixed
number of <code>handle</code> goroutines all reading from the request
channel.
The number of goroutines limits the number of simultaneous
calls to <code>process</code>.
This <code>Serve</code> function also accepts a channel on which
it will be told to exit; after launching the goroutines it blocks
receiving from that channel.
</p>
<pre>
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 &lt; MaxOutstanding; i++ {
go handle(clientRequests)
}
&lt;-quit // Wait to be told to exit.
}
</pre>
<h3 id="chan_of_chan">Channels of channels</h3>
<p>
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.
<p>
In the example in the previous section, <code>handle</code> 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 <code>Request</code>.
</p>
<pre>
type Request struct {
args []int
f func([]int) int
resultChan chan int
}
</pre>
<p>
The client provides a function and its arguments, as well as
a channel inside the request object on which to receive the answer.
</p>
<pre>
func sum(a []int) (s int) {
for _, v := range a {
s += v
}
return
}
request := &amp;Request{[]int{3, 4, 5}, sum, make(chan int)}
// Send request
clientRequests &lt;- request
// Wait for response.
fmt.Printf("answer: %d\n", &lt;-request.resultChan)
</pre>
<p>
On the server side, the handler function is the only thing that changes.
</p>
<pre>
func handle(queue chan *Request) {
for req := range queue {
req.resultChan &lt;- req.f(req.args)
}
}
</pre>
<p>
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.
</p>
<h3 id="parallel">Parallelization</h3>
<p>
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.
</p>
<p>
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.
</p>
<pre>
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 &lt; n; i++ {
v[i] += u.Op(v[i])
}
c &lt;- 1 // signal that this piece is done
}
</pre>
<p>
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.
</p>
<pre>
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 &lt; NCPU; i++ {
go v.DoSome(i*len(v)/NCPU, (i+1)*len(v)/NCPU, u, c)
}
// Drain the channel.
for i := 0; i &lt; NCPU; i++ {
&lt;-c // wait for one task to complete
}
// All done.
}
</pre>
<p>
The current implementation of <code>gc</code> (<code>6g</code>, 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 <code>GOMAXPROCS</code> set to the number of cores to use
or import the <code>runtime</code> package and call
<code>runtime.GOMAXPROCS(NCPU)</code>.
A helpful value might be <code>runtime.NumCPU()</code>, 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.
</p>
<h3 id="leaky_buffer">A leaky buffer</h3>
<p>
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
<code>serverChan</code>.
</p>
<pre>
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 = &lt;-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 &lt;- b // Send to server.
}
}
</pre>
<p>
The server loop receives each message from the client, processes it,
and returns the buffer to the free list.
</p>
<pre>
func server() {
for {
b := &lt;-serverChan // Wait for work.
process(b)
// Reuse buffer if there's room.
select {
case freeList &lt;- b:
// Buffer on free list; nothing more to do.
default:
// Free list full, just carry on.
}
}
}
</pre>
<p>
The client attempts to retrieve a buffer from <code>freeList</code>;
if none is available, it allocates a fresh one.
The server's send to <code>freeList</code> puts <code>b</code> 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 <code>default</code> clauses in the <code>select</code>
statements execute when no other case is ready,
meaning that the <code>selects</code> 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.
</p>
<h2 id="errors">Errors</h2>
<p>
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 <code>error</code>,
a simple built-in interface.
</p>
<pre>
type error interface {
Error() string
}
</pre>
<p>
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, <code>os.Open</code> returns an <code>os.PathError</code>.
</p>
<pre>
// 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()
}
</pre>
<p>
<code>PathError</code>'s <code>Error</code> generates
a string like this:
</p>
<pre>
open /etc/passwx: no such file or directory
</pre>
<p>
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".
</p>
<p>
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".
</p>
<p>
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 <code>PathErrors</code>
this might include examining the internal <code>Err</code>
field for recoverable failures.
</p>
<pre>
for try := 0; try &lt; 2; try++ {
file, err = os.Open(filename)
if err == nil {
return
}
if e, ok := err.(*os.PathError); ok &amp;&amp; e.Err == os.ENOSPC {
deleteTempFiles() // Recover some space.
continue
}
return
}
</pre>
<p>
The second <code>if</code> statement here is idiomatic Go.
The type assertion <code>err.(*os.PathError)</code> is
checked with the "comma ok" idiom (mentioned <a href="#maps">earlier</a>
in the context of examining maps).
If the type assertion fails, <code>ok</code> will be false, and <code>e</code>
will be <code>nil</code>.
If it succeeds, <code>ok</code> will be true, which means the
error was of type <code>*os.PathError</code>, and then so is <code>e</code>,
which we can examine for more information about the error.
</p>
<h3 id="panic">Panic</h3>
<p>
The usual way to report an error to a caller is to return an
<code>error</code> as an extra return value. The canonical
<code>Read</code> method is a well-known instance; it returns a byte
count and an <code>error</code>. But what if the error is
unrecoverable? Sometimes the program simply cannot continue.
</p>
<p>
For this purpose, there is a built-in function <code>panic</code>
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&mdash;often a string&mdash;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 <code>panic</code> at the end of a function and
suppresses the usual check for a <code>return</code> statement.
</p>
<pre>
// 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 &lt; 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))
}
</pre>
<p>
This is only an example but real library functions should
avoid <code>panic</code>. 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.
</p>
<pre>
var user = os.Getenv("USER")
func init() {
if user == "" {
panic("no value for $USER")
}
}
</pre>
<h3 id="recover">Recover</h3>
<p>
When <code>panic</code> 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 <code>recover</code> to regain control
of the goroutine and resume normal execution.
</p>
<p>
A call to <code>recover</code> stops the unwinding and returns the
argument passed to <code>panic</code>. Because the only code that
runs while unwinding is inside deferred functions, <code>recover</code>
is only useful inside deferred functions.
</p>
<p>
One application of <code>recover</code> is to shut down a failing goroutine
inside a server without killing the other executing goroutines.
</p>
<pre>
func server(workChan &lt;-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)
}
</pre>
<p>
In this example, if <code>do(work)</code> 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 <code>recover</code> handles the condition completely.
</p>
<p>
Because <code>recover</code> always returns <code>nil</code> unless called directly
from a deferred function, deferred code can call library routines that themselves
use <code>panic</code> and <code>recover</code> without failing. As an example,
the deferred function in <code>safelyDo</code> might call a logging function before
calling <code>recover</code>, and that logging code would run unaffected
by the panicking state.
</p>
<p>
With our recovery pattern in place, the <code>do</code>
function (and anything it calls) can get out of any bad situation
cleanly by calling <code>panic</code>. We can use that idea to
simplify error handling in complex software. Let's look at an
idealized excerpt from the <code>regexp</code> package, which reports
parsing errors by calling <code>panic</code> with a local
error type. Here's the definition of <code>Error</code>,
an <code>error</code> method, and the <code>Compile</code> function.
</p>
<pre>
// 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
}
</pre>
<p>
If <code>doParse</code> panics, the recovery block will set the
return value to <code>nil</code>&mdash;deferred functions can modify
named return values. It then will then check, in the assignment
to <code>err</code>, that the problem was a parse error by asserting
that it has the local type <code>Error</code>.
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 <code>panic</code> and <code>recover</code> to handle
user-triggered errors.
</p>
<p>
With error handling in place, the <code>error</code> method
makes it easy to report parse errors without worrying about unwinding
the parse stack by hand.
</p>
<p>
Useful though this pattern is, it should be used only within a package.
<code>Parse</code> turns its internal <code>panic</code> calls into
<code>error</code> values; it does not expose <code>panics</code>
to its client. That is a good rule to follow.
</p>
<p>
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&mdash;it's a crash after all&mdash;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.
</p>
<h2 id="web_server">A web server</h2>
<p>
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
<a href="http://chart.apis.google.com">http://chart.apis.google.com</a>
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.
</p>
<p>
Here's the complete program.
An explanation follows.
</p>
{{code "progs/eff_qr.go"}}
<p>
The pieces up to <code>main</code> should be easy to follow.
The one flag sets a default HTTP port for our server. The template
variable <code>templ</code> 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.
</p>
<p>
The <code>main</code> function parses the flags and, using the mechanism
we talked about above, binds the function <code>QR</code> to the root path
for the server. Then <code>http.ListenAndServe</code> is called to start the
server; it blocks while the server runs.
</p>
<p>
<code>QR</code> just receives the request, which contains form data, and
executes the template on the data in the form value named <code>s</code>.
</p>
<p>
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 <code>templ.Execute</code>, in this case the
form value.
Within the template text (<code>templateStr</code>),
double-brace-delimited pieces denote template actions.
The piece from <code>{{html "{{if .}}"}}</code>
to <code>{{html "{{end}}"}}</code> executes only if the value of the current data item, called <code>.</code> (dot),
is non-empty.
That is, when the string is empty, this piece of the template is suppressed.
</p>
<p>
The snippet <code>{{html "{{urlquery .}}"}}</code> says to process the data with the function
<code>urlquery</code>, which sanitizes the query string
for safe display on the web page.
</p>
<p>
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 <a href="/pkg/template/">documentation</a>
for the template package for a more thorough discussion.
</p>
<p>
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.
</p>
<!--
TODO
<pre>
verifying implementation
type Color uint32
// Check that Color implements image.Color and image.Image
var _ image.Color = Black
var _ image.Image = Black
</pre>
-->
doc/go1.html
View file @ a40065ac
<!--{
"Title": "Go 1 Release Notes"
"Title": "Go 1 Release Notes",
"Template": true
}-->
<!--
DO NOT EDIT: created by
tmpltohtml go1.tmpl
-->
<h2 id="introduction">Introduction to Go 1</h2>
......@@ -64,9 +60,7 @@ However, <code>append</code> did not provide a way to append a string to a <code
which is another common case.
</p>
<pre><!--{{code "progs/go1.go" `/greeting := ..byte/` `/append.*hello/`}}
--> greeting := []byte{}
greeting = append(greeting, []byte(&#34;hello &#34;)...)</pre>
{{code "/doc/progs/go1.go" `/greeting := ..byte/` `/append.*hello/`}}
<p>
By analogy with the similar property of <code>copy</code>, Go 1
......@@ -75,8 +69,7 @@ slice, reducing the friction between strings and byte slices.
The conversion is no longer necessary:
</p>
<pre><!--{{code "progs/go1.go" `/append.*world/`}}
--> greeting = append(greeting, &#34;world&#34;...)</pre>
{{code "/doc/progs/go1.go" `/append.*world/`}}
<p>
<em>Updating</em>:
......@@ -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.
</p>
<pre><!--{{code "progs/go1.go" `/type Date struct/` `/STOP/`}}
--> type Date struct {
month string
day int
}
// Struct values, fully qualified; always legal.
holiday1 := []Date{
Date{&#34;Feb&#34;, 14},
Date{&#34;Nov&#34;, 11},
Date{&#34;Dec&#34;, 25},
}
// Struct values, type name elided; always legal.
holiday2 := []Date{
{&#34;Feb&#34;, 14},
{&#34;Nov&#34;, 11},
{&#34;Dec&#34;, 25},
}
// Pointers, fully qualified, always legal.
holiday3 := []*Date{
&amp;Date{&#34;Feb&#34;, 14},
&amp;Date{&#34;Nov&#34;, 11},
&amp;Date{&#34;Dec&#34;, 25},
}
// Pointers, type name elided; legal in Go 1.
holiday4 := []*Date{
{&#34;Feb&#34;, 14},
{&#34;Nov&#34;, 11},
{&#34;Dec&#34;, 25},
}</pre>
{{code "/doc/progs/go1.go" `/type Date struct/` `/STOP/`}}
<p>
<em>Updating</em>:
......@@ -183,14 +148,7 @@ In Go 1, code that uses goroutines can be called from
without introducing a deadlock.
</p>
<pre><!--{{code "progs/go1.go" `/PackageGlobal/` `/^}/`}}
-->var PackageGlobal int
func init() {
c := make(chan int)
go initializationFunction(c)
PackageGlobal = &lt;-c
}</pre>
{{code "/doc/progs/go1.go" `/PackageGlobal/` `/^}/`}}
<p>
<em>Updating</em>:
......@@ -231,14 +189,7 @@ when appropriate. For instance, the functions <code>unicode.ToLower</code> and
relatives now take and return a <code>rune</code>.
</p>
<pre><!--{{code "progs/go1.go" `/STARTRUNE/` `/ENDRUNE/`}}
--> delta := &#39;δ&#39; // delta has type rune.
var DELTA rune
DELTA = unicode.ToUpper(delta)
epsilon := unicode.ToLower(DELTA + 1)
if epsilon != &#39;δ&#39;+1 {
log.Fatal(&#34;inconsistent casing for Greek&#34;)
}</pre>
{{code "/doc/progs/go1.go" `/STARTRUNE/` `/ENDRUNE/`}}
<p>
<em>Updating</em>:
......@@ -287,8 +238,7 @@ In Go 1, that syntax has gone; instead there is a new built-in
function, <code>delete</code>. The call
</p>
<pre><!--{{code "progs/go1.go" `/delete\(m, k\)/`}}
--> delete(m, k)</pre>
{{code "/doc/progs/go1.go" `/delete\(m, k\)/`}}
<p>
will delete the map entry retrieved by the expression <code>m[k]</code>.
......@@ -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.
</p>
<pre><!--{{code "progs/go1.go" `/Sunday/` `/^ }/`}}
--> m := map[string]int{&#34;Sunday&#34;: 0, &#34;Monday&#34;: 1}
for name, value := range m {
// This loop should not assume Sunday will be visited first.
f(name, value)
}</pre>
{{code "/doc/progs/go1.go" `/Sunday/` `/^ }/`}}
<p>
<em>Updating</em>:
......@@ -367,17 +312,7 @@ proceed in left-to-right order.
These examples illustrate the behavior.
</p>
<pre><!--{{code "progs/go1.go" `/sa :=/` `/then sc.0. = 2/`}}
--> 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)</pre>
{{code "/doc/progs/go1.go" `/sa :=/` `/then sc.0. = 2/`}}
<p>
<em>Updating</em>:
......@@ -504,18 +439,7 @@ provided they are composed from elements for which equality is also defined,
using element-wise comparison.
</p>
<pre><!--{{code "progs/go1.go" `/type Day struct/` `/Printf/`}}
--> type Day struct {
long string
short string
}
Christmas := Day{&#34;Christmas&#34;, &#34;XMas&#34;}
Thanksgiving := Day{&#34;Thanksgiving&#34;, &#34;Turkey&#34;}
holiday := map[Day]bool{
Christmas: true,
Thanksgiving: true,
}
fmt.Printf(&#34;Christmas is a holiday: %t\n&#34;, holiday[Christmas])</pre>
{{code "/doc/progs/go1.go" `/type Day struct/` `/Printf/`}}
<p>
Second, Go 1 removes the definition of equality for function values,
......@@ -831,16 +755,7 @@ The <code>fmt</code> library automatically invokes <code>Error</code>, as it alr
does for <code>String</code>, for easy printing of error values.
</p>
<pre><!--{{code "progs/go1.go" `/START ERROR EXAMPLE/` `/END ERROR EXAMPLE/`}}
-->type SyntaxError struct {
File string
Line int
Message string
}
func (se *SyntaxError) Error() string {
return fmt.Sprintf(&#34;%s:%d: %s&#34;, se.File, se.Line, se.Message)
}</pre>
{{code "/doc/progs/go1.go" `/START ERROR EXAMPLE/` `/END ERROR EXAMPLE/`}}
<p>
All standard packages have been updated to use the new interface; the old <code>os.Error</code> is gone.
......@@ -858,8 +773,7 @@ func New(text string) error
to turn a string into an error. It replaces the old <code>os.NewError</code>.
</p>
<pre><!--{{code "progs/go1.go" `/ErrSyntax/`}}
--> var ErrSyntax = errors.New(&#34;syntax error&#34;)</pre>
{{code "/doc/progs/go1.go" `/ErrSyntax/`}}
<p>
<em>Updating</em>:
......@@ -949,17 +863,7 @@ returns a <code>time.Time</code> value rather than, in the old
API, an integer nanosecond count since the Unix epoch.
</p>
<pre><!--{{code "progs/go1.go" `/sleepUntil/` `/^}/`}}
-->// sleepUntil sleeps until the specified time. It returns immediately if it&#39;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(&#34;Sleeping for %.3fs\n&#34;, delta.Seconds())
time.Sleep(delta)
}</pre>
{{code "/doc/progs/go1.go" `/sleepUntil/` `/^}/`}}
<p>
The new types, methods, and constants have been propagated through
......@@ -1196,8 +1100,7 @@ Values for such flags must be given units, just as <code>time.Duration</code>
formats them: <code>10s</code>, <code>1h30m</code>, etc.
</p>
<pre><!--{{code "progs/go1.go" `/timeout/`}}
-->var timeout = flag.Duration(&#34;timeout&#34;, 30*time.Second, &#34;how long to wait for completion&#34;)</pre>
{{code "/doc/progs/go1.go" `/timeout/`}}
<p>
<em>Updating</em>:
......@@ -1711,11 +1614,7 @@ and
<a href="/pkg/os/#IsPermission"><code>IsPermission</code></a>.
</p>
<pre><!--{{code "progs/go1.go" `/os\.Open/` `/}/`}}
--> f, err := os.OpenFile(name, os.O_RDWR|os.O_CREATE|os.O_EXCL, 0600)
if os.IsExist(err) {
log.Printf(&#34;%s already exists&#34;, name)
}</pre>
{{code "/doc/progs/go1.go" `/os\.Open/` `/}/`}}
<p>
<em>Updating</em>:
......@@ -1781,21 +1680,7 @@ If a directory's contents are to be skipped,
the function should return the value <a href="/pkg/path/filepath/#variables"><code>filepath.SkipDir</code></a>
</p>
<pre><!--{{code "progs/go1.go" `/STARTWALK/` `/ENDWALK/`}}
--> markFn := func(path string, info os.FileInfo, err error) error {
if path == &#34;pictures&#34; { // 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(&#34;.&#34;, markFn)
if err != nil {
log.Fatal(err)
}</pre>
{{code "/doc/progs/go1.go" `/STARTWALK/` `/ENDWALK/`}}
<p>
<em>Updating</em>:
......@@ -1993,20 +1878,7 @@ In Go 1, <code>B</code> has new methods, analogous to those of <code>T</code>, e
logging and failure reporting.
</p>
<pre><!--{{code "progs/go1.go" `/func.*Benchmark/` `/^}/`}}
-->func BenchmarkSprintf(b *testing.B) {
// Verify correctness before running benchmark.
b.StopTimer()
got := fmt.Sprintf(&#34;%x&#34;, 23)
const expect = &#34;17&#34;
if expect != got {
b.Fatalf(&#34;expected %q; got %q&#34;, expect, got)
}
b.StartTimer()
for i := 0; i &lt; b.N; i++ {
fmt.Sprintf(&#34;%x&#34;, 23)
}
}</pre>
{{code "/doc/progs/go1.go" `/func.*Benchmark/` `/^}/`}}
<p>
<em>Updating</em>:
......
doc/go1.tmpl deleted 100644 → 0
View file @ e38c5fb2
<!--{
"Title": "Go 1 Release Notes"
}-->
{{donotedit}}
<h2 id="introduction">Introduction to Go 1</h2>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
<a href="go1compat.html">The Go 1 compatibility document</a>
explains the compatibility guidelines in more detail.
</p>
<p>
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 <code>go</code> <code>fix</code> tool can
automate much of the work needed to bring programs up to the Go 1 standard.
</p>
<p>
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.
</p>
<h2 id="language">Changes to the language</h2>
<h3 id="append">Append</h3>
<p>
The <code>append</code> 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, <code>append</code> did not provide a way to append a string to a <code>[]byte</code>,
which is another common case.
</p>
{{code "progs/go1.go" `/greeting := ..byte/` `/append.*hello/`}}
<p>
By analogy with the similar property of <code>copy</code>, 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:
</p>
{{code "progs/go1.go" `/append.*world/`}}
<p>
<em>Updating</em>:
This is a new feature, so existing code needs no changes.
</p>
<h3 id="close">Close</h3>
<p>
The <code>close</code> predeclared function provides a mechanism
for a sender to signal that no more values will be sent.
It is important to the implementation of <code>for</code> <code>range</code>
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 <code>close</code>
was being used correctly.
</p>
<p>
To close this gap, at least in part, Go 1 disallows <code>close</code> on receive-only channels.
Attempting to close such a channel is a compile-time error.
</p>
<pre>
var c chan int
var csend chan&lt;- int = c
var crecv &lt;-chan int = c
close(c) // legal
close(csend) // legal
close(crecv) // illegal
</pre>
<p>
<em>Updating</em>:
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.
</p>
<h3 id="literals">Composite literals</h3>
<p>
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.
</p>
{{code "progs/go1.go" `/type Date struct/` `/STOP/`}}
<p>
<em>Updating</em>:
This change has no effect on existing code, but the command
<code>gofmt</code> <code>-s</code> applied to existing source
will, among other things, elide explicit element types wherever permitted.
</p>
<h3 id="init">Goroutines during init</h3>
<p>
The old language defined that <code>go</code> 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 <code>init</code> 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.
</p>
<p>
In Go 1, code that uses goroutines can be called from
<code>init</code> routines and global initialization expressions
without introducing a deadlock.
</p>
{{code "progs/go1.go" `/PackageGlobal/` `/^}/`}}
<p>
<em>Updating</em>:
This is a new feature, so existing code needs no changes,
although it's possible that code that depends on goroutines not starting before <code>main</code> will break.
There was no such code in the standard repository.
</p>
<h3 id="rune">The rune type</h3>
<p>
The language spec allows the <code>int</code> type to be 32 or 64 bits wide, but current implementations set <code>int</code> to 32 bits even on 64-bit platforms.
It would be preferable to have <code>int</code> 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 <code>int</code> type was also used to hold Unicode code points: each code point would waste an extra 32 bits of storage if <code>int</code> grew from 32 bits to 64.
</p>
<p>
To make changing to 64-bit <code>int</code> feasible,
Go 1 introduces a new basic type, <code>rune</code>, to represent
individual Unicode code points.
It is an alias for <code>int32</code>, analogous to <code>byte</code>
as an alias for <code>uint8</code>.
</p>
<p>
Character literals such as <code>'a'</code>, <code>'語'</code>, and <code>'\u0345'</code>
now have default type <code>rune</code>,
analogous to <code>1.0</code> having default type <code>float64</code>.
A variable initialized to a character constant will therefore
have type <code>rune</code> unless otherwise specified.
</p>
<p>
Libraries have been updated to use <code>rune</code> rather than <code>int</code>
when appropriate. For instance, the functions <code>unicode.ToLower</code> and
relatives now take and return a <code>rune</code>.
</p>
{{code "progs/go1.go" `/STARTRUNE/` `/ENDRUNE/`}}
<p>
<em>Updating</em>:
Most source code will be unaffected by this because the type inference from
<code>:=</code> initializers introduces the new type silently, and it propagates
from there.
Some code may get type errors that a trivial conversion will resolve.
</p>
<h3 id="error">The error type</h3>
<p>
Go 1 introduces a new built-in type, <code>error</code>, which has the following definition:
</p>
<pre>
type error interface {
Error() string
}
</pre>
<p>
Since the consequences of this type are all in the package library,
it is discussed <a href="#errors">below</a>.
</p>
<h3 id="delete">Deleting from maps</h3>
<p>
In the old language, to delete the entry with key <code>k</code> from map <code>m</code>, one wrote the statement,
</p>
<pre>
m[k] = value, false
</pre>
<p>
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 <code>false</code>.
It did the job but was odd and a point of contention.
</p>
<p>
In Go 1, that syntax has gone; instead there is a new built-in
function, <code>delete</code>. The call
</p>
{{code "progs/go1.go" `/delete\(m, k\)/`}}
<p>
will delete the map entry retrieved by the expression <code>m[k]</code>.
There is no return value. Deleting a non-existent entry is a no-op.
</p>
<p>
<em>Updating</em>:
Running <code>go</code> <code>fix</code> will convert expressions of the form <code>m[k] = value,
false</code> into <code>delete(m, k)</code> when it is clear that
the ignored value can be safely discarded from the program and
<code>false</code> refers to the predefined boolean constant.
The fix tool
will flag other uses of the syntax for inspection by the programmer.
</p>
<h3 id="iteration">Iterating in maps</h3>
<p>
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.
</p>
<p>
In Go 1, the order in which elements are visited when iterating
over a map using a <code>for</code> <code>range</code> 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.
</p>
<p>
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.
</p>
{{code "progs/go1.go" `/Sunday/` `/^ }/`}}
<p>
<em>Updating</em>:
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.
</p>
<h3 id="multiple_assignment">Multiple assignment</h3>
<p>
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.
</p>
<p>
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.
</p>
<p>
These examples illustrate the behavior.
</p>
{{code "progs/go1.go" `/sa :=/` `/then sc.0. = 2/`}}
<p>
<em>Updating</em>:
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.
</p>
<h3 id="shadowing">Returns and shadowed variables</h3>
<p>
A common mistake is to use <code>return</code> (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 <em>shadowing</em>: the result variable has been shadowed by another variable with the same name declared in an inner scope.
</p>
<p>
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.)
</p>
<p>
This function implicitly returns a shadowed return value and will be rejected by the compiler:
</p>
<pre>
func Bug() (i, j, k int) {
for i = 0; i &lt; 5; i++ {
for j := 0; j &lt; 5; j++ { // Redeclares j.
k += i*j
if k > 100 {
return // Rejected: j is shadowed here.
}
}
}
return // OK: j is not shadowed here.
}
</pre>
<p>
<em>Updating</em>:
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.
</p>
<h3 id="unexported">Copying structs with unexported fields</h3>
<p>
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 <code>copy</code> and <code>append</code> have never honored the restriction.
</p>
<p>
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 <code>time.Time</code> and
<code>reflect.Value</code> are examples of types taking advantage of this new property.
</p>
<p>
As an example, if package <code>p</code> includes the definitions,
</p>
<pre>
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)
}
</pre>
<p>
a package that imports <code>p</code> can assign and copy values of type
<code>p.Struct</code> 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
</p>
<pre>
import "p"
myStruct := p.NewStruct(23)
copyOfMyStruct := myStruct
fmt.Println(myStruct, copyOfMyStruct)
</pre>
<p>
will show that the secret field of the struct has been copied to the new value.
</p>
<p>
<em>Updating</em>:
This is a new feature, so existing code needs no changes.
</p>
<h3 id="equality">Equality</h3>
<p>
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.
</p>
<p>
Go 1 addressed these issues.
First, structs and arrays can be compared for equality and inequality
(<code>==</code> and <code>!=</code>),
and therefore be used as map keys,
provided they are composed from elements for which equality is also defined,
using element-wise comparison.
</p>
{{code "progs/go1.go" `/type Day struct/` `/Printf/`}}
<p>
Second, Go 1 removes the definition of equality for function values,
except for comparison with <code>nil</code>.
Finally, map equality is gone too, also except for comparison with <code>nil</code>.
</p>
<p>
Note that equality is still undefined for slices, for which the
calculation is in general infeasible. Also note that the ordered
comparison operators (<code>&lt;</code> <code>&lt;=</code>
<code>&gt;</code> <code>&gt;=</code>) are still undefined for
structs and arrays.
<p>
<em>Updating</em>:
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.
</p>
<h2 id="packages">The package hierarchy</h2>
<p>
Go 1 addresses many deficiencies in the old standard library and
cleans up a number of packages, making them more internally consistent
and portable.
</p>
<p>
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.
</p>
<h3 id="hierarchy">The package hierarchy</h3>
<p>
Go 1 has a rearranged package hierarchy that groups related items
into subdirectories. For instance, <code>utf8</code> and
<code>utf16</code> now occupy subdirectories of <code>unicode</code>.
Also, <a href="#subrepo">some packages</a> have moved into
subrepositories of
<a href="http://code.google.com/p/go"><code>code.google.com/p/go</code></a>
while <a href="#deleted">others</a> have been deleted outright.
</p>
<table class="codetable" frame="border" summary="Moved packages">
<colgroup align="left" width="60%"></colgroup>
<colgroup align="left" width="40%"></colgroup>
<tr>
<th align="left">Old path</th>
<th align="left">New path</th>
</tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>asn1</td> <td>encoding/asn1</td></tr>
<tr><td>csv</td> <td>encoding/csv</td></tr>
<tr><td>gob</td> <td>encoding/gob</td></tr>
<tr><td>json</td> <td>encoding/json</td></tr>
<tr><td>xml</td> <td>encoding/xml</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>exp/template/html</td> <td>html/template</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>big</td> <td>math/big</td></tr>
<tr><td>cmath</td> <td>math/cmplx</td></tr>
<tr><td>rand</td> <td>math/rand</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>http</td> <td>net/http</td></tr>
<tr><td>http/cgi</td> <td>net/http/cgi</td></tr>
<tr><td>http/fcgi</td> <td>net/http/fcgi</td></tr>
<tr><td>http/httptest</td> <td>net/http/httptest</td></tr>
<tr><td>http/pprof</td> <td>net/http/pprof</td></tr>
<tr><td>mail</td> <td>net/mail</td></tr>
<tr><td>rpc</td> <td>net/rpc</td></tr>
<tr><td>rpc/jsonrpc</td> <td>net/rpc/jsonrpc</td></tr>
<tr><td>smtp</td> <td>net/smtp</td></tr>
<tr><td>url</td> <td>net/url</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>exec</td> <td>os/exec</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>scanner</td> <td>text/scanner</td></tr>
<tr><td>tabwriter</td> <td>text/tabwriter</td></tr>
<tr><td>template</td> <td>text/template</td></tr>
<tr><td>template/parse</td> <td>text/template/parse</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>utf8</td> <td>unicode/utf8</td></tr>
<tr><td>utf16</td> <td>unicode/utf16</td></tr>
</table>
<p>
Note that the package names for the old <code>cmath</code> and
<code>exp/template/html</code> packages have changed to <code>cmplx</code>
and <code>template</code>.
</p>
<p>
<em>Updating</em>:
Running <code>go</code> <code>fix</code> 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.
</p>
<h3 id="exp">The package tree exp</h3>
<p>
Because they are not standardized, the packages under the <code>exp</code> directory will not be available in the
standard Go 1 release distributions, although they will be available in source code form
in <a href="http://code.google.com/p/go/">the repository</a> for
developers who wish to use them.
</p>
<p>
Several packages have moved under <code>exp</code> at the time of Go 1's release:
</p>
<ul>
<li><code>ebnf</code></li>
<li><code>html</code><sup>&#8224;</sup></li>
<li><code>go/types</code></li>
</ul>
<p>
(<sup>&#8224;</sup>The <code>EscapeString</code> and <code>UnescapeString</code> types remain
in package <code>html</code>.)
</p>
<p>
All these packages are available under the same names, with the prefix <code>exp/</code>: <code>exp/ebnf</code> etc.
</p>
<p>
Also, the <code>utf8.String</code> type has been moved to its own package, <code>exp/utf8string</code>.
</p>
<p>
Finally, the <code>gotype</code> command now resides in <code>exp/gotype</code>, while
<code>ebnflint</code> is now in <code>exp/ebnflint</code>.
If they are installed, they now reside in <code>$GOROOT/bin/tool</code>.
</p>
<p>
<em>Updating</em>:
Code that uses packages in <code>exp</code> will need to be updated by hand,
or else compiled from an installation that has <code>exp</code> available.
The <code>go</code> <code>fix</code> tool or the compiler will complain about such uses.
</p>
<h3 id="old">The package tree old</h3>
<p>
Because they are deprecated, the packages under the <code>old</code> 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.
</p>
<p>
The packages in their new locations are:
</p>
<ul>
<li><code>old/netchan</code></li>
<li><code>old/regexp</code></li>
<li><code>old/template</code></li>
</ul>
<p>
<em>Updating</em>:
Code that uses packages now in <code>old</code> will need to be updated by hand,
or else compiled from an installation that has <code>old</code> available.
The <code>go</code> <code>fix</code> tool will warn about such uses.
</p>
<h3 id="deleted">Deleted packages</h3>
<p>
Go 1 deletes several packages outright:
</p>
<ul>
<li><code>container/vector</code></li>
<li><code>exp/datafmt</code></li>
<li><code>go/typechecker</code></li>
<li><code>try</code></li>
</ul>
<p>
and also the command <code>gotry</code>.
</p>
<p>
<em>Updating</em>:
Code that uses <code>container/vector</code> should be updated to use
slices directly. See
<a href="http://code.google.com/p/go-wiki/wiki/SliceTricks">the Go
Language Community Wiki</a> for some suggestions.
Code that uses the other packages (there should be almost zero) will need to be rethought.
</p>
<h3 id="subrepo">Packages moving to subrepositories</h3>
<p>
Go 1 has moved a number of packages into other repositories, usually sub-repositories of
<a href="http://code.google.com/p/go/">the main Go repository</a>.
This table lists the old and new import paths:
<table class="codetable" frame="border" summary="Sub-repositories">
<colgroup align="left" width="40%"></colgroup>
<colgroup align="left" width="60%"></colgroup>
<tr>
<th align="left">Old</th>
<th align="left">New</th>
</tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>crypto/bcrypt</td> <td>code.google.com/p/go.crypto/bcrypt</tr>
<tr><td>crypto/blowfish</td> <td>code.google.com/p/go.crypto/blowfish</tr>
<tr><td>crypto/cast5</td> <td>code.google.com/p/go.crypto/cast5</tr>
<tr><td>crypto/md4</td> <td>code.google.com/p/go.crypto/md4</tr>
<tr><td>crypto/ocsp</td> <td>code.google.com/p/go.crypto/ocsp</tr>
<tr><td>crypto/openpgp</td> <td>code.google.com/p/go.crypto/openpgp</tr>
<tr><td>crypto/openpgp/armor</td> <td>code.google.com/p/go.crypto/openpgp/armor</tr>
<tr><td>crypto/openpgp/elgamal</td> <td>code.google.com/p/go.crypto/openpgp/elgamal</tr>
<tr><td>crypto/openpgp/errors</td> <td>code.google.com/p/go.crypto/openpgp/errors</tr>
<tr><td>crypto/openpgp/packet</td> <td>code.google.com/p/go.crypto/openpgp/packet</tr>
<tr><td>crypto/openpgp/s2k</td> <td>code.google.com/p/go.crypto/openpgp/s2k</tr>
<tr><td>crypto/ripemd160</td> <td>code.google.com/p/go.crypto/ripemd160</tr>
<tr><td>crypto/twofish</td> <td>code.google.com/p/go.crypto/twofish</tr>
<tr><td>crypto/xtea</td> <td>code.google.com/p/go.crypto/xtea</tr>
<tr><td>exp/ssh</td> <td>code.google.com/p/go.crypto/ssh</tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>image/bmp</td> <td>code.google.com/p/go.image/bmp</tr>
<tr><td>image/tiff</td> <td>code.google.com/p/go.image/tiff</tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>net/dict</td> <td>code.google.com/p/go.net/dict</tr>
<tr><td>net/websocket</td> <td>code.google.com/p/go.net/websocket</tr>
<tr><td>exp/spdy</td> <td>code.google.com/p/go.net/spdy</tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>encoding/git85</td> <td>code.google.com/p/go.codereview/git85</tr>
<tr><td>patch</td> <td>code.google.com/p/go.codereview/patch</tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>exp/wingui</td> <td>code.google.com/p/gowingui</tr>
</table>
<p>
<em>Updating</em>:
Running <code>go</code> <code>fix</code> 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 <code>go install</code> command.
</p>
<h2 id="major">Major changes to the library</h2>
<p>
This section describes significant changes to the core libraries, the ones that
affect the most programs.
</p>
<h3 id="errors">The error type and errors package</h3>
<p>
The placement of <code>os.Error</code> in package <code>os</code> is mostly historical: errors first came up when implementing package <code>os</code>, 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 <code>Errors</code> in packages that <code>os</code> depends on, like <code>syscall</code>.
Also, having <code>Error</code> in <code>os</code> introduces many dependencies on <code>os</code> that would otherwise not exist.
</p>
<p>
Go 1 solves these problems by introducing a built-in <code>error</code> interface type and a separate <code>errors</code> package (analogous to <code>bytes</code> and <code>strings</code>) that contains utility functions.
It replaces <code>os.NewError</code> with
<a href="/pkg/errors/#New"><code>errors.New</code></a>,
giving errors a more central place in the environment.
</p>
<p>
So the widely-used <code>String</code> method does not cause accidental satisfaction
of the <code>error</code> interface, the <code>error</code> interface uses instead
the name <code>Error</code> for that method:
</p>
<pre>
type error interface {
Error() string
}
</pre>
<p>
The <code>fmt</code> library automatically invokes <code>Error</code>, as it already
does for <code>String</code>, for easy printing of error values.
</p>
{{code "progs/go1.go" `/START ERROR EXAMPLE/` `/END ERROR EXAMPLE/`}}
<p>
All standard packages have been updated to use the new interface; the old <code>os.Error</code> is gone.
</p>
<p>
A new package, <a href="/pkg/errors/"><code>errors</code></a>, contains the function
</p>
<pre>
func New(text string) error
</pre>
<p>
to turn a string into an error. It replaces the old <code>os.NewError</code>.
</p>
{{code "progs/go1.go" `/ErrSyntax/`}}
<p>
<em>Updating</em>:
Running <code>go</code> <code>fix</code> will update almost all code affected by the change.
Code that defines error types with a <code>String</code> method will need to be updated
by hand to rename the methods to <code>Error</code>.
</p>
<h3 id="errno">System call errors</h3>
<p>
The old <code>syscall</code> package, which predated <code>os.Error</code>
(and just about everything else),
returned errors as <code>int</code> values.
In turn, the <code>os</code> package forwarded many of these errors, such
as <code>EINVAL</code>, but using a different set of errors on each platform.
This behavior was unpleasant and unportable.
</p>
<p>
In Go 1, the
<a href="/pkg/syscall/"><code>syscall</code></a>
package instead returns an <code>error</code> for system call errors.
On Unix, the implementation is done by a
<a href="/pkg/syscall/#Errno"><code>syscall.Errno</code></a> type
that satisfies <code>error</code> and replaces the old <code>os.Errno</code>.
</p>
<p>
The changes affecting <code>os.EINVAL</code> and relatives are
described <a href="#os">elsewhere</a>.
<p>
<em>Updating</em>:
Running <code>go</code> <code>fix</code> will update almost all code affected by the change.
Regardless, most code should use the <code>os</code> package
rather than <code>syscall</code> and so will be unaffected.
</p>
<h3 id="time">Time</h3>
<p>
Time is always a challenge to support well in a programming language.
The old Go <code>time</code> package had <code>int64</code> units, no
real type safety,
and no distinction between absolute times and durations.
</p>
<p>
One of the most sweeping changes in the Go 1 library is therefore a
complete redesign of the
<a href="/pkg/time/"><code>time</code></a> package.
Instead of an integer number of nanoseconds as an <code>int64</code>,
and a separate <code>*time.Time</code> type to deal with human
units such as hours and years,
there are now two fundamental types:
<a href="/pkg/time/#Time"><code>time.Time</code></a>
(a value, so the <code>*</code> is gone), which represents a moment in time;
and <a href="/pkg/time/#Duration"><code>time.Duration</code></a>,
which represents an interval.
Both have nanosecond resolution.
A <code>Time</code> can represent any time into the ancient
past and remote future, while a <code>Duration</code> 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 <code>time.Second</code>.
</p>
<p>
Among the new methods are things like
<a href="/pkg/time/#Time.Add"><code>Time.Add</code></a>,
which adds a <code>Duration</code> to a <code>Time</code>, and
<a href="/pkg/time/#Time.Sub"><code>Time.Sub</code></a>,
which subtracts two <code>Times</code> to yield a <code>Duration</code>.
</p>
<p>
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:
<a href="/pkg/time/#Unix"><code>time.Unix</code></a>
and the <a href="/pkg/time/#Time.Unix"><code>Unix</code></a>
and <a href="/pkg/time/#Time.UnixNano"><code>UnixNano</code></a> methods
of the <code>Time</code> type.
In particular,
<a href="/pkg/time/#Now"><code>time.Now</code></a>
returns a <code>time.Time</code> value rather than, in the old
API, an integer nanosecond count since the Unix epoch.
</p>
{{code "progs/go1.go" `/sleepUntil/` `/^}/`}}
<p>
The new types, methods, and constants have been propagated through
all the standard packages that use time, such as <code>os</code> and
its representation of file time stamps.
</p>
<p>
<em>Updating</em>:
The <code>go</code> <code>fix</code> tool will update many uses of the old <code>time</code> package to use the new
types and methods, although it does not replace values such as <code>1e9</code>
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.
</p>
<h2 id="minor">Minor changes to the library</h2>
<p>
This section describes smaller changes, such as those to less commonly
used packages or that affect
few programs beyond the need to run <code>go</code> <code>fix</code>.
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.
</p>
<h3 id="archive_zip">The archive/zip package</h3>
<p>
In Go 1, <a href="/pkg/archive/zip/#Writer"><code>*zip.Writer</code></a> no
longer has a <code>Write</code> method. Its presence was a mistake.
</p>
<p>
<em>Updating</em>:
What little code is affected will be caught by the compiler and must be updated by hand.
</p>
<h3 id="bufio">The bufio package</h3>
<p>
In Go 1, <a href="/pkg/bufio/#NewReaderSize"><code>bufio.NewReaderSize</code></a>
and
<a href="/pkg/bufio/#NewWriterSize"><code>bufio.NewWriterSize</code></a>
functions no longer return an error for invalid sizes.
If the argument size is too small or invalid, it is adjusted.
</p>
<p>
<em>Updating</em>:
Running <code>go</code> <code>fix</code> 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.
</p>
<h3 id="compress">The compress/flate, compress/gzip and compress/zlib packages</h3>
<p>
In Go 1, the <code>NewWriterXxx</code> functions in
<a href="/pkg/compress/flate"><code>compress/flate</code></a>,
<a href="/pkg/compress/gzip"><code>compress/gzip</code></a> and
<a href="/pkg/compress/zlib"><code>compress/zlib</code></a>
all return <code>(*Writer, error)</code> if they take a compression level,
and <code>*Writer</code> otherwise. Package <code>gzip</code>'s
<code>Compressor</code> and <code>Decompressor</code> types have been renamed
to <code>Writer</code> and <code>Reader</code>. Package <code>flate</code>'s
<code>WrongValueError</code> type has been removed.
</p>
<p>
<em>Updating</em>
Running <code>go</code> <code>fix</code> 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.
</p>
<h3 id="crypto_aes_des">The crypto/aes and crypto/des packages</h3>
<p>
In Go 1, the <code>Reset</code> method has been removed. Go does not guarantee
that memory is not copied and therefore this method was misleading.
</p>
<p>
The cipher-specific types <code>*aes.Cipher</code>, <code>*des.Cipher</code>,
and <code>*des.TripleDESCipher</code> have been removed in favor of
<code>cipher.Block</code>.
</p>
<p>
<em>Updating</em>:
Remove the calls to Reset. Replace uses of the specific cipher types with
cipher.Block.
</p>
<h3 id="crypto_elliptic">The crypto/elliptic package</h3>
<p>
In Go 1, <a href="/pkg/crypto/elliptic/#Curve"><code>elliptic.Curve</code></a>
has been made an interface to permit alternative implementations. The curve
parameters have been moved to the
<a href="/pkg/crypto/elliptic/#CurveParams"><code>elliptic.CurveParams</code></a>
structure.
</p>
<p>
<em>Updating</em>:
Existing users of <code>*elliptic.Curve</code> will need to change to
simply <code>elliptic.Curve</code>. Calls to <code>Marshal</code>,
<code>Unmarshal</code> and <code>GenerateKey</code> are now functions
in <code>crypto/elliptic</code> that take an <code>elliptic.Curve</code>
as their first argument.
</p>
<h3 id="crypto_hmac">The crypto/hmac package</h3>
<p>
In Go 1, the hash-specific functions, such as <code>hmac.NewMD5</code>, have
been removed from <code>crypto/hmac</code>. Instead, <code>hmac.New</code> takes
a function that returns a <code>hash.Hash</code>, such as <code>md5.New</code>.
</p>
<p>
<em>Updating</em>:
Running <code>go</code> <code>fix</code> will perform the needed changes.
</p>
<h3 id="crypto_x509">The crypto/x509 package</h3>
<p>
In Go 1, the
<a href="/pkg/crypto/x509/#CreateCertificate"><code>CreateCertificate</code></a>
and
<a href="/pkg/crypto/x509/#CreateCRL"><code>CreateCRL</code></a>
functions in <code>crypto/x509</code> have been altered to take an
<code>interface{}</code> where they previously took a <code>*rsa.PublicKey</code>
or <code>*rsa.PrivateKey</code>. This will allow other public key algorithms
to be implemented in the future.
</p>
<p>
<em>Updating</em>:
No changes will be needed.
</p>
<h3 id="encoding_binary">The encoding/binary package</h3>
<p>
In Go 1, the <code>binary.TotalSize</code> function has been replaced by
<a href="/pkg/encoding/binary/#Size"><code>Size</code></a>,
which takes an <code>interface{}</code> argument rather than
a <code>reflect.Value</code>.
</p>
<p>
<em>Updating</em>:
What little code is affected will be caught by the compiler and must be updated by hand.
</p>
<h3 id="encoding_xml">The encoding/xml package</h3>
<p>
In Go 1, the <a href="/pkg/encoding/xml/"><code>xml</code></a> package
has been brought closer in design to the other marshaling packages such
as <a href="/pkg/encoding/gob/"><code>encoding/gob</code></a>.
</p>
<p>
The old <code>Parser</code> type is renamed
<a href="/pkg/encoding/xml/#Decoder"><code>Decoder</code></a> and has a new
<a href="/pkg/encoding/xml/#Decoder.Decode"><code>Decode</code></a> method. An
<a href="/pkg/encoding/xml/#Encoder"><code>Encoder</code></a> type was also introduced.
</p>
<p>
The functions <a href="/pkg/encoding/xml/#Marshal"><code>Marshal</code></a>
and <a href="/pkg/encoding/xml/#Unmarshal"><code>Unmarshal</code></a>
work with <code>[]byte</code> values now. To work with streams,
use the new <a href="/pkg/encoding/xml/#Encoder"><code>Encoder</code></a>
and <a href="/pkg/encoding/xml/#Decoder"><code>Decoder</code></a> types.
</p>
<p>
When marshaling or unmarshaling values, the format of supported flags in
field tags has changed to be closer to the
<a href="/pkg/encoding/json"><code>json</code></a> package
(<code>`xml:"name,flag"`</code>). The matching done between field tags, field
names, and the XML attribute and element names is now case-sensitive.
The <code>XMLName</code> field tag, if present, must also match the name
of the XML element being marshaled.
</p>
<p>
<em>Updating</em>:
Running <code>go</code> <code>fix</code> will update most uses of the package except for some calls to
<code>Unmarshal</code>. 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
<code>"attr"</code> is now written <code>",attr"</code> while plain
<code>"attr"</code> remains valid but with a different meaning.
</p>
<h3 id="expvar">The expvar package</h3>
<p>
In Go 1, the <code>RemoveAll</code> function has been removed.
The <code>Iter</code> function and Iter method on <code>*Map</code> have
been replaced by
<a href="/pkg/expvar/#Do"><code>Do</code></a>
and
<a href="/pkg/expvar/#Map.Do"><code>(*Map).Do</code></a>.
</p>
<p>
<em>Updating</em>:
Most code using <code>expvar</code> will not need changing. The rare code that used
<code>Iter</code> can be updated to pass a closure to <code>Do</code> to achieve the same effect.
</p>
<h3 id="flag">The flag package</h3>
<p>
In Go 1, the interface <a href="/pkg/flag/#Value"><code>flag.Value</code></a> has changed slightly.
The <code>Set</code> method now returns an <code>error</code> instead of
a <code>bool</code> to indicate success or failure.
</p>
<p>
There is also a new kind of flag, <code>Duration</code>, to support argument
values specifying time intervals.
Values for such flags must be given units, just as <code>time.Duration</code>
formats them: <code>10s</code>, <code>1h30m</code>, etc.
</p>
{{code "progs/go1.go" `/timeout/`}}
<p>
<em>Updating</em>:
Programs that implement their own flags will need minor manual fixes to update their
<code>Set</code> methods.
The <code>Duration</code> flag is new and affects no existing code.
</p>
<h3 id="go">The go/* packages</h3>
<p>
Several packages under <code>go</code> have slightly revised APIs.
</p>
<p>
A concrete <code>Mode</code> type was introduced for configuration mode flags
in the packages
<a href="/pkg/go/scanner/"><code>go/scanner</code></a>,
<a href="/pkg/go/parser/"><code>go/parser</code></a>,
<a href="/pkg/go/printer/"><code>go/printer</code></a>, and
<a href="/pkg/go/doc/"><code>go/doc</code></a>.
</p>
<p>
The modes <code>AllowIllegalChars</code> and <code>InsertSemis</code> have been removed
from the <a href="/pkg/go/scanner/"><code>go/scanner</code></a> package. They were mostly
useful for scanning text other then Go source files. Instead, the
<a href="/pkg/text/scanner/"><code>text/scanner</code></a> package should be used
for that purpose.
</p>
<p>
The <a href="/pkg/go/scanner/#ErrorHandler"><code>ErrorHandler</code></a> provided
to the scanner's <a href="/pkg/go/scanner/#Scanner.Init"><code>Init</code></a> method is
now simply a function rather than an interface. The <code>ErrorVector</code> type has
been removed in favor of the (existing) <a href="/pkg/go/scanner/#ErrorList"><code>ErrorList</code></a>
type, and the <code>ErrorVector</code> methods have been migrated. Instead of embedding
an <code>ErrorVector</code> in a client of the scanner, now a client should maintain
an <code>ErrorList</code>.
</p>
<p>
The set of parse functions provided by the <a href="/pkg/go/parser/"><code>go/parser</code></a>
package has been reduced to the primary parse function
<a href="/pkg/go/parser/#ParseFile"><code>ParseFile</code></a>, and a couple of
convenience functions <a href="/pkg/go/parser/#ParseDir"><code>ParseDir</code></a>
and <a href="/pkg/go/parser/#ParseExpr"><code>ParseExpr</code></a>.
</p>
<p>
The <a href="/pkg/go/printer/"><code>go/printer</code></a> package supports an additional
configuration mode <a href="/pkg/go/printer/#Mode"><code>SourcePos</code></a>;
if set, the printer will emit <code>//line</code> comments such that the generated
output contains the original source code position information. The new type
<a href="/pkg/go/printer/#CommentedNode"><code>CommentedNode</code></a> can be
used to provide comments associated with an arbitrary
<a href="/pkg/go/ast/#Node"><code>ast.Node</code></a> (until now only
<a href="/pkg/go/ast/#File"><code>ast.File</code></a> carried comment information).
</p>
<p>
The type names of the <a href="/pkg/go/doc/"><code>go/doc</code></a> package have been
streamlined by removing the <code>Doc</code> suffix: <code>PackageDoc</code>
is now <code>Package</code>, <code>ValueDoc</code> is <code>Value</code>, etc.
Also, all types now consistently have a <code>Name</code> field (or <code>Names</code>,
in the case of type <code>Value</code>) and <code>Type.Factories</code> has become
<code>Type.Funcs</code>.
Instead of calling <code>doc.NewPackageDoc(pkg, importpath)</code>,
documentation for a package is created with:
</p>
<pre>
doc.New(pkg, importpath, mode)
</pre>
<p>
where the new <code>mode</code> parameter specifies the operation mode:
if set to <a href="/pkg/go/doc/#AllDecls"><code>AllDecls</code></a>, all declarations
(not just exported ones) are considered.
The function <code>NewFileDoc</code> was removed, and the function
<code>CommentText</code> has become the method
<a href="/pkg/go/ast/#Text"><code>Text</code></a> of
<a href="/pkg/go/ast/#CommentGroup"><code>ast.CommentGroup</code></a>.
</p>
<p>
In package <a href="/pkg/go/token/"><code>go/token</code></a>, the
<a href="/pkg/go/token/#FileSet"><code>token.FileSet</code></a> method <code>Files</code>
(which originally returned a channel of <code>*token.File</code>s) has been replaced
with the iterator <a href="/pkg/go/token/#FileSet.Iterate"><code>Iterate</code></a> that
accepts a function argument instead.
</p>
<p>
In package <a href="/pkg/go/build/"><code>go/build</code></a>, the API
has been nearly completely replaced.
The package still computes Go package information
but it does not run the build: the <code>Cmd</code> and <code>Script</code>
types are gone.
(To build code, use the new
<a href="/cmd/go/"><code>go</code></a> command instead.)
The <code>DirInfo</code> type is now named
<a href="/pkg/go/build/#Package"><code>Package</code></a>.
<code>FindTree</code> and <code>ScanDir</code> are replaced by
<a href="/pkg/go/build/#Import"><code>Import</code></a>
and
<a href="/pkg/go/build/#ImportDir"><code>ImportDir</code></a>.
</p>
<p>
<em>Updating</em>:
Code that uses packages in <code>go</code> will have to be updated by hand; the
compiler will reject incorrect uses. Templates used in conjunction with any of the
<code>go/doc</code> types may need manual fixes; the renamed fields will lead
to run-time errors.
</p>
<h3 id="hash">The hash package</h3>
<p>
In Go 1, the definition of <a href="/pkg/hash/#Hash"><code>hash.Hash</code></a> includes
a new method, <code>BlockSize</code>. This new method is used primarily in the
cryptographic libraries.
</p>
<p>
The <code>Sum</code> method of the
<a href="/pkg/hash/#Hash"><code>hash.Hash</code></a> interface now takes a
<code>[]byte</code> argument, to which the hash value will be appended.
The previous behavior can be recreated by adding a <code>nil</code> argument to the call.
</p>
<p>
<em>Updating</em>:
Existing implementations of <code>hash.Hash</code> will need to add a
<code>BlockSize</code> method. Hashes that process the input one byte at
a time can implement <code>BlockSize</code> to return 1.
Running <code>go</code> <code>fix</code> will update calls to the <code>Sum</code> methods of the various
implementations of <code>hash.Hash</code>.
</p>
<p>
<em>Updating</em>:
Since the package's functionality is new, no updating is necessary.
</p>
<h3 id="http">The http package</h3>
<p>
In Go 1 the <a href="/pkg/net/http/"><code>http</code></a> package is refactored,
putting some of the utilities into a
<a href="/pkg/net/httputil/"><code>httputil</code></a> subdirectory.
These pieces are only rarely needed by HTTP clients.
The affected items are:
</p>
<ul>
<li>ClientConn</li>
<li>DumpRequest</li>
<li>DumpRequest</li>
<li>DumpRequestOut</li>
<li>DumpResponse</li>
<li>NewChunkedReader</li>
<li>NewChunkedWriter</li>
<li>NewClientConn</li>
<li>NewProxyClientConn</li>
<li>NewServerConn</li>
<li>NewSingleHostReverseProxy</li>
<li>ReverseProxy</li>
<li>ServerConn</li>
</ul>
<p>
The <code>Request.RawURL</code> field has been removed; it was a
historical artifact.
</p>
<p>
The <code>Handle</code> and <code>HandleFunc</code>
functions, and the similarly-named methods of <code>ServeMux</code>,
now panic if an attempt is made to register the same pattern twice.
</p>
<p>
<em>Updating</em>:
Running <code>go</code> <code>fix</code> will update the few programs that are affected except for
uses of <code>RawURL</code>, which must be fixed by hand.
</p>
<h3 id="image">The image package</h3>
<p>
The <a href="/pkg/image/"><code>image</code></a> package has had a number of
minor changes, rearrangements and renamings.
</p>
<p>
Most of the color handling code has been moved into its own package,
<a href="/pkg/image/color/"><code>image/color</code></a>.
For the elements that moved, a symmetry arises; for instance,
each pixel of an
<a href="/pkg/image/#RGBA"><code>image.RGBA</code></a>
is a
<a href="/pkg/image/color/#RGBA"><code>color.RGBA</code></a>.
</p>
<p>
The old <code>image/ycbcr</code> package has been folded, with some
renamings, into the
<a href="/pkg/image/"><code>image</code></a>
and
<a href="/pkg/image/color/"><code>image/color</code></a>
packages.
</p>
<p>
The old <code>image.ColorImage</code> type is still in the <code>image</code>
package but has been renamed
<a href="/pkg/image/#Uniform"><code>image.Uniform</code></a>,
while <code>image.Tiled</code> has been removed.
</p>
<p>
This table lists the renamings.
</p>
<table class="codetable" frame="border" summary="image renames">
<colgroup align="left" width="50%"></colgroup>
<colgroup align="left" width="50%"></colgroup>
<tr>
<th align="left">Old</th>
<th align="left">New</th>
</tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>image.Color</td> <td>color.Color</td></tr>
<tr><td>image.ColorModel</td> <td>color.Model</td></tr>
<tr><td>image.ColorModelFunc</td> <td>color.ModelFunc</td></tr>
<tr><td>image.PalettedColorModel</td> <td>color.Palette</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>image.RGBAColor</td> <td>color.RGBA</td></tr>
<tr><td>image.RGBA64Color</td> <td>color.RGBA64</td></tr>
<tr><td>image.NRGBAColor</td> <td>color.NRGBA</td></tr>
<tr><td>image.NRGBA64Color</td> <td>color.NRGBA64</td></tr>
<tr><td>image.AlphaColor</td> <td>color.Alpha</td></tr>
<tr><td>image.Alpha16Color</td> <td>color.Alpha16</td></tr>
<tr><td>image.GrayColor</td> <td>color.Gray</td></tr>
<tr><td>image.Gray16Color</td> <td>color.Gray16</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>image.RGBAColorModel</td> <td>color.RGBAModel</td></tr>
<tr><td>image.RGBA64ColorModel</td> <td>color.RGBA64Model</td></tr>
<tr><td>image.NRGBAColorModel</td> <td>color.NRGBAModel</td></tr>
<tr><td>image.NRGBA64ColorModel</td> <td>color.NRGBA64Model</td></tr>
<tr><td>image.AlphaColorModel</td> <td>color.AlphaModel</td></tr>
<tr><td>image.Alpha16ColorModel</td> <td>color.Alpha16Model</td></tr>
<tr><td>image.GrayColorModel</td> <td>color.GrayModel</td></tr>
<tr><td>image.Gray16ColorModel</td> <td>color.Gray16Model</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>ycbcr.RGBToYCbCr</td> <td>color.RGBToYCbCr</td></tr>
<tr><td>ycbcr.YCbCrToRGB</td> <td>color.YCbCrToRGB</td></tr>
<tr><td>ycbcr.YCbCrColorModel</td> <td>color.YCbCrModel</td></tr>
<tr><td>ycbcr.YCbCrColor</td> <td>color.YCbCr</td></tr>
<tr><td>ycbcr.YCbCr</td> <td>image.YCbCr</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>ycbcr.SubsampleRatio444</td> <td>image.YCbCrSubsampleRatio444</td></tr>
<tr><td>ycbcr.SubsampleRatio422</td> <td>image.YCbCrSubsampleRatio422</td></tr>
<tr><td>ycbcr.SubsampleRatio420</td> <td>image.YCbCrSubsampleRatio420</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>image.ColorImage</td> <td>image.Uniform</td></tr>
</table>
<p>
The image package's <code>New</code> functions
(<a href="/pkg/image/#NewRGBA"><code>NewRGBA</code></a>,
<a href="/pkg/image/#NewRGBA64"><code>NewRGBA64</code></a>, etc.)
take an <a href="/pkg/image/#Rectangle"><code>image.Rectangle</code></a> as an argument
instead of four integers.
</p>
<p>
Finally, there are new predefined <code>color.Color</code> variables
<a href="/pkg/image/color/#Black"><code>color.Black</code></a>,
<a href="/pkg/image/color/#White"><code>color.White</code></a>,
<a href="/pkg/image/color/#Opaque"><code>color.Opaque</code></a>
and
<a href="/pkg/image/color/#Transparent"><code>color.Transparent</code></a>.
</p>
<p>
<em>Updating</em>:
Running <code>go</code> <code>fix</code> will update almost all code affected by the change.
</p>
<h3 id="log_syslog">The log/syslog package</h3>
<p>
In Go 1, the <a href="/pkg/log/syslog/#NewLogger"><code>syslog.NewLogger</code></a>
function returns an error as well as a <code>log.Logger</code>.
</p>
<p>
<em>Updating</em>:
What little code is affected will be caught by the compiler and must be updated by hand.
</p>
<h3 id="mime">The mime package</h3>
<p>
In Go 1, the <a href="/pkg/mime/#FormatMediaType"><code>FormatMediaType</code></a> function
of the <code>mime</code> package has been simplified to make it
consistent with
<a href="/pkg/mime/#ParseMediaType"><code>ParseMediaType</code></a>.
It now takes <code>"text/html"</code> rather than <code>"text"</code> and <code>"html"</code>.
</p>
<p>
<em>Updating</em>:
What little code is affected will be caught by the compiler and must be updated by hand.
</p>
<h3 id="net">The net package</h3>
<p>
In Go 1, the various <code>SetTimeout</code>,
<code>SetReadTimeout</code>, and <code>SetWriteTimeout</code> methods
have been replaced with
<a href="/pkg/net/#IPConn.SetDeadline"><code>SetDeadline</code></a>,
<a href="/pkg/net/#IPConn.SetReadDeadline"><code>SetReadDeadline</code></a>, and
<a href="/pkg/net/#IPConn.SetWriteDeadline"><code>SetWriteDeadline</code></a>,
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 <code>time.Time</code> value) after which
reads and writes will time out and no longer block.
</p>
<p>
There are also new functions
<a href="/pkg/net/#DialTimeout"><code>net.DialTimeout</code></a>
to simplify timing out dialing a network address and
<a href="/pkg/net/#ListenMulticastUDP"><code>net.ListenMulticastUDP</code></a>
to allow multicast UDP to listen concurrently across multiple listeners.
The <code>net.ListenMulticastUDP</code> function replaces the old
<code>JoinGroup</code> and <code>LeaveGroup</code> methods.
</p>
<p>
<em>Updating</em>:
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.
</p>
<h3 id="os">The os package</h3>
<p>
The <code>Time</code> function has been removed; callers should use
the <a href="/pkg/time/#Time"><code>Time</code></a> type from the
<code>time</code> package.
</p>
<p>
The <code>Exec</code> function has been removed; callers should use
<code>Exec</code> from the <code>syscall</code> package, where available.
</p>
<p>
The <code>ShellExpand</code> function has been renamed to <a
href="/pkg/os/#ExpandEnv"><code>ExpandEnv</code></a>.
</p>
<p>
The <a href="/pkg/os/#NewFile"><code>NewFile</code></a> function
now takes a <code>uintptr</code> fd, instead of an <code>int</code>.
The <a href="/pkg/os/#File.Fd"><code>Fd</code></a> method on files now
also returns a <code>uintptr</code>.
</p>
<p>
There are no longer error constants such as <code>EINVAL</code>
in the <code>os</code> package, since the set of values varied with
the underlying operating system. There are new portable functions like
<a href="/pkg/os/#IsPermission"><code>IsPermission</code></a>
to test common error properties, plus a few new error values
with more Go-like names, such as
<a href="/pkg/os/#ErrPermission"><code>ErrPermission</code></a>
and
<a href="/pkg/os/#ErrNoEnv"><code>ErrNoEnv</code></a>.
</p>
<p>
The <code>Getenverror</code> function has been removed. To distinguish
between a non-existent environment variable and an empty string,
use <a href="/pkg/os/#Environ"><code>os.Environ</code></a> or
<a href="/pkg/syscall/#Getenv"><code>syscall.Getenv</code></a>.
</p>
<p>
The <a href="/pkg/os/#Process.Wait"><code>Process.Wait</code></a> method has
dropped its option argument and the associated constants are gone
from the package.
Also, the function <code>Wait</code> is gone; only the method of
the <code>Process</code> type persists.
</p>
<p>
The <code>Waitmsg</code> type returned by
<a href="/pkg/os/#Process.Wait"><code>Process.Wait</code></a>
has been replaced with a more portable
<a href="/pkg/os/#ProcessState"><code>ProcessState</code></a>
type with accessor methods to recover information about the
process.
Because of changes to <code>Wait</code>, the <code>ProcessState</code>
value always describes an exited process.
Portability concerns simplified the interface in other ways, but the values returned by the
<a href="/pkg/os/#ProcessState.Sys"><code>ProcessState.Sys</code></a> and
<a href="/pkg/os/#ProcessState.SysUsage"><code>ProcessState.SysUsage</code></a>
methods can be type-asserted to underlying system-specific data structures such as
<a href="/pkg/syscall/#WaitStatus"><code>syscall.WaitStatus</code></a> and
<a href="/pkg/syscall/#Rusage"><code>syscall.Rusage</code></a> on Unix.
</p>
<p>
<em>Updating</em>:
Running <code>go</code> <code>fix</code> will drop a zero argument to <code>Process.Wait</code>.
All other changes will be caught by the compiler and must be updated by hand.
</p>
<h4 id="os_fileinfo">The os.FileInfo type</h4>
<p>
Go 1 redefines the <a href="/pkg/os/#FileInfo"><code>os.FileInfo</code></a> type,
changing it from a struct to an interface:
</p>
<pre>
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)
}
</pre>
<p>
The file mode information has been moved into a subtype called
<a href="/pkg/os/#FileMode"><code>os.FileMode</code></a>,
a simple integer type with <code>IsDir</code>, <code>Perm</code>, and <code>String</code>
methods.
</p>
<p>
The system-specific details of file modes and properties such as (on Unix)
i-number have been removed from <code>FileInfo</code> altogether.
Instead, each operating system's <code>os</code> package provides an
implementation of the <code>FileInfo</code> interface, which
has a <code>Sys</code> 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 <code>FileInfo</code> like this:
</p>
<pre>
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)
</pre>
<p>
Assuming (which is unwise) that <code>"hello.go"</code> is a Unix file,
the i-number expression could be contracted to
</p>
<pre>
fi.Sys().(*syscall.Stat_t).Ino
</pre>
<p>
The vast majority of uses of <code>FileInfo</code> need only the methods
of the standard interface.
</p>
<p>
The <code>os</code> package no longer contains wrappers for the POSIX errors
such as <code>ENOENT</code>.
For the few programs that need to verify particular error conditions, there are
now the boolean functions
<a href="/pkg/os/#IsExist"><code>IsExist</code></a>,
<a href="/pkg/os/#IsNotExist"><code>IsNotExist</code></a>
and
<a href="/pkg/os/#IsPermission"><code>IsPermission</code></a>.
</p>
{{code "progs/go1.go" `/os\.Open/` `/}/`}}
<p>
<em>Updating</em>:
Running <code>go</code> <code>fix</code> will update code that uses the old equivalent of the current <code>os.FileInfo</code>
and <code>os.FileMode</code> 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 <code>os</code> package
will fail to compile and will also need to be updated by hand.
</p>
<h3 id="os_signal">The os/signal package</h3>
<p>
The <code>os/signal</code> package in Go 1 replaces the
<code>Incoming</code> function, which returned a channel
that received all incoming signals,
with the selective <code>Notify</code> function, which asks
for delivery of specific signals on an existing channel.
</p>
<p>
<em>Updating</em>:
Code must be updated by hand.
A literal translation of
</p>
<pre>
c := signal.Incoming()
</pre>
<p>
is
</p>
<pre>
c := make(chan os.Signal)
signal.Notify(c) // ask for all signals
</pre>
<p>
but most code should list the specific signals it wants to handle instead:
</p>
<pre>
c := make(chan os.Signal)
signal.Notify(c, syscall.SIGHUP, syscall.SIGQUIT)
</pre>
<h3 id="path_filepath">The path/filepath package</h3>
<p>
In Go 1, the <a href="/pkg/path/filepath/#Walk"><code>Walk</code></a> function of the
<code>path/filepath</code> package
has been changed to take a function value of type
<a href="/pkg/path/filepath/#WalkFunc"><code>WalkFunc</code></a>
instead of a <code>Visitor</code> interface value.
<code>WalkFunc</code> unifies the handling of both files and directories.
</p>
<pre>
type WalkFunc func(path string, info os.FileInfo, err error) error
</pre>
<p>
The <code>WalkFunc</code> 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 <a href="/pkg/path/filepath/#variables"><code>filepath.SkipDir</code></a>
</p>
{{code "progs/go1.go" `/STARTWALK/` `/ENDWALK/`}}
<p>
<em>Updating</em>:
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.
</p>
<h3 id="regexp">The regexp package</h3>
<p>
The <a href="/pkg/regexp/"><code>regexp</code></a> 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
<a href="http://code.google.com/p/re2/">RE2</a>.
</p>
<p>
<em>Updating</em>:
Code that uses the package should have its regular expressions checked by hand.
</p>
<h3 id="runtime">The runtime package</h3>
<p>
In Go 1, much of the API exported by package
<code>runtime</code> has been removed in favor of
functionality provided by other packages.
Code using the <code>runtime.Type</code> interface
or its specific concrete type implementations should
now use package <a href="/pkg/reflect/"><code>reflect</code></a>.
Code using <code>runtime.Semacquire</code> or <code>runtime.Semrelease</code>
should use channels or the abstractions in package <a href="/pkg/sync/"><code>sync</code></a>.
The <code>runtime.Alloc</code>, <code>runtime.Free</code>,
and <code>runtime.Lookup</code> functions, an unsafe API created for
debugging the memory allocator, have no replacement.
</p>
<p>
Before, <code>runtime.MemStats</code> was a global variable holding
statistics about memory allocation, and calls to <code>runtime.UpdateMemStats</code>
ensured that it was up to date.
In Go 1, <code>runtime.MemStats</code> is a struct type, and code should use
<a href="/pkg/runtime/#ReadMemStats"><code>runtime.ReadMemStats</code></a>
to obtain the current statistics.
</p>
<p>
The package adds a new function,
<a href="/pkg/runtime/#NumCPU"><code>runtime.NumCPU</code></a>, that returns the number of CPUs available
for parallel execution, as reported by the operating system kernel.
Its value can inform the setting of <code>GOMAXPROCS</code>.
The <code>runtime.Cgocalls</code> and <code>runtime.Goroutines</code> functions
have been renamed to <code>runtime.NumCgoCall</code> and <code>runtime.NumGoroutine</code>.
</p>
<p>
<em>Updating</em>:
Running <code>go</code> <code>fix</code> will update code for the function renamings.
Other code will need to be updated by hand.
</p>
<h3 id="strconv">The strconv package</h3>
<p>
In Go 1, the
<a href="/pkg/strconv/"><code>strconv</code></a>
package has been significantly reworked to make it more Go-like and less C-like,
although <code>Atoi</code> lives on (it's similar to
<code>int(ParseInt(x, 10, 0))</code>, as does
<code>Itoa(x)</code> (<code>FormatInt(int64(x), 10)</code>).
There are also new variants of some of the functions that append to byte slices rather than
return strings, to allow control over allocation.
</p>
<p>
This table summarizes the renamings; see the
<a href="/pkg/strconv/">package documentation</a>
for full details.
</p>
<table class="codetable" frame="border" summary="strconv renames">
<colgroup align="left" width="50%"></colgroup>
<colgroup align="left" width="50%"></colgroup>
<tr>
<th align="left">Old call</th>
<th align="left">New call</th>
</tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>Atob(x)</td> <td>ParseBool(x)</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>Atof32(x)</td> <td>ParseFloat(x, 32)§</td></tr>
<tr><td>Atof64(x)</td> <td>ParseFloat(x, 64)</td></tr>
<tr><td>AtofN(x, n)</td> <td>ParseFloat(x, n)</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>Atoi(x)</td> <td>Atoi(x)</td></tr>
<tr><td>Atoi(x)</td> <td>ParseInt(x, 10, 0)§</td></tr>
<tr><td>Atoi64(x)</td> <td>ParseInt(x, 10, 64)</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>Atoui(x)</td> <td>ParseUint(x, 10, 0)§</td></tr>
<tr><td>Atoi64(x)</td> <td>ParseInt(x, 10, 64)</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>Btoi64(x, b)</td> <td>ParseInt(x, b, 64)</td></tr>
<tr><td>Btoui64(x, b)</td> <td>ParseUint(x, b, 64)</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>Btoa(x)</td> <td>FormatBool(x)</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>Ftoa32(x, f, p)</td> <td>FormatFloat(float64(x), f, p, 32)</td></tr>
<tr><td>Ftoa64(x, f, p)</td> <td>FormatFloat(x, f, p, 64)</td></tr>
<tr><td>FtoaN(x, f, p, n)</td> <td>FormatFloat(x, f, p, n)</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>Itoa(x)</td> <td>Itoa(x)</td></tr>
<tr><td>Itoa(x)</td> <td>FormatInt(int64(x), 10)</td></tr>
<tr><td>Itoa64(x)</td> <td>FormatInt(x, 10)</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>Itob(x, b)</td> <td>FormatInt(int64(x), b)</td></tr>
<tr><td>Itob64(x, b)</td> <td>FormatInt(x, b)</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>Uitoa(x)</td> <td>FormatUint(uint64(x), 10)</td></tr>
<tr><td>Uitoa64(x)</td> <td>FormatUint(x, 10)</td></tr>
<tr>
<td colspan="2"><hr></td>
</tr>
<tr><td>Uitob(x, b)</td> <td>FormatUint(uint64(x), b)</td></tr>
<tr><td>Uitob64(x, b)</td> <td>FormatUint(x, b)</td></tr>
</table>
<p>
<em>Updating</em>:
Running <code>go</code> <code>fix</code> will update almost all code affected by the change.
<br>
§ <code>Atoi</code> persists but <code>Atoui</code> and <code>Atof32</code> do not, so
they may require
a cast that must be added by hand; the <code>go</code> <code>fix</code> tool will warn about it.
</p>
<h3 id="templates">The template packages</h3>
<p>
The <code>template</code> and <code>exp/template/html</code> packages have moved to
<a href="/pkg/text/template/"><code>text/template</code></a> and
<a href="/pkg/html/template/"><code>html/template</code></a>.
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.
</p>
<p>
Instead of sets, a <code>Template</code> 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.
</p>
<p>
<em>Updating</em>:
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 <a href="/pkg/text/template/#examples">examples</a> in
the documentation for <code>text/template</code> can provide guidance.
</p>
<h3 id="testing">The testing package</h3>
<p>
The testing package has a type, <code>B</code>, passed as an argument to benchmark functions.
In Go 1, <code>B</code> has new methods, analogous to those of <code>T</code>, enabling
logging and failure reporting.
</p>
{{code "progs/go1.go" `/func.*Benchmark/` `/^}/`}}
<p>
<em>Updating</em>:
Existing code is unaffected, although benchmarks that use <code>println</code>
or <code>panic</code> should be updated to use the new methods.
</p>
<h3 id="testing_script">The testing/script package</h3>
<p>
The testing/script package has been deleted. It was a dreg.
</p>
<p>
<em>Updating</em>:
No code is likely to be affected.
</p>
<h3 id="unsafe">The unsafe package</h3>
<p>
In Go 1, the functions
<code>unsafe.Typeof</code>, <code>unsafe.Reflect</code>,
<code>unsafe.Unreflect</code>, <code>unsafe.New</code>, and
<code>unsafe.NewArray</code> have been removed;
they duplicated safer functionality provided by
package <a href="/pkg/reflect/"><code>reflect</code></a>.
</p>
<p>
<em>Updating</em>:
Code using these functions must be rewritten to use
package <a href="/pkg/reflect/"><code>reflect</code></a>.
The changes to <a href="http://code.google.com/p/go/source/detail?r=2646dc956207">encoding/gob</a> and the <a href="http://code.google.com/p/goprotobuf/source/detail?r=5340ad310031">protocol buffer library</a>
may be helpful as examples.
</p>
<h3 id="url">The url package</h3>
<p>
In Go 1 several fields from the <a href="/pkg/net/url/#URL"><code>url.URL</code></a> type
were removed or replaced.
</p>
<p>
The <a href="/pkg/net/url/#URL.String"><code>String</code></a> method now
predictably rebuilds an encoded URL string using all of <code>URL</code>'s
fields as necessary. The resulting string will also no longer have
passwords escaped.
</p>
<p>
The <code>Raw</code> field has been removed. In most cases the <code>String</code>
method may be used in its place.
</p>
<p>
The old <code>RawUserinfo</code> field is replaced by the <code>User</code>
field, of type <a href="/pkg/net/url/#Userinfo"><code>*net.Userinfo</code></a>.
Values of this type may be created using the new <a href="/pkg/net/url/#User"><code>net.User</code></a>
and <a href="/pkg/net/url/#UserPassword"><code>net.UserPassword</code></a>
functions. The <code>EscapeUserinfo</code> and <code>UnescapeUserinfo</code>
functions are also gone.
</p>
<p>
The <code>RawAuthority</code> field has been removed. The same information is
available in the <code>Host</code> and <code>User</code> fields.
</p>
<p>
The <code>RawPath</code> field and the <code>EncodedPath</code> 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 <code>Path</code> 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.
</p>
<p>
URLs with non-rooted paths, such as <code>"mailto:dev@golang.org?subject=Hi"</code>,
are also handled differently. The <code>OpaquePath</code> boolean field has been
removed and a new <code>Opaque</code> string field introduced to hold the encoded
path for such URLs. In Go 1, the cited URL parses as:
</p>
<pre>
URL{
Scheme: "mailto",
Opaque: "dev@golang.org",
RawQuery: "subject=Hi",
}
</pre>
<p>
A new <a href="/pkg/net/url/#URL.RequestURI"><code>RequestURI</code></a> method was
added to <code>URL</code>.
</p>
<p>
The <code>ParseWithReference</code> function has been renamed to <code>ParseWithFragment</code>.
</p>
<p>
<em>Updating</em>:
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.
</p>
<h2 id="cmd_go">The go command</h2>
<p>
Go 1 introduces the <a href="/cmd/go/">go command</a>, a tool for fetching,
building, and installing Go packages and commands. The <code>go</code> 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.
</p>
<p>
See <a href="/doc/code.html">How to Write Go Code</a> for a primer on the
<code>go</code> command and the <a href="/cmd/go/">go command documentation</a>
for the full details.
</p>
<p>
<em>Updating</em>:
Projects that depend on the Go project's old makefile-based build
infrastructure (<code>Make.pkg</code>, <code>Make.cmd</code>, and so on) should
switch to using the <code>go</code> command for building Go code and, if
necessary, rewrite their makefiles to perform any auxiliary build tasks.
</p>
<h2 id="cmd_cgo">The cgo command</h2>
<p>
In Go 1, the <a href="/cmd/cgo">cgo command</a>
uses a different <code>_cgo_export.h</code>
file, which is generated for packages containing <code>//export</code> lines.
The <code>_cgo_export.h</code> 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 <code>//export</code> must not put function definitions
or variable initializations in the C preamble.
</p>
<h2 id="releases">Packaged releases</h2>
src/cmd/godoc/doc.go
View file @ a40065ac
......@@ -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
......
src/cmd/godoc/godoc.go
View file @ a40065ac
......@@ -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
}
......
src/cmd/godoc/main.go
View file @ a40065ac
......@@ -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 }
doc/tmpltohtml.go → src/cmd/godoc/template.go
View file @ a40065ac
......@@ -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 <pre> 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 DO NOT EDIT: created by\n tmpltohtml %s\n-->\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
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7