Go prebuilts for linux-x86, version 1.4.1
See README.ANDROID for instructions on rebuilding the prebuilts.
Change-Id: I86db7f4fb3269585078da4d38947ca9126ac813b
diff --git a/doc/articles/go_command.html b/doc/articles/go_command.html
new file mode 100644
index 0000000..2978628
--- /dev/null
+++ b/doc/articles/go_command.html
@@ -0,0 +1,266 @@
+<!--{
+ "title": "About the go command"
+}-->
+
+<p>The Go distribution includes a command, named
+"<code><a href="/cmd/go/">go</a></code>", that
+automates the downloading, building, installation, and testing of Go packages
+and commands. This document talks about why we wrote a new command, what it
+is, what it's not, and how to use it.</p>
+
+<h2>Motivation</h2>
+
+<p>You might have seen early Go talks in which Rob Pike jokes that the idea
+for Go arose while waiting for a large Google server to compile. That
+really was the motivation for Go: to build a language that worked well
+for building the large software that Google writes and runs. It was
+clear from the start that such a language must provide a way to
+express dependencies between code libraries clearly, hence the package
+grouping and the explicit import blocks. It was also clear from the
+start that you might want arbitrary syntax for describing the code
+being imported; this is why import paths are string literals.</p>
+
+<p>An explicit goal for Go from the beginning was to be able to build Go
+code using only the information found in the source itself, not
+needing to write a makefile or one of the many modern replacements for
+makefiles. If Go needed a configuration file to explain how to build
+your program, then Go would have failed.</p>
+
+<p>At first, there was no Go compiler, and the initial development
+focused on building one and then building libraries for it. For
+expedience, we postponed the automation of building Go code by using
+make and writing makefiles. When compiling a single package involved
+multiple invocations of the Go compiler, we even used a program to
+write the makefiles for us. You can find it if you dig through the
+repository history.</p>
+
+<p>The purpose of the new go command is our return to this ideal, that Go
+programs should compile without configuration or additional effort on
+the part of the developer beyond writing the necessary import
+statements.</p>
+
+<h2>Configuration versus convention</h2>
+
+<p>The way to achieve the simplicity of a configuration-free system is to
+establish conventions. The system works only to the extent that those conventions
+are followed. When we first launched Go, many people published packages that
+had to be installed in certain places, under certain names, using certain build
+tools, in order to be used. That's understandable: that's the way it works in
+most other languages. Over the last few years we consistently reminded people
+about the <code>goinstall</code> command
+(now replaced by <a href="/cmd/go/#hdr-Download_and_install_packages_and_dependencies"><code>go get</code></a>)
+and its conventions: first, that the import path is derived in a known way from
+the URL of the source code; second, that the place to store the sources in
+the local file system is derived in a known way from the import path; third,
+that each directory in a source tree corresponds to a single package; and
+fourth, that the package is built using only information in the source code.
+Today, the vast majority of packages follow these conventions.
+The Go ecosystem is simpler and more powerful as a result.</p>
+
+<p>We received many requests to allow a makefile in a package directory to
+provide just a little extra configuration beyond what's in the source code.
+But that would have introduced new rules. Because we did not accede to such
+requests, we were able to write the go command and eliminate our use of make
+or any other build system.</p>
+
+<p>It is important to understand that the go command is not a general
+build tool. It cannot be configured and it does not attempt to build
+anything but Go packages. These are important simplifying
+assumptions: they simplify not only the implementation but also, more
+important, the use of the tool itself.</p>
+
+<h2>Go's conventions</h2>
+
+<p>The <code>go</code> command requires that code adheres to a few key,
+well-established conventions.</p>
+
+<p>First, the import path is derived in an known way from the URL of the
+source code. For Bitbucket, GitHub, Google Code, and Launchpad, the
+root directory of the repository is identified by the repository's
+main URL, without the <code>http://</code> prefix. Subdirectories are named by
+adding to that path.
+For example, the Go example programs are obtained by running</p>
+
+<pre>
+git clone https://github.com/golang/example
+</pre>
+
+<p>and thus the import path for the root directory of that repository is
+"<code>github.com/golang/example</code>".
+The <a href="https://godoc.org/github.com/golang/example/stringutil">stringutil</a>
+package is stored in a subdirectory, so its import path is
+"<code>github.com/golang/example/stringutil</code>".</p>
+
+<p>These paths are on the long side, but in exchange we get an
+automatically managed name space for import paths and the ability for
+a tool like the go command to look at an unfamiliar import path and
+deduce where to obtain the source code.</p>
+
+<p>Second, the place to store sources in the local file system is derived
+in a known way from the import path. Specifically, the first choice
+is <code>$GOPATH/src/<import-path></code>. If <code>$GOPATH</code> is
+unset, the go command will fall back to storing source code alongside the
+standard Go packages, in <code>$GOROOT/src/<import-path></code>.
+If <code>$GOPATH</code> is set to a list of paths, the go command tries
+<code><dir>/src/<import-path></code> for each of the directories in
+that list.</p>
+
+<p>Each of those trees contains, by convention, a top-level directory named
+"<code>bin</code>", for holding compiled executables, and a top-level directory
+named "<code>pkg</code>", for holding compiled packages that can be imported,
+and the "<code>src</code>" directory, for holding package source files.
+Imposing this structure lets us keep each of these directory trees
+self-contained: the compiled form and the sources are always near each
+other.</p>
+
+<p>These naming conventions also let us work in the reverse direction,
+from a directory name to its import path. This mapping is important
+for many of the go command's subcommands, as we'll see below.</p>
+
+<p>Third, each directory in a source tree corresponds to a single
+package. By restricting a directory to a single package, we don't have
+to create hybrid import paths that specify first the directory and
+then the package within that directory. Also, most file management
+tools and UIs work on directories as fundamental units. Tying the
+fundamental Go unit—the package—to file system structure means
+that file system tools become Go package tools. Copying, moving, or
+deleting a package corresponds to copying, moving, or deleting a
+directory.</p>
+
+<p>Fourth, each package is built using only the information present in
+the source files. This makes it much more likely that the tool will
+be able to adapt to changing build environments and conditions. For
+example, if we allowed extra configuration such as compiler flags or
+command line recipes, then that configuration would need to be updated
+each time the build tools changed; it would also be inherently tied
+to the use of a specific tool chain.</p>
+
+<h2>Getting started with the go command</h2>
+
+<p>Finally, a quick tour of how to use the go command, to supplement
+the information in <a href="/doc/code.html">How to Write Go Code</a>,
+which you might want to read first. Assuming you want
+to keep your source code separate from the Go distribution source
+tree, the first step is to set <code>$GOPATH</code>, the one piece of global
+configuration that the go command needs. The <code>$GOPATH</code> can be a
+list of directories, but by far the most common usage should be to set it to a
+single directory. In particular, you do not need a separate entry in
+<code>$GOPATH</code> for each of your projects. One <code>$GOPATH</code> can
+support many projects.</p>
+
+<p>Here’s an example. Let’s say we decide to keep our Go code in the directory
+<code>$HOME/mygo</code>. We need to create that directory and set
+<code>$GOPATH</code> accordingly.</p>
+
+<pre>
+$ mkdir $HOME/mygo
+$ export GOPATH=$HOME/mygo
+$
+</pre>
+
+<p>Into this directory, we now add some source code. Suppose we want to use
+the indexing library from the codesearch project along with a left-leaning
+red-black tree. We can install both with the "<code>go get</code>"
+subcommand:</p>
+
+<pre>
+$ go get code.google.com/p/codesearch/index
+$ go get github.com/petar/GoLLRB/llrb
+$
+</pre>
+
+<p>Both of these projects are now downloaded and installed into our
+<code>$GOPATH</code> directory. The one tree now contains the two directories
+<code>src/code.google.com/p/codesearch/index/</code> and
+<code>src/github.com/petar/GoLLRB/llrb/</code>, along with the compiled
+packages (in <code>pkg/</code>) for those libraries and their dependencies.</p>
+
+<p>Because we used version control systems (Mercurial and Git) to check
+out the sources, the source tree also contains the other files in the
+corresponding repositories, such as related packages. The "<code>go list</code>"
+subcommand lists the import paths corresponding to its arguments, and
+the pattern "<code>./...</code>" means start in the current directory
+("<code>./</code>") and find all packages below that directory
+("<code>...</code>"):</p>
+
+<pre>
+$ go list ./...
+code.google.com/p/codesearch/cmd/cgrep
+code.google.com/p/codesearch/cmd/cindex
+code.google.com/p/codesearch/cmd/csearch
+code.google.com/p/codesearch/index
+code.google.com/p/codesearch/regexp
+code.google.com/p/codesearch/sparse
+github.com/petar/GoLLRB/example
+github.com/petar/GoLLRB/llrb
+$
+</pre>
+
+<p>We can also test those packages:</p>
+
+<pre>
+$ go test ./...
+? code.google.com/p/codesearch/cmd/cgrep [no test files]
+? code.google.com/p/codesearch/cmd/cindex [no test files]
+? code.google.com/p/codesearch/cmd/csearch [no test files]
+ok code.google.com/p/codesearch/index 0.239s
+ok code.google.com/p/codesearch/regexp 0.021s
+? code.google.com/p/codesearch/sparse [no test files]
+? github.com/petar/GoLLRB/example [no test files]
+ok github.com/petar/GoLLRB/llrb 0.231s
+$
+</pre>
+
+<p>If a go subcommand is invoked with no paths listed, it operates on the
+current directory:</p>
+
+<pre>
+$ cd $GOPATH/src/code.google.com/p/codesearch/regexp
+$ go list
+code.google.com/p/codesearch/regexp
+$ go test -v
+=== RUN TestNstateEnc
+--- PASS: TestNstateEnc (0.00 seconds)
+=== RUN TestMatch
+--- PASS: TestMatch (0.01 seconds)
+=== RUN TestGrep
+--- PASS: TestGrep (0.00 seconds)
+PASS
+ok code.google.com/p/codesearch/regexp 0.021s
+$ go install
+$
+</pre>
+
+<p>That "<code>go install</code>" subcommand installs the latest copy of the
+package into the pkg directory. Because the go command can analyze the
+dependency graph, "<code>go install</code>" also installs any packages that
+this package imports but that are out of date, recursively.</p>
+
+<p>Notice that "<code>go install</code>" was able to determine the name of the
+import path for the package in the current directory, because of the convention
+for directory naming. It would be a little more convenient if we could pick
+the name of the directory where we kept source code, and we probably wouldn't
+pick such a long name, but that ability would require additional configuration
+and complexity in the tool. Typing an extra directory name or two is a small
+price to pay for the increased simplicity and power.</p>
+
+<p>As the example shows, it’s fine to work with packages from many different
+projects at once within a single <code>$GOPATH</code> root directory.</p>
+
+<h2>Limitations</h2>
+
+<p>As mentioned above, the go command is not a general-purpose build
+tool. In particular, it does not have any facility for generating Go
+source files during a build. Instead, if you want to use a tool like
+yacc or the protocol buffer compiler, you will need to write a
+makefile (or a configuration file for the build tool of your choice)
+to generate the Go files and then check those generated source files
+into your repository. This is more work for you, the package author,
+but it is significantly less work for your users, who can use
+"<code>go get</code>" without needing to obtain and build
+any additional tools.</p>
+
+<h2>More information</h2>
+
+<p>For more information, read <a href="/doc/code.html">How to Write Go Code</a>
+and see the <a href="/cmd/go/">go command documentation</a>.</p>
diff --git a/doc/articles/index.html b/doc/articles/index.html
new file mode 100644
index 0000000..9ddd669
--- /dev/null
+++ b/doc/articles/index.html
@@ -0,0 +1,8 @@
+<!--{
+ "Title": "/doc/articles/"
+}-->
+
+<p>
+See the <a href="/doc/#articles">Documents page</a> and the
+<a href="/blog/index">Blog index</a> for a complete list of Go articles.
+</p>
diff --git a/doc/articles/race_detector.html b/doc/articles/race_detector.html
new file mode 100644
index 0000000..6defd98
--- /dev/null
+++ b/doc/articles/race_detector.html
@@ -0,0 +1,389 @@
+<!--{
+ "Title": "Data Race Detector",
+ "Template": true
+}-->
+
+<h2 id="Introduction">Introduction</h2>
+
+<p>
+Data races are among the most common and hardest to debug types of bugs in concurrent systems.
+A data race occurs when two goroutines access the same variable concurrently and at least one of the accesses is a write.
+See the <a href="/ref/mem/">The Go Memory Model</a> for details.
+</p>
+
+<p>
+Here is an example of a data race that can lead to crashes and memory corruption:
+</p>
+
+<pre>
+func main() {
+ c := make(chan bool)
+ m := make(map[string]string)
+ go func() {
+ m["1"] = "a" // First conflicting access.
+ c <- true
+ }()
+ m["2"] = "b" // Second conflicting access.
+ <-c
+ for k, v := range m {
+ fmt.Println(k, v)
+ }
+}
+</pre>
+
+<h2 id="Usage">Usage</h2>
+
+<p>
+To help diagnose such bugs, Go includes a built-in data race detector.
+To use it, add the <code>-race</code> flag to the go command:
+</p>
+
+<pre>
+$ go test -race mypkg // to test the package
+$ go run -race mysrc.go // to run the source file
+$ go build -race mycmd // to build the command
+$ go install -race mypkg // to install the package
+</pre>
+
+<h2 id="Report_Format">Report Format</h2>
+
+<p>
+When the race detector finds a data race in the program, it prints a report.
+The report contains stack traces for conflicting accesses, as well as stacks where the involved goroutines were created.
+Here is an example:
+</p>
+
+<pre>
+WARNING: DATA RACE
+Read by goroutine 185:
+ net.(*pollServer).AddFD()
+ src/net/fd_unix.go:89 +0x398
+ net.(*pollServer).WaitWrite()
+ src/net/fd_unix.go:247 +0x45
+ net.(*netFD).Write()
+ src/net/fd_unix.go:540 +0x4d4
+ net.(*conn).Write()
+ src/net/net.go:129 +0x101
+ net.func·060()
+ src/net/timeout_test.go:603 +0xaf
+
+Previous write by goroutine 184:
+ net.setWriteDeadline()
+ src/net/sockopt_posix.go:135 +0xdf
+ net.setDeadline()
+ src/net/sockopt_posix.go:144 +0x9c
+ net.(*conn).SetDeadline()
+ src/net/net.go:161 +0xe3
+ net.func·061()
+ src/net/timeout_test.go:616 +0x3ed
+
+Goroutine 185 (running) created at:
+ net.func·061()
+ src/net/timeout_test.go:609 +0x288
+
+Goroutine 184 (running) created at:
+ net.TestProlongTimeout()
+ src/net/timeout_test.go:618 +0x298
+ testing.tRunner()
+ src/testing/testing.go:301 +0xe8
+</pre>
+
+<h2 id="Options">Options</h2>
+
+<p>
+The <code>GORACE</code> environment variable sets race detector options.
+The format is:
+</p>
+
+<pre>
+GORACE="option1=val1 option2=val2"
+</pre>
+
+<p>
+The options are:
+</p>
+
+<ul>
+<li>
+<code>log_path</code> (default <code>stderr</code>): The race detector writes
+its report to a file named <code>log_path.<em>pid</em></code>.
+The special names <code>stdout</code>
+and <code>stderr</code> cause reports to be written to standard output and
+standard error, respectively.
+</li>
+
+<li>
+<code>exitcode</code> (default <code>66</code>): The exit status to use when
+exiting after a detected race.
+</li>
+
+<li>
+<code>strip_path_prefix</code> (default <code>""</code>): Strip this prefix
+from all reported file paths, to make reports more concise.
+</li>
+
+<li>
+<code>history_size</code> (default <code>1</code>): The per-goroutine memory
+access history is <code>32K * 2**history_size elements</code>.
+Increasing this value can avoid a "failed to restore the stack" error in reports, at the
+cost of increased memory usage.
+</li>
+
+<li>
+<code>halt_on_error</code> (default <code>0</code>): Controls whether the program
+exits after reporting first data race.
+</li>
+</ul>
+
+<p>
+Example:
+</p>
+
+<pre>
+$ GORACE="log_path=/tmp/race/report strip_path_prefix=/my/go/sources/" go test -race
+</pre>
+
+<h2 id="Excluding_Tests">Excluding Tests</h2>
+
+<p>
+When you build with <code>-race</code> flag, the <code>go</code> command defines additional
+<a href="/pkg/go/build/#hdr-Build_Constraints">build tag</a> <code>race</code>.
+You can use the tag to exclude some code and tests when running the race detector.
+Some examples:
+</p>
+
+<pre>
+// +build !race
+
+package foo
+
+// The test contains a data race. See issue 123.
+func TestFoo(t *testing.T) {
+ // ...
+}
+
+// The test fails under the race detector due to timeouts.
+func TestBar(t *testing.T) {
+ // ...
+}
+
+// The test takes too long under the race detector.
+func TestBaz(t *testing.T) {
+ // ...
+}
+</pre>
+
+<h2 id="How_To_Use">How To Use</h2>
+
+<p>
+To start, run your tests using the race detector (<code>go test -race</code>).
+The race detector only finds races that happen at runtime, so it can't find
+races in code paths that are not executed.
+If your tests have incomplete coverage,
+you may find more races by running a binary built with <code>-race</code> under a realistic
+workload.
+</p>
+
+<h2 id="Typical_Data_Races">Typical Data Races</h2>
+
+<p>
+Here are some typical data races. All of them can be detected with the race detector.
+</p>
+
+<h3 id="Race_on_loop_counter">Race on loop counter</h3>
+
+<pre>
+func main() {
+ var wg sync.WaitGroup
+ wg.Add(5)
+ for i := 0; i < 5; i++ {
+ go func() {
+ fmt.Println(i) // Not the 'i' you are looking for.
+ wg.Done()
+ }()
+ }
+ wg.Wait()
+}
+</pre>
+
+<p>
+The variable <code>i</code> in the function literal is the same variable used by the loop, so
+the read in the goroutine races with the loop increment.
+(This program typically prints 55555, not 01234.)
+The program can be fixed by making a copy of the variable:
+</p>
+
+<pre>
+func main() {
+ var wg sync.WaitGroup
+ wg.Add(5)
+ for i := 0; i < 5; i++ {
+ go func(j int) {
+ fmt.Println(j) // Good. Read local copy of the loop counter.
+ wg.Done()
+ }(i)
+ }
+ wg.Wait()
+}
+</pre>
+
+<h3 id="Accidentally_shared_variable">Accidentally shared variable</h3>
+
+<pre>
+// ParallelWrite writes data to file1 and file2, returns the errors.
+func ParallelWrite(data []byte) chan error {
+ res := make(chan error, 2)
+ f1, err := os.Create("file1")
+ if err != nil {
+ res <- err
+ } else {
+ go func() {
+ // This err is shared with the main goroutine,
+ // so the write races with the write below.
+ _, err = f1.Write(data)
+ res <- err
+ f1.Close()
+ }()
+ }
+ f2, err := os.Create("file2") // The second conflicting write to err.
+ if err != nil {
+ res <- err
+ } else {
+ go func() {
+ _, err = f2.Write(data)
+ res <- err
+ f2.Close()
+ }()
+ }
+ return res
+}
+</pre>
+
+<p>
+The fix is to introduce new variables in the goroutines (note the use of <code>:=</code>):
+</p>
+
+<pre>
+ ...
+ _, err := f1.Write(data)
+ ...
+ _, err := f2.Write(data)
+ ...
+</pre>
+
+<h3 id="Unprotected_global_variable">Unprotected global variable</h3>
+
+<p>
+If the following code is called from several goroutines, it leads to races on the <code>service</code> map.
+Concurrent reads and writes of the same map are not safe:
+</p>
+
+<pre>
+var service map[string]net.Addr
+
+func RegisterService(name string, addr net.Addr) {
+ service[name] = addr
+}
+
+func LookupService(name string) net.Addr {
+ return service[name]
+}
+</pre>
+
+<p>
+To make the code safe, protect the accesses with a mutex:
+</p>
+
+<pre>
+var (
+ service map[string]net.Addr
+ serviceMu sync.Mutex
+)
+
+func RegisterService(name string, addr net.Addr) {
+ serviceMu.Lock()
+ defer serviceMu.Unlock()
+ service[name] = addr
+}
+
+func LookupService(name string) net.Addr {
+ serviceMu.Lock()
+ defer serviceMu.Unlock()
+ return service[name]
+}
+</pre>
+
+<h3 id="Primitive_unprotected_variable">Primitive unprotected variable</h3>
+
+<p>
+Data races can happen on variables of primitive types as well (<code>bool</code>, <code>int</code>, <code>int64</code>, etc.),
+as in this example:
+</p>
+
+<pre>
+type Watchdog struct{ last int64 }
+
+func (w *Watchdog) KeepAlive() {
+ w.last = time.Now().UnixNano() // First conflicting access.
+}
+
+func (w *Watchdog) Start() {
+ go func() {
+ for {
+ time.Sleep(time.Second)
+ // Second conflicting access.
+ if w.last < time.Now().Add(-10*time.Second).UnixNano() {
+ fmt.Println("No keepalives for 10 seconds. Dying.")
+ os.Exit(1)
+ }
+ }
+ }()
+}
+</pre>
+
+<p>
+Even such "innocent" data races can lead to hard-to-debug problems caused by
+non-atomicity of the memory accesses,
+interference with compiler optimizations,
+or reordering issues accessing processor memory .
+</p>
+
+<p>
+A typical fix for this race is to use a channel or a mutex.
+To preserve the lock-free behavior, one can also use the
+<a href="/pkg/sync/atomic/"><code>sync/atomic</code></a> package.
+</p>
+
+<pre>
+type Watchdog struct{ last int64 }
+
+func (w *Watchdog) KeepAlive() {
+ atomic.StoreInt64(&w.last, time.Now().UnixNano())
+}
+
+func (w *Watchdog) Start() {
+ go func() {
+ for {
+ time.Sleep(time.Second)
+ if atomic.LoadInt64(&w.last) < time.Now().Add(-10*time.Second).UnixNano() {
+ fmt.Println("No keepalives for 10 seconds. Dying.")
+ os.Exit(1)
+ }
+ }
+ }()
+}
+</pre>
+
+<h2 id="Supported_Systems">Supported Systems</h2>
+
+<p>
+The race detector runs on <code>darwin/amd64</code>, <code>freebsd/amd64</code>,
+<code>linux/amd64</code>, and <code>windows/amd64</code>.
+</p>
+
+<h2 id="Runtime_Overheads">Runtime Overhead</h2>
+
+<p>
+The cost of race detection varies by program, but for a typical program, memory
+usage may increase by 5-10x and execution time by 2-20x.
+</p>
diff --git a/doc/articles/wiki/edit.html b/doc/articles/wiki/edit.html
new file mode 100644
index 0000000..044c3be
--- /dev/null
+++ b/doc/articles/wiki/edit.html
@@ -0,0 +1,6 @@
+<h1>Editing {{.Title}}</h1>
+
+<form action="/save/{{.Title}}" method="POST">
+<div><textarea name="body" rows="20" cols="80">{{printf "%s" .Body}}</textarea></div>
+<div><input type="submit" value="Save"></div>
+</form>
diff --git a/doc/articles/wiki/final-noclosure.go b/doc/articles/wiki/final-noclosure.go
new file mode 100644
index 0000000..d72ca80
--- /dev/null
+++ b/doc/articles/wiki/final-noclosure.go
@@ -0,0 +1,102 @@
+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "errors"
+ "html/template"
+ "io/ioutil"
+ "net/http"
+ "regexp"
+)
+
+type Page struct {
+ Title string
+ Body []byte
+}
+
+func (p *Page) save() error {
+ filename := p.Title + ".txt"
+ return ioutil.WriteFile(filename, p.Body, 0600)
+}
+
+func loadPage(title string) (*Page, error) {
+ filename := title + ".txt"
+ body, err := ioutil.ReadFile(filename)
+ if err != nil {
+ return nil, err
+ }
+ return &Page{Title: title, Body: body}, nil
+}
+
+func viewHandler(w http.ResponseWriter, r *http.Request) {
+ title, err := getTitle(w, r)
+ if err != nil {
+ return
+ }
+ p, err := loadPage(title)
+ if err != nil {
+ http.Redirect(w, r, "/edit/"+title, http.StatusFound)
+ return
+ }
+ renderTemplate(w, "view", p)
+}
+
+func editHandler(w http.ResponseWriter, r *http.Request) {
+ title, err := getTitle(w, r)
+ if err != nil {
+ return
+ }
+ p, err := loadPage(title)
+ if err != nil {
+ p = &Page{Title: title}
+ }
+ renderTemplate(w, "edit", p)
+}
+
+func saveHandler(w http.ResponseWriter, r *http.Request) {
+ title, err := getTitle(w, r)
+ if err != nil {
+ return
+ }
+ body := r.FormValue("body")
+ p := &Page{Title: title, Body: []byte(body)}
+ err = p.save()
+ if err != nil {
+ http.Error(w, err.Error(), http.StatusInternalServerError)
+ return
+ }
+ http.Redirect(w, r, "/view/"+title, http.StatusFound)
+}
+
+func renderTemplate(w http.ResponseWriter, tmpl string, p *Page) {
+ t, err := template.ParseFiles(tmpl + ".html")
+ if err != nil {
+ http.Error(w, err.Error(), http.StatusInternalServerError)
+ return
+ }
+ err = t.Execute(w, p)
+ if err != nil {
+ http.Error(w, err.Error(), http.StatusInternalServerError)
+ }
+}
+
+var validPath = regexp.MustCompile("^/(edit|save|view)/([a-zA-Z0-9]+)$")
+
+func getTitle(w http.ResponseWriter, r *http.Request) (string, error) {
+ m := validPath.FindStringSubmatch(r.URL.Path)
+ if m == nil {
+ http.NotFound(w, r)
+ return "", errors.New("Invalid Page Title")
+ }
+ return m[2], nil // The title is the second subexpression.
+}
+
+func main() {
+ http.HandleFunc("/view/", viewHandler)
+ http.HandleFunc("/edit/", editHandler)
+ http.HandleFunc("/save/", saveHandler)
+ http.ListenAndServe(":8080", nil)
+}
diff --git a/doc/articles/wiki/final-noerror.go b/doc/articles/wiki/final-noerror.go
new file mode 100644
index 0000000..86d8da7
--- /dev/null
+++ b/doc/articles/wiki/final-noerror.go
@@ -0,0 +1,53 @@
+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "html/template"
+ "io/ioutil"
+ "net/http"
+)
+
+type Page struct {
+ Title string
+ Body []byte
+}
+
+func (p *Page) save() error {
+ filename := p.Title + ".txt"
+ return ioutil.WriteFile(filename, p.Body, 0600)
+}
+
+func loadPage(title string) (*Page, error) {
+ filename := title + ".txt"
+ body, err := ioutil.ReadFile(filename)
+ if err != nil {
+ return nil, err
+ }
+ return &Page{Title: title, Body: body}, nil
+}
+
+func editHandler(w http.ResponseWriter, r *http.Request) {
+ title := r.URL.Path[len("/edit/"):]
+ p, err := loadPage(title)
+ if err != nil {
+ p = &Page{Title: title}
+ }
+ t, _ := template.ParseFiles("edit.html")
+ t.Execute(w, p)
+}
+
+func viewHandler(w http.ResponseWriter, r *http.Request) {
+ title := r.URL.Path[len("/view/"):]
+ p, _ := loadPage(title)
+ t, _ := template.ParseFiles("view.html")
+ t.Execute(w, p)
+}
+
+func main() {
+ http.HandleFunc("/view/", viewHandler)
+ http.HandleFunc("/edit/", editHandler)
+ http.ListenAndServe(":8080", nil)
+}
diff --git a/doc/articles/wiki/final-parsetemplate.go b/doc/articles/wiki/final-parsetemplate.go
new file mode 100644
index 0000000..5ff8bf6
--- /dev/null
+++ b/doc/articles/wiki/final-parsetemplate.go
@@ -0,0 +1,91 @@
+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "html/template"
+ "io/ioutil"
+ "net/http"
+ "regexp"
+)
+
+type Page struct {
+ Title string
+ Body []byte
+}
+
+func (p *Page) save() error {
+ filename := p.Title + ".txt"
+ return ioutil.WriteFile(filename, p.Body, 0600)
+}
+
+func loadPage(title string) (*Page, error) {
+ filename := title + ".txt"
+ body, err := ioutil.ReadFile(filename)
+ if err != nil {
+ return nil, err
+ }
+ return &Page{Title: title, Body: body}, nil
+}
+
+func viewHandler(w http.ResponseWriter, r *http.Request, title string) {
+ p, err := loadPage(title)
+ if err != nil {
+ http.Redirect(w, r, "/edit/"+title, http.StatusFound)
+ return
+ }
+ renderTemplate(w, "view", p)
+}
+
+func editHandler(w http.ResponseWriter, r *http.Request, title string) {
+ p, err := loadPage(title)
+ if err != nil {
+ p = &Page{Title: title}
+ }
+ renderTemplate(w, "edit", p)
+}
+
+func saveHandler(w http.ResponseWriter, r *http.Request, title string) {
+ body := r.FormValue("body")
+ p := &Page{Title: title, Body: []byte(body)}
+ err := p.save()
+ if err != nil {
+ http.Error(w, err.Error(), http.StatusInternalServerError)
+ return
+ }
+ http.Redirect(w, r, "/view/"+title, http.StatusFound)
+}
+
+func renderTemplate(w http.ResponseWriter, tmpl string, p *Page) {
+ t, err := template.ParseFiles(tmpl + ".html")
+ if err != nil {
+ http.Error(w, err.Error(), http.StatusInternalServerError)
+ return
+ }
+ err = t.Execute(w, p)
+ if err != nil {
+ http.Error(w, err.Error(), http.StatusInternalServerError)
+ }
+}
+
+var validPath = regexp.MustCompile("^/(edit|save|view)/([a-zA-Z0-9]+)$")
+
+func makeHandler(fn func(http.ResponseWriter, *http.Request, string)) http.HandlerFunc {
+ return func(w http.ResponseWriter, r *http.Request) {
+ m := validPath.FindStringSubmatch(r.URL.Path)
+ if m == nil {
+ http.NotFound(w, r)
+ return
+ }
+ fn(w, r, m[2])
+ }
+}
+
+func main() {
+ http.HandleFunc("/view/", makeHandler(viewHandler))
+ http.HandleFunc("/edit/", makeHandler(editHandler))
+ http.HandleFunc("/save/", makeHandler(saveHandler))
+ http.ListenAndServe(":8080", nil)
+}
diff --git a/doc/articles/wiki/final-template.go b/doc/articles/wiki/final-template.go
new file mode 100644
index 0000000..719157d
--- /dev/null
+++ b/doc/articles/wiki/final-template.go
@@ -0,0 +1,65 @@
+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "html/template"
+ "io/ioutil"
+ "net/http"
+)
+
+type Page struct {
+ Title string
+ Body []byte
+}
+
+func (p *Page) save() error {
+ filename := p.Title + ".txt"
+ return ioutil.WriteFile(filename, p.Body, 0600)
+}
+
+func loadPage(title string) (*Page, error) {
+ filename := title + ".txt"
+ body, err := ioutil.ReadFile(filename)
+ if err != nil {
+ return nil, err
+ }
+ return &Page{Title: title, Body: body}, nil
+}
+
+func editHandler(w http.ResponseWriter, r *http.Request) {
+ title := r.URL.Path[len("/edit/"):]
+ p, err := loadPage(title)
+ if err != nil {
+ p = &Page{Title: title}
+ }
+ renderTemplate(w, "edit", p)
+}
+
+func viewHandler(w http.ResponseWriter, r *http.Request) {
+ title := r.URL.Path[len("/view/"):]
+ p, _ := loadPage(title)
+ renderTemplate(w, "view", p)
+}
+
+func saveHandler(w http.ResponseWriter, r *http.Request) {
+ title := r.URL.Path[len("/save/"):]
+ body := r.FormValue("body")
+ p := &Page{Title: title, Body: []byte(body)}
+ p.save()
+ http.Redirect(w, r, "/view/"+title, http.StatusFound)
+}
+
+func renderTemplate(w http.ResponseWriter, tmpl string, p *Page) {
+ t, _ := template.ParseFiles(tmpl + ".html")
+ t.Execute(w, p)
+}
+
+func main() {
+ http.HandleFunc("/view/", viewHandler)
+ http.HandleFunc("/edit/", editHandler)
+ http.HandleFunc("/save/", saveHandler)
+ http.ListenAndServe(":8080", nil)
+}
diff --git a/doc/articles/wiki/final.go b/doc/articles/wiki/final.go
new file mode 100644
index 0000000..d84c1ff
--- /dev/null
+++ b/doc/articles/wiki/final.go
@@ -0,0 +1,111 @@
+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "flag"
+ "html/template"
+ "io/ioutil"
+ "log"
+ "net"
+ "net/http"
+ "regexp"
+)
+
+var (
+ addr = flag.Bool("addr", false, "find open address and print to final-port.txt")
+)
+
+type Page struct {
+ Title string
+ Body []byte
+}
+
+func (p *Page) save() error {
+ filename := p.Title + ".txt"
+ return ioutil.WriteFile(filename, p.Body, 0600)
+}
+
+func loadPage(title string) (*Page, error) {
+ filename := title + ".txt"
+ body, err := ioutil.ReadFile(filename)
+ if err != nil {
+ return nil, err
+ }
+ return &Page{Title: title, Body: body}, nil
+}
+
+func viewHandler(w http.ResponseWriter, r *http.Request, title string) {
+ p, err := loadPage(title)
+ if err != nil {
+ http.Redirect(w, r, "/edit/"+title, http.StatusFound)
+ return
+ }
+ renderTemplate(w, "view", p)
+}
+
+func editHandler(w http.ResponseWriter, r *http.Request, title string) {
+ p, err := loadPage(title)
+ if err != nil {
+ p = &Page{Title: title}
+ }
+ renderTemplate(w, "edit", p)
+}
+
+func saveHandler(w http.ResponseWriter, r *http.Request, title string) {
+ body := r.FormValue("body")
+ p := &Page{Title: title, Body: []byte(body)}
+ err := p.save()
+ if err != nil {
+ http.Error(w, err.Error(), http.StatusInternalServerError)
+ return
+ }
+ http.Redirect(w, r, "/view/"+title, http.StatusFound)
+}
+
+var templates = template.Must(template.ParseFiles("edit.html", "view.html"))
+
+func renderTemplate(w http.ResponseWriter, tmpl string, p *Page) {
+ err := templates.ExecuteTemplate(w, tmpl+".html", p)
+ if err != nil {
+ http.Error(w, err.Error(), http.StatusInternalServerError)
+ }
+}
+
+var validPath = regexp.MustCompile("^/(edit|save|view)/([a-zA-Z0-9]+)$")
+
+func makeHandler(fn func(http.ResponseWriter, *http.Request, string)) http.HandlerFunc {
+ return func(w http.ResponseWriter, r *http.Request) {
+ m := validPath.FindStringSubmatch(r.URL.Path)
+ if m == nil {
+ http.NotFound(w, r)
+ return
+ }
+ fn(w, r, m[2])
+ }
+}
+
+func main() {
+ flag.Parse()
+ http.HandleFunc("/view/", makeHandler(viewHandler))
+ http.HandleFunc("/edit/", makeHandler(editHandler))
+ http.HandleFunc("/save/", makeHandler(saveHandler))
+
+ if *addr {
+ l, err := net.Listen("tcp", "127.0.0.1:0")
+ if err != nil {
+ log.Fatal(err)
+ }
+ err = ioutil.WriteFile("final-port.txt", []byte(l.Addr().String()), 0644)
+ if err != nil {
+ log.Fatal(err)
+ }
+ s := &http.Server{}
+ s.Serve(l)
+ return
+ }
+
+ http.ListenAndServe(":8080", nil)
+}
diff --git a/doc/articles/wiki/get.go b/doc/articles/wiki/get.go
new file mode 100644
index 0000000..b3e464b
--- /dev/null
+++ b/doc/articles/wiki/get.go
@@ -0,0 +1,63 @@
+// Copyright 2011 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "flag"
+ "fmt"
+ "io"
+ "log"
+ "net"
+ "net/http"
+ "os"
+ "strings"
+ "time"
+)
+
+var (
+ post = flag.String("post", "", "urlencoded form data to POST")
+ addr = flag.Bool("addr", false, "find open address and print to stdout")
+ wait = flag.Duration("wait_for_port", 0, "if non-zero, the amount of time to wait for the address to become available")
+)
+
+func main() {
+ flag.Parse()
+ if *addr {
+ l, err := net.Listen("tcp", "127.0.0.1:0")
+ if err != nil {
+ log.Fatal(err)
+ }
+ defer l.Close()
+ fmt.Print(l.Addr())
+ return
+ }
+ url := flag.Arg(0)
+ if url == "" {
+ log.Fatal("no url supplied")
+ }
+ var r *http.Response
+ var err error
+ loopUntil := time.Now().Add(*wait)
+ for {
+ if *post != "" {
+ b := strings.NewReader(*post)
+ r, err = http.Post(url, "application/x-www-form-urlencoded", b)
+ } else {
+ r, err = http.Get(url)
+ }
+ if err == nil || *wait == 0 || time.Now().After(loopUntil) {
+ break
+ }
+ time.Sleep(100 * time.Millisecond)
+ }
+ if err != nil {
+ log.Fatal(err)
+ }
+ defer r.Body.Close()
+ _, err = io.Copy(os.Stdout, r.Body)
+ if err != nil {
+ log.Fatal(err)
+ }
+}
diff --git a/doc/articles/wiki/http-sample.go b/doc/articles/wiki/http-sample.go
new file mode 100644
index 0000000..ac8cc4f
--- /dev/null
+++ b/doc/articles/wiki/http-sample.go
@@ -0,0 +1,15 @@
+package main
+
+import (
+ "fmt"
+ "net/http"
+)
+
+func handler(w http.ResponseWriter, r *http.Request) {
+ fmt.Fprintf(w, "Hi there, I love %s!", r.URL.Path[1:])
+}
+
+func main() {
+ http.HandleFunc("/", handler)
+ http.ListenAndServe(":8080", nil)
+}
diff --git a/doc/articles/wiki/index.html b/doc/articles/wiki/index.html
new file mode 100644
index 0000000..b6b080d
--- /dev/null
+++ b/doc/articles/wiki/index.html
@@ -0,0 +1,734 @@
+<!--{
+ "Title": "Writing Web Applications",
+ "Template": true
+}-->
+
+<h2>Introduction</h2>
+
+<p>
+Covered in this tutorial:
+</p>
+<ul>
+<li>Creating a data structure with load and save methods</li>
+<li>Using the <code>net/http</code> package to build web applications
+<li>Using the <code>html/template</code> package to process HTML templates</li>
+<li>Using the <code>regexp</code> package to validate user input</li>
+<li>Using closures</li>
+</ul>
+
+<p>
+Assumed knowledge:
+</p>
+<ul>
+<li>Programming experience</li>
+<li>Understanding of basic web technologies (HTTP, HTML)</li>
+<li>Some UNIX/DOS command-line knowledge</li>
+</ul>
+
+<h2>Getting Started</h2>
+
+<p>
+At present, you need to have a FreeBSD, Linux, OS X, or Windows machine to run Go.
+We will use <code>$</code> to represent the command prompt.
+</p>
+
+<p>
+Install Go (see the <a href="/doc/install">Installation Instructions</a>).
+</p>
+
+<p>
+Make a new directory for this tutorial inside your <code>GOPATH</code> and cd to it:
+</p>
+
+<pre>
+$ mkdir gowiki
+$ cd gowiki
+</pre>
+
+<p>
+Create a file named <code>wiki.go</code>, open it in your favorite editor, and
+add the following lines:
+</p>
+
+<pre>
+package main
+
+import (
+ "fmt"
+ "io/ioutil"
+)
+</pre>
+
+<p>
+We import the <code>fmt</code> and <code>ioutil</code> packages from the Go
+standard library. Later, as we implement additional functionality, we will
+add more packages to this <code>import</code> declaration.
+</p>
+
+<h2>Data Structures</h2>
+
+<p>
+Let's start by defining the data structures. A wiki consists of a series of
+interconnected pages, each of which has a title and a body (the page content).
+Here, we define <code>Page</code> as a struct with two fields representing
+the title and body.
+</p>
+
+{{code "doc/articles/wiki/part1.go" `/^type Page/` `/}/`}}
+
+<p>
+The type <code>[]byte</code> means "a <code>byte</code> slice".
+(See <a href="/doc/articles/slices_usage_and_internals.html">Slices: usage and
+internals</a> for more on slices.)
+The <code>Body</code> element is a <code>[]byte</code> rather than
+<code>string</code> because that is the type expected by the <code>io</code>
+libraries we will use, as you'll see below.
+</p>
+
+<p>
+The <code>Page</code> struct describes how page data will be stored in memory.
+But what about persistent storage? We can address that by creating a
+<code>save</code> method on <code>Page</code>:
+</p>
+
+{{code "doc/articles/wiki/part1.go" `/^func.*Page.*save/` `/}/`}}
+
+<p>
+This method's signature reads: "This is a method named <code>save</code> that
+takes as its receiver <code>p</code>, a pointer to <code>Page</code> . It takes
+no parameters, and returns a value of type <code>error</code>."
+</p>
+
+<p>
+This method will save the <code>Page</code>'s <code>Body</code> to a text
+file. For simplicity, we will use the <code>Title</code> as the file name.
+</p>
+
+<p>
+The <code>save</code> method returns an <code>error</code> value because
+that is the return type of <code>WriteFile</code> (a standard library function
+that writes a byte slice to a file). The <code>save</code> method returns the
+error value, to let the application handle it should anything go wrong while
+writing the file. If all goes well, <code>Page.save()</code> will return
+<code>nil</code> (the zero-value for pointers, interfaces, and some other
+types).
+</p>
+
+<p>
+The octal integer literal <code>0600</code>, passed as the third parameter to
+<code>WriteFile</code>, indicates that the file should be created with
+read-write permissions for the current user only. (See the Unix man page
+<code>open(2)</code> for details.)
+</p>
+
+<p>
+In addition to saving pages, we will want to load pages, too:
+</p>
+
+{{code "doc/articles/wiki/part1-noerror.go" `/^func loadPage/` `/^}/`}}
+
+<p>
+The function <code>loadPage</code> constructs the file name from the title
+parameter, reads the file's contents into a new variable <code>body</code>, and
+returns a pointer to a <code>Page</code> literal constructed with the proper
+title and body values.
+</p>
+
+<p>
+Functions can return multiple values. The standard library function
+<code>io.ReadFile</code> returns <code>[]byte</code> and <code>error</code>.
+In <code>loadPage</code>, error isn't being handled yet; the "blank identifier"
+represented by the underscore (<code>_</code>) symbol is used to throw away the
+error return value (in essence, assigning the value to nothing).
+</p>
+
+<p>
+But what happens if <code>ReadFile</code> encounters an error? For example,
+the file might not exist. We should not ignore such errors. Let's modify the
+function to return <code>*Page</code> and <code>error</code>.
+</p>
+
+{{code "doc/articles/wiki/part1.go" `/^func loadPage/` `/^}/`}}
+
+<p>
+Callers of this function can now check the second parameter; if it is
+<code>nil</code> then it has successfully loaded a Page. If not, it will be an
+<code>error</code> that can be handled by the caller (see the
+<a href="/ref/spec#Errors">language specification</a> for details).
+</p>
+
+<p>
+At this point we have a simple data structure and the ability to save to and
+load from a file. Let's write a <code>main</code> function to test what we've
+written:
+</p>
+
+{{code "doc/articles/wiki/part1.go" `/^func main/` `/^}/`}}
+
+<p>
+After compiling and executing this code, a file named <code>TestPage.txt</code>
+would be created, containing the contents of <code>p1</code>. The file would
+then be read into the struct <code>p2</code>, and its <code>Body</code> element
+printed to the screen.
+</p>
+
+<p>
+You can compile and run the program like this:
+</p>
+
+<pre>
+$ go build wiki.go
+$ ./wiki
+This is a sample page.
+</pre>
+
+<p>
+(If you're using Windows you must type "<code>wiki</code>" without the
+"<code>./</code>" to run the program.)
+</p>
+
+<p>
+<a href="part1.go">Click here to view the code we've written so far.</a>
+</p>
+
+<h2>Introducing the <code>net/http</code> package (an interlude)</h2>
+
+<p>
+Here's a full working example of a simple web server:
+</p>
+
+{{code "doc/articles/wiki/http-sample.go"}}
+
+<p>
+The <code>main</code> function begins with a call to
+<code>http.HandleFunc</code>, which tells the <code>http</code> package to
+handle all requests to the web root (<code>"/"</code>) with
+<code>handler</code>.
+</p>
+
+<p>
+It then calls <code>http.ListenAndServe</code>, specifying that it should
+listen on port 8080 on any interface (<code>":8080"</code>). (Don't
+worry about its second parameter, <code>nil</code>, for now.)
+This function will block until the program is terminated.
+</p>
+
+<p>
+The function <code>handler</code> is of the type <code>http.HandlerFunc</code>.
+It takes an <code>http.ResponseWriter</code> and an <code>http.Request</code> as
+its arguments.
+</p>
+
+<p>
+An <code>http.ResponseWriter</code> value assembles the HTTP server's response; by writing
+to it, we send data to the HTTP client.
+</p>
+
+<p>
+An <code>http.Request</code> is a data structure that represents the client
+HTTP request. <code>r.URL.Path</code> is the path component
+of the request URL. The trailing <code>[1:]</code> means
+"create a sub-slice of <code>Path</code> from the 1st character to the end."
+This drops the leading "/" from the path name.
+</p>
+
+<p>
+If you run this program and access the URL:
+</p>
+<pre>http://localhost:8080/monkeys</pre>
+<p>
+the program would present a page containing:
+</p>
+<pre>Hi there, I love monkeys!</pre>
+
+<h2>Using <code>net/http</code> to serve wiki pages</h2>
+
+<p>
+To use the <code>net/http</code> package, it must be imported:
+</p>
+
+<pre>
+import (
+ "fmt"
+ "io/ioutil"
+ <b>"net/http"</b>
+)
+</pre>
+
+<p>
+Let's create a handler, <code>viewHandler</code> that will allow users to
+view a wiki page. It will handle URLs prefixed with "/view/".
+</p>
+
+{{code "doc/articles/wiki/part2.go" `/^func viewHandler/` `/^}/`}}
+
+<p>
+First, this function extracts the page title from <code>r.URL.Path</code>,
+the path component of the request URL.
+The <code>Path</code> is re-sliced with <code>[len("/view/"):]</code> to drop
+the leading <code>"/view/"</code> component of the request path.
+This is because the path will invariably begin with <code>"/view/"</code>,
+which is not part of the page's title.
+</p>
+
+<p>
+The function then loads the page data, formats the page with a string of simple
+HTML, and writes it to <code>w</code>, the <code>http.ResponseWriter</code>.
+</p>
+
+<p>
+Again, note the use of <code>_</code> to ignore the <code>error</code>
+return value from <code>loadPage</code>. This is done here for simplicity
+and generally considered bad practice. We will attend to this later.
+</p>
+
+<p>
+To use this handler, we rewrite our <code>main</code> function to
+initialize <code>http</code> using the <code>viewHandler</code> to handle
+any requests under the path <code>/view/</code>.
+</p>
+
+{{code "doc/articles/wiki/part2.go" `/^func main/` `/^}/`}}
+
+<p>
+<a href="part2.go">Click here to view the code we've written so far.</a>
+</p>
+
+<p>
+Let's create some page data (as <code>test.txt</code>), compile our code, and
+try serving a wiki page.
+</p>
+
+<p>
+Open <code>test.txt</code> file in your editor, and save the string "Hello world" (without quotes)
+in it.
+</p>
+
+<pre>
+$ go build wiki.go
+$ ./wiki
+</pre>
+
+<p>
+(If you're using Windows you must type "<code>wiki</code>" without the
+"<code>./</code>" to run the program.)
+</p>
+
+<p>
+With this web server running, a visit to <code><a
+href="http://localhost:8080/view/test">http://localhost:8080/view/test</a></code>
+should show a page titled "test" containing the words "Hello world".
+</p>
+
+<h2>Editing Pages</h2>
+
+<p>
+A wiki is not a wiki without the ability to edit pages. Let's create two new
+handlers: one named <code>editHandler</code> to display an 'edit page' form,
+and the other named <code>saveHandler</code> to save the data entered via the
+form.
+</p>
+
+<p>
+First, we add them to <code>main()</code>:
+</p>
+
+{{code "doc/articles/wiki/final-noclosure.go" `/^func main/` `/^}/`}}
+
+<p>
+The function <code>editHandler</code> loads the page
+(or, if it doesn't exist, create an empty <code>Page</code> struct),
+and displays an HTML form.
+</p>
+
+{{code "doc/articles/wiki/notemplate.go" `/^func editHandler/` `/^}/`}}
+
+<p>
+This function will work fine, but all that hard-coded HTML is ugly.
+Of course, there is a better way.
+</p>
+
+<h2>The <code>html/template</code> package</h2>
+
+<p>
+The <code>html/template</code> package is part of the Go standard library.
+We can use <code>html/template</code> to keep the HTML in a separate file,
+allowing us to change the layout of our edit page without modifying the
+underlying Go code.
+</p>
+
+<p>
+First, we must add <code>html/template</code> to the list of imports. We
+also won't be using <code>fmt</code> anymore, so we have to remove that.
+</p>
+
+<pre>
+import (
+ <b>"html/template"</b>
+ "io/ioutil"
+ "net/http"
+)
+</pre>
+
+<p>
+Let's create a template file containing the HTML form.
+Open a new file named <code>edit.html</code>, and add the following lines:
+</p>
+
+{{code "doc/articles/wiki/edit.html"}}
+
+<p>
+Modify <code>editHandler</code> to use the template, instead of the hard-coded
+HTML:
+</p>
+
+{{code "doc/articles/wiki/final-noerror.go" `/^func editHandler/` `/^}/`}}
+
+<p>
+The function <code>template.ParseFiles</code> will read the contents of
+<code>edit.html</code> and return a <code>*template.Template</code>.
+</p>
+
+<p>
+The method <code>t.Execute</code> executes the template, writing the
+generated HTML to the <code>http.ResponseWriter</code>.
+The <code>.Title</code> and <code>.Body</code> dotted identifiers refer to
+<code>p.Title</code> and <code>p.Body</code>.
+</p>
+
+<p>
+Template directives are enclosed in double curly braces.
+The <code>printf "%s" .Body</code> instruction is a function call
+that outputs <code>.Body</code> as a string instead of a stream of bytes,
+the same as a call to <code>fmt.Printf</code>.
+The <code>html/template</code> package helps guarantee that only safe and
+correct-looking HTML is generated by template actions. For instance, it
+automatically escapes any greater than sign (<code>></code>), replacing it
+with <code>&gt;</code>, to make sure user data does not corrupt the form
+HTML.
+</p>
+
+<p>
+Since we're working with templates now, let's create a template for our
+<code>viewHandler</code> called <code>view.html</code>:
+</p>
+
+{{code "doc/articles/wiki/view.html"}}
+
+<p>
+Modify <code>viewHandler</code> accordingly:
+</p>
+
+{{code "doc/articles/wiki/final-noerror.go" `/^func viewHandler/` `/^}/`}}
+
+<p>
+Notice that we've used almost exactly the same templating code in both
+handlers. Let's remove this duplication by moving the templating code
+to its own function:
+</p>
+
+{{code "doc/articles/wiki/final-template.go" `/^func renderTemplate/` `/^}/`}}
+
+<p>
+And modify the handlers to use that function:
+</p>
+
+{{code "doc/articles/wiki/final-template.go" `/^func viewHandler/` `/^}/`}}
+{{code "doc/articles/wiki/final-template.go" `/^func editHandler/` `/^}/`}}
+
+<p>
+If we comment out the registration of our unimplemented save handler in
+<code>main</code>, we can once again build and test our program.
+<a href="part3.go">Click here to view the code we've written so far.</a>
+</p>
+
+<h2>Handling non-existent pages</h2>
+
+<p>
+What if you visit <a href="http://localhost:8080/view/APageThatDoesntExist">
+<code>/view/APageThatDoesntExist</code></a>? You'll see a page containing
+HTML. This is because it ignores the error return value from
+<code>loadPage</code> and continues to try and fill out the template
+with no data. Instead, if the requested Page doesn't exist, it should
+redirect the client to the edit Page so the content may be created:
+</p>
+
+{{code "doc/articles/wiki/part3-errorhandling.go" `/^func viewHandler/` `/^}/`}}
+
+<p>
+The <code>http.Redirect</code> function adds an HTTP status code of
+<code>http.StatusFound</code> (302) and a <code>Location</code>
+header to the HTTP response.
+</p>
+
+<h2>Saving Pages</h2>
+
+<p>
+The function <code>saveHandler</code> will handle the submission of forms
+located on the edit pages. After uncommenting the related line in
+<code>main</code>, let's implement the handler:
+</p>
+
+{{code "doc/articles/wiki/final-template.go" `/^func saveHandler/` `/^}/`}}
+
+<p>
+The page title (provided in the URL) and the form's only field,
+<code>Body</code>, are stored in a new <code>Page</code>.
+The <code>save()</code> method is then called to write the data to a file,
+and the client is redirected to the <code>/view/</code> page.
+</p>
+
+<p>
+The value returned by <code>FormValue</code> is of type <code>string</code>.
+We must convert that value to <code>[]byte</code> before it will fit into
+the <code>Page</code> struct. We use <code>[]byte(body)</code> to perform
+the conversion.
+</p>
+
+<h2>Error handling</h2>
+
+<p>
+There are several places in our program where errors are being ignored. This
+is bad practice, not least because when an error does occur the program will
+have unintended behavior. A better solution is to handle the errors and return
+an error message to the user. That way if something does go wrong, the server
+will function exactly how we want and the user can be notified.
+</p>
+
+<p>
+First, let's handle the errors in <code>renderTemplate</code>:
+</p>
+
+{{code "doc/articles/wiki/final-parsetemplate.go" `/^func renderTemplate/` `/^}/`}}
+
+<p>
+The <code>http.Error</code> function sends a specified HTTP response code
+(in this case "Internal Server Error") and error message.
+Already the decision to put this in a separate function is paying off.
+</p>
+
+<p>
+Now let's fix up <code>saveHandler</code>:
+</p>
+
+{{code "doc/articles/wiki/part3-errorhandling.go" `/^func saveHandler/` `/^}/`}}
+
+<p>
+Any errors that occur during <code>p.save()</code> will be reported
+to the user.
+</p>
+
+<h2>Template caching</h2>
+
+<p>
+There is an inefficiency in this code: <code>renderTemplate</code> calls
+<code>ParseFiles</code> every time a page is rendered.
+A better approach would be to call <code>ParseFiles</code> once at program
+initialization, parsing all templates into a single <code>*Template</code>.
+Then we can use the
+<a href="/pkg/html/template/#Template.ExecuteTemplate"><code>ExecuteTemplate</code></a>
+method to render a specific template.
+</p>
+
+<p>
+First we create a global variable named <code>templates</code>, and initialize
+it with <code>ParseFiles</code>.
+</p>
+
+{{code "doc/articles/wiki/final.go" `/var templates/`}}
+
+<p>
+The function <code>template.Must</code> is a convenience wrapper that panics
+when passed a non-nil <code>error</code> value, and otherwise returns the
+<code>*Template</code> unaltered. A panic is appropriate here; if the templates
+can't be loaded the only sensible thing to do is exit the program.
+</p>
+
+<p>
+The <code>ParseFiles</code> function takes any number of string arguments that
+identify our template files, and parses those files into templates that are
+named after the base file name. If we were to add more templates to our
+program, we would add their names to the <code>ParseFiles</code> call's
+arguments.
+</p>
+
+<p>
+We then modify the <code>renderTemplate</code> function to call the
+<code>templates.ExecuteTemplate</code> method with the name of the appropriate
+template:
+</p>
+
+{{code "doc/articles/wiki/final.go" `/func renderTemplate/` `/^}/`}}
+
+<p>
+Note that the template name is the template file name, so we must
+append <code>".html"</code> to the <code>tmpl</code> argument.
+</p>
+
+<h2>Validation</h2>
+
+<p>
+As you may have observed, this program has a serious security flaw: a user
+can supply an arbitrary path to be read/written on the server. To mitigate
+this, we can write a function to validate the title with a regular expression.
+</p>
+
+<p>
+First, add <code>"regexp"</code> to the <code>import</code> list.
+Then we can create a global variable to store our validation
+expression:
+</p>
+
+{{code "doc/articles/wiki/final-noclosure.go" `/^var validPath/`}}
+
+<p>
+The function <code>regexp.MustCompile</code> will parse and compile the
+regular expression, and return a <code>regexp.Regexp</code>.
+<code>MustCompile</code> is distinct from <code>Compile</code> in that it will
+panic if the expression compilation fails, while <code>Compile</code> returns
+an <code>error</code> as a second parameter.
+</p>
+
+<p>
+Now, let's write a function that uses the <code>validPath</code>
+expression to validate path and extract the page title:
+</p>
+
+{{code "doc/articles/wiki/final-noclosure.go" `/func getTitle/` `/^}/`}}
+
+<p>
+If the title is valid, it will be returned along with a <code>nil</code>
+error value. If the title is invalid, the function will write a
+"404 Not Found" error to the HTTP connection, and return an error to the
+handler. To create a new error, we have to import the <code>errors</code>
+package.
+</p>
+
+<p>
+Let's put a call to <code>getTitle</code> in each of the handlers:
+</p>
+
+{{code "doc/articles/wiki/final-noclosure.go" `/^func viewHandler/` `/^}/`}}
+{{code "doc/articles/wiki/final-noclosure.go" `/^func editHandler/` `/^}/`}}
+{{code "doc/articles/wiki/final-noclosure.go" `/^func saveHandler/` `/^}/`}}
+
+<h2>Introducing Function Literals and Closures</h2>
+
+<p>
+Catching the error condition in each handler introduces a lot of repeated code.
+What if we could wrap each of the handlers in a function that does this
+validation and error checking? Go's
+<a href="/ref/spec#Function_literals">function
+literals</a> provide a powerful means of abstracting functionality
+that can help us here.
+</p>
+
+<p>
+First, we re-write the function definition of each of the handlers to accept
+a title string:
+</p>
+
+<pre>
+func viewHandler(w http.ResponseWriter, r *http.Request, title string)
+func editHandler(w http.ResponseWriter, r *http.Request, title string)
+func saveHandler(w http.ResponseWriter, r *http.Request, title string)
+</pre>
+
+<p>
+Now let's define a wrapper function that <i>takes a function of the above
+type</i>, and returns a function of type <code>http.HandlerFunc</code>
+(suitable to be passed to the function <code>http.HandleFunc</code>):
+</p>
+
+<pre>
+func makeHandler(fn func (http.ResponseWriter, *http.Request, string)) http.HandlerFunc {
+ return func(w http.ResponseWriter, r *http.Request) {
+ // Here we will extract the page title from the Request,
+ // and call the provided handler 'fn'
+ }
+}
+</pre>
+
+<p>
+The returned function is called a closure because it encloses values defined
+outside of it. In this case, the variable <code>fn</code> (the single argument
+to <code>makeHandler</code>) is enclosed by the closure. The variable
+<code>fn</code> will be one of our save, edit, or view handlers.
+</p>
+
+<p>
+Now we can take the code from <code>getTitle</code> and use it here
+(with some minor modifications):
+</p>
+
+{{code "doc/articles/wiki/final.go" `/func makeHandler/` `/^}/`}}
+
+<p>
+The closure returned by <code>makeHandler</code> is a function that takes
+an <code>http.ResponseWriter</code> and <code>http.Request</code> (in other
+words, an <code>http.HandlerFunc</code>).
+The closure extracts the <code>title</code> from the request path, and
+validates it with the <code>TitleValidator</code> regexp. If the
+<code>title</code> is invalid, an error will be written to the
+<code>ResponseWriter</code> using the <code>http.NotFound</code> function.
+If the <code>title</code> is valid, the enclosed handler function
+<code>fn</code> will be called with the <code>ResponseWriter</code>,
+<code>Request</code>, and <code>title</code> as arguments.
+</p>
+
+<p>
+Now we can wrap the handler functions with <code>makeHandler</code> in
+<code>main</code>, before they are registered with the <code>http</code>
+package:
+</p>
+
+{{code "doc/articles/wiki/final.go" `/func main/` `/^}/`}}
+
+<p>
+Finally we remove the calls to <code>getTitle</code> from the handler functions,
+making them much simpler:
+</p>
+
+{{code "doc/articles/wiki/final.go" `/^func viewHandler/` `/^}/`}}
+{{code "doc/articles/wiki/final.go" `/^func editHandler/` `/^}/`}}
+{{code "doc/articles/wiki/final.go" `/^func saveHandler/` `/^}/`}}
+
+<h2>Try it out!</h2>
+
+<p>
+<a href="final.go">Click here to view the final code listing.</a>
+</p>
+
+<p>
+Recompile the code, and run the app:
+</p>
+
+<pre>
+$ go build wiki.go
+$ ./wiki
+</pre>
+
+<p>
+Visiting <a href="http://localhost:8080/view/ANewPage">http://localhost:8080/view/ANewPage</a>
+should present you with the page edit form. You should then be able to
+enter some text, click 'Save', and be redirected to the newly created page.
+</p>
+
+<h2>Other tasks</h2>
+
+<p>
+Here are some simple tasks you might want to tackle on your own:
+</p>
+
+<ul>
+<li>Store templates in <code>tmpl/</code> and page data in <code>data/</code>.
+<li>Add a handler to make the web root redirect to
+ <code>/view/FrontPage</code>.</li>
+<li>Spruce up the page templates by making them valid HTML and adding some
+ CSS rules.</li>
+<li>Implement inter-page linking by converting instances of
+ <code>[PageName]</code> to <br>
+ <code><a href="/view/PageName">PageName</a></code>.
+ (hint: you could use <code>regexp.ReplaceAllFunc</code> to do this)
+ </li>
+</ul>
diff --git a/doc/articles/wiki/notemplate.go b/doc/articles/wiki/notemplate.go
new file mode 100644
index 0000000..be214d1
--- /dev/null
+++ b/doc/articles/wiki/notemplate.go
@@ -0,0 +1,56 @@
+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "fmt"
+ "io/ioutil"
+ "net/http"
+)
+
+type Page struct {
+ Title string
+ Body []byte
+}
+
+func (p *Page) save() error {
+ filename := p.Title + ".txt"
+ return ioutil.WriteFile(filename, p.Body, 0600)
+}
+
+func loadPage(title string) (*Page, error) {
+ filename := title + ".txt"
+ body, err := ioutil.ReadFile(filename)
+ if err != nil {
+ return nil, err
+ }
+ return &Page{Title: title, Body: body}, nil
+}
+
+func viewHandler(w http.ResponseWriter, r *http.Request) {
+ title := r.URL.Path[len("/view/"):]
+ p, _ := loadPage(title)
+ fmt.Fprintf(w, "<h1>%s</h1><div>%s</div>", p.Title, p.Body)
+}
+
+func editHandler(w http.ResponseWriter, r *http.Request) {
+ title := r.URL.Path[len("/edit/"):]
+ p, err := loadPage(title)
+ if err != nil {
+ p = &Page{Title: title}
+ }
+ fmt.Fprintf(w, "<h1>Editing %s</h1>"+
+ "<form action=\"/save/%s\" method=\"POST\">"+
+ "<textarea name=\"body\">%s</textarea><br>"+
+ "<input type=\"submit\" value=\"Save\">"+
+ "</form>",
+ p.Title, p.Title, p.Body)
+}
+
+func main() {
+ http.HandleFunc("/view/", viewHandler)
+ http.HandleFunc("/edit/", editHandler)
+ http.ListenAndServe(":8080", nil)
+}
diff --git a/doc/articles/wiki/part1-noerror.go b/doc/articles/wiki/part1-noerror.go
new file mode 100644
index 0000000..7577b7b
--- /dev/null
+++ b/doc/articles/wiki/part1-noerror.go
@@ -0,0 +1,33 @@
+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "fmt"
+ "io/ioutil"
+)
+
+type Page struct {
+ Title string
+ Body []byte
+}
+
+func (p *Page) save() error {
+ filename := p.Title + ".txt"
+ return ioutil.WriteFile(filename, p.Body, 0600)
+}
+
+func loadPage(title string) *Page {
+ filename := title + ".txt"
+ body, _ := ioutil.ReadFile(filename)
+ return &Page{Title: title, Body: body}
+}
+
+func main() {
+ p1 := &Page{Title: "TestPage", Body: []byte("This is a sample page.")}
+ p1.save()
+ p2 := loadPage("TestPage")
+ fmt.Println(string(p2.Body))
+}
diff --git a/doc/articles/wiki/part1.go b/doc/articles/wiki/part1.go
new file mode 100644
index 0000000..d7bf1be
--- /dev/null
+++ b/doc/articles/wiki/part1.go
@@ -0,0 +1,36 @@
+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "fmt"
+ "io/ioutil"
+)
+
+type Page struct {
+ Title string
+ Body []byte
+}
+
+func (p *Page) save() error {
+ filename := p.Title + ".txt"
+ return ioutil.WriteFile(filename, p.Body, 0600)
+}
+
+func loadPage(title string) (*Page, error) {
+ filename := title + ".txt"
+ body, err := ioutil.ReadFile(filename)
+ if err != nil {
+ return nil, err
+ }
+ return &Page{Title: title, Body: body}, nil
+}
+
+func main() {
+ p1 := &Page{Title: "TestPage", Body: []byte("This is a sample Page.")}
+ p1.save()
+ p2, _ := loadPage("TestPage")
+ fmt.Println(string(p2.Body))
+}
diff --git a/doc/articles/wiki/part2.go b/doc/articles/wiki/part2.go
new file mode 100644
index 0000000..c023169
--- /dev/null
+++ b/doc/articles/wiki/part2.go
@@ -0,0 +1,41 @@
+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "fmt"
+ "io/ioutil"
+ "net/http"
+)
+
+type Page struct {
+ Title string
+ Body []byte
+}
+
+func (p *Page) save() error {
+ filename := p.Title + ".txt"
+ return ioutil.WriteFile(filename, p.Body, 0600)
+}
+
+func loadPage(title string) (*Page, error) {
+ filename := title + ".txt"
+ body, err := ioutil.ReadFile(filename)
+ if err != nil {
+ return nil, err
+ }
+ return &Page{Title: title, Body: body}, nil
+}
+
+func viewHandler(w http.ResponseWriter, r *http.Request) {
+ title := r.URL.Path[len("/view/"):]
+ p, _ := loadPage(title)
+ fmt.Fprintf(w, "<h1>%s</h1><div>%s</div>", p.Title, p.Body)
+}
+
+func main() {
+ http.HandleFunc("/view/", viewHandler)
+ http.ListenAndServe(":8080", nil)
+}
diff --git a/doc/articles/wiki/part3-errorhandling.go b/doc/articles/wiki/part3-errorhandling.go
new file mode 100644
index 0000000..bb4ecda
--- /dev/null
+++ b/doc/articles/wiki/part3-errorhandling.go
@@ -0,0 +1,73 @@
+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "html/template"
+ "io/ioutil"
+ "net/http"
+)
+
+type Page struct {
+ Title string
+ Body []byte
+}
+
+func (p *Page) save() error {
+ filename := p.Title + ".txt"
+ return ioutil.WriteFile(filename, p.Body, 0600)
+}
+
+func loadPage(title string) (*Page, error) {
+ filename := title + ".txt"
+ body, err := ioutil.ReadFile(filename)
+ if err != nil {
+ return nil, err
+ }
+ return &Page{Title: title, Body: body}, nil
+}
+
+func renderTemplate(w http.ResponseWriter, tmpl string, p *Page) {
+ t, _ := template.ParseFiles(tmpl + ".html")
+ t.Execute(w, p)
+}
+
+func viewHandler(w http.ResponseWriter, r *http.Request) {
+ title := r.URL.Path[len("/view/"):]
+ p, err := loadPage(title)
+ if err != nil {
+ http.Redirect(w, r, "/edit/"+title, http.StatusFound)
+ return
+ }
+ renderTemplate(w, "view", p)
+}
+
+func editHandler(w http.ResponseWriter, r *http.Request) {
+ title := r.URL.Path[len("/edit/"):]
+ p, err := loadPage(title)
+ if err != nil {
+ p = &Page{Title: title}
+ }
+ renderTemplate(w, "edit", p)
+}
+
+func saveHandler(w http.ResponseWriter, r *http.Request) {
+ title := r.URL.Path[len("/save/"):]
+ body := r.FormValue("body")
+ p := &Page{Title: title, Body: []byte(body)}
+ err := p.save()
+ if err != nil {
+ http.Error(w, err.Error(), http.StatusInternalServerError)
+ return
+ }
+ http.Redirect(w, r, "/view/"+title, http.StatusFound)
+}
+
+func main() {
+ http.HandleFunc("/view/", viewHandler)
+ http.HandleFunc("/edit/", editHandler)
+ http.HandleFunc("/save/", saveHandler)
+ http.ListenAndServe(":8080", nil)
+}
diff --git a/doc/articles/wiki/part3.go b/doc/articles/wiki/part3.go
new file mode 100644
index 0000000..174f3ab
--- /dev/null
+++ b/doc/articles/wiki/part3.go
@@ -0,0 +1,57 @@
+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "html/template"
+ "io/ioutil"
+ "net/http"
+)
+
+type Page struct {
+ Title string
+ Body []byte
+}
+
+func (p *Page) save() error {
+ filename := p.Title + ".txt"
+ return ioutil.WriteFile(filename, p.Body, 0600)
+}
+
+func loadPage(title string) (*Page, error) {
+ filename := title + ".txt"
+ body, err := ioutil.ReadFile(filename)
+ if err != nil {
+ return nil, err
+ }
+ return &Page{Title: title, Body: body}, nil
+}
+
+func renderTemplate(w http.ResponseWriter, tmpl string, p *Page) {
+ t, _ := template.ParseFiles(tmpl + ".html")
+ t.Execute(w, p)
+}
+
+func viewHandler(w http.ResponseWriter, r *http.Request) {
+ title := r.URL.Path[len("/view/"):]
+ p, _ := loadPage(title)
+ renderTemplate(w, "view", p)
+}
+
+func editHandler(w http.ResponseWriter, r *http.Request) {
+ title := r.URL.Path[len("/edit/"):]
+ p, err := loadPage(title)
+ if err != nil {
+ p = &Page{Title: title}
+ }
+ renderTemplate(w, "edit", p)
+}
+
+func main() {
+ http.HandleFunc("/view/", viewHandler)
+ http.HandleFunc("/edit/", editHandler)
+ //http.HandleFunc("/save/", saveHandler)
+ http.ListenAndServe(":8080", nil)
+}
diff --git a/doc/articles/wiki/test.bash b/doc/articles/wiki/test.bash
new file mode 100755
index 0000000..2997f16
--- /dev/null
+++ b/doc/articles/wiki/test.bash
@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Copyright 2010 The Go Authors. All rights reserved.
+# Use of this source code is governed by a BSD-style
+# license that can be found in the LICENSE file.
+
+set -e
+wiki_pid=
+cleanup() {
+ kill $wiki_pid
+ rm -f test_*.out Test.txt final.bin final-port.txt a.out get.bin
+}
+trap cleanup 0 INT
+
+rm -f get.bin final.bin a.out
+
+# If called with -all, check that all code snippets compile.
+if [ "$1" == "-all" ]; then
+ for fn in *.go; do
+ go build -o a.out $fn
+ done
+fi
+
+go build -o get.bin get.go
+go build -o final.bin final.go
+(./final.bin --addr) &
+wiki_pid=$!
+
+l=0
+while [ ! -f ./final-port.txt ]
+do
+ l=$(($l+1))
+ if [ "$l" -gt 5 ]
+ then
+ echo "port not available within 5 seconds"
+ exit 1
+ break
+ fi
+ sleep 1
+done
+
+addr=$(cat final-port.txt)
+./get.bin http://$addr/edit/Test > test_edit.out
+diff -u test_edit.out test_edit.good
+./get.bin -post=body=some%20content http://$addr/save/Test > test_save.out
+diff -u test_save.out test_view.good # should be the same as viewing
+diff -u Test.txt test_Test.txt.good
+./get.bin http://$addr/view/Test > test_view.out
+diff -u test_view.out test_view.good
+
+echo PASS
diff --git a/doc/articles/wiki/test_Test.txt.good b/doc/articles/wiki/test_Test.txt.good
new file mode 100644
index 0000000..f0eec86
--- /dev/null
+++ b/doc/articles/wiki/test_Test.txt.good
@@ -0,0 +1 @@
+some content
\ No newline at end of file
diff --git a/doc/articles/wiki/test_edit.good b/doc/articles/wiki/test_edit.good
new file mode 100644
index 0000000..36c6dbb
--- /dev/null
+++ b/doc/articles/wiki/test_edit.good
@@ -0,0 +1,6 @@
+<h1>Editing Test</h1>
+
+<form action="/save/Test" method="POST">
+<div><textarea name="body" rows="20" cols="80"></textarea></div>
+<div><input type="submit" value="Save"></div>
+</form>
diff --git a/doc/articles/wiki/test_view.good b/doc/articles/wiki/test_view.good
new file mode 100644
index 0000000..07e8edb
--- /dev/null
+++ b/doc/articles/wiki/test_view.good
@@ -0,0 +1,5 @@
+<h1>Test</h1>
+
+<p>[<a href="/edit/Test">edit</a>]</p>
+
+<div>some content</div>
diff --git a/doc/articles/wiki/view.html b/doc/articles/wiki/view.html
new file mode 100644
index 0000000..b1e87ef
--- /dev/null
+++ b/doc/articles/wiki/view.html
@@ -0,0 +1,5 @@
+<h1>{{.Title}}</h1>
+
+<p>[<a href="/edit/{{.Title}}">edit</a>]</p>
+
+<div>{{printf "%s" .Body}}</div>
diff --git a/doc/asm.html b/doc/asm.html
new file mode 100644
index 0000000..771c493
--- /dev/null
+++ b/doc/asm.html
@@ -0,0 +1,537 @@
+<!--{
+ "Title": "A Quick Guide to Go's Assembler",
+ "Path": "/doc/asm"
+}-->
+
+<h2 id="introduction">A Quick Guide to Go's Assembler</h2>
+
+<p>
+This document is a quick outline of the unusual form of assembly language used by the <code>gc</code>
+suite of Go compilers (<code>6g</code>, <code>8g</code>, etc.).
+The document is not comprehensive.
+</p>
+
+<p>
+The assembler is based on the input to the Plan 9 assemblers, which is documented in detail
+<a href="http://plan9.bell-labs.com/sys/doc/asm.html">on the Plan 9 site</a>.
+If you plan to write assembly language, you should read that document although much of it is Plan 9-specific.
+This document provides a summary of the syntax and
+describes the peculiarities that apply when writing assembly code to interact with Go.
+</p>
+
+<p>
+The most important thing to know about Go's assembler is that it is not a direct representation of the underlying machine.
+Some of the details map precisely to the machine, but some do not.
+This is because the compiler suite (see
+<a href="http://plan9.bell-labs.com/sys/doc/compiler.html">this description</a>)
+needs no assembler pass in the usual pipeline.
+Instead, the compiler emits a kind of incompletely defined instruction set, in binary form, which the linker
+then completes.
+In particular, the linker does instruction selection, so when you see an instruction like <code>MOV</code>
+what the linker actually generates for that operation might not be a move instruction at all, perhaps a clear or load.
+Or it might correspond exactly to the machine instruction with that name.
+In general, machine-specific operations tend to appear as themselves, while more general concepts like
+memory move and subroutine call and return are more abstract.
+The details vary with architecture, and we apologize for the imprecision; the situation is not well-defined.
+</p>
+
+<p>
+The assembler program is a way to generate that intermediate, incompletely defined instruction sequence
+as input for the linker.
+If you want to see what the instructions look like in assembly for a given architecture, say amd64, there
+are many examples in the sources of the standard library, in packages such as
+<a href="/pkg/runtime/"><code>runtime</code></a> and
+<a href="/pkg/math/big/"><code>math/big</code></a>.
+You can also examine what the compiler emits as assembly code:
+</p>
+
+<pre>
+$ cat x.go
+package main
+
+func main() {
+ println(3)
+}
+$ go tool 6g -S x.go # or: go build -gcflags -S x.go
+
+--- prog list "main" ---
+0000 (x.go:3) TEXT main+0(SB),$8-0
+0001 (x.go:3) FUNCDATA $0,gcargs·0+0(SB)
+0002 (x.go:3) FUNCDATA $1,gclocals·0+0(SB)
+0003 (x.go:4) MOVQ $3,(SP)
+0004 (x.go:4) PCDATA $0,$8
+0005 (x.go:4) CALL ,runtime.printint+0(SB)
+0006 (x.go:4) PCDATA $0,$-1
+0007 (x.go:4) PCDATA $0,$0
+0008 (x.go:4) CALL ,runtime.printnl+0(SB)
+0009 (x.go:4) PCDATA $0,$-1
+0010 (x.go:5) RET ,
+...
+</pre>
+
+<p>
+The <code>FUNCDATA</code> and <code>PCDATA</code> directives contain information
+for use by the garbage collector; they are introduced by the compiler.
+</p>
+
+<!-- Commenting out because the feature is gone but it's popular and may come back.
+
+<p>
+To see what gets put in the binary after linking, add the <code>-a</code> flag to the linker:
+</p>
+
+<pre>
+$ go tool 6l -a x.6 # or: go build -ldflags -a x.go
+codeblk [0x2000,0x1d059) at offset 0x1000
+002000 main.main | (3) TEXT main.main+0(SB),$8
+002000 65488b0c25a0080000 | (3) MOVQ 2208(GS),CX
+002009 483b21 | (3) CMPQ SP,(CX)
+00200c 7707 | (3) JHI ,2015
+00200e e83da20100 | (3) CALL ,1c250+runtime.morestack00
+002013 ebeb | (3) JMP ,2000
+002015 4883ec08 | (3) SUBQ $8,SP
+002019 | (3) FUNCDATA $0,main.gcargs·0+0(SB)
+002019 | (3) FUNCDATA $1,main.gclocals·0+0(SB)
+002019 48c7042403000000 | (4) MOVQ $3,(SP)
+002021 | (4) PCDATA $0,$8
+002021 e8aad20000 | (4) CALL ,f2d0+runtime.printint
+002026 | (4) PCDATA $0,$-1
+002026 | (4) PCDATA $0,$0
+002026 e865d40000 | (4) CALL ,f490+runtime.printnl
+00202b | (4) PCDATA $0,$-1
+00202b 4883c408 | (5) ADDQ $8,SP
+00202f c3 | (5) RET ,
+...
+</pre>
+
+-->
+
+<h3 id="symbols">Symbols</h3>
+
+<p>
+Some symbols, such as <code>PC</code>, <code>R0</code> and <code>SP</code>, are predeclared and refer to registers.
+There are two other predeclared symbols, <code>SB</code> (static base) and <code>FP</code> (frame pointer).
+All user-defined symbols other than jump labels are written as offsets to these pseudo-registers.
+</p>
+
+<p>
+The <code>SB</code> pseudo-register can be thought of as the origin of memory, so the symbol <code>foo(SB)</code>
+is the name <code>foo</code> as an address in memory.
+This form is used to name global functions and data.
+Adding <code><></code> to the name, as in <code>foo<>(SB)</code>, makes the name
+visible only in the current source file, like a top-level <code>static</code> declaration in a C file.
+</p>
+
+<p>
+The <code>FP</code> pseudo-register is a virtual frame pointer
+used to refer to function arguments.
+The compilers maintain a virtual frame pointer and refer to the arguments on the stack as offsets from that pseudo-register.
+Thus <code>0(FP)</code> is the first argument to the function,
+<code>8(FP)</code> is the second (on a 64-bit machine), and so on.
+When referring to a function argument this way, it is conventional to place the name
+at the beginning, as in <code>first_arg+0(FP)</code> and <code>second_arg+8(FP)</code>.
+Some of the assemblers enforce this convention, rejecting plain <code>0(FP)</code> and <code>8(FP)</code>.
+For assembly functions with Go prototypes, <code>go</code> <code>vet</code> will check that the argument names
+and offsets match.
+On 32-bit systems, the low and high 32 bits of a 64-bit value are distinguished by adding
+a <code>_lo</code> or <code>_hi</code> suffix to the name, as in <code>arg_lo+0(FP)</code> or <code>arg_hi+4(FP)</code>.
+If a Go prototype does not name its result, the expected assembly name is <code>ret</code>.
+</p>
+
+<p>
+The <code>SP</code> pseudo-register is a virtual stack pointer
+used to refer to frame-local variables and the arguments being
+prepared for function calls.
+It points to the top of the local stack frame, so references should use negative offsets
+in the range [−framesize, 0):
+<code>x-8(SP)</code>, <code>y-4(SP)</code>, and so on.
+On architectures with a real register named <code>SP</code>, the name prefix distinguishes
+references to the virtual stack pointer from references to the architectural <code>SP</code> register.
+That is, <code>x-8(SP)</code> and <code>-8(SP)</code> are different memory locations:
+the first refers to the virtual stack pointer pseudo-register, while the second refers to the
+hardware's <code>SP</code> register.
+</p>
+
+<p>
+Instructions, registers, and assembler directives are always in UPPER CASE to remind you
+that assembly programming is a fraught endeavor.
+(Exception: the <code>g</code> register renaming on ARM.)
+</p>
+
+<p>
+In Go object files and binaries, the full name of a symbol is the
+package path followed by a period and the symbol name:
+<code>fmt.Printf</code> or <code>math/rand.Int</code>.
+Because the assembler's parser treats period and slash as punctuation,
+those strings cannot be used directly as identifier names.
+Instead, the assembler allows the middle dot character U+00B7
+and the division slash U+2215 in identifiers and rewrites them to
+plain period and slash.
+Within an assembler source file, the symbols above are written as
+<code>fmt·Printf</code> and <code>math∕rand·Int</code>.
+The assembly listings generated by the compilers when using the <code>-S</code> flag
+show the period and slash directly instead of the Unicode replacements
+required by the assemblers.
+</p>
+
+<p>
+Most hand-written assembly files do not include the full package path
+in symbol names, because the linker inserts the package path of the current
+object file at the beginning of any name starting with a period:
+in an assembly source file within the math/rand package implementation,
+the package's Int function can be referred to as <code>·Int</code>.
+This convention avoids the need to hard-code a package's import path in its
+own source code, making it easier to move the code from one location to another.
+</p>
+
+<h3 id="directives">Directives</h3>
+
+<p>
+The assembler uses various directives to bind text and data to symbol names.
+For example, here is a simple complete function definition. The <code>TEXT</code>
+directive declares the symbol <code>runtime·profileloop</code> and the instructions
+that follow form the body of the function.
+The last instruction in a <code>TEXT</code> block must be some sort of jump, usually a <code>RET</code> (pseudo-)instruction.
+(If it's not, the linker will append a jump-to-itself instruction; there is no fallthrough in <code>TEXTs</code>.)
+After the symbol, the arguments are flags (see below)
+and the frame size, a constant (but see below):
+</p>
+
+<pre>
+TEXT runtime·profileloop(SB),NOSPLIT,$8
+ MOVQ $runtime·profileloop1(SB), CX
+ MOVQ CX, 0(SP)
+ CALL runtime·externalthreadhandler(SB)
+ RET
+</pre>
+
+<p>
+In the general case, the frame size is followed by an argument size, separated by a minus sign.
+(It's not a subtraction, just idiosyncratic syntax.)
+The frame size <code>$24-8</code> states that the function has a 24-byte frame
+and is called with 8 bytes of argument, which live on the caller's frame.
+If <code>NOSPLIT</code> is not specified for the <code>TEXT</code>,
+the argument size must be provided.
+For assembly functions with Go prototypes, <code>go</code> <code>vet</code> will check that the
+argument size is correct.
+</p>
+
+<p>
+Note that the symbol name uses a middle dot to separate the components and is specified as an offset from the
+static base pseudo-register <code>SB</code>.
+This function would be called from Go source for package <code>runtime</code> using the
+simple name <code>profileloop</code>.
+</p>
+
+<p>
+Global data symbols are defined by a sequence of initializing
+<code>DATA</code> directives followed by a <code>GLOBL</code> directive.
+Each <code>DATA</code> directive initializes a section of the
+corresponding memory.
+The memory not explicitly initialized is zeroed.
+The general form of the <code>DATA</code> directive is
+
+<pre>
+DATA symbol+offset(SB)/width, value
+</pre>
+
+<p>
+which initializes the symbol memory at the given offset and width with the given value.
+The <code>DATA</code> directives for a given symbol must be written with increasing offsets.
+</p>
+
+<p>
+The <code>GLOBL</code> directive declares a symbol to be global.
+The arguments are optional flags and the size of the data being declared as a global,
+which will have initial value all zeros unless a <code>DATA</code> directive
+has initialized it.
+The <code>GLOBL</code> directive must follow any corresponding <code>DATA</code> directives.
+</p>
+
+<p>
+For example,
+</p>
+
+<pre>
+DATA divtab<>+0x00(SB)/4, $0xf4f8fcff
+DATA divtab<>+0x04(SB)/4, $0xe6eaedf0
+...
+DATA divtab<>+0x3c(SB)/4, $0x81828384
+GLOBL divtab<>(SB), RODATA, $64
+
+GLOBL runtime·tlsoffset(SB), NOPTR, $4
+</pre>
+
+<p>
+declares and initializes <code>divtab<></code>, a read-only 64-byte table of 4-byte integer values,
+and declares <code>runtime·tlsoffset</code>, a 4-byte, implicitly zeroed variable that
+contains no pointers.
+</p>
+
+<p>
+There may be one or two arguments to the directives.
+If there are two, the first is a bit mask of flags,
+which can be written as numeric expressions, added or or-ed together,
+or can be set symbolically for easier absorption by a human.
+Their values, defined in the standard <code>#include</code> file <code>textflag.h</code>, are:
+</p>
+
+<ul>
+<li>
+<code>NOPROF</code> = 1
+<br>
+(For <code>TEXT</code> items.)
+Don't profile the marked function. This flag is deprecated.
+</li>
+<li>
+<code>DUPOK</code> = 2
+<br>
+It is legal to have multiple instances of this symbol in a single binary.
+The linker will choose one of the duplicates to use.
+</li>
+<li>
+<code>NOSPLIT</code> = 4
+<br>
+(For <code>TEXT</code> items.)
+Don't insert the preamble to check if the stack must be split.
+The frame for the routine, plus anything it calls, must fit in the
+spare space at the top of the stack segment.
+Used to protect routines such as the stack splitting code itself.
+</li>
+<li>
+<code>RODATA</code> = 8
+<br>
+(For <code>DATA</code> and <code>GLOBL</code> items.)
+Put this data in a read-only section.
+</li>
+<li>
+<code>NOPTR</code> = 16
+<br>
+(For <code>DATA</code> and <code>GLOBL</code> items.)
+This data contains no pointers and therefore does not need to be
+scanned by the garbage collector.
+</li>
+<li>
+<code>WRAPPER</code> = 32
+<br>
+(For <code>TEXT</code> items.)
+This is a wrapper function and should not count as disabling <code>recover</code>.
+</li>
+</ul>
+
+<h3 id="runtime">Runtime Coordination</h3>
+
+<p>
+For garbage collection to run correctly, the runtime must know the
+location of pointers in all global data and in most stack frames.
+The Go compiler emits this information when compiling Go source files,
+but assembly programs must define it explicitly.
+</p>
+
+<p>
+A data symbol marked with the <code>NOPTR</code> flag (see above)
+is treated as containing no pointers to runtime-allocated data.
+A data symbol with the <code>RODATA</code> flag
+is allocated in read-only memory and is therefore treated
+as implicitly marked <code>NOPTR</code>.
+A data symbol with a total size smaller than a pointer
+is also treated as implicitly marked <code>NOPTR</code>.
+It is not possible to define a symbol containing pointers in an assembly source file;
+such a symbol must be defined in a Go source file instead.
+Assembly source can still refer to the symbol by name
+even without <code>DATA</code> and <code>GLOBL</code> directives.
+A good general rule of thumb is to define all non-<code>RODATA</code>
+symbols in Go instead of in assembly.
+</p>
+
+<p>
+Each function also needs annotations giving the location of
+live pointers in its arguments, results, and local stack frame.
+For an assembly function with no pointer results and
+either no local stack frame or no function calls,
+the only requirement is to define a Go prototype for the function
+in a Go source file in the same package.
+For more complex situations, explicit annotation is needed.
+These annotations use pseudo-instructions defined in the standard
+<code>#include</code> file <code>funcdata.h</code>.
+</p>
+
+<p>
+If a function has no arguments and no results,
+the pointer information can be omitted.
+This is indicated by an argument size annotation of <code>$<i>n</i>-0</code>
+on the <code>TEXT</code> instruction.
+Otherwise, pointer information must be provided by
+a Go prototype for the function in a Go source file,
+even for assembly functions not called directly from Go.
+(The prototype will also let <code>go</code> <code>vet</code> check the argument references.)
+At the start of the function, the arguments are assumed
+to be initialized but the results are assumed uninitialized.
+If the results will hold live pointers during a call instruction,
+the function should start by zeroing the results and then
+executing the pseudo-instruction <code>GO_RESULTS_INITIALIZED</code>.
+This instruction records that the results are now initialized
+and should be scanned during stack movement and garbage collection.
+It is typically easier to arrange that assembly functions do not
+return pointers or do not contain call instructions;
+no assembly functions in the standard library use
+<code>GO_RESULTS_INITIALIZED</code>.
+</p>
+
+<p>
+If a function has no local stack frame,
+the pointer information can be omitted.
+This is indicated by a local frame size annotation of <code>$0-<i>n</i></code>
+on the <code>TEXT</code> instruction.
+The pointer information can also be omitted if the
+function contains no call instructions.
+Otherwise, the local stack frame must not contain pointers,
+and the assembly must confirm this fact by executing the
+pseudo-instruction <code>NO_LOCAL_POINTERS</code>.
+Because stack resizing is implemented by moving the stack,
+the stack pointer may change during any function call:
+even pointers to stack data must not be kept in local variables.
+</p>
+
+<h2 id="architectures">Architecture-specific details</h2>
+
+<p>
+It is impractical to list all the instructions and other details for each machine.
+To see what instructions are defined for a given machine, say 32-bit Intel x86,
+look in the top-level header file for the corresponding linker, in this case <code>8l</code>.
+That is, the file <code>$GOROOT/src/cmd/8l/8.out.h</code> contains a C enumeration, called <code>as</code>,
+of the instructions and their spellings as known to the assembler and linker for that architecture.
+In that file you'll find a declaration that begins
+</p>
+
+<pre>
+enum as
+{
+ AXXX,
+ AAAA,
+ AAAD,
+ AAAM,
+ AAAS,
+ AADCB,
+ ...
+</pre>
+
+<p>
+Each instruction begins with a initial capital <code>A</code> in this list, so <code>AADCB</code>
+represents the <code>ADCB</code> (add carry byte) instruction.
+The enumeration is in alphabetical order, plus some late additions (<code>AXXX</code> occupies
+the zero slot as an invalid instruction).
+The sequence has nothing to do with the actual encoding of the machine instructions.
+Again, the linker takes care of that detail.
+</p>
+
+<p>
+One detail evident in the examples from the previous sections is that data in the instructions flows from left to right:
+<code>MOVQ</code> <code>$0,</code> <code>CX</code> clears <code>CX</code>.
+This convention applies even on architectures where the usual mode is the opposite direction.
+</p>
+
+<p>
+Here follows some descriptions of key Go-specific details for the supported architectures.
+</p>
+
+<h3 id="x86">32-bit Intel 386</h3>
+
+<p>
+The runtime pointer to the <code>g</code> structure is maintained
+through the value of an otherwise unused (as far as Go is concerned) register in the MMU.
+A OS-dependent macro <code>get_tls</code> is defined for the assembler if the source includes
+an architecture-dependent header file, like this:
+</p>
+
+<pre>
+#include "zasm_GOOS_GOARCH.h"
+</pre>
+
+<p>
+Within the runtime, the <code>get_tls</code> macro loads its argument register
+with a pointer to the <code>g</code> pointer, and the <code>g</code> struct
+contains the <code>m</code> pointer.
+The sequence to load <code>g</code> and <code>m</code> using <code>CX</code> looks like this:
+</p>
+
+<pre>
+get_tls(CX)
+MOVL g(CX), AX // Move g into AX.
+MOVL g_m(AX), BX // Move g->m into BX.
+</pre>
+
+<h3 id="amd64">64-bit Intel 386 (a.k.a. amd64)</h3>
+
+<p>
+The assembly code to access the <code>m</code> and <code>g</code>
+pointers is the same as on the 386, except it uses <code>MOVQ</code> rather than
+<code>MOVL</code>:
+</p>
+
+<pre>
+get_tls(CX)
+MOVQ g(CX), AX // Move g into AX.
+MOVQ g_m(AX), BX // Move g->m into BX.
+</pre>
+
+<h3 id="arm">ARM</h3>
+
+<p>
+The registers <code>R10</code> and <code>R11</code>
+are reserved by the compiler and linker.
+</p>
+
+<p>
+<code>R10</code> points to the <code>g</code> (goroutine) structure.
+Within assembler source code, this pointer must be referred to as <code>g</code>;
+the name <code>R10</code> is not recognized.
+</p>
+
+<p>
+To make it easier for people and compilers to write assembly, the ARM linker
+allows general addressing forms and pseudo-operations like <code>DIV</code> or <code>MOD</code>
+that may not be expressible using a single hardware instruction.
+It implements these forms as multiple instructions, often using the <code>R11</code> register
+to hold temporary values.
+Hand-written assembly can use <code>R11</code>, but doing so requires
+being sure that the linker is not also using it to implement any of the other
+instructions in the function.
+</p>
+
+<p>
+When defining a <code>TEXT</code>, specifying frame size <code>$-4</code>
+tells the linker that this is a leaf function that does not need to save <code>LR</code> on entry.
+</p>
+
+<p>
+The name <code>SP</code> always refers to the virtual stack pointer described earlier.
+For the hardware register, use <code>R13</code>.
+</p>
+
+<h3 id="unsupported_opcodes">Unsupported opcodes</h3>
+
+<p>
+The assemblers are designed to support the compiler so not all hardware instructions
+are defined for all architectures: if the compiler doesn't generate it, it might not be there.
+If you need to use a missing instruction, there are two ways to proceed.
+One is to update the assembler to support that instruction, which is straightforward
+but only worthwhile if it's likely the instruction will be used again.
+Instead, for simple one-off cases, it's possible to use the <code>BYTE</code>
+and <code>WORD</code> directives
+to lay down explicit data into the instruction stream within a <code>TEXT</code>.
+Here's how the 386 runtime defines the 64-bit atomic load function.
+</p>
+
+<pre>
+// uint64 atomicload64(uint64 volatile* addr);
+// so actually
+// void atomicload64(uint64 *res, uint64 volatile *addr);
+TEXT runtime·atomicload64(SB), NOSPLIT, $0-8
+ MOVL ptr+0(FP), AX
+ LEAL ret_lo+4(FP), BX
+ BYTE $0x0f; BYTE $0x6f; BYTE $0x00 // MOVQ (%EAX), %MM0
+ BYTE $0x0f; BYTE $0x7f; BYTE $0x03 // MOVQ %MM0, 0(%EBX)
+ BYTE $0x0F; BYTE $0x77 // EMMS
+ RET
+</pre>
diff --git a/doc/cmd.html b/doc/cmd.html
new file mode 100644
index 0000000..5d20d38
--- /dev/null
+++ b/doc/cmd.html
@@ -0,0 +1,109 @@
+<!--{
+ "Title": "Command Documentation",
+ "Path": "/doc/cmd"
+}-->
+
+<p>
+There is a suite of programs to build and process Go source code.
+Instead of being run directly, programs in the suite are usually invoked
+by the <a href="/cmd/go/">go</a> program.
+</p>
+
+<p>
+The most common way to run these programs is as a subcommand of the go program,
+for instance as <code>go fmt</code>. Run like this, the command operates on
+complete packages of Go source code, with the go program invoking the
+underlying binary with arguments appropriate to package-level processing.
+</p>
+
+<p>
+The programs can also be run as stand-alone binaries, with unmodified arguments,
+using the go <code>tool</code> subcommand, such as <code>go tool vet</code>.
+This style of invocation allows, for instance, checking a single source file
+rather than an entire package: <code>go tool vet myprogram.go</code> as
+compared to <code>go vet mypackage</code>.
+Some of the commands, such as <code>yacc</code>, are accessible only through
+the go <code>tool</code> subcommand.
+</p>
+
+<p>
+Finally the <code>fmt</code> and <code>godoc</code> commands are installed
+as regular binaries called <code>gofmt</code> and <code>godoc</code> because
+they are so often referenced.
+</p>
+
+<p>
+Click on the links for more documentation, invocation methods, and usage details.
+</p>
+
+<table class="dir">
+<tr>
+<th>Name</th>
+<th> </th>
+<th>Synopsis</th>
+</tr>
+
+<tr>
+<td><a href="/cmd/go/">go</a></td>
+<td> </td>
+<td>
+The <code>go</code> program manages Go source code and runs the other
+commands listed here.
+See the command docs for usage
+details.
+<br><br>
+</td>
+</tr>
+
+<tr>
+<td><a href="/cmd/cgo/">cgo</a></td>
+<td> </td>
+<td>Cgo enables the creation of Go packages that call C code.</td>
+</tr>
+
+<tr>
+<td><a href="//godoc.org/golang.org/x/tools/cmd/cover/">cover</a></td>
+<td> </td>
+<td>Cover is a program for creating and analyzing the coverage profiles
+generated by <code>"go test -coverprofile"</code>.</td>
+</tr>
+
+<tr>
+<td><a href="/cmd/fix/">fix</a></td>
+<td> </td>
+<td>Fix finds Go programs that use old features of the language and libraries
+and rewrites them to use newer ones.</td>
+</tr>
+
+<tr>
+<td><a href="/cmd/go/">fmt</a></td>
+<td> </td>
+<td>Fmt formats Go packages, it is also available as an independent <a href="/cmd/gofmt/">
+gofmt</a> command with more general options.</td>
+</tr>
+
+<tr>
+<td><a href="//godoc.org/golang.org/x/tools/cmd/godoc/">godoc</a></td>
+<td> </td>
+<td>Godoc extracts and generates documentation for Go packages.</td>
+</tr>
+
+<tr>
+<td><a href="//godoc.org/golang.org/x/tools/cmd/vet/">vet</a></td>
+<td> </td>
+<td>Vet examines Go source code and reports suspicious constructs, such as Printf
+calls whose arguments do not align with the format string.</td>
+</tr>
+
+<tr>
+<td><a href="/cmd/yacc/">yacc</a></td>
+<td> </td>
+<td>Yacc is a version of yacc that generates parsers implemented in Go.</td>
+</tr>
+
+</table>
+
+<p>
+This is an abridged list. See the <a href="/cmd/">full command reference</a>
+for documentation of the compilers and more.
+</p>
diff --git a/doc/code.html b/doc/code.html
new file mode 100644
index 0000000..a4638f9
--- /dev/null
+++ b/doc/code.html
@@ -0,0 +1,631 @@
+<!--{
+ "Title": "How to Write Go Code"
+}-->
+
+<h2 id="Introduction">Introduction</h2>
+
+<p>
+This document demonstrates the development of a simple Go package and
+introduces the <a href="/cmd/go/">go tool</a>, the standard way to fetch,
+build, and install Go packages and commands.
+</p>
+
+<p>
+The <code>go</code> tool requires you to organize your code in a specific
+way. Please read this document carefully.
+It explains the simplest way to get up and running with your Go installation.
+</p>
+
+<p>
+A similar explanation is available as a
+<a href="//www.youtube.com/watch?v=XCsL89YtqCs">screencast</a>.
+</p>
+
+
+<h2 id="Organization">Code organization</h2>
+
+<h3 id="Workspaces">Workspaces</h3>
+
+<p>
+The <code>go</code> tool is designed to work with open source code maintained
+in public repositories. Although you don't need to publish your code, the model
+for how the environment is set up works the same whether you do or not.
+</p>
+
+<p>
+Go code must be kept inside a <i>workspace</i>.
+A workspace is a directory hierarchy with three directories at its root:
+</p>
+
+<ul>
+<li><code>src</code> contains Go source files organized into packages (one package per directory),
+<li><code>pkg</code> contains package objects, and
+<li><code>bin</code> contains executable commands.
+</ul>
+
+<p>
+The <code>go</code> tool builds source packages and installs the resulting
+binaries to the <code>pkg</code> and <code>bin</code> directories.
+</p>
+
+<p>
+The <code>src</code> subdirectory typically contains multiple version control
+repositories (such as for Git or Mercurial) that track the development of one
+or more source packages.
+</p>
+
+<p>
+To give you an idea of how a workspace looks in practice, here's an example:
+</p>
+
+<pre>
+bin/
+ hello # command executable
+ outyet # command executable
+pkg/
+ linux_amd64/
+ github.com/golang/example/
+ stringutil.a # package object
+src/
+ <a href="https://github.com/golang/example/">github.com/golang/example/</a>
+ .git/ # Git repository metadata
+ hello/
+ hello.go # command source
+ outyet/
+ main.go # command source
+ main_test.go # test source
+ stringutil/
+ reverse.go # package source
+ reverse_test.go # test source
+</pre>
+
+<p>
+This workspace contains one repository (<code>example</code>)
+comprising two commands (<code>hello</code> and <code>outyet</code>)
+and one library (<code>stringutil</code>).
+</p>
+
+<p>
+A typical workspace would contain many source repositories containing many
+packages and commands. Most Go programmers keep <i>all</i> their Go source code
+and dependencies in a single workspace.
+</p>
+
+<p>
+Commands and libraries are built from different kinds of source packages.
+We will discuss the distinction <a href="#PackageNames">later</a>.
+</p>
+
+
+<h3 id="GOPATH">The <code>GOPATH</code> environment variable</h3>
+
+<p>
+The <code>GOPATH</code> environment variable specifies the location of your
+workspace. It is likely the only environment variable you'll need to set
+when developing Go code.
+</p>
+
+<p>
+To get started, create a workspace directory and set <code>GOPATH</code>
+accordingly. Your workspace can be located wherever you like, but we'll use
+<code>$HOME/go</code> in this document. Note that this must <b>not</b> be the
+same path as your Go installation.
+</p>
+
+<pre>
+$ <b>mkdir $HOME/go</b>
+$ <b>export GOPATH=$HOME/go</b>
+</pre>
+
+<p>
+For convenience, add the workspace's <code>bin</code> subdirectory
+to your <code>PATH</code>:
+</p>
+
+<pre>
+$ <b>export PATH=$PATH:$GOPATH/bin</b>
+</pre>
+
+
+<h3 id="PackagePaths">Package paths</h3>
+
+<p>
+The packages from the standard library are given short paths such as
+<code>"fmt"</code> and <code>"net/http"</code>.
+For your own packages, you must choose a base path that is unlikely to
+collide with future additions to the standard library or other external
+libraries.
+</p>
+
+<p>
+If you keep your code in a source repository somewhere, then you should use the
+root of that source repository as your base path.
+For instance, if you have a <a href="https://github.com/">GitHub</a> account at
+<code>github.com/user</code>, that should be your base path.
+</p>
+
+<p>
+Note that you don't need to publish your code to a remote repository before you
+can build it. It's just a good habit to organize your code as if you will
+publish it someday. In practice you can choose any arbitrary path name,
+as long as it is unique to the standard library and greater Go ecosystem.
+</p>
+
+<p>
+We'll use <code>github.com/user</code> as our base path. Create a directory
+inside your workspace in which to keep source code:
+</p>
+
+<pre>
+$ <b>mkdir -p $GOPATH/src/github.com/user</b>
+</pre>
+
+
+<h3 id="Command">Your first program</h3>
+
+<p>
+To compile and run a simple program, first choose a package path (we'll use
+<code>github.com/user/hello</code>) and create a corresponding package directory
+inside your workspace:
+</p>
+
+<pre>
+$ <b>mkdir $GOPATH/src/github.com/user/hello</b>
+</pre>
+
+<p>
+Next, create a file named <code>hello.go</code> inside that directory,
+containing the following Go code.
+</p>
+
+<pre>
+package main
+
+import "fmt"
+
+func main() {
+ fmt.Printf("Hello, world.\n")
+}
+</pre>
+
+<p>
+Now you can build and install that program with the <code>go</code> tool:
+</p>
+
+<pre>
+$ <b>go install github.com/user/hello</b>
+</pre>
+
+<p>
+Note that you can run this command from anywhere on your system. The
+<code>go</code> tool finds the source code by looking for the
+<code>github.com/user/hello</code> package inside the workspace specified by
+<code>GOPATH</code>.
+</p>
+
+<p>
+You can also omit the package path if you run <code>go install</code> from the
+package directory:
+</p>
+
+<pre>
+$ <b>cd $GOPATH/src/github.com/user/hello</b>
+$ <b>go install</b>
+</pre>
+
+<p>
+This command builds the <code>hello</code> command, producing an executable
+binary. It then installs that binary to the workspace's <code>bin</code>
+directory as <code>hello</code> (or, under Windows, <code>hello.exe</code>).
+In our example, that will be <code>$GOPATH/bin/hello</code>, which is
+<code>$HOME/go/bin/hello</code>.
+</p>
+
+<p>
+The <code>go</code> tool will only print output when an error occurs, so if
+these commands produce no output they have executed successfully.
+</p>
+
+<p>
+You can now run the program by typing its full path at the command line:
+</p>
+
+<pre>
+$ <b>$GOPATH/bin/hello</b>
+Hello, world.
+</pre>
+
+<p>
+Or, as you have added <code>$GOPATH/bin</code> to your <code>PATH</code>,
+just type the binary name:
+</p>
+
+<pre>
+$ <b>hello</b>
+Hello, world.
+</pre>
+
+<p>
+If you're using a source control system, now would be a good time to initialize
+a repository, add the files, and commit your first change. Again, this step is
+optional: you do not need to use source control to write Go code.
+</p>
+
+<pre>
+$ <b>cd $GOPATH/src/github.com/user/hello</b>
+$ <b>git init</b>
+Initialized empty Git repository in /home/user/go/src/github.com/user/hello/.git/
+$ <b>git add hello.go</b>
+$ <b>git commit -m "initial commit"</b>
+[master (root-commit) 0b4507d] initial commit
+ 1 file changed, 1 insertion(+)
+ create mode 100644 hello.go
+</pre>
+
+<p>
+Pushing the code to a remote repository is left as an exercise for the reader.
+</p>
+
+
+<h3 id="Library">Your first library</h3>
+
+<p>
+Let's write a library and use it from the <code>hello</code> program.
+</p>
+
+<p>
+Again, the first step is to choose a package path (we'll use
+<code>github.com/user/stringutil</code>) and create the package directory:
+</p>
+
+<pre>
+$ <b>mkdir $GOPATH/src/github.com/user/stringutil</b>
+</pre>
+
+<p>
+Next, create a file named <code>reverse.go</code> in that directory with the
+following contents.
+</p>
+
+<pre>
+// Package stringutil contains utility functions for working with strings.
+package stringutil
+
+// Reverse returns its argument string reversed rune-wise left to right.
+func Reverse(s string) string {
+ r := []rune(s)
+ for i, j := 0, len(r)-1; i < len(r)/2; i, j = i+1, j-1 {
+ r[i], r[j] = r[j], r[i]
+ }
+ return string(r)
+}
+</pre>
+
+<p>
+Now, test that the package compiles with <code>go build</code>:
+</p>
+
+<pre>
+$ <b>go build github.com/user/stringutil</b>
+</pre>
+
+<p>
+Or, if you are working in the package's source directory, just:
+</p>
+
+<pre>
+$ <b>go build</b>
+</pre>
+
+<p>
+This won't produce an output file. To do that, you must use <code>go
+install</code>, which places the package object inside the <code>pkg</code>
+directory of the workspace.
+</p>
+
+<p>
+After confirming that the <code>stringutil</code> package builds,
+modify your original <code>hello.go</code> (which is in
+<code>$GOPATH/src/github.com/user/hello</code>) to use it:
+</p>
+
+<pre>
+package main
+
+import (
+ "fmt"
+
+ <b>"github.com/user/stringutil"</b>
+)
+
+func main() {
+ fmt.Printf(stringutil.Reverse("!oG ,olleH"))
+}
+</pre>
+
+<p>
+Whenever the <code>go</code> tool installs a package or binary, it also
+installs whatever dependencies it has.
+So when you install the <code>hello</code> program
+</p>
+
+<pre>
+$ <b>go install github.com/user/hello</b>
+</pre>
+
+<p>
+the <code>stringutil</code> package will be installed as well, automatically.
+</p>
+
+<p>
+Running the new version of the program, you should see a new, reversed message:
+</p>
+
+<pre>
+$ <b>hello</b>
+Hello, Go!
+</pre>
+
+<p>
+After the steps above, your workspace should look like this:
+</p>
+
+<pre>
+bin/
+ hello # command executable
+pkg/
+ linux_amd64/ # this will reflect your OS and architecture
+ github.com/user/
+ stringutil.a # package object
+src/
+ github.com/user/
+ hello/
+ hello.go # command source
+ stringutil/
+ reverse.go # package source
+</pre>
+
+<p>
+Note that <code>go install</code> placed the <code>stringutil.a</code> object
+in a directory inside <code>pkg/linux_amd64</code> that mirrors its source
+directory.
+This is so that future invocations of the <code>go</code> tool can find the
+package object and avoid recompiling the package unnecessarily.
+The <code>linux_amd64</code> part is there to aid in cross-compilation,
+and will reflect the operating system and architecture of your system.
+</p>
+
+<p>
+Go command executables are statically linked; the package objects need not
+be present to run Go programs.
+</p>
+
+
+<h3 id="PackageNames">Package names</h3>
+
+<p>
+The first statement in a Go source file must be
+</p>
+
+<pre>
+package <i>name</i>
+</pre>
+
+<p>
+where <code><i>name</i></code> is the package's default name for imports.
+(All files in a package must use the same <code><i>name</i></code>.)
+</p>
+
+<p>
+Go's convention is that the package name is the last element of the
+import path: the package imported as "<code>crypto/rot13</code>"
+should be named <code>rot13</code>.
+</p>
+
+<p>
+Executable commands must always use <code>package main</code>.
+</p>
+
+<p>
+There is no requirement that package names be unique
+across all packages linked into a single binary,
+only that the import paths (their full file names) be unique.
+</p>
+
+<p>
+See <a href="/doc/effective_go.html#names">Effective Go</a> to learn more about
+Go's naming conventions.
+</p>
+
+
+<h2 id="Testing">Testing</h2>
+
+<p>
+Go has a lightweight test framework composed of the <code>go test</code>
+command and the <code>testing</code> package.
+</p>
+
+<p>
+You write a test by creating a file with a name ending in <code>_test.go</code>
+that contains functions named <code>TestXXX</code> with signature
+<code>func (t *testing.T)</code>.
+The test framework runs each such function;
+if the function calls a failure function such as <code>t.Error</code> or
+<code>t.Fail</code>, the test is considered to have failed.
+</p>
+
+<p>
+Add a test to the <code>stringutil</code> package by creating the file
+<code>$GOPATH/src/github.com/user/stringutil/reverse_test.go</code> containing
+the following Go code.
+</p>
+
+<pre>
+package stringutil
+
+import "testing"
+
+func TestReverse(t *testing.T) {
+ cases := []struct {
+ in, want string
+ }{
+ {"Hello, world", "dlrow ,olleH"},
+ {"Hello, 世界", "界世 ,olleH"},
+ {"", ""},
+ }
+ for _, c := range cases {
+ got := Reverse(c.in)
+ if got != c.want {
+ t.Errorf("Reverse(%q) == %q, want %q", c.in, got, c.want)
+ }
+ }
+}
+</pre>
+
+<p>
+Then run the test with <code>go test</code>:
+</p>
+
+<pre>
+$ <b>go test github.com/user/stringutil</b>
+ok github.com/user/stringutil 0.165s
+</pre>
+
+<p>
+As always, if you are running the <code>go</code> tool from the package
+directory, you can omit the package path:
+</p>
+
+<pre>
+$ <b>go test</b>
+ok github.com/user/stringutil 0.165s
+</pre>
+
+<p>
+Run <code><a href="/cmd/go/#hdr-Test_packages">go help test</a></code> and see the
+<a href="/pkg/testing/">testing package documentation</a> for more detail.
+</p>
+
+
+<h2 id="remote">Remote packages</h2>
+
+<p>
+An import path can describe how to obtain the package source code using a
+revision control system such as Git or Mercurial. The <code>go</code> tool uses
+this property to automatically fetch packages from remote repositories.
+For instance, the examples described in this document are also kept in a
+Git repository hosted at GitHub
+<code><a href="https://github.com/golang/example">github.com/golang/example</a></code>.
+If you include the repository URL in the package's import path,
+<code>go get</code> will fetch, build, and install it automatically:
+</p>
+
+<pre>
+$ <b>go get github.com/golang/example/hello</b>
+$ <b>$GOPATH/bin/hello</b>
+Hello, Go examples!
+</pre>
+
+<p>
+If the specified package is not present in a workspace, <code>go get</code>
+will place it inside the first workspace specified by <code>GOPATH</code>.
+(If the package does already exist, <code>go get</code> skips the remote
+fetch and behaves the same as <code>go install</code>.)
+</p>
+
+<p>
+After issuing the above <code>go get</code> command, the workspace directory
+tree should now look like this:
+</p>
+
+<pre>
+bin/
+ hello # command executable
+pkg/
+ linux_amd64/
+ github.com/golang/example/
+ stringutil.a # package object
+ github.com/user/
+ stringutil.a # package object
+src/
+ github.com/golang/example/
+ .git/ # Git repository metadata
+ hello/
+ hello.go # command source
+ stringutil/
+ reverse.go # package source
+ reverse_test.go # test source
+ github.com/user/
+ hello/
+ hello.go # command source
+ stringutil/
+ reverse.go # package source
+ reverse_test.go # test source
+</pre>
+
+<p>
+The <code>hello</code> command hosted at GitHub depends on the
+<code>stringutil</code> package within the same repository. The imports in
+<code>hello.go</code> file use the same import path convention, so the
+<code>go get</code> command is able to locate and install the dependent
+package, too.
+</p>
+
+<pre>
+import "github.com/golang/example/stringutil"
+</pre>
+
+<p>
+This convention is the easiest way to make your Go packages available for
+others to use.
+The <a href="//golang.org/wiki/Projects">Go Wiki</a>
+and <a href="//godoc.org/">godoc.org</a>
+provide lists of external Go projects.
+</p>
+
+<p>
+For more information on using remote repositories with the <code>go</code> tool, see
+<code><a href="/cmd/go/#hdr-Remote_import_paths">go help importpath</a></code>.
+</p>
+
+
+<h2 id="next">What's next</h2>
+
+<p>
+Subscribe to the
+<a href="//groups.google.com/group/golang-announce">golang-announce</a>
+mailing list to be notified when a new stable version of Go is released.
+</p>
+
+<p>
+See <a href="/doc/effective_go.html">Effective Go</a> for tips on writing
+clear, idiomatic Go code.
+</p>
+
+<p>
+Take <a href="//tour.golang.org/">A Tour of Go</a> to learn the language
+proper.
+</p>
+
+<p>
+Visit the <a href="/doc/#articles">documentation page</a> for a set of in-depth
+articles about the Go language and its libraries and tools.
+</p>
+
+
+<h2 id="help">Getting help</h2>
+
+<p>
+For real-time help, ask the helpful gophers in <code>#go-nuts</code> on the
+<a href="http://freenode.net/">Freenode</a> IRC server.
+</p>
+
+<p>
+The official mailing list for discussion of the Go language is
+<a href="//groups.google.com/group/golang-nuts">Go Nuts</a>.
+</p>
+
+<p>
+Report bugs using the
+<a href="//golang.org/issue">Go issue tracker</a>.
+</p>
diff --git a/doc/codewalk/codewalk.css b/doc/codewalk/codewalk.css
new file mode 100644
index 0000000..a0814e4
--- /dev/null
+++ b/doc/codewalk/codewalk.css
@@ -0,0 +1,234 @@
+/*
+ Copyright 2010 The Go Authors. All rights reserved.
+ Use of this source code is governed by a BSD-style
+ license that can be found in the LICENSE file.
+*/
+
+#codewalk-main {
+ text-align: left;
+ width: 100%;
+ overflow: auto;
+}
+
+#code-display {
+ border: 0;
+ width: 100%;
+}
+
+.setting {
+ font-size: 8pt;
+ color: #888888;
+ padding: 5px;
+}
+
+.hotkey {
+ text-decoration: underline;
+}
+
+/* Style for Comments (the left-hand column) */
+
+#comment-column {
+ margin: 0pt;
+ width: 30%;
+}
+
+#comment-column.right {
+ float: right;
+}
+
+#comment-column.left {
+ float: left;
+}
+
+#comment-area {
+ overflow-x: hidden;
+ overflow-y: auto;
+}
+
+.comment {
+ cursor: pointer;
+ font-size: 16px;
+ border: 2px solid #ba9836;
+ margin-bottom: 10px;
+ margin-right: 10px; /* yes, for both .left and .right */
+}
+
+.comment:last-child {
+ margin-bottom: 0px;
+}
+
+.right .comment {
+ margin-left: 10px;
+}
+
+.right .comment.first {
+}
+
+.right .comment.last {
+}
+
+.left .comment.first {
+}
+
+.left .comment.last {
+}
+
+.comment.selected {
+ border-color: #99b2cb;
+}
+
+.right .comment.selected {
+ border-left-width: 12px;
+ margin-left: 0px;
+}
+
+.left .comment.selected {
+ border-right-width: 12px;
+ margin-right: 0px;
+}
+
+.comment-link {
+ display: none;
+}
+
+.comment-title {
+ font-size: small;
+ font-weight: bold;
+ background-color: #fffff0;
+ padding-right: 10px;
+ padding-left: 10px;
+ padding-top: 5px;
+ padding-bottom: 5px;
+}
+
+.right .comment-title {
+}
+
+.left .comment-title {
+}
+
+.comment.selected .comment-title {
+ background-color: #f8f8ff;
+}
+
+.comment-text {
+ overflow: auto;
+ padding-left: 10px;
+ padding-right: 10px;
+ padding-top: 10px;
+ padding-bottom: 5px;
+ font-size: small;
+ line-height: 1.3em;
+}
+
+.comment-text p {
+ margin-top: 0em;
+ margin-bottom: 0.5em;
+}
+
+.comment-text p:last-child {
+ margin-bottom: 0em;
+}
+
+.file-name {
+ font-size: x-small;
+ padding-top: 0px;
+ padding-bottom: 5px;
+}
+
+.hidden-filepaths .file-name {
+ display: none;
+}
+
+.path-dir {
+ color: #555;
+}
+
+.path-file {
+ color: #555;
+}
+
+
+/* Style for Code (the right-hand column) */
+
+/* Wrapper for the code column to make widths get calculated correctly */
+#code-column {
+ display: block;
+ position: relative;
+ margin: 0pt;
+ width: 70%;
+}
+
+#code-column.left {
+ float: left;
+}
+
+#code-column.right {
+ float: right;
+}
+
+#code-area {
+ background-color: #f8f8ff;
+ border: 2px solid #99b2cb;
+ padding: 5px;
+}
+
+.left #code-area {
+ margin-right: -1px;
+}
+
+.right #code-area {
+ margin-left: -1px;
+}
+
+#code-header {
+ margin-bottom: 5px;
+}
+
+#code {
+ background-color: white;
+}
+
+code {
+ font-size: 100%;
+}
+
+.codewalkhighlight {
+ font-weight: bold;
+ background-color: #f8f8ff;
+}
+
+#code-display {
+ margin-top: 0px;
+ margin-bottom: 0px;
+}
+
+#sizer {
+ position: absolute;
+ cursor: col-resize;
+ left: 0px;
+ top: 0px;
+ width: 8px;
+}
+
+/* Style for options (bottom strip) */
+
+#code-options {
+ display: none;
+}
+
+#code-options > span {
+ padding-right: 20px;
+}
+
+#code-options .selected {
+ border-bottom: 1px dotted;
+}
+
+#comment-options {
+ text-align: center;
+}
+
+div#content {
+ padding-bottom: 0em;
+}
diff --git a/doc/codewalk/codewalk.js b/doc/codewalk/codewalk.js
new file mode 100644
index 0000000..7bfcd39
--- /dev/null
+++ b/doc/codewalk/codewalk.js
@@ -0,0 +1,305 @@
+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+/**
+ * A class to hold information about the Codewalk Viewer.
+ * @param {jQuery} context The top element in whose context the viewer should
+ * operate. It will not touch any elements above this one.
+ * @constructor
+ */
+ var CodewalkViewer = function(context) {
+ this.context = context;
+
+ /**
+ * The div that contains all of the comments and their controls.
+ */
+ this.commentColumn = this.context.find('#comment-column');
+
+ /**
+ * The div that contains the comments proper.
+ */
+ this.commentArea = this.context.find('#comment-area');
+
+ /**
+ * The div that wraps the iframe with the code, as well as the drop down menu
+ * listing the different files.
+ * @type {jQuery}
+ */
+ this.codeColumn = this.context.find('#code-column');
+
+ /**
+ * The div that contains the code but excludes the options strip.
+ * @type {jQuery}
+ */
+ this.codeArea = this.context.find('#code-area');
+
+ /**
+ * The iframe that holds the code (from Sourcerer).
+ * @type {jQuery}
+ */
+ this.codeDisplay = this.context.find('#code-display');
+
+ /**
+ * The overlaid div used as a grab handle for sizing the code/comment panes.
+ * @type {jQuery}
+ */
+ this.sizer = this.context.find('#sizer');
+
+ /**
+ * The full-screen overlay that ensures we don't lose track of the mouse
+ * while dragging.
+ * @type {jQuery}
+ */
+ this.overlay = this.context.find('#overlay');
+
+ /**
+ * The hidden input field that we use to hold the focus so that we can detect
+ * shortcut keypresses.
+ * @type {jQuery}
+ */
+ this.shortcutInput = this.context.find('#shortcut-input');
+
+ /**
+ * The last comment that was selected.
+ * @type {jQuery}
+ */
+ this.lastSelected = null;
+};
+
+/**
+ * Minimum width of the comments or code pane, in pixels.
+ * @type {number}
+ */
+CodewalkViewer.MIN_PANE_WIDTH = 200;
+
+/**
+ * Navigate the code iframe to the given url and update the code popout link.
+ * @param {string} url The target URL.
+ * @param {Object} opt_window Window dependency injection for testing only.
+ */
+CodewalkViewer.prototype.navigateToCode = function(url, opt_window) {
+ if (!opt_window) opt_window = window;
+ // Each iframe is represented by two distinct objects in the DOM: an iframe
+ // object and a window object. These do not expose the same capabilities.
+ // Here we need to get the window representation to get the location member,
+ // so we access it directly through window[] since jQuery returns the iframe
+ // representation.
+ // We replace location rather than set so as not to create a history for code
+ // navigation.
+ opt_window['code-display'].location.replace(url);
+ var k = url.indexOf('&');
+ if (k != -1) url = url.slice(0, k);
+ k = url.indexOf('fileprint=');
+ if (k != -1) url = url.slice(k+10, url.length);
+ this.context.find('#code-popout-link').attr('href', url);
+};
+
+/**
+ * Selects the first comment from the list and forces a refresh of the code
+ * view.
+ */
+CodewalkViewer.prototype.selectFirstComment = function() {
+ // TODO(rsc): handle case where there are no comments
+ var firstSourcererLink = this.context.find('.comment:first');
+ this.changeSelectedComment(firstSourcererLink);
+};
+
+/**
+ * Sets the target on all links nested inside comments to be _blank.
+ */
+CodewalkViewer.prototype.targetCommentLinksAtBlank = function() {
+ this.context.find('.comment a[href], #description a[href]').each(function() {
+ if (!this.target) this.target = '_blank';
+ });
+};
+
+/**
+ * Installs event handlers for all the events we care about.
+ */
+CodewalkViewer.prototype.installEventHandlers = function() {
+ var self = this;
+
+ this.context.find('.comment')
+ .click(function(event) {
+ if (jQuery(event.target).is('a[href]')) return true;
+ self.changeSelectedComment(jQuery(this));
+ return false;
+ });
+
+ this.context.find('#code-selector')
+ .change(function() {self.navigateToCode(jQuery(this).val());});
+
+ this.context.find('#description-table .quote-feet.setting')
+ .click(function() {self.toggleDescription(jQuery(this)); return false;});
+
+ this.sizer
+ .mousedown(function(ev) {self.startSizerDrag(ev); return false;});
+ this.overlay
+ .mouseup(function(ev) {self.endSizerDrag(ev); return false;})
+ .mousemove(function(ev) {self.handleSizerDrag(ev); return false;});
+
+ this.context.find('#prev-comment')
+ .click(function() {
+ self.changeSelectedComment(self.lastSelected.prev()); return false;
+ });
+
+ this.context.find('#next-comment')
+ .click(function() {
+ self.changeSelectedComment(self.lastSelected.next()); return false;
+ });
+
+ // Workaround for Firefox 2 and 3, which steal focus from the main document
+ // whenever the iframe content is (re)loaded. The input field is not shown,
+ // but is a way for us to bring focus back to a place where we can detect
+ // keypresses.
+ this.context.find('#code-display')
+ .load(function(ev) {self.shortcutInput.focus();});
+
+ jQuery(document).keypress(function(ev) {
+ switch(ev.which) {
+ case 110: // 'n'
+ self.changeSelectedComment(self.lastSelected.next());
+ return false;
+ case 112: // 'p'
+ self.changeSelectedComment(self.lastSelected.prev());
+ return false;
+ default: // ignore
+ }
+ });
+
+ window.onresize = function() {self.updateHeight();};
+};
+
+/**
+ * Starts dragging the pane sizer.
+ * @param {Object} ev The mousedown event that started us dragging.
+ */
+CodewalkViewer.prototype.startSizerDrag = function(ev) {
+ this.initialCodeWidth = this.codeColumn.width();
+ this.initialCommentsWidth = this.commentColumn.width();
+ this.initialMouseX = ev.pageX;
+ this.overlay.show();
+};
+
+/**
+ * Handles dragging the pane sizer.
+ * @param {Object} ev The mousemove event updating dragging position.
+ */
+CodewalkViewer.prototype.handleSizerDrag = function(ev) {
+ var delta = ev.pageX - this.initialMouseX;
+ if (this.codeColumn.is('.right')) delta = -delta;
+ var proposedCodeWidth = this.initialCodeWidth + delta;
+ var proposedCommentWidth = this.initialCommentsWidth - delta;
+ var mw = CodewalkViewer.MIN_PANE_WIDTH;
+ if (proposedCodeWidth < mw) delta = mw - this.initialCodeWidth;
+ if (proposedCommentWidth < mw) delta = this.initialCommentsWidth - mw;
+ proposedCodeWidth = this.initialCodeWidth + delta;
+ proposedCommentWidth = this.initialCommentsWidth - delta;
+ // If window is too small, don't even try to resize.
+ if (proposedCodeWidth < mw || proposedCommentWidth < mw) return;
+ this.codeColumn.width(proposedCodeWidth);
+ this.commentColumn.width(proposedCommentWidth);
+ this.options.codeWidth = parseInt(
+ this.codeColumn.width() /
+ (this.codeColumn.width() + this.commentColumn.width()) * 100);
+ this.context.find('#code-column-width').text(this.options.codeWidth + '%');
+};
+
+/**
+ * Ends dragging the pane sizer.
+ * @param {Object} ev The mouseup event that caused us to stop dragging.
+ */
+CodewalkViewer.prototype.endSizerDrag = function(ev) {
+ this.overlay.hide();
+ this.updateHeight();
+};
+
+/**
+ * Toggles the Codewalk description between being shown and hidden.
+ * @param {jQuery} target The target that was clicked to trigger this function.
+ */
+CodewalkViewer.prototype.toggleDescription = function(target) {
+ var description = this.context.find('#description');
+ description.toggle();
+ target.find('span').text(description.is(':hidden') ? 'show' : 'hide');
+ this.updateHeight();
+};
+
+/**
+ * Changes the side of the window on which the code is shown and saves the
+ * setting in a cookie.
+ * @param {string?} codeSide The side on which the code should be, either
+ * 'left' or 'right'.
+ */
+CodewalkViewer.prototype.changeCodeSide = function(codeSide) {
+ var commentSide = codeSide == 'left' ? 'right' : 'left';
+ this.context.find('#set-code-' + codeSide).addClass('selected');
+ this.context.find('#set-code-' + commentSide).removeClass('selected');
+ // Remove previous side class and add new one.
+ this.codeColumn.addClass(codeSide).removeClass(commentSide);
+ this.commentColumn.addClass(commentSide).removeClass(codeSide);
+ this.sizer.css(codeSide, 'auto').css(commentSide, 0);
+ this.options.codeSide = codeSide;
+};
+
+/**
+ * Adds selected class to newly selected comment, removes selected style from
+ * previously selected comment, changes drop down options so that the correct
+ * file is selected, and updates the code popout link.
+ * @param {jQuery} target The target that was clicked to trigger this function.
+ */
+CodewalkViewer.prototype.changeSelectedComment = function(target) {
+ var currentFile = target.find('.comment-link').attr('href');
+ if (!currentFile) return;
+
+ if (!(this.lastSelected && this.lastSelected.get(0) === target.get(0))) {
+ if (this.lastSelected) this.lastSelected.removeClass('selected');
+ target.addClass('selected');
+ this.lastSelected = target;
+ var targetTop = target.position().top;
+ var parentTop = target.parent().position().top;
+ if (targetTop + target.height() > parentTop + target.parent().height() ||
+ targetTop < parentTop) {
+ var delta = targetTop - parentTop;
+ target.parent().animate(
+ {'scrollTop': target.parent().scrollTop() + delta},
+ Math.max(delta / 2, 200), 'swing');
+ }
+ var fname = currentFile.match(/(?:select=|fileprint=)\/[^&]+/)[0];
+ fname = fname.slice(fname.indexOf('=')+2, fname.length);
+ this.context.find('#code-selector').val(fname);
+ this.context.find('#prev-comment').toggleClass(
+ 'disabled', !target.prev().length);
+ this.context.find('#next-comment').toggleClass(
+ 'disabled', !target.next().length);
+ }
+
+ // Force original file even if user hasn't changed comments since they may
+ // have nagivated away from it within the iframe without us knowing.
+ this.navigateToCode(currentFile);
+};
+
+/**
+ * Updates the viewer by changing the height of the comments and code so that
+ * they fit within the height of the window. The function is typically called
+ * after the user changes the window size.
+ */
+CodewalkViewer.prototype.updateHeight = function() {
+ var windowHeight = jQuery(window).height() - 5 // GOK
+ var areaHeight = windowHeight - this.codeArea.offset().top
+ var footerHeight = this.context.find('#footer').outerHeight(true)
+ this.commentArea.height(areaHeight - footerHeight - this.context.find('#comment-options').outerHeight(true))
+ var codeHeight = areaHeight - footerHeight - 15 // GOK
+ this.codeArea.height(codeHeight)
+ this.codeDisplay.height(codeHeight - this.codeDisplay.offset().top + this.codeArea.offset().top);
+ this.sizer.height(codeHeight);
+};
+
+window.initFuncs.push(function() {
+ var viewer = new CodewalkViewer(jQuery('#codewalk-main'));
+ viewer.selectFirstComment();
+ viewer.targetCommentLinksAtBlank();
+ viewer.installEventHandlers();
+ viewer.updateHeight();
+});
diff --git a/doc/codewalk/codewalk.xml b/doc/codewalk/codewalk.xml
new file mode 100644
index 0000000..3496db7
--- /dev/null
+++ b/doc/codewalk/codewalk.xml
@@ -0,0 +1,124 @@
+<codewalk title="How to Write a Codewalk">
+
+<step title="Introduction" src="doc/codewalk/codewalk.xml">
+ A codewalk is a guided tour through a piece of code.
+ It consists of a sequence of steps, each typically explaining
+ a highlighted section of code.
+ <br/><br/>
+
+ The <a href="/cmd/godoc">godoc</a> web server translates
+ an XML file like the one in the main window pane into the HTML
+ page that you're viewing now.
+ <br/><br/>
+
+ The codewalk with URL path <code>/doc/codewalk/</code><i>name</i>
+ is loaded from the input file <code>$GOROOT/doc/codewalk/</code><i>name</i><code>.xml</code>.
+ <br/><br/>
+
+ This codewalk explains how to write a codewalk by examining
+ its own source code,
+ <code><a href="/doc/codewalk/codewalk.xml">$GOROOT/doc/codewalk/codewalk.xml</a></code>,
+ shown in the main window pane to the left.
+</step>
+
+<step title="Title" src="doc/codewalk/codewalk.xml:/title=/">
+ The codewalk input file is an XML file containing a single
+ <code><codewalk></code> element.
+ That element's <code>title</code> attribute gives the title
+ that is used both on the codewalk page and in the codewalk list.
+</step>
+
+<step title="Steps" src="doc/codewalk/codewalk.xml:/<step/,/step>/">
+ Each step in the codewalk is a <code><step></code> element
+ nested inside the main <code><codewalk></code>.
+ The step element's <code>title</code> attribute gives the step's title,
+ which is shown in a shaded bar above the main step text.
+ The element's <code>src</code> attribute specifies the source
+ code to show in the main window pane and, optionally, a range of
+ lines to highlight.
+ <br/><br/>
+
+ The first step in this codewalk does not highlight any lines:
+ its <code>src</code> is just a file name.
+</step>
+
+<step title="Specifying a source line" src='doc/codewalk/codewalk.xml:/title="Title"/'>
+ The most complex part of the codewalk specification is
+ saying what lines to highlight.
+ Instead of ordinary line numbers,
+ the codewalk uses an address syntax that makes it possible
+ to describe the match by its content.
+ As the file gets edited, this descriptive address has a better
+ chance to continue to refer to the right section of the file.
+ <br/><br/>
+
+ To specify a source line, use a <code>src</code> attribute of the form
+ <i>filename</i><code>:</code><i>address</i>,
+ where <i>address</i> is an address in the syntax used by the text editors <i>sam</i> and <i>acme</i>.
+ <br/><br/>
+
+ The simplest address is a single regular expression.
+ The highlighted line in the main window pane shows that the
+ address for the “Title” step was <code>/title=/</code>,
+ which matches the first instance of that <a href="/pkg/regexp">regular expression</a> (<code>title=</code>) in the file.
+</step>
+
+<step title="Specifying a source range" src='doc/codewalk/codewalk.xml:/title="Steps"/'>
+ To highlight a range of source lines, the simplest address to use is
+ a pair of regular expressions
+ <code>/</code><i>regexp1</i><code>/,/</code><i>regexp2</i><code>/</code>.
+ The highlight begins with the line containing the first match for <i>regexp1</i>
+ and ends with the line containing the first match for <i>regexp2</i>
+ after the end of the match for <i>regexp1</i>.
+ Ignoring the HTML quoting,
+ The line containing the first match for <i>regexp1</i> will be the first one highlighted,
+ and the line containing the first match for <i>regexp2</i>.
+ <br/><br/>
+
+ The address <code>/<step/,/step>/</code> looks for the first instance of
+ <code><step</code> in the file, and then starting after that point,
+ looks for the first instance of <code>step></code>.
+ (Click on the “Steps” step above to see the highlight in action.)
+ Note that the <code><</code> and <code>></code> had to be written
+ using XML escapes in order to be valid XML.
+</step>
+
+<step title="Advanced addressing" src="doc/codewalk/codewalk.xml:/Advanced/,/step>/">
+ The <code>/</code><i>regexp</i><code>/</code>
+ and <code>/</code><i>regexp1</i><code>/,/</code><i>regexp2</i><code>/</code>
+ forms suffice for most highlighting.
+ <br/><br/>
+
+ The full address syntax is summarized in this table
+ (an excerpt of Table II from
+ <a href="http://plan9.bell-labs.com/sys/doc/sam/sam.html">The text editor <code>sam</code></a>):
+ <br/><br/>
+
+ <table>
+ <tr><td colspan="2"><b>Simple addresses</b></td></tr>
+ <tr><td><code>#</code><i>n</i></td>
+ <td>The empty string after character <i>n</i></td></tr>
+ <tr><td><i>n</i></td>
+ <td>Line <i>n</i></td></tr>
+ <tr><td><code>/</code><i>regexp</i><code>/</code></td>
+ <td>The first following match of the regular expression</td></tr>
+ <!-- not supported (yet?)
+ <tr><td><code>–/</code><i>regexp</i><code>/</code></td>
+ <td>The first previous match of the regular expression</td></tr>
+ -->
+ <tr><td><code>$</code></td>
+ <td>The null string at the end of the file</td></tr>
+
+ <tr><td colspan="2"><b>Compound addresses</b></td></tr>
+ <tr><td><i>a1</i><code>+</code><i>a2</i></td>
+ <td>The address <i>a2</i> evaluated starting at the right of <i>a1</i></td></tr>
+ <tr><td><i>a1</i><code>-</code><i>a2</i></td>
+ <td>The address <i>a2</i> evaluated in the reverse direction starting at the left of <i>a1</i></td></tr>
+ <tr><td><i>a1</i><code>,</code><i>a2</i></td>
+ <td>From the left of <i>a1</i> to the right of <i>a2</i> (default <code>0,$</code>).</td></tr>
+ </table>
+</step>
+
+
+
+</codewalk>
diff --git a/doc/codewalk/functions.xml b/doc/codewalk/functions.xml
new file mode 100644
index 0000000..db518dc
--- /dev/null
+++ b/doc/codewalk/functions.xml
@@ -0,0 +1,105 @@
+<codewalk title="First-Class Functions in Go">
+
+<step title="Introduction" src="doc/codewalk/pig.go">
+ Go supports first class functions, higher-order functions, user-defined
+ function types, function literals, closures, and multiple return values.
+ <br/><br/>
+
+ This rich feature set supports a functional programming style in a strongly
+ typed language.
+ <br/><br/>
+
+ In this codewalk we will look at a simple program that simulates a dice game
+ called <a href="http://en.wikipedia.org/wiki/Pig_(dice)">Pig</a> and evaluates
+ basic strategies.
+</step>
+
+<step title="Game overview" src="doc/codewalk/pig.go:/\/\/ A score/,/thisTurn int\n}/">
+ Pig is a two-player game played with a 6-sided die. Each turn, you may roll or stay.
+ <ul>
+ <li> If you roll a 1, you lose all points for your turn and play passes to
+ your opponent. Any other roll adds its value to your turn score. </li>
+ <li> If you stay, your turn score is added to your total score, and play passes
+ to your opponent. </li>
+ </ul>
+
+ The first person to reach 100 total points wins.
+ <br/><br/>
+
+ The <code>score</code> type stores the scores of the current and opposing
+ players, in addition to the points accumulated during the current turn.
+</step>
+
+<step title="User-defined function types" src="doc/codewalk/pig.go:/\/\/ An action/,/bool\)/">
+ In Go, functions can be passed around just like any other value. A function's
+ type signature describes the types of its arguments and return values.
+ <br/><br/>
+
+ The <code>action</code> type is a function that takes a <code>score</code>
+ and returns the resulting <code>score</code> and whether the current turn is
+ over.
+ <br/><br/>
+
+ If the turn is over, the <code>player</code> and <code>opponent</code> fields
+ in the resulting <code>score</code> should be swapped, as it is now the other player's
+ turn.
+</step>
+
+<step title="Multiple return values" src="doc/codewalk/pig.go:/\/\/ roll returns/,/true\n}/">
+ Go functions can return multiple values.
+ <br/><br/>
+
+ The functions <code>roll</code> and <code>stay</code> each return a pair of
+ values. They also match the <code>action</code> type signature. These
+ <code>action</code> functions define the rules of Pig.
+</step>
+
+<step title="Higher-order functions" src="doc/codewalk/pig.go:/\/\/ A strategy/,/action\n/">
+ A function can use other functions as arguments and return values.
+ <br/><br/>
+
+ A <code>strategy</code> is a function that takes a <code>score</code> as input
+ and returns an <code>action</code> to perform. <br/>
+ (Remember, an <code>action</code> is itself a function.)
+</step>
+
+<step title="Function literals and closures" src="doc/codewalk/pig.go:/return func/,/return roll\n\t}/">
+ Anonymous functions can be declared in Go, as in this example. Function
+ literals are closures: they inherit the scope of the function in which they
+ are declared.
+ <br/><br/>
+
+ One basic strategy in Pig is to continue rolling until you have accumulated at
+ least k points in a turn, and then stay. The argument <code>k</code> is
+ enclosed by this function literal, which matches the <code>strategy</code> type
+ signature.
+</step>
+
+<step title="Simulating games" src="doc/codewalk/pig.go:/\/\/ play/,/currentPlayer\n}/">
+ We simulate a game of Pig by calling an <code>action</code> to update the
+ <code>score</code> until one player reaches 100 points. Each
+ <code>action</code> is selected by calling the <code>strategy</code> function
+ associated with the current player.
+</step>
+
+<step title="Simulating a tournament" src="doc/codewalk/pig.go:/\/\/ roundRobin/,/gamesPerStrategy\n}/">
+ The <code>roundRobin</code> function simulates a tournament and tallies wins.
+ Each strategy plays each other strategy <code>gamesPerSeries</code> times.
+</step>
+
+<step title="Variadic function declarations" src="doc/codewalk/pig.go:/\/\/ ratioS/,/string {/">
+ Variadic functions like <code>ratioString</code> take a variable number of
+ arguments. These arguments are available as a slice inside the function.
+</step>
+
+<step title="Simulation results" src="doc/codewalk/pig.go:/func main/,/\n}/">
+ The <code>main</code> function defines 100 basic strategies, simulates a round
+ robin tournament, and then prints the win/loss record of each strategy.
+ <br/><br/>
+
+ Among these strategies, staying at 25 is best, but the <a
+ href="http://www.google.com/search?q=optimal+play+pig">optimal strategy for
+ Pig</a> is much more complex.
+</step>
+
+</codewalk>
diff --git a/doc/codewalk/markov.go b/doc/codewalk/markov.go
new file mode 100644
index 0000000..a8f322e
--- /dev/null
+++ b/doc/codewalk/markov.go
@@ -0,0 +1,130 @@
+// Copyright 2011 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+/*
+Generating random text: a Markov chain algorithm
+
+Based on the program presented in the "Design and Implementation" chapter
+of The Practice of Programming (Kernighan and Pike, Addison-Wesley 1999).
+See also Computer Recreations, Scientific American 260, 122 - 125 (1989).
+
+A Markov chain algorithm generates text by creating a statistical model of
+potential textual suffixes for a given prefix. Consider this text:
+
+ I am not a number! I am a free man!
+
+Our Markov chain algorithm would arrange this text into this set of prefixes
+and suffixes, or "chain": (This table assumes a prefix length of two words.)
+
+ Prefix Suffix
+
+ "" "" I
+ "" I am
+ I am a
+ I am not
+ a free man!
+ am a free
+ am not a
+ a number! I
+ number! I am
+ not a number!
+
+To generate text using this table we select an initial prefix ("I am", for
+example), choose one of the suffixes associated with that prefix at random
+with probability determined by the input statistics ("a"),
+and then create a new prefix by removing the first word from the prefix
+and appending the suffix (making the new prefix is "am a"). Repeat this process
+until we can't find any suffixes for the current prefix or we exceed the word
+limit. (The word limit is necessary as the chain table may contain cycles.)
+
+Our version of this program reads text from standard input, parsing it into a
+Markov chain, and writes generated text to standard output.
+The prefix and output lengths can be specified using the -prefix and -words
+flags on the command-line.
+*/
+package main
+
+import (
+ "bufio"
+ "flag"
+ "fmt"
+ "io"
+ "math/rand"
+ "os"
+ "strings"
+ "time"
+)
+
+// Prefix is a Markov chain prefix of one or more words.
+type Prefix []string
+
+// String returns the Prefix as a string (for use as a map key).
+func (p Prefix) String() string {
+ return strings.Join(p, " ")
+}
+
+// Shift removes the first word from the Prefix and appends the given word.
+func (p Prefix) Shift(word string) {
+ copy(p, p[1:])
+ p[len(p)-1] = word
+}
+
+// Chain contains a map ("chain") of prefixes to a list of suffixes.
+// A prefix is a string of prefixLen words joined with spaces.
+// A suffix is a single word. A prefix can have multiple suffixes.
+type Chain struct {
+ chain map[string][]string
+ prefixLen int
+}
+
+// NewChain returns a new Chain with prefixes of prefixLen words.
+func NewChain(prefixLen int) *Chain {
+ return &Chain{make(map[string][]string), prefixLen}
+}
+
+// Build reads text from the provided Reader and
+// parses it into prefixes and suffixes that are stored in Chain.
+func (c *Chain) Build(r io.Reader) {
+ br := bufio.NewReader(r)
+ p := make(Prefix, c.prefixLen)
+ for {
+ var s string
+ if _, err := fmt.Fscan(br, &s); err != nil {
+ break
+ }
+ key := p.String()
+ c.chain[key] = append(c.chain[key], s)
+ p.Shift(s)
+ }
+}
+
+// Generate returns a string of at most n words generated from Chain.
+func (c *Chain) Generate(n int) string {
+ p := make(Prefix, c.prefixLen)
+ var words []string
+ for i := 0; i < n; i++ {
+ choices := c.chain[p.String()]
+ if len(choices) == 0 {
+ break
+ }
+ next := choices[rand.Intn(len(choices))]
+ words = append(words, next)
+ p.Shift(next)
+ }
+ return strings.Join(words, " ")
+}
+
+func main() {
+ // Register command-line flags.
+ numWords := flag.Int("words", 100, "maximum number of words to print")
+ prefixLen := flag.Int("prefix", 2, "prefix length in words")
+
+ flag.Parse() // Parse command-line flags.
+ rand.Seed(time.Now().UnixNano()) // Seed the random number generator.
+
+ c := NewChain(*prefixLen) // Initialize a new Chain.
+ c.Build(os.Stdin) // Build chains from standard input.
+ text := c.Generate(*numWords) // Generate text.
+ fmt.Println(text) // Write text to standard output.
+}
diff --git a/doc/codewalk/markov.xml b/doc/codewalk/markov.xml
new file mode 100644
index 0000000..76c448a
--- /dev/null
+++ b/doc/codewalk/markov.xml
@@ -0,0 +1,307 @@
+<!--
+Copyright 2011 The Go Authors. All rights reserved.
+Use of this source code is governed by a BSD-style
+license that can be found in the LICENSE file.
+-->
+
+<codewalk title="Generating arbitrary text: a Markov chain algorithm">
+
+<step title="Introduction" src="doc/codewalk/markov.go:/Generating/,/line\./">
+ This codewalk describes a program that generates random text using
+ a Markov chain algorithm. The package comment describes the algorithm
+ and the operation of the program. Please read it before continuing.
+</step>
+
+<step title="Modeling Markov chains" src="doc/codewalk/markov.go:/ chain/">
+ A chain consists of a prefix and a suffix. Each prefix is a set
+ number of words, while a suffix is a single word.
+ A prefix can have an arbitrary number of suffixes.
+ To model this data, we use a <code>map[string][]string</code>.
+ Each map key is a prefix (a <code>string</code>) and its values are
+ lists of suffixes (a slice of strings, <code>[]string</code>).
+ <br/><br/>
+ Here is the example table from the package comment
+ as modeled by this data structure:
+ <pre>
+map[string][]string{
+ " ": {"I"},
+ " I": {"am"},
+ "I am": {"a", "not"},
+ "a free": {"man!"},
+ "am a": {"free"},
+ "am not": {"a"},
+ "a number!": {"I"},
+ "number! I": {"am"},
+ "not a": {"number!"},
+}</pre>
+ While each prefix consists of multiple words, we
+ store prefixes in the map as a single <code>string</code>.
+ It would seem more natural to store the prefix as a
+ <code>[]string</code>, but we can't do this with a map because the
+ key type of a map must implement equality (and slices do not).
+ <br/><br/>
+ Therefore, in most of our code we will model prefixes as a
+ <code>[]string</code> and join the strings together with a space
+ to generate the map key:
+ <pre>
+Prefix Map key
+
+[]string{"", ""} " "
+[]string{"", "I"} " I"
+[]string{"I", "am"} "I am"
+</pre>
+</step>
+
+<step title="The Chain struct" src="doc/codewalk/markov.go:/type Chain/,/}/">
+ The complete state of the chain table consists of the table itself and
+ the word length of the prefixes. The <code>Chain</code> struct stores
+ this data.
+</step>
+
+<step title="The NewChain constructor function" src="doc/codewalk/markov.go:/func New/,/\n}/">
+ The <code>Chain</code> struct has two unexported fields (those that
+ do not begin with an upper case character), and so we write a
+ <code>NewChain</code> constructor function that initializes the
+ <code>chain</code> map with <code>make</code> and sets the
+ <code>prefixLen</code> field.
+ <br/><br/>
+ This is constructor function is not strictly necessary as this entire
+ program is within a single package (<code>main</code>) and therefore
+ there is little practical difference between exported and unexported
+ fields. We could just as easily write out the contents of this function
+ when we want to construct a new Chain.
+ But using these unexported fields is good practice; it clearly denotes
+ that only methods of Chain and its constructor function should access
+ those fields. Also, structuring <code>Chain</code> like this means we
+ could easily move it into its own package at some later date.
+</step>
+
+<step title="The Prefix type" src="doc/codewalk/markov.go:/type Prefix/">
+ Since we'll be working with prefixes often, we define a
+ <code>Prefix</code> type with the concrete type <code>[]string</code>.
+ Defining a named type clearly allows us to be explicit when we are
+ working with a prefix instead of just a <code>[]string</code>.
+ Also, in Go we can define methods on any named type (not just structs),
+ so we can add methods that operate on <code>Prefix</code> if we need to.
+</step>
+
+<step title="The String method" src="doc/codewalk/markov.go:/func[^\n]+String/,/}/">
+ The first method we define on <code>Prefix</code> is
+ <code>String</code>. It returns a <code>string</code> representation
+ of a <code>Prefix</code> by joining the slice elements together with
+ spaces. We will use this method to generate keys when working with
+ the chain map.
+</step>
+
+<step title="Building the chain" src="doc/codewalk/markov.go:/func[^\n]+Build/,/\n}/">
+ The <code>Build</code> method reads text from an <code>io.Reader</code>
+ and parses it into prefixes and suffixes that are stored in the
+ <code>Chain</code>.
+ <br/><br/>
+ The <code><a href="/pkg/io/#Reader">io.Reader</a></code> is an
+ interface type that is widely used by the standard library and
+ other Go code. Our code uses the
+ <code><a href="/pkg/fmt/#Fscan">fmt.Fscan</a></code> function, which
+ reads space-separated values from an <code>io.Reader</code>.
+ <br/><br/>
+ The <code>Build</code> method returns once the <code>Reader</code>'s
+ <code>Read</code> method returns <code>io.EOF</code> (end of file)
+ or some other read error occurs.
+</step>
+
+<step title="Buffering the input" src="doc/codewalk/markov.go:/bufio\.NewReader/">
+ This function does many small reads, which can be inefficient for some
+ <code>Readers</code>. For efficiency we wrap the provided
+ <code>io.Reader</code> with
+ <code><a href="/pkg/bufio/">bufio.NewReader</a></code> to create a
+ new <code>io.Reader</code> that provides buffering.
+</step>
+
+<step title="The Prefix variable" src="doc/codewalk/markov.go:/make\(Prefix/">
+ At the top of the function we make a <code>Prefix</code> slice
+ <code>p</code> using the <code>Chain</code>'s <code>prefixLen</code>
+ field as its length.
+ We'll use this variable to hold the current prefix and mutate it with
+ each new word we encounter.
+</step>
+
+<step title="Scanning words" src="doc/codewalk/markov.go:/var s string/,/\n }/">
+ In our loop we read words from the <code>Reader</code> into a
+ <code>string</code> variable <code>s</code> using
+ <code>fmt.Fscan</code>. Since <code>Fscan</code> uses space to
+ separate each input value, each call will yield just one word
+ (including punctuation), which is exactly what we need.
+ <br/><br/>
+ <code>Fscan</code> returns an error if it encounters a read error
+ (<code>io.EOF</code>, for example) or if it can't scan the requested
+ value (in our case, a single string). In either case we just want to
+ stop scanning, so we <code>break</code> out of the loop.
+</step>
+
+<step title="Adding a prefix and suffix to the chain" src="doc/codewalk/markov.go:/ key/,/key\], s\)">
+ The word stored in <code>s</code> is a new suffix. We add the new
+ prefix/suffix combination to the <code>chain</code> map by computing
+ the map key with <code>p.String</code> and appending the suffix
+ to the slice stored under that key.
+ <br/><br/>
+ The built-in <code>append</code> function appends elements to a slice
+ and allocates new storage when necessary. When the provided slice is
+ <code>nil</code>, <code>append</code> allocates a new slice.
+ This behavior conveniently ties in with the semantics of our map:
+ retrieving an unset key returns the zero value of the value type and
+ the zero value of <code>[]string</code> is <code>nil</code>.
+ When our program encounters a new prefix (yielding a <code>nil</code>
+ value in the map) <code>append</code> will allocate a new slice.
+ <br/><br/>
+ For more information about the <code>append</code> function and slices
+ in general see the
+ <a href="/doc/articles/slices_usage_and_internals.html">Slices: usage and internals</a> article.
+</step>
+
+<step title="Pushing the suffix onto the prefix" src="doc/codewalk/markov.go:/p\.Shift/">
+ Before reading the next word our algorithm requires us to drop the
+ first word from the prefix and push the current suffix onto the prefix.
+ <br/><br/>
+ When in this state
+ <pre>
+p == Prefix{"I", "am"}
+s == "not" </pre>
+ the new value for <code>p</code> would be
+ <pre>
+p == Prefix{"am", "not"}</pre>
+ This operation is also required during text generation so we put
+ the code to perform this mutation of the slice inside a method on
+ <code>Prefix</code> named <code>Shift</code>.
+</step>
+
+<step title="The Shift method" src="doc/codewalk/markov.go:/func[^\n]+Shift/,/\n}/">
+ The <code>Shift</code> method uses the built-in <code>copy</code>
+ function to copy the last len(p)-1 elements of <code>p</code> to
+ the start of the slice, effectively moving the elements
+ one index to the left (if you consider zero as the leftmost index).
+ <pre>
+p := Prefix{"I", "am"}
+copy(p, p[1:])
+// p == Prefix{"am", "am"}</pre>
+ We then assign the provided <code>word</code> to the last index
+ of the slice:
+ <pre>
+// suffix == "not"
+p[len(p)-1] = suffix
+// p == Prefix{"am", "not"}</pre>
+</step>
+
+<step title="Generating text" src="doc/codewalk/markov.go:/func[^\n]+Generate/,/\n}/">
+ The <code>Generate</code> method is similar to <code>Build</code>
+ except that instead of reading words from a <code>Reader</code>
+ and storing them in a map, it reads words from the map and
+ appends them to a slice (<code>words</code>).
+ <br/><br/>
+ <code>Generate</code> uses a conditional for loop to generate
+ up to <code>n</code> words.
+</step>
+
+<step title="Getting potential suffixes" src="doc/codewalk/markov.go:/choices/,/}\n/">
+ At each iteration of the loop we retrieve a list of potential suffixes
+ for the current prefix. We access the <code>chain</code> map at key
+ <code>p.String()</code> and assign its contents to <code>choices</code>.
+ <br/><br/>
+ If <code>len(choices)</code> is zero we break out of the loop as there
+ are no potential suffixes for that prefix.
+ This test also works if the key isn't present in the map at all:
+ in that case, <code>choices</code> will be <code>nil</code> and the
+ length of a <code>nil</code> slice is zero.
+</step>
+
+<step title="Choosing a suffix at random" src="doc/codewalk/markov.go:/next := choices/,/Shift/">
+ To choose a suffix we use the
+ <code><a href="/pkg/math/rand/#Intn">rand.Intn</a></code> function.
+ It returns a random integer up to (but not including) the provided
+ value. Passing in <code>len(choices)</code> gives us a random index
+ into the full length of the list.
+ <br/><br/>
+ We use that index to pick our new suffix, assign it to
+ <code>next</code> and append it to the <code>words</code> slice.
+ <br/><br/>
+ Next, we <code>Shift</code> the new suffix onto the prefix just as
+ we did in the <code>Build</code> method.
+</step>
+
+<step title="Returning the generated text" src="doc/codewalk/markov.go:/Join\(words/">
+ Before returning the generated text as a string, we use the
+ <code>strings.Join</code> function to join the elements of
+ the <code>words</code> slice together, separated by spaces.
+</step>
+
+<step title="Command-line flags" src="doc/codewalk/markov.go:/Register command-line flags/,/prefixLen/">
+ To make it easy to tweak the prefix and generated text lengths we
+ use the <code><a href="/pkg/flag/">flag</a></code> package to parse
+ command-line flags.
+ <br/><br/>
+ These calls to <code>flag.Int</code> register new flags with the
+ <code>flag</code> package. The arguments to <code>Int</code> are the
+ flag name, its default value, and a description. The <code>Int</code>
+ function returns a pointer to an integer that will contain the
+ user-supplied value (or the default value if the flag was omitted on
+ the command-line).
+</step>
+
+<step title="Program set up" src="doc/codewalk/markov.go:/flag.Parse/,/rand.Seed/">
+ The <code>main</code> function begins by parsing the command-line
+ flags with <code>flag.Parse</code> and seeding the <code>rand</code>
+ package's random number generator with the current time.
+ <br/><br/>
+ If the command-line flags provided by the user are invalid the
+ <code>flag.Parse</code> function will print an informative usage
+ message and terminate the program.
+</step>
+
+<step title="Creating and building a new Chain" src="doc/codewalk/markov.go:/c := NewChain/,/c\.Build/">
+ To create the new <code>Chain</code> we call <code>NewChain</code>
+ with the value of the <code>prefix</code> flag.
+ <br/><br/>
+ To build the chain we call <code>Build</code> with
+ <code>os.Stdin</code> (which implements <code>io.Reader</code>) so
+ that it will read its input from standard input.
+</step>
+
+<step title="Generating and printing text" src="doc/codewalk/markov.go:/c\.Generate/,/fmt.Println/">
+ Finally, to generate text we call <code>Generate</code> with
+ the value of the <code>words</code> flag and assigning the result
+ to the variable <code>text</code>.
+ <br/><br/>
+ Then we call <code>fmt.Println</code> to write the text to standard
+ output, followed by a carriage return.
+</step>
+
+<step title="Using this program" src="doc/codewalk/markov.go">
+ To use this program, first build it with the
+ <a href="/cmd/go/">go</a> command:
+ <pre>
+$ go build markov.go</pre>
+ And then execute it while piping in some input text:
+ <pre>
+$ echo "a man a plan a canal panama" \
+ | ./markov -prefix=1
+a plan a man a plan a canal panama</pre>
+ Here's a transcript of generating some text using the Go distribution's
+ README file as source material:
+ <pre>
+$ ./markov -words=10 < $GOROOT/README
+This is the source code repository for the Go source
+$ ./markov -prefix=1 -words=10 < $GOROOT/README
+This is the go directory (the one containing this README).
+$ ./markov -prefix=1 -words=10 < $GOROOT/README
+This is the variable if you have just untarred a</pre>
+</step>
+
+<step title="An exercise for the reader" src="doc/codewalk/markov.go">
+ The <code>Generate</code> function does a lot of allocations when it
+ builds the <code>words</code> slice. As an exercise, modify it to
+ take an <code>io.Writer</code> to which it incrementally writes the
+ generated text with <code>Fprint</code>.
+ Aside from being more efficient this makes <code>Generate</code>
+ more symmetrical to <code>Build</code>.
+</step>
+
+</codewalk>
diff --git a/doc/codewalk/pig.go b/doc/codewalk/pig.go
new file mode 100644
index 0000000..941daae
--- /dev/null
+++ b/doc/codewalk/pig.go
@@ -0,0 +1,121 @@
+// Copyright 2011 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "fmt"
+ "math/rand"
+)
+
+const (
+ win = 100 // The winning score in a game of Pig
+ gamesPerSeries = 10 // The number of games per series to simulate
+)
+
+// A score includes scores accumulated in previous turns for each player,
+// as well as the points scored by the current player in this turn.
+type score struct {
+ player, opponent, thisTurn int
+}
+
+// An action transitions stochastically to a resulting score.
+type action func(current score) (result score, turnIsOver bool)
+
+// roll returns the (result, turnIsOver) outcome of simulating a die roll.
+// If the roll value is 1, then thisTurn score is abandoned, and the players'
+// roles swap. Otherwise, the roll value is added to thisTurn.
+func roll(s score) (score, bool) {
+ outcome := rand.Intn(6) + 1 // A random int in [1, 6]
+ if outcome == 1 {
+ return score{s.opponent, s.player, 0}, true
+ }
+ return score{s.player, s.opponent, outcome + s.thisTurn}, false
+}
+
+// stay returns the (result, turnIsOver) outcome of staying.
+// thisTurn score is added to the player's score, and the players' roles swap.
+func stay(s score) (score, bool) {
+ return score{s.opponent, s.player + s.thisTurn, 0}, true
+}
+
+// A strategy chooses an action for any given score.
+type strategy func(score) action
+
+// stayAtK returns a strategy that rolls until thisTurn is at least k, then stays.
+func stayAtK(k int) strategy {
+ return func(s score) action {
+ if s.thisTurn >= k {
+ return stay
+ }
+ return roll
+ }
+}
+
+// play simulates a Pig game and returns the winner (0 or 1).
+func play(strategy0, strategy1 strategy) int {
+ strategies := []strategy{strategy0, strategy1}
+ var s score
+ var turnIsOver bool
+ currentPlayer := rand.Intn(2) // Randomly decide who plays first
+ for s.player+s.thisTurn < win {
+ action := strategies[currentPlayer](s)
+ s, turnIsOver = action(s)
+ if turnIsOver {
+ currentPlayer = (currentPlayer + 1) % 2
+ }
+ }
+ return currentPlayer
+}
+
+// roundRobin simulates a series of games between every pair of strategies.
+func roundRobin(strategies []strategy) ([]int, int) {
+ wins := make([]int, len(strategies))
+ for i := 0; i < len(strategies); i++ {
+ for j := i + 1; j < len(strategies); j++ {
+ for k := 0; k < gamesPerSeries; k++ {
+ winner := play(strategies[i], strategies[j])
+ if winner == 0 {
+ wins[i]++
+ } else {
+ wins[j]++
+ }
+ }
+ }
+ }
+ gamesPerStrategy := gamesPerSeries * (len(strategies) - 1) // no self play
+ return wins, gamesPerStrategy
+}
+
+// ratioString takes a list of integer values and returns a string that lists
+// each value and its percentage of the sum of all values.
+// e.g., ratios(1, 2, 3) = "1/6 (16.7%), 2/6 (33.3%), 3/6 (50.0%)"
+func ratioString(vals ...int) string {
+ total := 0
+ for _, val := range vals {
+ total += val
+ }
+ s := ""
+ for _, val := range vals {
+ if s != "" {
+ s += ", "
+ }
+ pct := 100 * float64(val) / float64(total)
+ s += fmt.Sprintf("%d/%d (%0.1f%%)", val, total, pct)
+ }
+ return s
+}
+
+func main() {
+ strategies := make([]strategy, win)
+ for k := range strategies {
+ strategies[k] = stayAtK(k + 1)
+ }
+ wins, games := roundRobin(strategies)
+
+ for k := range strategies {
+ fmt.Printf("Wins, losses staying at k =% 4d: %s\n",
+ k+1, ratioString(wins[k], games-wins[k]))
+ }
+}
diff --git a/doc/codewalk/popout.png b/doc/codewalk/popout.png
new file mode 100644
index 0000000..9c0c236
--- /dev/null
+++ b/doc/codewalk/popout.png
Binary files differ
diff --git a/doc/codewalk/run b/doc/codewalk/run
new file mode 100755
index 0000000..afc64c1
--- /dev/null
+++ b/doc/codewalk/run
@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Copyright 2013 The Go Authors. All rights reserved.
+# Use of this source code is governed by a BSD-style
+# license that can be found in the LICENSE file.
+
+set -e
+
+function fail {
+ echo FAIL: doc/codewalk/$1
+ exit 1
+}
+
+# markov.xml
+echo foo | go run markov.go | grep foo > /dev/null || fail markov
+
+# functions.xml
+go run pig.go | grep 'Wins, losses staying at k = 100: 210/990 (21.2%), 780/990 (78.8%)' > /dev/null || fail pig
+
+# sharemem.xml: only build the example, as it uses the network
+go build urlpoll.go || fail urlpoll
+rm -f urlpoll
diff --git a/doc/codewalk/sharemem.xml b/doc/codewalk/sharemem.xml
new file mode 100644
index 0000000..8b47f12
--- /dev/null
+++ b/doc/codewalk/sharemem.xml
@@ -0,0 +1,181 @@
+<codewalk title="Share Memory By Communicating">
+
+<step title="Introduction" src="doc/codewalk/urlpoll.go">
+Go's approach to concurrency differs from the traditional use of
+threads and shared memory. Philosophically, it can be summarized:
+<br/><br/>
+<i>Don't communicate by sharing memory; share memory by communicating.</i>
+<br/><br/>
+Channels allow you to pass references to data structures between goroutines.
+If you consider this as passing around ownership of the data (the ability to
+read and write it), they become a powerful and expressive synchronization
+mechanism.
+<br/><br/>
+In this codewalk we will look at a simple program that polls a list of
+URLs, checking their HTTP response codes and periodically printing their state.
+</step>
+
+<step title="State type" src="doc/codewalk/urlpoll.go:/State/,/}/">
+The State type represents the state of a URL.
+<br/><br/>
+The Pollers send State values to the StateMonitor,
+which maintains a map of the current state of each URL.
+</step>
+
+<step title="Resource type" src="doc/codewalk/urlpoll.go:/Resource/,/}/">
+A Resource represents the state of a URL to be polled: the URL itself
+and the number of errors encountered since the last successful poll.
+<br/><br/>
+When the program starts, it allocates one Resource for each URL.
+The main goroutine and the Poller goroutines send the Resources to
+each other on channels.
+</step>
+
+<step title="Poller function" src="doc/codewalk/urlpoll.go:/func Poller/,/\n}/">
+Each Poller receives Resource pointers from an input channel.
+In this program, the convention is that sending a Resource pointer on
+a channel passes ownership of the underlying data from the sender
+to the receiver. Because of this convention, we know that
+no two goroutines will access this Resource at the same time.
+This means we don't have to worry about locking to prevent concurrent
+access to these data structures.
+<br/><br/>
+The Poller processes the Resource by calling its Poll method.
+<br/><br/>
+It sends a State value to the status channel, to inform the StateMonitor
+of the result of the Poll.
+<br/><br/>
+Finally, it sends the Resource pointer to the out channel. This can be
+interpreted as the Poller saying "I'm done with this Resource" and
+returning ownership of it to the main goroutine.
+<br/><br/>
+Several goroutines run Pollers, processing Resources in parallel.
+</step>
+
+<step title="The Poll method" src="doc/codewalk/urlpoll.go:/Poll executes/,/\n}/">
+The Poll method (of the Resource type) performs an HTTP HEAD request
+for the Resource's URL and returns the HTTP response's status code.
+If an error occurs, Poll logs the message to standard error and returns the
+error string instead.
+</step>
+
+<step title="main function" src="doc/codewalk/urlpoll.go:/func main/,/\n}/">
+The main function starts the Poller and StateMonitor goroutines
+and then loops passing completed Resources back to the pending
+channel after appropriate delays.
+</step>
+
+<step title="Creating channels" src="doc/codewalk/urlpoll.go:/Create our/,/complete/">
+First, main makes two channels of *Resource, pending and complete.
+<br/><br/>
+Inside main, a new goroutine sends one Resource per URL to pending
+and the main goroutine receives completed Resources from complete.
+<br/><br/>
+The pending and complete channels are passed to each of the Poller
+goroutines, within which they are known as in and out.
+</step>
+
+<step title="Initializing StateMonitor" src="doc/codewalk/urlpoll.go:/Launch the StateMonitor/,/statusInterval/">
+StateMonitor will initialize and launch a goroutine that stores the state
+of each Resource. We will look at this function in detail later.
+<br/><br/>
+For now, the important thing to note is that it returns a channel of State,
+which is saved as status and passed to the Poller goroutines.
+</step>
+
+<step title="Launching Poller goroutines" src="doc/codewalk/urlpoll.go:/Launch some Poller/,/}/">
+Now that it has the necessary channels, main launches a number of
+Poller goroutines, passing the channels as arguments.
+The channels provide the means of communication between the main, Poller, and
+StateMonitor goroutines.
+</step>
+
+<step title="Send Resources to pending" src="doc/codewalk/urlpoll.go:/Send some Resources/,/}\(\)/">
+To add the initial work to the system, main starts a new goroutine
+that allocates and sends one Resource per URL to pending.
+<br/><br/>
+The new goroutine is necessary because unbuffered channel sends and
+receives are synchronous. That means these channel sends will block until
+the Pollers are ready to read from pending.
+<br/><br/>
+Were these sends performed in the main goroutine with fewer Pollers than
+channel sends, the program would reach a deadlock situation, because
+main would not yet be receiving from complete.
+<br/><br/>
+Exercise for the reader: modify this part of the program to read a list of
+URLs from a file. (You may want to move this goroutine into its own
+named function.)
+</step>
+
+<step title="Main Event Loop" src="doc/codewalk/urlpoll.go:/range complete/,/\n }/">
+When a Poller is done with a Resource, it sends it on the complete channel.
+This loop receives those Resource pointers from complete.
+For each received Resource, it starts a new goroutine calling
+the Resource's Sleep method. Using a new goroutine for each
+ensures that the sleeps can happen in parallel.
+<br/><br/>
+Note that any single Resource pointer may only be sent on either pending or
+complete at any one time. This ensures that a Resource is either being
+handled by a Poller goroutine or sleeping, but never both simultaneously.
+In this way, we share our Resource data by communicating.
+</step>
+
+<step title="The Sleep method" src="doc/codewalk/urlpoll.go:/Sleep/,/\n}/">
+Sleep calls time.Sleep to pause before sending the Resource to done.
+The pause will either be of a fixed length (pollInterval) plus an
+additional delay proportional to the number of sequential errors (r.errCount).
+<br/><br/>
+This is an example of a typical Go idiom: a function intended to run inside
+a goroutine takes a channel, upon which it sends its return value
+(or other indication of completed state).
+</step>
+
+<step title="StateMonitor" src="doc/codewalk/urlpoll.go:/StateMonitor/,/\n}/">
+The StateMonitor receives State values on a channel and periodically
+outputs the state of all Resources being polled by the program.
+</step>
+
+<step title="The updates channel" src="doc/codewalk/urlpoll.go:/updates :=/">
+The variable updates is a channel of State, on which the Poller goroutines
+send State values.
+<br/><br/>
+This channel is returned by the function.
+</step>
+
+<step title="The urlStatus map" src="doc/codewalk/urlpoll.go:/urlStatus/">
+The variable urlStatus is a map of URLs to their most recent status.
+</step>
+
+<step title="The Ticker object" src="doc/codewalk/urlpoll.go:/ticker/">
+A time.Ticker is an object that repeatedly sends a value on a channel at a
+specified interval.
+<br/><br/>
+In this case, ticker triggers the printing of the current state to
+standard output every updateInterval nanoseconds.
+</step>
+
+<step title="The StateMonitor goroutine" src="doc/codewalk/urlpoll.go:/go func/,/}\(\)/">
+StateMonitor will loop forever, selecting on two channels:
+ticker.C and update. The select statement blocks until one of its
+communications is ready to proceed.
+<br/><br/>
+When StateMonitor receives a tick from ticker.C, it calls logState to
+print the current state. When it receives a State update from updates,
+it records the new status in the urlStatus map.
+<br/><br/>
+Notice that this goroutine owns the urlStatus data structure,
+ensuring that it can only be accessed sequentially.
+This prevents memory corruption issues that might arise from parallel reads
+and/or writes to a shared map.
+</step>
+
+<step title="Conclusion" src="doc/codewalk/urlpoll.go">
+In this codewalk we have explored a simple example of using Go's concurrency
+primitives to share memory through communication.
+<br/><br/>
+This should provide a starting point from which to explore the ways in which
+goroutines and channels can be used to write expressive and concise concurrent
+programs.
+</step>
+
+</codewalk>
diff --git a/doc/codewalk/urlpoll.go b/doc/codewalk/urlpoll.go
new file mode 100644
index 0000000..1fb9958
--- /dev/null
+++ b/doc/codewalk/urlpoll.go
@@ -0,0 +1,116 @@
+// Copyright 2010 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "log"
+ "net/http"
+ "time"
+)
+
+const (
+ numPollers = 2 // number of Poller goroutines to launch
+ pollInterval = 60 * time.Second // how often to poll each URL
+ statusInterval = 10 * time.Second // how often to log status to stdout
+ errTimeout = 10 * time.Second // back-off timeout on error
+)
+
+var urls = []string{
+ "http://www.google.com/",
+ "http://golang.org/",
+ "http://blog.golang.org/",
+}
+
+// State represents the last-known state of a URL.
+type State struct {
+ url string
+ status string
+}
+
+// StateMonitor maintains a map that stores the state of the URLs being
+// polled, and prints the current state every updateInterval nanoseconds.
+// It returns a chan State to which resource state should be sent.
+func StateMonitor(updateInterval time.Duration) chan<- State {
+ updates := make(chan State)
+ urlStatus := make(map[string]string)
+ ticker := time.NewTicker(updateInterval)
+ go func() {
+ for {
+ select {
+ case <-ticker.C:
+ logState(urlStatus)
+ case s := <-updates:
+ urlStatus[s.url] = s.status
+ }
+ }
+ }()
+ return updates
+}
+
+// logState prints a state map.
+func logState(s map[string]string) {
+ log.Println("Current state:")
+ for k, v := range s {
+ log.Printf(" %s %s", k, v)
+ }
+}
+
+// Resource represents an HTTP URL to be polled by this program.
+type Resource struct {
+ url string
+ errCount int
+}
+
+// Poll executes an HTTP HEAD request for url
+// and returns the HTTP status string or an error string.
+func (r *Resource) Poll() string {
+ resp, err := http.Head(r.url)
+ if err != nil {
+ log.Println("Error", r.url, err)
+ r.errCount++
+ return err.Error()
+ }
+ r.errCount = 0
+ return resp.Status
+}
+
+// Sleep sleeps for an appropriate interval (dependent on error state)
+// before sending the Resource to done.
+func (r *Resource) Sleep(done chan<- *Resource) {
+ time.Sleep(pollInterval + errTimeout*time.Duration(r.errCount))
+ done <- r
+}
+
+func Poller(in <-chan *Resource, out chan<- *Resource, status chan<- State) {
+ for r := range in {
+ s := r.Poll()
+ status <- State{r.url, s}
+ out <- r
+ }
+}
+
+func main() {
+ // Create our input and output channels.
+ pending, complete := make(chan *Resource), make(chan *Resource)
+
+ // Launch the StateMonitor.
+ status := StateMonitor(statusInterval)
+
+ // Launch some Poller goroutines.
+ for i := 0; i < numPollers; i++ {
+ go Poller(pending, complete, status)
+ }
+
+ // Send some Resources to the pending queue.
+ go func() {
+ for _, url := range urls {
+ pending <- &Resource{url: url}
+ }
+ }()
+
+ for r := range complete {
+ go r.Sleep(pending)
+ }
+}
diff --git a/doc/contrib.html b/doc/contrib.html
new file mode 100644
index 0000000..93a609f
--- /dev/null
+++ b/doc/contrib.html
@@ -0,0 +1,108 @@
+<!--{
+ "Title": "The Go Project",
+ "Path": "/project/"
+}-->
+
+<img class="gopher" src="/doc/gopher/project.png" />
+
+<div id="manual-nav"></div>
+
+<p>
+Go is an open source project developed by a team at
+<a href="//google.com/">Google</a> and many
+<a href="/CONTRIBUTORS">contributors</a> from the open source community.
+</p>
+
+<p>
+Go is distributed under a <a href="/LICENSE">BSD-style license</a>.
+</p>
+
+<h3 id="announce"><a href="//groups.google.com/group/golang-announce">Announcements Mailing List</a></h3>
+<p>
+A low traffic mailing list for important announcements, such as new releases.
+</p>
+<p>
+We encourage all Go users to subscribe to
+<a href="//groups.google.com/group/golang-announce">golang-announce</a>.
+</p>
+
+
+<h2 id="go1">Version history</h2>
+
+<h3 id="release"><a href="/doc/devel/release.html">Release History</a></h3>
+
+<p>A <a href="/doc/devel/release.html">summary</a> of the changes between Go releases. Notes for the major releases:</p>
+
+<ul>
+ <li><a href="/doc/go1.4">Go 1.4</a> <small>(December 2014)</small></li>
+ <li><a href="/doc/go1.3">Go 1.3</a> <small>(June 2014)</small></li>
+ <li><a href="/doc/go1.2">Go 1.2</a> <small>(December 2013)</small></li>
+ <li><a href="/doc/go1.1">Go 1.1</a> <small>(May 2013)</small></li>
+ <li><a href="/doc/go1">Go 1</a> <small>(March 2012)</small></li>
+</ul>
+
+<h3 id="go1compat"><a href="/doc/go1compat">Go 1 and the Future of Go Programs</a></h3>
+<p>
+What Go 1 defines and the backwards-compatibility guarantees one can expect as
+Go 1 matures.
+</p>
+
+
+<h2 id="resources">Developer Resources</h2>
+
+<h3 id="source"><a href="https://golang.org/change">Source Code</a></h3>
+<p>Check out the Go source code.</p>
+
+<h3 id="golang-dev"><a href="https://groups.google.com/group/golang-dev">Developer</a> and
+<a href="https://groups.google.com/group/golang-codereviews">Code Review Mailing List</a></h3>
+<p>The <a href="https://groups.google.com/group/golang-dev">golang-dev</a>
+mailing list is for discussing code changes to the Go project.
+The <a href="https://groups.google.com/group/golang-codereviews">golang-codereviews</a>
+mailing list is for actual reviewing of the code changes (CLs).</p>
+
+<p>For general discussion of Go programming, see <a
+href="https://groups.google.com/group/golang-nuts">golang-nuts</a>.</p>
+
+<h3 id="golang-checkins"><a href="https://groups.google.com/group/golang-checkins">Checkins Mailing List</a></h3>
+<p>A mailing list that receives a message summarizing each checkin to the Go repository.</p>
+
+<h3 id="golang-bugs"><a href="https://groups.google.com/group/golang-bugs">Bugs Mailing List</a></h3>
+<p>A mailing list that receives each update to the Go <a href="//golang.org/issue">issue tracker</a>.</p>
+
+<h3 id="build_status"><a href="//build.golang.org/">Build Status</a></h3>
+<p>View the status of Go builds across the supported operating
+systems and architectures.</p>
+
+
+<h2 id="howto">How you can help</h2>
+
+<h3><a href="//golang.org/issue">Reporting issues</a></h3>
+
+<p>
+If you spot bugs, mistakes, or inconsistencies in the Go project's code or
+documentation, please let us know by
+<a href="//golang.org/issue/new">filing a ticket</a>
+on our <a href="//golang.org/issue">issue tracker</a>.
+(Of course, you should check it's not an existing issue before creating
+a new one.)
+</p>
+
+<p>
+We pride ourselves on being meticulous; no issue is too small.
+</p>
+
+<h3><a href="/doc/contribute.html">Contributing code</a></h3>
+
+<p>
+Go is an open source project and we welcome contributions from the community.
+</p>
+<p>
+To get started, read these <a href="/doc/contribute.html">contribution
+guidelines</a> for information on design, testing, and our code review process.
+</p>
+<p>
+Check <a href="//golang.org/issue">the tracker</a> for
+open issues that interest you. Those labeled
+<a href="https://github.com/golang/go/issues?q=is%3Aopen+is%3Aissue+label%3Ahelpwanted">helpwanted</a>
+are particularly in need of outside help.
+</p>
diff --git a/doc/contribute.html b/doc/contribute.html
new file mode 100644
index 0000000..63d4774
--- /dev/null
+++ b/doc/contribute.html
@@ -0,0 +1,663 @@
+<!--{
+ "Title": "Contribution Guidelines"
+}-->
+
+<h2 id="Introduction">Introduction</h2>
+
+<p>
+This document explains how to contribute changes to the Go project.
+It assumes you have followed the
+<a href="/doc/install/source">installation instructions</a> and
+have <a href="code.html">written and tested your code</a>.
+</p>
+
+<p>
+(Note that the <code>gccgo</code> frontend lives elsewhere;
+see <a href="gccgo_contribute.html">Contributing to gccgo</a>.)
+</p>
+
+<h2 id="Design">Discuss your design</h2>
+
+<p>
+The project welcomes submissions but please let everyone know what
+you're working on if you want it to become part of the main repository.
+</p>
+
+<p>
+Before undertaking to write something new for the Go project, send
+mail to the <a href="https://groups.google.com/group/golang-nuts">mailing
+list</a> to discuss what you plan to do. This gives everyone a
+chance to validate the design, helps prevent duplication of effort,
+and ensures that the idea fits inside the goals for the language
+and tools. It also guarantees that the design is sound before code
+is written; the code review tool is not the place for high-level
+discussions.
+</p>
+
+<p>
+In short, send mail before you code.
+And don't start the discussion by mailing a change list!
+</p>
+
+<h2 id="Testing">Testing redux</h2>
+
+<p>
+You've <a href="code.html">written and tested your code</a>, but
+before sending code out for review, run all the tests for the whole
+tree to make sure the changes don't break other packages or programs:
+</p>
+
+<pre>
+$ cd go/src
+$ ./all.bash
+</pre>
+
+<p>
+(To build under Windows use <code>all.bat</code>.)
+</p>
+
+<p>
+After running for a while, the command should print
+"<code>ALL</code> <code>TESTS</code> <code>PASSED</code>".
+</p>
+
+<h2 id="Code_review">Code review</h2>
+
+<p>
+Changes to Go must be reviewed before they are submitted,
+no matter who makes the change.
+(In exceptional cases, such as fixing a build, the review can
+follow shortly after submitting.)
+A custom git command called <code>git-codereview</code>,
+discussed below, helps manage the code review process through a Google-hosted
+<a href="https://go-review.googlesource.com/">instance</a> of the code review
+system called <a href="https://code.google.com/p/gerrit/">Gerrit</a>.
+</p>
+
+<h3>Set up authentication for code review</h3>
+
+<p>
+The Git code hosting server and Gerrit code review server both use a Google
+Account to authenticate. You therefore need a Google Account to proceed.
+(If you can use the account to
+<a href="https://www.google.com/accounts/Login">sign in at google.com</a>,
+you can use it to sign in to the code review server.)
+The email address you use with the code review system
+will be recorded in the <a href="https://go.googlesource.com/go">change log</a>
+and in the <a href="/CONTRIBUTORS"><code>CONTRIBUTORS</code></a> file.
+You can <a href="https://www.google.com/accounts/NewAccount">create a Google Account</a>
+associated with any address where you receive email.
+</p>
+
+<p>
+Visit the site <a href="https://go.googlesource.com">go.googlesource.com</a>
+and log in using your Google Account.
+Click on the "Generate Password" link that appears at the top of the page.
+</p>
+
+<p>
+Click the radio button that says "Only <code>go.googlesource.com</code>"
+to use this authentication token only for the Go project.
+</p>
+
+<p>
+Further down the page is a box containing commands to install
+the authentication cookie in file called <code>.gitcookies</code> in your home
+directory.
+Copy the text for the commands into a Unix shell window to execute it.
+That will install the authentication token.
+</p>
+
+<p>
+(If you are on a Windows computer, you should instead follow the instructions
+in the yellow box to run the command.)
+</p>
+
+<h3>Register with Gerrit</h3>
+
+<p>
+Now that you have a Google account and the authentication token,
+you need to register your account with Gerrit, the code review system.
+To do this, visit <a href="https://golang.org/cl">golang.org/cl</a>
+and log in using the same Google Account you used above.
+That is all that is required.
+</p>
+
+<h3>Install the git-codereview command</h3>
+
+<p>
+Now install the <code>git-codereview</code> command by running,
+</p>
+
+<pre>
+go get -u golang.org/x/review/git-codereview
+</pre>
+
+<p>
+Make sure <code>git-codereview</code> is installed in your shell path, so that the
+<code>git</code> command can find it. Check that
+</p>
+
+<pre>
+$ git codereview help
+</pre>
+
+<p>
+prints help text, not an error.
+</p>
+
+<p>
+Note to Git aficionados: The <code>git-codereview</code> command is not required to
+upload and manage Gerrit code reviews. For those who prefer plain Git, the text
+below gives the Git equivalent of each git-codereview command. If you do use plain
+Git, note that you still need the commit hooks that the git-codereview command
+configures; those hooks add a Gerrit <code>Change-Id</code> line to the commit
+message and check that all Go source files have been formatted with gofmt. Even
+if you intend to use plain Git for daily work, install the hooks in a new Git
+checkout by running <code>git-codereview</code> <code>hooks</code>.
+</p>
+
+<h3>Set up git aliases</h3>
+
+<p>
+The <code>git-codereview</code> command can be run directly from the shell
+by typing, for instance,
+</p>
+
+<pre>
+$ git codereview sync
+</pre>
+
+<p>
+but it is more convenient to set up aliases for <code>git-codereview</code>'s own
+subcommands, so that the above becomes,
+</p>
+
+<pre>
+$ git sync
+</pre>
+
+<p>
+The <code>git-codereview</code> subcommands have been chosen to be distinct from
+Git's own, so it's safe to do so.
+</p>
+
+<p>
+The aliases are optional, but in the rest of this document we will assume
+they are installed.
+To install them, copy this text into your Git configuration file
+(usually <code>.gitconfig</code> in your home directory):
+</p>
+
+<pre>
+[alias]
+ change = codereview change
+ gofmt = codereview gofmt
+ mail = codereview mail
+ pending = codereview pending
+ submit = codereview submit
+ sync = codereview sync
+</pre>
+
+<h3>Understanding the git-codereview command</h3>
+
+<p>After installing the <code>git-codereview</code> command, you can run</p>
+
+<pre>
+$ git codereview help
+</pre>
+
+<p>
+to learn more about its commands.
+You can also read the <a href="https://godoc.org/golang.org/x/review/git-codereview">command documentation</a>.
+</p>
+
+<h3>Switch to the master branch</h3>
+
+<p>
+Most Go installations use a release branch, but new changes should
+only be made based on the master branch.
+(They may be applied later to a release branch as part of the release process,
+but most contributors won't do this themselves.)
+Before making a change, make sure you start on the master branch:
+</p>
+
+<pre>
+$ git checkout master
+$ git sync
+</pre>
+
+<p>
+(In Git terms, <code>git</code> <code>sync</code> runs
+<code>git</code> <code>pull</code> <code>-r</code>.)
+</p>
+
+<h3>Make a change</h3>
+
+<p>
+The entire checked-out tree is writable.
+Once you have edited files, you must tell Git that they have been modified.
+You must also tell Git about any files that are added, removed, or renamed files.
+These operations are done with the usual Git commands,
+<code>git</code> <code>add</code>,
+<code>git</code> <code>rm</code>,
+and
+<code>git</code> <code>mv</code>.
+</p>
+
+<p>
+If you wish to checkpoint your work, or are ready to send the code out for review, run</p>
+
+<pre>
+$ git change <i><branch></i>
+</pre>
+
+<p>
+from any directory in your Go repository to commit the changes so far.
+The name <i><branch></i> is an arbitrary one you choose to identify the
+local branch containing your changes.
+</p>
+
+<p>
+(In Git terms, <code>git</code> <code>change</code> <code><branch></code>
+runs <code>git</code> <code>checkout</code> <code>-b</code> <code>branch</code>,
+then <code>git</code> <code>branch</code> <code>--set-upstream-to</code> <code>origin/master</code>,
+then <code>git</code> <code>commit</code>.)
+</p>
+
+<p>
+Git will open a change description file in your editor.
+(It uses the editor named by the <code>$EDITOR</code> environment variable,
+<code>vi</code> by default.)
+The file will look like:
+</p>
+
+<pre>
+
+# Please enter the commit message for your changes. Lines starting
+# with '#' will be ignored, and an empty message aborts the commit.
+# On branch foo
+# Changes not staged for commit:
+# modified: editedfile.go
+#
+</pre>
+
+<p>
+At the beginning of this file is a blank line; replace it
+with a thorough description of your change.
+The first line of the change description is conventionally a one-line
+summary of the change, prefixed by the primary affected package,
+and is used as the subject for code review mail.
+The rest of the
+description elaborates and should provide context for the
+change and explain what it does.
+If there is a helpful reference, mention it here.
+</p>
+
+<p>
+After editing, the template might now read:
+</p>
+
+<pre>
+math: improved Sin, Cos and Tan precision for very large arguments
+
+The existing implementation has poor numerical properties for
+large arguments, so use the McGillicutty algorithm to improve
+accuracy above 1e10.
+
+The algorithm is described at http://wikipedia.org/wiki/McGillicutty_Algorithm
+
+Fixes #159
+
+# Please enter the commit message for your changes. Lines starting
+# with '#' will be ignored, and an empty message aborts the commit.
+# On branch foo
+# Changes not staged for commit:
+# modified: editedfile.go
+#
+</pre>
+
+<p>
+The commented section of the file lists all the modified files in your client.
+It is best to keep unrelated changes in different change lists,
+so if you see a file listed that should not be included, abort
+the command and move that file to a different branch.
+</p>
+
+<p>
+The special notation "Fixes #159" associates the change with issue 159 in the
+<a href="https://golang.org/issue/159">Go issue tracker</a>.
+When this change is eventually submitted, the issue
+tracker will automatically mark the issue as fixed.
+(There are several such conventions, described in detail in the
+<a href="https://help.github.com/articles/closing-issues-via-commit-messages/">GitHub Issue Tracker documentation</a>.)
+</p>
+
+<p>
+Once you have finished writing the commit message,
+save the file and exit the editor.
+</p>
+
+<p>
+If you wish to do more editing, re-stage your changes using
+<code>git</code> <code>add</code>, and then run
+</p>
+
+<pre>
+$ git change
+</pre>
+
+<p>
+to update the change description and incorporate the staged changes. The
+change description contains a <code>Change-Id</code> line near the bottom,
+added by a Git commit hook during the initial
+<code>git</code> <code>change</code>.
+That line is used by Gerrit to match successive uploads of the same change.
+Do not edit or delete it.
+</p>
+
+<p>
+(In Git terms, <code>git</code> <code>change</code> with no branch name
+runs <code>git</code> <code>commit</code> <code>--amend</code>.)
+</p>
+
+<h3>Mail the change for review</h3>
+
+<p>
+Once the change is ready, mail it out for review:
+</p>
+
+<pre>
+$ git mail
+</pre>
+
+<p>
+You can specify a reviewer or CC interested parties
+using the <code>-r</code> or <code>-cc</code> options.
+Both accept a comma-separated list of email addresses:
+</p>
+
+<pre>
+$ git mail -r joe@golang.org -cc mabel@example.com,math-nuts@swtch.com
+</pre>
+
+<p>
+Unless explicitly told otherwise, such as in the discussion leading
+up to sending in the change list, it's better not to specify a reviewer.
+All changes are automatically CC'ed to the
+<a href="https://groups.google.com/group/golang-codereviews">golang-codereviews@googlegroups.com</a>
+mailing list.
+</p>
+
+<p>
+(In Git terms, <code>git</code> <code>mail</code> pushes the local committed
+changes to Gerrit using <code>git</code> <code>push</code> <code>origin</code>
+<code>HEAD:refs/for/master</code>.)
+</p>
+
+<p>
+If your change relates to an open issue, please add a comment to the issue
+announcing your proposed fix, including a link to your CL.
+</p>
+
+<p>
+The code review server assigns your change an issue number and URL,
+which <code>git</code> <code>mail</code> will print, something like:
+</p>
+
+<pre>
+remote: New Changes:
+remote: https://go-review.googlesource.com/99999 math: improved Sin, Cos and Tan precision for very large arguments
+</pre>
+
+<h3>Reviewing code</h3>
+
+<p>
+Running <code>git</code> <code>mail</code> will send an email to you and the
+reviewers asking them to visit the issue's URL and make comments on the change.
+When done, the reviewer adds comments through the Gerrit user interface
+and clicks "Reply" to send comments back.
+You will receive a mail notification when this happens.
+You must reply through the web interface.
+(Unlike with the old Rietveld review system, replying by mail has no effect.)
+</p>
+
+<h3>Revise and upload</h3>
+
+<p>
+You must respond to review comments through the web interface.
+(Unlike with the old Rietveld review system, responding by mail has no effect.)
+</p>
+
+<p>
+When you have revised the code and are ready for another round of review,
+stage those changes and use <code>git</code> <code>change</code> to update the
+commit.
+To send the update change list for another round of review,
+run <code>git</code> <code>mail</code> again.
+</p>
+
+<p>
+The reviewer can comment on the new copy, and the process repeats.
+The reviewer approves the change by giving it a positive score
+(+1 or +2) and replying <code>LGTM</code>: looks good to me.
+</p>
+
+<p>
+You can see a list of your pending changes by running <code>git</code>
+<code>pending</code>, and switch between change branches with <code>git</code>
+<code>change</code> <code><i><branch></i></code>.
+</p>
+
+<h3>Synchronize your client</h3>
+
+<p>
+While you were working, others might have submitted changes to the repository.
+To update your local branch, run
+</p>
+
+<pre>
+$ git sync
+</pre>
+
+<p>
+(In git terms, <code>git</code> <code>sync</code> runs
+<code>git</code> <code>pull</code> <code>-r</code>.)
+</p>
+
+<p>
+If files you were editing have changed, Git does its best to merge the
+remote changes into your local changes.
+It may leave some files to merge by hand.
+</p>
+
+<p>
+For example, suppose you have edited <code>sin.go</code> but
+someone else has committed an independent change.
+When you run <code>git</code> <code>sync</code>,
+you will get the (scary-looking) output:
+
+<pre>
+$ git sync
+Failed to merge in the changes.
+Patch failed at 0023 math: improved Sin, Cos and Tan precision for very large arguments
+The copy of the patch that failed is found in:
+ /home/you/repo/.git/rebase-apply/patch
+
+When you have resolved this problem, run "git rebase --continue".
+If you prefer to skip this patch, run "git rebase --skip" instead.
+To check out the original branch and stop rebasing, run "git rebase --abort".
+</pre>
+
+<p>
+If this happens, run
+</p>
+
+<pre>
+$ git status
+</pre>
+
+<p>
+to see which files failed to merge.
+The output will look something like this:
+</p>
+
+<pre>
+rebase in progress; onto a24c3eb
+You are currently rebasing branch 'mcgillicutty' on 'a24c3eb'.
+ (fix conflicts and then run "git rebase --continue")
+ (use "git rebase --skip" to skip this patch)
+ (use "git rebase --abort" to check out the original branch)
+
+Unmerged paths:
+ (use "git reset HEAD <file>..." to unstage)
+ (use "git add <file>..." to mark resolution)
+
+ <i>both modified: sin.go</i>
+</pre>
+
+<p>
+The only important part in that transcript is the italicized "both modified"
+line: Git failed to merge your changes with the conflicting change.
+When this happens, Git leaves both sets of edits in the file,
+with conflicts marked by <code><<<<<<<</code> and
+<code>>>>>>>></code>.
+It is now your job to edit the file to combine them.
+Continuing the example, searching for those strings in <code>sin.go</code>
+might turn up:
+</p>
+
+<pre>
+ arg = scale(arg)
+<<<<<<< HEAD
+ if arg > 1e9 {
+=======
+ if arg > 1e10 {
+>>>>>>> mcgillicutty
+ largeReduce(arg)
+</pre>
+
+<p>
+Git doesn't show it, but suppose the original text that both edits
+started with was 1e8; you changed it to 1e10 and the other change to 1e9,
+so the correct answer might now be 1e10. First, edit the section
+to remove the markers and leave the correct code:
+</p>
+
+<pre>
+ arg = scale(arg)
+ if arg > 1e10 {
+ largeReduce(arg)
+</pre>
+
+<p>
+Then tell Git that the conflict is resolved by running
+</p>
+
+<pre>
+$ git add sin.go
+</pre>
+
+<p>
+If you had been editing the file, say for debugging, but do not
+care to preserve your changes, you can run
+<code>git</code> <code>reset</code> <code>HEAD</code> <code>sin.go</code>
+to abandon your changes.
+Then run <code>git</code> <code>rebase</code> <code>--continue</code> to
+restore the change commit.
+</p>
+
+<h3>Reviewing code by others</h3>
+
+<p>
+You can import a change proposed by someone else into your local Git repository.
+On the Gerrit review page, click the "Download ▼" link in the upper right
+corner, copy the "Checkout" command and run it from your local Git repo.
+It should look something like this:
+</p>
+
+<pre>
+$ git fetch https://go.googlesource.com/review refs/changes/21/1221/1 && git checkout FETCH_HEAD
+</pre>
+
+<p>
+To revert, change back to the branch you were working in.
+</p>
+
+<h3>Submit the change after the review</h3>
+
+<p>
+After the code has been <code>LGTM</code>'ed, an approver may
+submit it to the master branch using the Gerrit UI.
+There is a "Submit" button on the web page for the change
+that appears once the change is approved (marked +2).
+</p>
+
+<p>
+This checks the change into the repository.
+The change description will include a link to the code review,
+and the code review will be updated with a link to the change
+in the repository.
+Since the method used to integrate the changes is "Cherry Pick",
+the commit hashes in the repository will be changed by
+the submit operation.
+</p>
+
+<h3>More information</h3>
+
+<p>
+In addition to the information here, the Go community maintains a <a href="https://golang.org/wiki/CodeReview">CodeReview</a> wiki page.
+Feel free to contribute to this page as you learn the review process.
+</p>
+
+<h2 id="copyright">Copyright</h2>
+
+<p>Files in the Go repository don't list author names,
+both to avoid clutter and to avoid having to keep the lists up to date.
+Instead, your name will appear in the
+<a href="https://golang.org/change">change log</a>
+and in the <a href="/CONTRIBUTORS"><code>CONTRIBUTORS</code></a> file
+and perhaps the <a href="/AUTHORS"><code>AUTHORS</code></a> file.
+</p>
+
+<p>The <a href="/CONTRIBUTORS"><code>CONTRIBUTORS</code></a> file
+defines who the Go contributors—the people—are;
+the <a href="/AUTHORS"><code>AUTHORS</code></a> file defines
+who “The Go Authors”—the copyright holders—are.
+The Go developers at Google will update these files when submitting
+your first change.
+In order for them to do that, you need to have completed one of the
+contributor license agreements:
+<ul>
+<li>
+If you are the copyright holder, you will need to agree to the
+<a href="https://developers.google.com/open-source/cla/individual">individual
+contributor license agreement</a>, which can be completed online.
+</li>
+<li>
+If your organization is the copyright holder, the organization
+will need to agree to the
+<a href="https://developers.google.com/open-source/cla/corporate">corporate
+contributor license agreement</a>.
+(If the copyright holder for your code has already completed the
+agreement in connection with another Google open source project,
+it does not need to be completed again.)
+</li>
+</ul>
+
+<p>
+This rigmarole needs to be done only for your first submission.
+</p>
+
+<p>Code that you contribute should use the standard copyright header:</p>
+
+<pre>
+// Copyright 2015 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+</pre>
+
+<p>
+Files in the repository are copyright the year they are added. It is not
+necessary to update the copyright year on files that you change.
+</p>
diff --git a/doc/debugging_with_gdb.html b/doc/debugging_with_gdb.html
new file mode 100644
index 0000000..8368164
--- /dev/null
+++ b/doc/debugging_with_gdb.html
@@ -0,0 +1,507 @@
+<!--{
+ "Title": "Debugging Go Code with GDB",
+ "Path": "/doc/gdb"
+}-->
+
+<p><i>
+This applies to the <code>gc</code> toolchain. Gccgo has native gdb support.
+Besides this overview you might want to consult the
+<a href="http://sourceware.org/gdb/current/onlinedocs/gdb/">GDB manual</a>.
+</i></p>
+
+<p>
+GDB does not understand Go programs well.
+The stack management, threading, and runtime contain aspects that differ
+enough from the execution model GDB expects that they can confuse
+the debugger, even when the program is compiled with gccgo.
+As a consequence, although GDB can be useful in some situations, it is
+not a reliable debugger for Go programs, particularly heavily concurrent ones.
+Moreover, it is not a priority for the Go project to address these issues, which
+are difficult.
+In short, the instructions below should be taken only as a guide to how
+to use GDB when it works, not as a guarantee of success.
+</p>
+
+<p>
+In time, a more Go-centric debugging architecture may be required.
+</p>
+
+<h2 id="Introduction">Introduction</h2>
+
+<p>
+When you compile and link your Go programs with the <code>gc</code> toolchain
+on Linux, Mac OS X, FreeBSD or NetBSD, the resulting binaries contain DWARFv3
+debugging information that recent versions (>7.1) of the GDB debugger can
+use to inspect a live process or a core dump.
+</p>
+
+<p>
+Pass the <code>'-w'</code> flag to the linker to omit the debug information
+(for example, <code>go build -ldflags "-w" prog.go</code>).
+</p>
+
+<p>
+The code generated by the <code>gc</code> compiler includes inlining of
+function invocations and registerization of variables. These optimizations
+can sometimes make debugging with <code>gdb</code> harder. To disable them
+when debugging, pass the flags <code>-gcflags "-N -l"</code> to the
+<a href="/cmd/go"><code>go</code></a> command used to build the code being
+debugged.
+</p>
+
+<h3 id="Common_Operations">Common Operations</h3>
+
+<ul>
+<li>
+Show file and line number for code, set breakpoints and disassemble:
+<pre>(gdb) <b>list</b>
+(gdb) <b>list <i>line</i></b>
+(gdb) <b>list <i>file.go</i>:<i>line</i></b>
+(gdb) <b>break <i>line</i></b>
+(gdb) <b>break <i>file.go</i>:<i>line</i></b>
+(gdb) <b>disas</b></pre>
+</li>
+<li>
+Show backtraces and unwind stack frames:
+<pre>(gdb) <b>bt</b>
+(gdb) <b>frame <i>n</i></b></pre>
+</li>
+<li>
+Show the name, type and location on the stack frame of local variables,
+arguments and return values:
+<pre>(gdb) <b>info locals</b>
+(gdb) <b>info args</b>
+(gdb) <b>p variable</b>
+(gdb) <b>whatis variable</b></pre>
+</li>
+<li>
+Show the name, type and location of global variables:
+<pre>(gdb) <b>info variables <i>regexp</i></b></pre>
+</li>
+</ul>
+
+
+<h3 id="Go_Extensions">Go Extensions</h3>
+
+<p>
+A recent extension mechanism to GDB allows it to load extension scripts for a
+given binary. The tool chain uses this to extend GDB with a handful of
+commands to inspect internals of the runtime code (such as goroutines) and to
+pretty print the built-in map, slice and channel types.
+</p>
+
+<ul>
+<li>
+Pretty printing a string, slice, map, channel or interface:
+<pre>(gdb) <b>p <i>var</i></b></pre>
+</li>
+<li>
+A $len() and $cap() function for strings, slices and maps:
+<pre>(gdb) <b>p $len(<i>var</i>)</b></pre>
+</li>
+<li>
+A function to cast interfaces to their dynamic types:
+<pre>(gdb) <b>p $dtype(<i>var</i>)</b>
+(gdb) <b>iface <i>var</i></b></pre>
+<p class="detail"><b>Known issue:</b> GDB can’t automatically find the dynamic
+type of an interface value if its long name differs from its short name
+(annoying when printing stacktraces, the pretty printer falls back to printing
+the short type name and a pointer).</p>
+</li>
+<li>
+Inspecting goroutines:
+<pre>(gdb) <b>info goroutines</b>
+(gdb) <b>goroutine <i>n</i> <i>cmd</i></b>
+(gdb) <b>help goroutine</b></pre>
+For example:
+<pre>(gdb) <b>goroutine 12 bt</b></pre>
+</li>
+</ul>
+
+<p>
+If you'd like to see how this works, or want to extend it, take a look at <a
+href="/src/runtime/runtime-gdb.py">src/runtime/runtime-gdb.py</a> in
+the Go source distribution. It depends on some special magic types
+(<code>hash<T,U></code>) and variables (<code>runtime.m</code> and
+<code>runtime.g</code>) that the linker
+(<a href="/src/cmd/ld/dwarf.c">src/cmd/ld/dwarf.c</a>) ensures are described in
+the DWARF code.
+</p>
+
+<p>
+If you're interested in what the debugging information looks like, run
+'<code>objdump -W 6.out</code>' and browse through the <code>.debug_*</code>
+sections.
+</p>
+
+
+<h3 id="Known_Issues">Known Issues</h3>
+
+<ol>
+<li>String pretty printing only triggers for type string, not for types derived
+from it.</li>
+<li>Type information is missing for the C parts of the runtime library.</li>
+<li>GDB does not understand Go’s name qualifications and treats
+<code>"fmt.Print"</code> as an unstructured literal with a <code>"."</code>
+that needs to be quoted. It objects even more strongly to method names of
+the form <code>pkg.(*MyType).Meth</code>.
+<li>All global variables are lumped into package <code>"main"</code>.</li>
+</ol>
+
+<h2 id="Tutorial">Tutorial</h2>
+
+<p>
+In this tutorial we will inspect the binary of the
+<a href="/pkg/regexp/">regexp</a> package's unit tests. To build the binary,
+change to <code>$GOROOT/src/regexp</code> and run <code>go test -c</code>.
+This should produce an executable file named <code>regexp.test</code>.
+</p>
+
+
+<h3 id="Getting_Started">Getting Started</h3>
+
+<p>
+Launch GDB, debugging <code>regexp.test</code>:
+</p>
+
+<pre>
+$ <b>gdb regexp.test</b>
+GNU gdb (GDB) 7.2-gg8
+Copyright (C) 2010 Free Software Foundation, Inc.
+License GPLv 3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+Type "show copying" and "show warranty" for licensing/warranty details.
+This GDB was configured as "x86_64-linux".
+
+Reading symbols from /home/user/go/src/regexp/regexp.test...
+done.
+Loading Go Runtime support.
+(gdb)
+</pre>
+
+<p>
+The message <code>"Loading Go Runtime support"</code> means that GDB loaded the
+extension from <code>$GOROOT/src/runtime/runtime-gdb.py</code>.
+</p>
+
+<p>
+To help GDB find the Go runtime sources and the accompanying support script,
+pass your <code>$GOROOT</code> with the <code>'-d'</code> flag:
+</p>
+
+<pre>
+$ <b>gdb regexp.test -d $GOROOT</b>
+</pre>
+
+<p>
+If for some reason GDB still can't find that directory or that script, you can load
+it by hand by telling gdb (assuming you have the go sources in
+<code>~/go/</code>):
+</p>
+
+<pre>
+(gdb) <b>source ~/go/src/runtime/runtime-gdb.py</b>
+Loading Go Runtime support.
+</pre>
+
+<h3 id="Inspecting_the_source">Inspecting the source</h3>
+
+<p>
+Use the <code>"l"</code> or <code>"list"</code> command to inspect source code.
+</p>
+
+<pre>
+(gdb) <b>l</b>
+</pre>
+
+<p>
+List a specific part of the source parametrizing <code>"list"</code> with a
+function name (it must be qualified with its package name).
+</p>
+
+<pre>
+(gdb) <b>l main.main</b>
+</pre>
+
+<p>
+List a specific file and line number:
+</p>
+
+<pre>
+(gdb) <b>l regexp.go:1</b>
+(gdb) <i># Hit enter to repeat last command. Here, this lists next 10 lines.</i>
+</pre>
+
+
+<h3 id="Naming">Naming</h3>
+
+<p>
+Variable and function names must be qualified with the name of the packages
+they belong to. The <code>Compile</code> function from the <code>regexp</code>
+package is known to GDB as <code>'regexp.Compile'</code>.
+</p>
+
+<p>
+Methods must be qualified with the name of their receiver types. For example,
+the <code>*Regexp</code> type’s <code>String</code> method is known as
+<code>'regexp.(*Regexp).String'</code>.
+</p>
+
+<p>
+Variables that shadow other variables are magically suffixed with a number in the debug info.
+Variables referenced by closures will appear as pointers magically prefixed with '&'.
+</p>
+
+<h3 id="Setting_breakpoints">Setting breakpoints</h3>
+
+<p>
+Set a breakpoint at the <code>TestFind</code> function:
+</p>
+
+<pre>
+(gdb) <b>b 'regexp.TestFind'</b>
+Breakpoint 1 at 0x424908: file /home/user/go/src/regexp/find_test.go, line 148.
+</pre>
+
+<p>
+Run the program:
+</p>
+
+<pre>
+(gdb) <b>run</b>
+Starting program: /home/user/go/src/regexp/regexp.test
+
+Breakpoint 1, regexp.TestFind (t=0xf8404a89c0) at /home/user/go/src/regexp/find_test.go:148
+148 func TestFind(t *testing.T) {
+</pre>
+
+<p>
+Execution has paused at the breakpoint.
+See which goroutines are running, and what they're doing:
+</p>
+
+<pre>
+(gdb) <b>info goroutines</b>
+ 1 waiting runtime.gosched
+* 13 running runtime.goexit
+</pre>
+
+<p>
+the one marked with the <code>*</code> is the current goroutine.
+</p>
+
+<h3 id="Inspecting_the_stack">Inspecting the stack</h3>
+
+<p>
+Look at the stack trace for where we’ve paused the program:
+</p>
+
+<pre>
+(gdb) <b>bt</b> <i># backtrace</i>
+#0 regexp.TestFind (t=0xf8404a89c0) at /home/user/go/src/regexp/find_test.go:148
+#1 0x000000000042f60b in testing.tRunner (t=0xf8404a89c0, test=0x573720) at /home/user/go/src/testing/testing.go:156
+#2 0x000000000040df64 in runtime.initdone () at /home/user/go/src/runtime/proc.c:242
+#3 0x000000f8404a89c0 in ?? ()
+#4 0x0000000000573720 in ?? ()
+#5 0x0000000000000000 in ?? ()
+</pre>
+
+<p>
+The other goroutine, number 1, is stuck in <code>runtime.gosched</code>, blocked on a channel receive:
+</p>
+
+<pre>
+(gdb) <b>goroutine 1 bt</b>
+#0 0x000000000040facb in runtime.gosched () at /home/user/go/src/runtime/proc.c:873
+#1 0x00000000004031c9 in runtime.chanrecv (c=void, ep=void, selected=void, received=void)
+ at /home/user/go/src/runtime/chan.c:342
+#2 0x0000000000403299 in runtime.chanrecv1 (t=void, c=void) at/home/user/go/src/runtime/chan.c:423
+#3 0x000000000043075b in testing.RunTests (matchString={void (struct string, struct string, bool *, error *)}
+ 0x7ffff7f9ef60, tests= []testing.InternalTest = {...}) at /home/user/go/src/testing/testing.go:201
+#4 0x00000000004302b1 in testing.Main (matchString={void (struct string, struct string, bool *, error *)}
+ 0x7ffff7f9ef80, tests= []testing.InternalTest = {...}, benchmarks= []testing.InternalBenchmark = {...})
+at /home/user/go/src/testing/testing.go:168
+#5 0x0000000000400dc1 in main.main () at /home/user/go/src/regexp/_testmain.go:98
+#6 0x00000000004022e7 in runtime.mainstart () at /home/user/go/src/runtime/amd64/asm.s:78
+#7 0x000000000040ea6f in runtime.initdone () at /home/user/go/src/runtime/proc.c:243
+#8 0x0000000000000000 in ?? ()
+</pre>
+
+<p>
+The stack frame shows we’re currently executing the <code>regexp.TestFind</code> function, as expected.
+</p>
+
+<pre>
+(gdb) <b>info frame</b>
+Stack level 0, frame at 0x7ffff7f9ff88:
+ rip = 0x425530 in regexp.TestFind (/home/user/go/src/regexp/find_test.go:148);
+ saved rip 0x430233
+ called by frame at 0x7ffff7f9ffa8
+ source language minimal.
+ Arglist at 0x7ffff7f9ff78, args: t=0xf840688b60
+ Locals at 0x7ffff7f9ff78, Previous frame's sp is 0x7ffff7f9ff88
+ Saved registers:
+ rip at 0x7ffff7f9ff80
+</pre>
+
+<p>
+The command <code>info locals</code> lists all variables local to the function and their values, but is a bit
+dangerous to use, since it will also try to print uninitialized variables. Uninitialized slices may cause gdb to try
+to print arbitrary large arrays.
+</p>
+
+<p>
+The function’s arguments:
+</p>
+
+<pre>
+(gdb) <b>info args</b>
+t = 0xf840688b60
+</pre>
+
+<p>
+When printing the argument, notice that it’s a pointer to a
+<code>Regexp</code> value. Note that GDB has incorrectly put the <code>*</code>
+on the right-hand side of the type name and made up a 'struct' keyword, in traditional C style.
+</p>
+
+<pre>
+(gdb) <b>p re</b>
+(gdb) p t
+$1 = (struct testing.T *) 0xf840688b60
+(gdb) p t
+$1 = (struct testing.T *) 0xf840688b60
+(gdb) p *t
+$2 = {errors = "", failed = false, ch = 0xf8406f5690}
+(gdb) p *t->ch
+$3 = struct hchan<*testing.T>
+</pre>
+
+<p>
+That <code>struct hchan<*testing.T></code> is the runtime-internal representation of a channel. It is currently empty, or gdb would have pretty-printed it's contents.
+</p>
+
+<p>
+Stepping forward:
+</p>
+
+<pre>
+(gdb) <b>n</b> <i># execute next line</i>
+149 for _, test := range findTests {
+(gdb) <i># enter is repeat</i>
+150 re := MustCompile(test.pat)
+(gdb) <b>p test.pat</b>
+$4 = ""
+(gdb) <b>p re</b>
+$5 = (struct regexp.Regexp *) 0xf84068d070
+(gdb) <b>p *re</b>
+$6 = {expr = "", prog = 0xf840688b80, prefix = "", prefixBytes = []uint8, prefixComplete = true,
+ prefixRune = 0, cond = 0 '\000', numSubexp = 0, longest = false, mu = {state = 0, sema = 0},
+ machine = []*regexp.machine}
+(gdb) <b>p *re->prog</b>
+$7 = {Inst = []regexp/syntax.Inst = {{Op = 5 '\005', Out = 0, Arg = 0, Rune = []int}, {Op =
+ 6 '\006', Out = 2, Arg = 0, Rune = []int}, {Op = 4 '\004', Out = 0, Arg = 0, Rune = []int}},
+ Start = 1, NumCap = 2}
+</pre>
+
+
+<p>
+We can step into the <code>String</code>function call with <code>"s"</code>:
+</p>
+
+<pre>
+(gdb) <b>s</b>
+regexp.(*Regexp).String (re=0xf84068d070, noname=void) at /home/user/go/src/regexp/regexp.go:97
+97 func (re *Regexp) String() string {
+</pre>
+
+<p>
+Get a stack trace to see where we are:
+</p>
+
+<pre>
+(gdb) <b>bt</b>
+#0 regexp.(*Regexp).String (re=0xf84068d070, noname=void)
+ at /home/user/go/src/regexp/regexp.go:97
+#1 0x0000000000425615 in regexp.TestFind (t=0xf840688b60)
+ at /home/user/go/src/regexp/find_test.go:151
+#2 0x0000000000430233 in testing.tRunner (t=0xf840688b60, test=0x5747b8)
+ at /home/user/go/src/testing/testing.go:156
+#3 0x000000000040ea6f in runtime.initdone () at /home/user/go/src/runtime/proc.c:243
+....
+</pre>
+
+<p>
+Look at the source code:
+</p>
+
+<pre>
+(gdb) <b>l</b>
+92 mu sync.Mutex
+93 machine []*machine
+94 }
+95
+96 // String returns the source text used to compile the regular expression.
+97 func (re *Regexp) String() string {
+98 return re.expr
+99 }
+100
+101 // Compile parses a regular expression and returns, if successful,
+</pre>
+
+<h3 id="Pretty_Printing">Pretty Printing</h3>
+
+<p>
+GDB's pretty printing mechanism is triggered by regexp matches on type names. An example for slices:
+</p>
+
+<pre>
+(gdb) <b>p utf</b>
+$22 = []uint8 = {0 '\000', 0 '\000', 0 '\000', 0 '\000'}
+</pre>
+
+<p>
+Since slices, arrays and strings are not C pointers, GDB can't interpret the subscripting operation for you, but
+you can look inside the runtime representation to do that (tab completion helps here):
+</p>
+<pre>
+
+(gdb) <b>p slc</b>
+$11 = []int = {0, 0}
+(gdb) <b>p slc-></b><i><TAB></i>
+array slc len
+(gdb) <b>p slc->array</b>
+$12 = (int *) 0xf84057af00
+(gdb) <b>p slc->array[1]</b>
+$13 = 0</pre>
+
+
+
+<p>
+The extension functions $len and $cap work on strings, arrays and slices:
+</p>
+
+<pre>
+(gdb) <b>p $len(utf)</b>
+$23 = 4
+(gdb) <b>p $cap(utf)</b>
+$24 = 4
+</pre>
+
+<p>
+Channels and maps are 'reference' types, which gdb shows as pointers to C++-like types <code>hash<int,string>*</code>. Dereferencing will trigger prettyprinting
+</p>
+
+<p>
+Interfaces are represented in the runtime as a pointer to a type descriptor and a pointer to a value. The Go GDB runtime extension decodes this and automatically triggers pretty printing for the runtime type. The extension function <code>$dtype</code> decodes the dynamic type for you (examples are taken from a breakpoint at <code>regexp.go</code> line 293.)
+</p>
+
+<pre>
+(gdb) <b>p i</b>
+$4 = {str = "cbb"}
+(gdb) <b>whatis i</b>
+type = regexp.input
+(gdb) <b>p $dtype(i)</b>
+$26 = (struct regexp.inputBytes *) 0xf8400b4930
+(gdb) <b>iface i</b>
+regexp.input: struct regexp.inputBytes *
+</pre>
diff --git a/doc/devel/release.html b/doc/devel/release.html
new file mode 100644
index 0000000..6e69ce7
--- /dev/null
+++ b/doc/devel/release.html
@@ -0,0 +1,588 @@
+<!--{
+ "Title": "Release History"
+}-->
+
+<p>This page summarizes the changes between official stable releases of Go.
+The <a href="//golang.org/change">change log</a> has the full details.</p>
+
+<p>To update to a specific release, use:</p>
+
+<pre>
+hg pull
+hg update <i>tag</i>
+</pre>
+
+<h2 id="go1.4">go1.4 (released 2014/12/10)</h2>
+
+<p>
+Go 1.4 is a major release of Go.
+Read the <a href="/doc/go1.4">Go 1.4 Release Notes</a> for more information.
+</p>
+
+<h3 id="go1.4.minor">Minor revisions</h3>
+
+<p>
+go1.4.1 (released 2015/01/15) includes bug fixes to the linker and the <code>log</code>, <code>syscall</code>, and <code>runtime</code> packages.
+See the <a href="https://github.com/golang/go/issues?q=milestone%3AGo1.4.1">Go 1.4.1 milestone on our issue tracker</a> for details.
+</p>
+
+<h2 id="go1.3">go1.3 (released 2014/06/18)</h2>
+
+<p>
+Go 1.3 is a major release of Go.
+Read the <a href="/doc/go1.3">Go 1.3 Release Notes</a> for more information.
+</p>
+
+<h3 id="go1.3.minor">Minor revisions</h3>
+
+<p>
+go1.3.1 (released 2014/08/13) includes bug fixes to the compiler and the <code>runtime</code>, <code>net</code>, and <code>crypto/rsa</code> packages.
+See the <a href="//code.google.com/p/go/source/list?name=release-branch.go1.3&r=073fc578434bf3e1e22749b559d273c8da728ebb">change history</a> for details.
+</p>
+
+<p>
+go1.3.2 (released 2014/09/25) includes bug fixes to cgo and the crypto/tls packages.
+See the <a href="//code.google.com/p/go/source/list?name=release-branch.go1.3&r=go1.3.2">change history</a> for details.
+</p>
+
+<p>
+go1.3.3 (released 2014/09/30) includes further bug fixes to cgo, the runtime package, and the nacl port.
+See the <a href="//code.google.com/p/go/source/list?name=release-branch.go1.3&r=go1.3.3">change history</a> for details.
+</p>
+
+<h2 id="go1.2">go1.2 (released 2013/12/01)</h2>
+
+<p>
+Go 1.2 is a major release of Go.
+Read the <a href="/doc/go1.2">Go 1.2 Release Notes</a> for more information.
+</p>
+
+<h3 id="go1.2.minor">Minor revisions</h3>
+
+<p>
+go1.2.1 (released 2014/03/02) includes bug fixes to the <code>runtime</code>, <code>net</code>, and <code>database/sql</code> packages.
+See the <a href="//code.google.com/p/go/source/list?name=release-branch.go1.2&r=7ada9e760ce34e78aee5b476c9621556d0fa5d31">change history</a> for details.
+</p>
+
+<p>
+go1.2.2 (released 2014/05/05) includes a
+<a href="//code.google.com/p/go/source/detail?r=bda3619e7a2c&repo=tools">security fix</a>
+that affects the tour binary included in the binary distributions (thanks to Guillaume T).
+</p>
+
+<h2 id="go1.1">go1.1 (released 2013/05/13)</h2>
+
+<p>
+Go 1.1 is a major release of Go.
+Read the <a href="/doc/go1.1">Go 1.1 Release Notes</a> for more information.
+</p>
+
+<h3 id="go1.1.minor">Minor revisions</h3>
+
+<p>
+go1.1.1 (released 2013/06/13) includes several compiler and runtime bug fixes.
+See the <a href="//code.google.com/p/go/source/list?name=release-branch.go1.1&r=43c4a41d24382a56a90e924800c681e435d9e399">change history</a> for details.
+</p>
+
+<p>
+go1.1.2 (released 2013/08/13) includes fixes to the <code>gc</code> compiler
+and <code>cgo</code>, and the <code>bufio</code>, <code>runtime</code>,
+<code>syscall</code>, and <code>time</code> packages.
+See the <a href="//code.google.com/p/go/source/list?name=release-branch.go1.1&r=a6a9792f94acd4ff686b2bc57383d163608b91cf">change history</a> for details.
+If you use package syscall's <code>Getrlimit</code> and <code>Setrlimit</code>
+functions under Linux on the ARM or 386 architectures, please note change
+<a href="//golang.org/change/55ac276af5a7">55ac276af5a7</a>
+that fixes <a href="//golang.org/issue/5949">issue 5949</a>.
+</p>
+
+<h2 id="go1">go1 (released 2012/03/28)</h2>
+
+<p>
+Go 1 is a major release of Go that will be stable in the long term.
+Read the <a href="/doc/go1.html">Go 1 Release Notes</a> for more information.
+</p>
+
+<p>
+It is intended that programs written for Go 1 will continue to compile and run
+correctly, unchanged, under future versions of Go 1.
+Read the <a href="/doc/go1compat.html">Go 1 compatibility document</a> for more
+about the future of Go 1.
+</p>
+
+<p>
+The go1 release corresponds to
+<code><a href="weekly.html#2012-03-27">weekly.2012-03-27</a></code>.
+</p>
+
+<h3 id="go1.minor">Minor revisions</h3>
+
+<p>
+go1.0.1 (released 2012/04/25) was issued to
+<a href="//golang.org/change/a890477d3dfb">fix</a> an
+<a href="//golang.org/issue/3545">escape analysis bug</a>
+that can lead to memory corruption.
+It also includes several minor code and documentation fixes.
+</p>
+
+<p>
+go1.0.2 (released 2012/06/13) was issued to fix two bugs in the implementation
+of maps using struct or array keys:
+<a href="//golang.org/issue/3695">issue 3695</a> and
+<a href="//golang.org/issue/3573">issue 3573</a>.
+It also includes many minor code and documentation fixes.
+</p>
+
+<p>
+go1.0.3 (released 2012/09/21) includes minor code and documentation fixes.
+</p>
+
+<p>
+See the <a href="//code.google.com/p/go/source/list?name=release-branch.go1">go1 release branch history</a> for the complete list of changes.
+</p>
+
+<h2 id="r60">r60 (released 2011/09/07)</h2>
+
+<p>
+The r60 release corresponds to
+<code><a href="weekly.html#2011-08-17">weekly.2011-08-17</a></code>.
+This section highlights the most significant changes in this release.
+For a more detailed summary, see the
+<a href="weekly.html#2011-08-17">weekly release notes</a>.
+For complete information, see the
+<a href="//code.google.com/p/go/source/list?r=release-branch.r60">Mercurial change list</a>.
+</p>
+
+<h3 id="r60.lang">Language</h3>
+
+<p>
+An "else" block is now required to have braces except if the body of the "else"
+is another "if". Since gofmt always puts those braces in anyway,
+gofmt-formatted programs will not be affected.
+To fix other programs, run gofmt.
+</p>
+
+<h3 id="r60.pkg">Packages</h3>
+
+<p>
+<a href="/pkg/http/">Package http</a>'s URL parsing and query escaping code
+(such as <code>ParseURL</code> and <code>URLEscape</code>) has been moved to
+the new <a href="/pkg/url/">url package</a>, with several simplifications to
+the names. Client code can be updated automatically with gofix.
+</p>
+
+<p>
+<a href="/pkg/image/">Package image</a> has had significant changes made to the
+<code>Pix</code> field of struct types such as
+<a href="/pkg/image/#RGBA">image.RGBA</a> and
+<a href="/pkg/image/#NRGBA">image.NRGBA</a>.
+The <a href="/pkg/image/#Image">image.Image</a> interface type has not changed,
+though, and you should not need to change your code if you don't explicitly
+refer to <code>Pix</code> fields. For example, if you decode a number of images
+using the <a href="/pkg/image/jpeg/">image/jpeg</a> package, compose them using
+<a href="/pkg/image/draw/">image/draw</a>, and then encode the result using
+<a href="/pkg/img/png">image/png</a>, then your code should still work as
+before.
+If your code <i>does</i> refer to <code>Pix</code> fields see the
+<a href="/doc/devel/weekly.html#2011-07-19">weekly.2011-07-19</a>
+snapshot notes for how to update your code.
+</p>
+
+<p>
+<a href="/pkg/template/">Package template</a> has been replaced with a new
+templating package (formerly <code>exp/template</code>). The original template
+package is still available as <a href="/pkg/old/template/">old/template</a>.
+The <code>old/template</code> package is deprecated and will be removed.
+The Go tree has been updated to use the new template package. We encourage
+users of the old template package to switch to the new one. Code that uses
+<code>template</code> or <code>exp/template</code> will need to change its
+import lines to <code>"old/template"</code> or <code>"template"</code>,
+respectively.
+</p>
+
+<h3 id="r60.cmd">Tools</h3>
+
+<p>
+<a href="/cmd/goinstall/">Goinstall</a> now uses a new tag selection scheme.
+When downloading or updating, goinstall looks for a tag or branch with the
+<code>"go."</code> prefix that corresponds to the local Go version. For Go
+<code>release.r58</code> it looks for <code>go.r58</code>. For
+<code>weekly.2011-06-03</code> it looks for <code>go.weekly.2011-06-03</code>.
+If the specific <code>go.X</code> tag or branch is not found, it chooses the
+closest earlier version. If an appropriate tag or branch is found, goinstall
+uses that version of the code. Otherwise it uses the default version selected
+by the version control system. Library authors are encouraged to use the
+appropriate tag or branch names in their repositories to make their libraries
+more accessible.
+</p>
+
+<h3 id="r60.minor">Minor revisions</h3>
+
+<p>
+r60.1 includes a
+<a href="//golang.org/change/1824581bf62d">linker
+fix</a>, a pair of
+<a href="//golang.org/change/9ef4429c2c64">goplay</a>
+<a href="//golang.org/change/d42ed8c3098e">fixes</a>,
+and a <code>json</code> package
+<a href="//golang.org/change/d5e97874fe84">fix</a> and
+a new
+<a href="//golang.org/change/4f0e6269213f">struct tag
+option</a>.
+</p>
+
+<p>
+r60.2
+<a href="//golang.org/change/ff19536042ac">fixes</a>
+a memory leak involving maps.
+</p>
+
+<p>
+r60.3 fixes a
+<a href="//golang.org/change/01fa62f5e4e5">reflect bug</a>.
+</p>
+
+<h2 id="r59">r59 (released 2011/08/01)</h2>
+
+<p>
+The r59 release corresponds to
+<code><a href="weekly.html#2011-07-07">weekly.2011-07-07</a></code>.
+This section highlights the most significant changes in this release.
+For a more detailed summary, see the
+<a href="weekly.html#2011-07-07">weekly release notes</a>.
+For complete information, see the
+<a href="//code.google.com/p/go/source/list?r=release-branch.r59">Mercurial change list</a>.
+</p>
+
+<h3 id="r59.lang">Language</h3>
+
+<p>
+This release includes a language change that restricts the use of
+<code>goto</code>. In essence, a <code>goto</code> statement outside a block
+cannot jump to a label inside that block. Your code may require changes if it
+uses <code>goto</code>.
+See <a href="//golang.org/change/dc6d3cf9279d">this
+changeset</a> for how the new rule affected the Go tree.
+</p>
+
+<h3 id="r59.pkg">Packages</h3>
+
+<p>
+As usual, <a href="/cmd/gofix/">gofix</a> will handle the bulk of the rewrites
+necessary for these changes to package APIs.
+</p>
+
+<p>
+<a href="/pkg/http">Package http</a> has a new
+<a href="/pkg/http/#FileSystem">FileSystem</a> interface that provides access
+to files. The <a href="/pkg/http/#FileServer">FileServer</a> helper now takes a
+<code>FileSystem</code> argument instead of an explicit file system root. By
+implementing your own <code>FileSystem</code> you can use the
+<code>FileServer</code> to serve arbitrary data.
+</p>
+
+<p>
+<a href="/pkg/os/">Package os</a>'s <code>ErrorString</code> type has been
+hidden. Most uses of <code>os.ErrorString</code> can be replaced with
+<a href="/pkg/os/#NewError">os.NewError</a>.
+</p>
+
+<p>
+<a href="/pkg/reflect/">Package reflect</a> supports a new struct tag scheme
+that enables sharing of struct tags between multiple packages.
+In this scheme, the tags must be of the form:
+</p>
+<pre>
+ `key:"value" key2:"value2"`
+</pre>
+<p>
+The <a href="/pkg/reflect/#StructField">StructField</a> type's Tag field now
+has type <a href="/pkg/reflect/#StructTag">StructTag</a>, which has a
+<code>Get</code> method. Clients of <a href="/pkg/json">json</a> and
+<a href="/pkg/xml">xml</a> will need to be updated. Code that says
+</p>
+<pre>
+ type T struct {
+ X int "name"
+ }
+</pre>
+<p>
+should become
+</p>
+<pre>
+ type T struct {
+ X int `json:"name"` // or `xml:"name"`
+ }
+</pre>
+<p>
+Use <a href="/cmd/govet/">govet</a> to identify struct tags that need to be
+changed to use the new syntax.
+</p>
+
+<p>
+<a href="/pkg/sort/">Package sort</a>'s <code>IntArray</code> type has been
+renamed to <a href="/pkg/sort/#IntSlice">IntSlice</a>, and similarly for
+<a href="/pkg/sort/#Float64Slice">Float64Slice</a> and
+<a href="/pkg/sort/#StringSlice">StringSlice</a>.
+</p>
+
+<p>
+<a href="/pkg/strings/">Package strings</a>'s <code>Split</code> function has
+itself been split into <a href="/pkg/strings/#Split">Split</a> and
+<a href="/pkg/strings/#SplitN">SplitN</a>.
+<code>SplitN</code> is the same as the old <code>Split</code>.
+The new <code>Split</code> is equivalent to <code>SplitN</code> with a final
+argument of -1.
+</p>
+
+<a href="/pkg/image/draw/">Package image/draw</a>'s
+<a href="/pkg/image/draw/#Draw">Draw</a> function now takes an additional
+argument, a compositing operator.
+If in doubt, use <a href="/pkg/image/draw/#Op">draw.Over</a>.
+</p>
+
+<h3 id="r59.cmd">Tools</h3>
+
+<p>
+<a href="/cmd/goinstall/">Goinstall</a> now installs packages and commands from
+arbitrary remote repositories (not just Google Code, Github, and so on).
+See the <a href="/cmd/goinstall/">goinstall documentation</a> for details.
+</p>
+
+<h2 id="r58">r58 (released 2011/06/29)</h2>
+
+<p>
+The r58 release corresponds to
+<code><a href="weekly.html#2011-06-09">weekly.2011-06-09</a></code>
+with additional bug fixes.
+This section highlights the most significant changes in this release.
+For a more detailed summary, see the
+<a href="weekly.html#2011-06-09">weekly release notes</a>.
+For complete information, see the
+<a href="//code.google.com/p/go/source/list?r=release-branch.r58">Mercurial change list</a>.
+</p>
+
+<h3 id="r58.lang">Language</h3>
+
+<p>
+This release fixes a <a href="//golang.org/change/b720749486e1">use of uninitialized memory in programs that misuse <code>goto</code></a>.
+</p>
+
+<h3 id="r58.pkg">Packages</h3>
+
+<p>
+As usual, <a href="/cmd/gofix/">gofix</a> will handle the bulk of the rewrites
+necessary for these changes to package APIs.
+</p>
+
+<p>
+<a href="/pkg/http/">Package http</a> drops the <code>finalURL</code> return
+value from the <a href="/pkg/http/#Client.Get">Client.Get</a> method. The value
+is now available via the new <code>Request</code> field on <a
+href="/pkg/http/#Response">http.Response</a>.
+Most instances of the type map[string][]string in have been
+replaced with the new <a href="/pkg/http/#Values">Values</a> type.
+</p>
+
+<p>
+<a href="/pkg/exec/">Package exec</a> has been redesigned with a more
+convenient and succinct API.
+</p>
+
+<p>
+<a href="/pkg/strconv/">Package strconv</a>'s <a href="/pkg/strconv/#Quote">Quote</a>
+function now escapes only those Unicode code points not classified as printable
+by <a href="/pkg/unicode/#IsPrint">unicode.IsPrint</a>.
+Previously Quote would escape all non-ASCII characters.
+This also affects the <a href="/pkg/fmt/">fmt</a> package's <code>"%q"</code>
+formatting directive. The previous quoting behavior is still available via
+strconv's new <a href="/pkg/strconv/#QuoteToASCII">QuoteToASCII</a> function.
+</p>
+
+<p>
+<a href="/pkg/os/signal/">Package os/signal</a>'s
+<a href="/pkg/os/#Signal">Signal</a> and
+<a href="/pkg/os/#UnixSignal">UnixSignal</a> types have been moved to the
+<a href="/pkg/os/">os</a> package.
+</p>
+
+<p>
+<a href="/pkg/image/draw/">Package image/draw</a> is the new name for
+<code>exp/draw</code>. The GUI-related code from <code>exp/draw</code> is now
+located in the <a href="/pkg/exp/gui/">exp/gui</a> package.
+</p>
+
+<h3 id="r58.cmd">Tools</h3>
+
+<p>
+<a href="/cmd/goinstall/">Goinstall</a> now observes the GOPATH environment
+variable to build and install your own code and external libraries outside of
+the Go tree (and avoid writing Makefiles).
+</p>
+
+
+<h3 id="r58.minor">Minor revisions</h3>
+
+<p>r58.1 adds
+<a href="//golang.org/change/293c25943586">build</a> and
+<a href="//golang.org/change/bf17e96b6582">runtime</a>
+changes to make Go run on OS X 10.7 Lion.
+</p>
+
+<h2 id="r57">r57 (released 2011/05/03)</h2>
+
+<p>
+The r57 release corresponds to
+<code><a href="weekly.html#2011-04-27">weekly.2011-04-27</a></code>
+with additional bug fixes.
+This section highlights the most significant changes in this release.
+For a more detailed summary, see the
+<a href="weekly.html#2011-04-27">weekly release notes</a>.
+For complete information, see the
+<a href="//code.google.com/p/go/source/list?r=release-branch.r57">Mercurial change list</a>.
+</p>
+
+<p>The new <a href="/cmd/gofix">gofix</a> tool finds Go programs that use old APIs and rewrites them to use
+newer ones. After you update to a new Go release, gofix helps make the
+necessary changes to your programs. Gofix will handle the http, os, and syscall
+package changes described below, and we will update the program to keep up with
+future changes to the libraries.
+Gofix can’t
+handle all situations perfectly, so read and test the changes it makes before
+committing them.
+See <a href="//blog.golang.org/2011/04/introducing-gofix.html">the gofix blog post</a> for more
+information.</p>
+
+<h3 id="r57.lang">Language</h3>
+
+<p>
+<a href="/doc/go_spec.html#Receive_operator">Multiple assignment syntax</a> replaces the <code>closed</code> function.
+The syntax for channel
+receives allows an optional second assigned value, a boolean value
+indicating whether the channel is closed. This code:
+</p>
+
+<pre>
+ v := <-ch
+ if closed(ch) {
+ // channel is closed
+ }
+</pre>
+
+<p>should now be written as:</p>
+
+<pre>
+ v, ok := <-ch
+ if !ok {
+ // channel is closed
+ }
+</pre>
+
+<p><a href="/doc/go_spec.html#Label_scopes">Unused labels are now illegal</a>, just as unused local variables are.</p>
+
+<h3 id="r57.pkg">Packages</h3>
+
+<p>
+<a href="/pkg/gob/">Package gob</a> will now encode and decode values of types that implement the
+<a href="/pkg/gob/#GobEncoder">GobEncoder</a> and
+<a href="/pkg/gob/#GobDecoder">GobDecoder</a> interfaces. This allows types with unexported
+fields to transmit self-consistent descriptions; examples include
+<a href="/pkg/big/#Int.GobDecode">big.Int</a> and <a href="/pkg/big/#Rat.GobDecode">big.Rat</a>.
+</p>
+
+<p>
+<a href="/pkg/http/">Package http</a> has been redesigned.
+For clients, there are new
+<a href="/pkg/http/#Client">Client</a> and <a href="/pkg/http/#Transport">Transport</a>
+abstractions that give more control over HTTP details such as headers sent
+and redirections followed. These abstractions make it easy to implement
+custom clients that add functionality such as <a href="//code.google.com/p/goauth2/source/browse/oauth/oauth.go">OAuth2</a>.
+For servers, <a href="/pkg/http/#ResponseWriter">ResponseWriter</a>
+has dropped its non-essential methods.
+The Hijack and Flush methods are no longer required;
+code can test for them by checking whether a specific value implements
+<a href="/pkg/http/#Hijacker">Hijacker</a> or <a href="/pkg/http/#Flusher">Flusher</a>.
+The RemoteAddr and UsingTLS methods are replaced by <a href="/pkg/http/#Request">Request</a>'s
+RemoteAddr and TLS fields.
+The SetHeader method is replaced by a Header method;
+its result, of type <a href="/pkg/http/#Header">Header</a>,
+implements Set and other methods.
+</p>
+
+<p>
+<a href="/pkg/net/">Package net</a>
+drops the <code>laddr</code> argument from <a href="/pkg/net/#Conn.Dial">Dial</a>
+and drops the <code>cname</code> return value
+from <a href="/pkg/net/#LookupHost">LookupHost</a>.
+The implementation now uses <a href="/cmd/cgo/">cgo</a> to implement
+network name lookups using the C library getaddrinfo(3)
+function when possible. This ensures that Go and C programs
+resolve names the same way and also avoids the OS X
+application-level firewall.
+</p>
+
+<p>
+<a href="/pkg/os/">Package os</a>
+introduces simplified <a href="/pkg/os/#File.Open">Open</a>
+and <a href="/pkg/os/#File.Create">Create</a> functions.
+The original Open is now available as <a href="/pkg/os/#File.OpenFile">OpenFile</a>.
+The final three arguments to <a href="/pkg/os/#Process.StartProcess">StartProcess</a>
+have been replaced by a pointer to a <a href="/pkg/os/#ProcAttr">ProcAttr</a>.
+</p>
+
+<p>
+<a href="/pkg/reflect/">Package reflect</a> has been redesigned.
+<a href="/pkg/reflect/#Type">Type</a> is now an interface that implements
+all the possible type methods.
+Instead of a type switch on a Type <code>t</code>, switch on <code>t.Kind()</code>.
+<a href="/pkg/reflect/#Value">Value</a> is now a struct value that
+implements all the possible value methods.
+Instead of a type switch on a Value <code>v</code>, switch on <code>v.Kind()</code>.
+Typeof and NewValue are now called <a href="/pkg/reflect/#Type.TypeOf">TypeOf</a> and <a href="/pkg/reflect/#Value.ValueOf">ValueOf</a>
+To create a writable Value, use <code>New(t).Elem()</code> instead of <code>Zero(t)</code>.
+See <a href="//golang.org/change/843855f3c026">the change description</a>
+for the full details.
+The new API allows a more efficient implementation of Value
+that avoids many of the allocations required by the previous API.
+</p>
+
+<p>
+Remember that gofix will handle the bulk of the rewrites
+necessary for these changes to package APIs.
+</p>
+
+<h3 id="r57.cmd">Tools</h3>
+
+<p><a href="/cmd/gofix/">Gofix</a>, a new command, is described above.</p>
+
+<p>
+<a href="/cmd/gotest/">Gotest</a> is now a Go program instead of a shell script.
+The new <code>-test.short</code> flag in combination with package testing's Short function
+allows you to write tests that can be run in normal or “short” mode;
+all.bash runs tests in short mode to reduce installation time.
+The Makefiles know about the flag: use <code>make testshort</code>.
+</p>
+
+<p>
+The run-time support now implements CPU and memory profiling.
+Gotest's new
+<a href="/cmd/gotest/"><code>-test.cpuprofile</code> and
+<code>-test.memprofile</code> flags</a> make it easy to
+profile tests.
+To add profiling to your web server, see the <a href="/pkg/http/pprof/">http/pprof</a>
+documentation.
+For other uses, see the <a href="/pkg/runtime/pprof/">runtime/pprof</a> documentation.
+</p>
+
+<h3 id="r57.minor">Minor revisions</h3>
+
+<p>r57.1 fixes a <a href="//golang.org/change/ff2bc62726e7145eb2ecc1e0f076998e4a8f86f0">nil pointer dereference in http.FormFile</a>.</p>
+<p>r57.2 fixes a <a href="//golang.org/change/063b0ff67d8277df03c956208abc068076818dae">use of uninitialized memory in programs that misuse <code>goto</code></a>.</p>
+
+<h2 id="r56">r56 (released 2011/03/16)</h2>
+
+<p>
+The r56 release was the first stable release and corresponds to
+<code><a href="weekly.html#2011-03-07">weekly.2011-03-07.1</a></code>.
+The numbering starts at 56 because before this release,
+what we now consider weekly snapshots were called releases.
+</p>
diff --git a/doc/devel/weekly.html b/doc/devel/weekly.html
new file mode 100644
index 0000000..5a9c51e
--- /dev/null
+++ b/doc/devel/weekly.html
@@ -0,0 +1,6200 @@
+<!--{
+ "Title": "Weekly Snapshot History"
+}-->
+
+<p>This page summarizes the changes between tagged weekly snapshots of Go.
+Such snapshots are no longer created. This page remains as a historical reference only.</p>
+
+<p>For recent information, see the <a href="//golang.org/change">change log</a> and <a href="//groups.google.com/group/golang-dev/">development mailing list</a>.</p>
+
+<h2 id="2012-03-27">2012-03-27 (<a href="release.html#go1">Go 1</a>)</h2>
+
+<pre>
+* cmd/dist: fix detection of go1 version.
+* cmd/go: add missing error check (thanks Evan Shaw),
+ allow underscores in tool name (thanks Shenghou Ma),
+ bug fixes,
+ copy tag_test.go from goinstall,
+ explain versions better,
+ respect $GOBIN always,
+ update for go1 tag format.
+* cmd/godoc: canonicalize custom path redirects,
+ fix app engine version,
+ use virtual filesystem to implement -templates flag.
+* codewalk/sharemem.xml: fix references to files.
+* crypto/tls: don't select ECC ciphersuites with no mutual curve.
+* doc: add JSON-RPC: a tale of interfaces article (thanks Francisco Souza),
+ describe the Windows MSI installer as experimental,
+ link to Go Project Dashboard from package list,
+ update wiki tutorial templates and template discussion,
+ and many minor fixes.
+* exp/types: generalized GCImporter API.
+* go/build: cgoEnabled is not known to cmd/dist anymore (thanks Shenghou Ma),
+ fix import check.
+* godoc: make 'Overview' section collapsible.
+* misc/dist: many fixes and tweaks.
+* misc/emacs: fix indentation bug.
+* misc/goplay: fix error on IE8 (thanks Yasuhiro Matsumoto).
+* net: ignore ECONNABORTED from syscall.Accept (thanks Devon H. O'Dell).
+* os: add missing byte to FileMode buffer (thanks Stefan Nilsson).
+* path/filepath: convert drive letter to upper case in windows EvalSymlinks (thanks Alex Brainman),
+ correct comment in EvalSymlinks (thanks Alex Brainman),
+ use windows GetShortPathName api to force GetLongPathName to do its work (thanks Alex Brainman),
+ windows drive letter cannot be a digit (thanks Alex Brainman).
+* run.bash: compile the codewalks.
+* runtime: restore deadlock detection in the simplest case (thanks Rémy Oudompheng),
+ work around false negative in deadlock detection.
+* text/template: fix typo in package comment.
+* windows: installer fixes (thanks Joe Poirier).
+</pre>
+
+<h2 id="2012-03-22">2012-03-22 (Go 1 Release Candidate 2)</h2>
+
+<pre>
+As with last week's snapshot, this snapshot is another Go 1 release candidate.
+A notable change in this snapshot are Windows installer fixes.
+
+Changes in this snapshot:
+* 5l, 6l, 8l: fix stack split logic for stacks near default segment size.
+* archive/zip: move r.zip off disk, into reader_test.go.
+* build: catch API changes during build,
+ do more during windows build (thanks Alex Brainman),
+ lengthen timeout for the lengthy runtime test (thanks Shenghou Ma),
+ unset GOPATH before tests (thanks Shenghou Ma).
+* cmd/cgo: add support for function export for gccgo (thanks Rémy Oudompheng),
+ fix handling of errno for gccgo.
+* cmd/go: add -fno-common by default on Darwin (thanks Shenghou Ma),
+ don't add detail to errPrintedOutput,
+ fix directory->import path conversion,
+ make build errors more visible,
+ use .o, not .{5,6,8}, for gccgo created object files,
+ work around occasional ETXTBSY running cgo.
+* cmd/godoc: add toys, tour button to playground,
+ inform users that the playground doesn't work via local godoc,
+ style example headings like links,
+ use *goroot as base path in zip file,
+ use FormatText for formating code in html template,
+ use shorter titles for tabs.
+* cmd/gofmt: show ascii in usage (thanks Yasuhiro Matsumoto).
+* cmd/pack: also recognize '\\' as path separator in filenames (thanks Shenghou Ma).
+* crypto/tls: always send a Certificate message if one was requested.
+* doc/install: remove reference to "Go Tutorial" (thanks Shenghou Ma).
+* doc/play: use []rune instead of []int (thanks Yasuhiro Matsumoto).
+* doc: add Go Concurrency Patterns: Timing out, moving on article (thanks Francisco Souza),
+ add Go image/draw package article and convert code snippets to Go1,
+ add Gobs of data article (thanks Francisco Souza),
+ add Godoc: documenting Go code article (thanks Francisco Souza),
+ add JSON and Go article (thanks Francisco Souza),
+ general update of gccgo installation instructions,
+ minor updates to most docs.
+* flag: add examples.
+* gc: fix struct and array comparisons for new bool rules (thanks Anthony Martin),
+ use quoted string format in import error,
+ when expanding append inline, preserve arguments.
+* go/build: clarify why we exclude files starting with '_' or '.' (thanks Shenghou Ma),
+ clearer argument name for Import (src -> srcDir),
+ do not report Target for local imports,
+ fix match.
+* go/printer, gofmt: fix multi-line logic.
+* html/template: add Templates and XXXEscape functions,
+ fix nil pointer bug,
+ fix panic on Clone.
+* io/ioutil: fix crash when Stat fails.
+* make.bat: fix for old files (thanks Christopher Redden),
+ don't show error message if old generated files do not exist (thanks Shenghou Ma),
+ properly handle directories with spaces (thanks Alex Brainman).
+* misc/cgo/gmp: update for Go 1 (thanks Shenghou Ma).
+* misc/dashboard: remove old python package dashboard.
+* misc/dist: don't ship cmd/cov or cmd/prof,
+ force modes to 0755 or 0644 in tarballs,
+ remove exp and old before building.
+* misc/vim: restore fileencodings (thanks Yasuhiro Matsumoto).
+* net/http: couple more triv.go modernizations,
+ ensure triv.go compiles and runs (thanks Robert Hencke).
+* net: drop unnecessary type assertions and fix leak in test (thanks Mikio Hara).
+* os: IsNotExist() should also consider ERROR_PATH_NOT_FOUND on Windows (thanks Shenghou Ma),
+ do not assume syscall.Write will write everything,
+ remove document duplication in error predicate functions (thanks Shenghou Ma),
+ return some invented data from Stat(DevNull) on windows (thanks Alex Brainman).
+* path/filepath: implement Match and Glob on windows (thanks Alex Brainman).
+* reflect: document PkgPath, Method, StructField,
+ panic if MakeSlice is given bad len/cap arguments.
+* run.bat: disable test in test\bench\go1 to fix build (thanks Alex Brainman).
+* runtime/cgo: darwin signal masking (thanks Mikio Hara),
+ linux signal masking (thanks Mikio Hara).
+* runtime: do not handle signals before configuring handler,
+ manage stack by ourselves for badcallback on windows/amd64 (thanks Shenghou Ma),
+ remove unused goc2c.c (thanks Shenghou Ma).
+* sort: add time complexity to doc (thanks Stefan Nilsson),
+ fix computation of maxDepth to avoid infinite loop (thanks Stefan Nilsson).
+* spec: delete references to unsafe.Reflect,Typeof,Unreflect.
+* syscall: Test SCM_CREDENTIALS, SO_PASSCRED on Linux (thanks Albert Strasheim),
+ add a test for passing an fd over a unix socket,
+ delete passfd_test.go.
+* test: use testlib in a few more cases (thanks Shenghou Ma).
+* text/template: fix a couple of parse bugs around identifiers,
+ variables do not take arguments.
+</pre>
+
+<h2 id="2012-03-13">2012-03-13 (Go 1 Release Candidate 1)</h2>
+
+<pre>
+This weekly snapshot is very close to what we expect will be the contents of
+the Go 1 release. There are still a few minor documentation issues to resolve,
+and a handful of bugs that should be addressed before the release, but the vast
+majority of Go programs should be completely unaffected by any changes we make
+between now and the full release.
+
+If you're interested in helping us test, eager to try out Go 1, or just
+curious, this weekly snapshot is the one to try. We'll issue a new App Engine
+Go 1 beta SDK very soon, so if you're an App Engine user you can try it there
+too.
+
+To help us focus on any remaining bugs and avoid introducing new ones, we will
+restrict our attention to critical fixes and issues marked Go1-Must in the
+issue tracker. Everything non-essential will be held until after the Go 1
+release is cut and in the field for a while.
+
+Changes in this snapshot:
+* archive/zip: verify CRC32s in non-streamed files,
+ write data descriptor signature for OS X; fix bugs reading it.
+* build: build correct cmd/dist matching GOHOSTARCH (thanks Shenghou Ma),
+ re-enable some broken tests in run.bash (thanks Shenghou Ma),
+ remove some references to Make.inc etc.
+ use run.go for running tests.
+* builder: use short test for subrepos (thanks Shenghou Ma).
+* cgo, runtime: diagnose callback on non-Go thread.
+* cmd/api: set compiler for all build contexts,
+ work on Windows again, and make gccgo files work a bit more.
+* cmd/cgo: document CGO_LDFLAGS and CGO_CFLAGS,
+ silence const warnings.
+* cmd/dist, cmd/go: move CGO_ENABLED from 'go tool dist env' to 'go env' (thanks Shenghou Ma).
+* cmd/dist: fix build for Linux/ARM (thanks Shenghou Ma),
+ use correct hg tag for go version (thanks Alex Brainman).
+* cmd/fix: add rules for net/http -> net/http/httputil renames.
+* cmd/gc: allow ~ in import paths,
+ delete old map delete in walk,
+ do not confuse unexported methods of same name,
+ if $GOROOT_FINAL is set, rewrite file names in object files,
+ implement len(array) / cap(array) rule,
+ import path cannot start with slash on Windows (thanks Shenghou Ma),
+ must not inline panic, recover,
+ show duplicate key in error,
+ unnamed struct types can have methods.
+* cmd/go: add -compiler,
+ add env command, use to fix misc/cgo/testso,
+ allow go get with arbitrary URLs,
+ allow ssh tunnelled bzr, git and svn (thanks Ingo Oeser),
+ always provide .exe suffix on windows (thanks Shenghou Ma),
+ document import path meta tag discovery in go help remote,
+ honor buildflags in run, test (thanks Rémy Oudompheng),
+ local import fixes,
+ make go get new.code/... work,
+ rebuild external test package dependencies,
+ respect $GOBIN always,
+ support -compiler for go list, fix isStale for gccgo (thanks Rémy Oudompheng).
+* cmd/godoc: add support for serving templates.
+ fix codewalk handler (thanks Francisco Souza).
+ remove extra / in paths (thanks Ugorji Nwoke),
+ support $GOPATH, simplify file system code,
+ switch on +1 buttons.
+* cmd/gofmt: fix race in long test (thanks Mikio Hara).
+* codereview: fix for Mercurial 2.1.
+* crypto/x509: allow server gated crypto in windows systemVerify (thanks Mikkel Krautz),
+ do not forget to free cert context (thanks Alex Brainman),
+ don't include empty additional primes in PKCS#1 private key,
+ enforce path length constraint,
+ new home for root fetchers; build chains using Windows API (thanks Mikkel Krautz).
+* csv: clarify what a negative FieldsPerRecord means.
+* database/sql: add docs about connection state, pooling,
+ ensure Stmts are correctly closed (thanks Gwenael Treguier),
+ fix double connection free on Stmt.Query error,
+ fix typo bug resulting in double-Prepare.
+* database/sql: add ErrBadConn.
+* doc/go1: template packages have changed since r60.
+* doc/go_mem: init-created goroutine behavior changes for Go 1 (thanks Shenghou Ma).
+* doc/gopher: flip frontpage gopher's eyes.
+* doc: add "About the go command" article,
+ add C? Go? Cgo! article (thanks Francisco Souza),
+ add Go's declaration syntax article (thanks Francisco Souza),
+ add more gophers,
+ add note about import . to Go 1 compatibility notes,
+ several doc fixes and improvements,
+ update Effective Go init section,
+ update progs/run (thanks Shenghou Ma),
+ update reference gopher,
+ web site tweaks.
+* encoding/asn1: handle UTCTime before the year 2000.
+* encoding/binary: improve package comment (thanks Stefan Nilsson).
+* encoding/gob: fix memory corruption.
+* encoding/json: document that nil slice encodes as `null`.
+* exp/wingui: moved to code.google.com/p/gowingui.
+* expvar: add locking to String, and use RWMutex properly throughout,
+ add missing locking in String methods.
+* fmt, log: stop using unicode.
+* fmt: minor tweak of package doc to show headings in godoc (thanks Volker Dobler).
+* go/build, cmd/go: add support for .syso files.
+* go/build: add NoGoError,
+ add dependency test,
+ do not parse .syso files (thanks Alex Brainman).
+* go/parser: avoid endless loop in case of internal error,
+ better error synchronization.
+* go/printer, gofmt: nicer formatting of multi-line returns.
+* go/printer: example for Fprint.
+* go/scanner: better panic diagnostic.
+* go spec: no known implementation differences anymore,
+ fix inaccuracy in type identity definition.
+* io: better document WriterAt.
+* misc/dashboard: remove obsolete package builder code.
+* misc/dist: add source archive support,
+ add windows installer and zip support,
+ minimum target requirement is 10.6 for Darwin (thanks Shenghou Ma).
+* misc/emacs: fix extra indentation after comments that end with a period.
+* misc/xcode: example install of language spec for Xcode 4.x (thanks Emil Hessman).
+* net, net/rpc, reflect, time: document concurrency guarantees.
+* net/http: fix crash with Transport.CloseIdleConnections,
+ return appropriate errors from ReadRequest.
+* net: add skip message to test (thanks Mikio Hara),
+ disable use of external listen along with other external network uses,
+ do not use reflect for DNS messages (thanks Rémy Oudompheng),
+ document ReadMsgUnix, WriteMsgUnix,
+ fix TestDialTimeout on windows builder,
+ improve server and file tests (thanks Mikio Hara),
+ make Dial and Listen behavior consistent across over platforms (thanks Mikio Hara),
+ remove dependence on bytes, fmt, strconv,
+ silence another epoll print,
+ use IANA reserved port to test dial timeout (thanks Mikio Hara).
+* os: document FileInfo.Size as system-dependent for irregular files,
+ fix SameFile to work for directories on windows (thanks Alex Brainman).
+* path/filepath/path_test.go: repair and enable TestAbs.
+* path/filepath: disable AbsTest on windows,
+ retrieve real file name in windows EvalSymlinks (thanks Alex Brainman).
+* runtime/pprof: disable test on Leopard 64-bit.
+* runtime: add Compiler,
+ fix windows/amd64 exception handler (thanks Alex Brainman),
+ inline calls to notok,
+ move runtime.write back to C,
+ print error on receipt of signal on non-Go thread,
+ remove unused runtime·signame and runtime·newError,
+ try extending arena size in 32-bit allocator (thanks Rémy Oudompheng),
+ wait for main goroutine before setting GOMAXPROCS (thanks Rémy Oudompheng).
+* strconv: add table-based isPrint, remove dependence on bytes, unicode, and strings.
+* sync/atomic: disable store and load test on a single processor machine (thanks Mikio Hara).
+* syscall: fix mkall.sh, mksyscall_linux.pl, and regen for Linux/ARM (thanks Shenghou Ma).
+* test/run: use all available cores on ARM system (thanks Shenghou Ma).
+* test: actually run them on windows (thanks Alex Brainman),
+ add inherited interface test to ddd.go,
+ enable method expression tests in ddd.go,
+ invoke go command in run.go,
+ match gccgo error messages for bug388.go,
+ skip . files in directory.
+* testing: do not print 'no tests' when there are examples.
+* time: during short test, do not bother tickers take longer than expected (thanks Shenghou Ma),
+ mention receiver in Unix, UnixNano docs.
+* unicode/utf16: remove dependence on package unicode.
+* unicode/utf8: remove dependence on unicode.
+* windows: make background of gopher icon transparent (thanks Volker Dobler).
+</pre>
+
+<h2 id="2012-03-04">2012-03-04</h2>
+
+<pre>
+This snapshot includes a major re-design of the go/build package.
+Its FindTree, ScanDir, Tree, and DirInfo types have been replaced with the
+Import and Package types. There is no gofix. Code that uses go/build will need
+to be updated manually to use the package's new interface.
+
+Other changes:
+* 6a/6l: add IMUL3Q and SHLDL.
+* all: remove unused unexported functions and constants (thanks Rémy Oudompheng).
+* build: add GO_ prefix to LDFLAGS and GCFLAGS (thanks Gustavo Niemeyer).
+* cmd/cc: fix an out of bounds array access (thanks Anthony Martin),
+ grow some global arrays.
+* cmd/dist: force line-buffering stdout/stderr on Unix (thanks Shenghou Ma),
+ recognize CC="ccache clang" as clang.
+* cmd/go: avoid repeated include dirs (thanks Rémy Oudompheng),
+ fix -I flag for gc command (thanks Gustavo Niemeyer),
+ fix verbose command displaying (thanks Gustavo Niemeyer),
+ fixes for gccgo (thanks Rémy Oudompheng),
+ many fixes,
+ test -i should not disable -c (thanks Shenghou Ma).
+* cmd/vet: don't give error for Printf("%+5.2e", x) (thanks Shenghou Ma).
+* cmd/yacc/units.y: update comment, give better error messages when $GOROOT not set (thanks Shenghou Ma).
+* crypto/tls: force OS X target version to 10.6 for API compatibility (thanks Mikkel Krautz).
+* crypto/x509: fix typo in Verify documentation (thanks Mikkel Krautz).
+* dist: treat CC as one unit (thanks Scott Lawrence).
+* doc/go1: add justification discussions to major changes,
+ minor corrections and updates.
+* doc: describe API changes to go/build,
+ elaborate available checks for cmd/vet (thanks Shenghou Ma),
+ expand code.html to discuss the go tool in more depth,
+ instruct FreeBSD/Linux users to rm the old version first,
+ remove Go for C++ Programmers,
+ remove roadmap document,
+ remove tutorial,
+ update codelab/wiki to Go 1 (thanks Shenghou Ma),
+* encoding/gob: fix "// +build" comment for debug.go (thanks Shenghou Ma),
+ more hardening for lengths of input strings.
+* encoding/json: drop MarshalForHTML; gofix calls to Marshal,
+ escape output from Marshalers.
+* encoding/xml: fix anonymous field Unmarshal example (thanks Gustavo Niemeyer),
+ fix xml test tag usage (thanks Gustavo Niemeyer).
+* gc: disallow absolute import paths,
+ fix escape analysis + inlining + closure bug,
+ fix string comparisons for new bool rules (thanks Anthony Martin),
+ reject import paths containing special characters (thanks Anthony Martin).
+* go/ast: examples for ast.Print, ast.Inspect.
+* go/doc, godoc: fix range of type declarations.
+* go/parser: check import path restrictions,
+ expand test cases for bad import.
+* go/printer, gofmt: improved comment placement.
+* go/printer: fix printing of variadic function calls (thanks Anthony Martin),
+ fix test for new import path restrictions (thanks Anthony Martin),
+ replace multiline logic,
+ simpler exprList code, more tests.
+* godoc: add Examples link to top-level index,
+ bring back highlighting, selections, and alerts,
+ consistent placement of documentation sections,
+ don't show directories w/o packages in flat dir mode,
+ don't show testdata directories,
+ fix codewalks.
+* gotype: provide -comments flag.
+* html/template: make doctype check case-insensitive (thanks Scott Lawrence),
+ use correct method signature in introduction example (thanks Mike Rosset).
+* io: document that I/O is not necessarily safe for parallel access.
+* ld: allow more -L options (thanks Shenghou Ma),
+ fix alignment of rodata section.
+* misc: add zsh completion for go tool (thanks Rémy Oudompheng).
+* misc/bash: Completion for go tool (thanks Yissakhar Z. Beck).
+* misc/dashboard: fix bug in UI template,
+ record install counts for external packages.
+* misc/dist: implement binary distribution scripts in go.
+* misc/gobuilder: send commit time in RFC3339 format.
+* misc/xcode: move Xcode3 specific files into sub directory.
+* net/http/cgi: add an empty response test,
+ fix empty response.
+* net/http/httptest: make Server.Close wait for outstanding requests to finish.
+* net/http/httputil: fix DumpRequestOut on https URLs,
+ make https DumpRequestOut less racy.
+* net/http: add overlooked 418 status code, per RFC 2324,
+ fix ProxyFromEnvironment bug, docs, add tests,
+ make a test more paranoid & reliable on Windows.
+* net/rpc: silence read error on closing connection.
+* net: add stubs for NetBSD (thanks Benny Siegert),
+ make -external flag for tests default to true (thanks Mikio Hara),
+ reorganize test files (thanks Mikio Hara).
+* os: diagnose chdir error during StartProcess,
+ implement UserTime/SystemTime on windows (thanks Alex Brainman),
+ implement sameFile on windows (thanks Alex Brainman),
+ release process handle at the end of windows (*Process).Wait (thanks Alex Brainman),
+ sleep 5ms after process has exited on windows (thanks Alex Brainman).
+* path/filepath: note that SplitList is different from strings.Split,
+ steer people away from HasPrefix.
+* reflect: don't panic comparing functions in DeepEqual.
+ make Value.Interface return immutable data.
+* runtime/pprof: support OS X CPU profiling.
+* runtime: add sanity checks to the runtime-gdb.py prettyprinters,
+ check for ARM syscall failures (thanks Shenghou Ma),
+ darwin and linux signal masking,
+ run init on main thread,
+ size arena to fit in virtual address space limit.
+* spec: allow disallow of \uFFFD in import path,
+ apply method sets, embedding to all types, not just named types,
+ clarifications around exports, uniqueness of identifiers,
+ import path implementation restriction,
+ inside functions, variables must be evaluated,
+ use the term "lexical token" (rather then "lexical symbol").
+* sync: add Once example, remove old WaitGroup example.
+* test/bench/shootout: update post-Makefile.
+* test: add documentation, misc fixes.
+* testing: add -test.example flag to control execution of examples.
+* text/template: add example showing use of custom function,
+ add examples that use multiple templates,
+ fix redefinition bugs.
+* time: add a comment about how to use the Duration constants.
+</pre>
+
+<h2 id="2012-02-22">2012-02-22</h2>
+
+<pre>
+This weekly snapshot includes changes to the os and runtime packages.
+
+This should be the last of the significant incompatible changes before Go 1.
+
+There are no longer error constants such as EINVAL in the os package, since the
+set of values varied with the underlying operating system. There are new
+portable functions like IsPermission to test common error properties, plus a
+few new error values with more Go-like names, such as ErrPermission and
+ErrNoEnv.
+
+The os.Getenverror function has been removed. To distinguish between a
+non-existent environment variable and an empty string, use os.Environ or
+syscall.Getenv.
+
+The Process.Wait method has dropped its option argument and the associated
+constants are gone from the package. Also, the function Wait is gone; only the
+method of the Process type persists.
+
+The non-portable Waitmsg type has been replaced with the portable ProcessState.
+
+Much of the API exported by package runtime has been removed in favor of
+functionality provided by other packages. Code using the runtime.Type
+interface or its specific concrete type implementations should now use package
+reflect. Code using runtime.Semacquire or runtime.Semrelease should use
+channels or the abstractions in package sync.
+
+The runtime.Alloc, runtime.Free, and runtime.Lookup functions, an unsafe API
+created for debugging the memory allocator, have no replacement.
+
+The runtime.Cgocalls and runtime.Goroutines functions have been renamed to
+runtime.NumCgoCall and runtime.NumGoroutine.
+
+The "go fix" command will update code to accommodate most of these changes.
+
+Other changes:
+* 5c, 6c, 8c, 6g, 8g: correct boundary checking (thanks Shenghou Ma).
+* 5g, 6g, 8g: flush modified globals aggressively.
+* 8a, 8l: add EMMS instruction (thanks Evan Shaw).
+* bufio: don't return errors from good Peeks.
+* build: add make.bash --no-clean option,
+ improve Windows support.
+* builder: reuse existing workspace if possible (thanks Shenghou Ma),
+ update for os.Wait changes.
+* bytes: document Compare/Equal semantics for nil arguments, and add tests.
+* cgo: fix definition of opaque types (thanks Gustavo Niemeyer).
+* cmd/api: record return type of functions for variable typecheck (thanks Rémy Oudompheng).
+* cmd/cgo: bug fixes.
+* cmd/dist: add clang specific -Wno options (thanks Bobby Powers),
+ fix install cmd/5g on non-arm system,
+ fix pprof permissions (thanks Bobby Powers),
+ make dir check in defaulttarg() more robust (thanks Shenghou Ma),
+ use correct package target when cross-compiling (thanks Alex Brainman).
+* cmd/gc: correctly typecheck expression lists in returns (thanks Rémy Oudompheng),
+ don't believe that variables mentioned 256 times are unused (thanks Rémy Oudompheng),
+ error on constant shift overflows (thanks Rémy Oudompheng),
+ fix comparison of struct with _ field.
+ fix error for floating-point constant %,
+ new, less strict bool rules.
+* cmd/go: add tool -n flag,
+ go test -i correctly handle cgo packages (thanks Shenghou Ma).
+* codereview: fix submit message for new clone URL (thanks Shenghou Ma).
+* database/sql/driver: API cleanups.
+* doc: many fixes and adjustments.
+* encoding/gob: cache engine for user type, not base type,
+ catch internal error when it happens,
+ fix mutually recursive slices of structs.
+* encoding/json: ignore anonymous fields.
+* go/doc: return Examples in name order.
+* go/parser: imaginary constants and ! may start an expression.
+* go/printer, gofmt: improved comma placement.
+* go/printer: don't lose relevant parentheses when rewriting selector expressions.
+* godoc: adjust line height in pre blocks,
+ don't print spurious suggestion when running "go doc foo",
+ fix absolute->relative mapping,
+ fix tag mismatch validation errors (thanks Scott Lawrence),
+ import example code support,
+ support flat directory view again.
+* html/template: add Clone and AddParseTree,
+ don't indirect past a Stringer,
+ minor tweak to docs to improve HTML typography.
+* image: add Decode example.
+* ld: add NOPTRBSS for large, pointer-free uninitialized data.
+* math/rand: Intn etc. should panic if their argument is <= 0.
+* misc/dist/windows: distro builder updates (thanks Joe Poirier).
+* misc/goplay: remain in work directory, build in temp directory.
+* net, os, syscall: delete os.EPLAN9 (thanks Mikio Hara).
+* net/http: add optional Server.TLSConfig field.
+* net/smtp: use EHLO then HELO.
+* net/textproto: accept bad MIME headers as browsers do.
+* net/url: regularise receiver names.
+* net: make LocalAddr on multicast return group address (thanks Mikio Hara),
+ make parseProcNetIGMP more robust (thanks Mikio Hara),
+ more selfConnect debugging: panic if ra == nil in internetSocket,
+ panic if sockaddrToTCP returns nil incorrectly,
+ other miscellaneous fixes.
+* path, path/filepath: polish documentation (thanks Rémy Oudompheng).
+* pprof: add Profile type.
+* runtime: avoid malloc during malloc,
+ define NSIG to fix plan 9 build (thanks David du Colombier),
+ fix FreeBSD signal handling around thread creation (thanks Devon H. O'Dell),
+ goroutine profile, stack dumps,
+ implement runtime.osyield on FreeBSD 386, amd64 (thanks Devon H. O'Dell),
+ permit default behaviour of SIGTSTP, SIGTTIN, SIGTTOU,
+ release unused memory to the OS (thanks Sébastien Paolacci),
+ remove an obsolete file (thanks Mikio Hara).
+* spec: make all comparison results untyped bool,
+ refine the wording about variables in type switches,
+ struct comparison only compares non-blank fields.
+* syscall: Make Pdeathsig type Signal in SysProcAttr on Linux (thanks Albert Strasheim),
+ fix bounds check in Error,
+ force Windows to always use US English error messages (thanks Shenghou Ma).
+* test: migrated to new go-based testing framework.
+* text/template: evaluate function fields.
+* time: use Go distribution zoneinfo if system copy not found.
+</pre>
+
+<h2 id="2012-02-14">2012-02-14</h2>
+
+<pre>
+This release includes some package changes that require changes to client code.
+
+The flate, gzip and zlib's NewWriterXxx functions no longer return an error.
+The compiler will flag all affected code which must then be updated by hand.
+
+The os package's Exec and Time functions were removed. Callers should use
+syscall.Exec and time.Now instead. The ShellExpand function was renamed to
+ExpandEnv. The NewFile function now takes a uintptr and the *File.Fd method
+returns a uintptr.
+
+The runtime package's Type type and its methods have been removed.
+Use the reflect package instead.
+
+Other changes:
+* 8a, 8l: add LFENCE, MFENCE, SFENCE (thanks Darren Elwood).
+* all.bat: report error code back to the gobuilder (thanks Alex Brainman).
+* archive/zip: hide Write method from *Writer type.
+* build: create the correct $GOTOOLDIR,
+ get rid of deps.bash (thanks Anthony Martin),
+ reject make.bash on Windows.
+* builder: set $GOBUILDEXIT for Windows (thanks Alex Brainman),
+* bytes: add Reader,
+ return error in WriteTo if buffer is not drained.
+* cgo: add support for returning errno with gccgo (thanks Rémy Oudompheng).
+* cmd/api: follow constant references.
+* cmd/cgo: omit //line in -godefs, -cdefs output.
+* cmd/dist: fixes (thanks Alex Brainman, Gustavo Niemeyer, Mikio Hara, Shenghou Ma).
+* cmd/fix: warn about exp, old, deleted packages.
+* cmd/gc: suspend safemode during typecheck of inlined bodies.
+* cmd/go: a raft of fixes,
+ connect os.Stdin for go run and go tool,
+ go get scheme detection (thanks Daniel Krech),
+ respect test -timeout flag.
+* cmd/vet: warn for construct 'Println(os.Stderr, ...)' (thanks Shenghou Ma).
+* compress/gzip: remove dead code (thanks Alex Brainman).
+* container/heap: add example.
+* dashboard: add gobuilder -fail mode.
+* database/sql: more tests,
+ remove Into from ScannerInto/ScanInto,
+ rename ErrTransactionFinished to ErrTxDone,
+ support ErrSkip in Tx.Exec (thanks Andrew Balholm),
+ treat pointers as nullable types as with encoding/json (thanks Andrew Pritchard).
+* debug/macho: drop terrifyingly monstrous URL from package comment.
+* dist: prevent recusive loop on windows when fatal() is called (thanks Daniel Theophanes).
+* doc: add App Engine docs to 'learn' and 'reference' pages,
+ add playground.js,
+ new document about compatibility of releases,
+ update install.html for binary distros, add install-source.html.
+* effective_go: use new map deletion syntax.
+* encoding/binary: add Size, to replace the functionality of the old TotalSize,
+ another attempt to describe the type of Read and Write's data,
+ slices are allowed; say so.
+* encoding/json: document buffering.
+* encoding/xml: add support for the omitempty flag (thanks Gustavo Niemeyer).
+* exp/norm: merged charinfo and decomposition tables.
+* exp/types: use build.FindTree in GcImporter (thanks James Whitehead).
+* flate: delete WrongValueError type.
+* fmt: diagnose invalid verb applied to pointer,
+ scan FALSE correctly.
+* gc: bug fixes, better error messages.
+* go/doc: handle recursive embedded types (thanks Gary Burd),
+ don't lose exported consts/vars with unexported type,
+ treat predeclared error interface like an exported type.
+* go/printer: implement SourcePos mode.
+* godoc: list examples in index,
+ new design,
+ regard lone examples as "whole file" examples.
+* html/template: added more words about examples and doc (thanks Bjorn Tipling).
+* log/syslog: return length of data provided by the user, not length of header.
+* make.bat: remove double quotes (thanks Alex Brainman).
+* math: fix gamma doc, link to OEIS.
+* mime: unexport some internal details.
+* misc/dist: add binary distribution packaging script for linux,
+ new hierarchy for binary distribution packaging scripts.
+* net/http: add ServeContent,
+ don't spin on temporary accept failure,
+ fix client goroutine leak with persistent connections,
+ fix reference to URL.RawPath in docs (thanks Bjorn Tipling),
+ panic on duplicate registrations,
+ use mtime < t+1s to check for unmodified (thanks Hong Ruiqi).
+* net: avoid Shutdown during Close,
+ avoid TCP self-connect,
+ disable TestDialTimeout on Windows,
+ disable multicast test on Alpha GNU/Linux,
+ disable wild use of SO_REUSEPORT on BSD variants (thanks Mikio Hara),
+ enable flags on stream for multicast listeners (thanks Mikio Hara),
+ make use of listenerBacklog (thanks Mikio Hara),
+ prefer an IPv4 listen if no address given (thanks Mikio Hara).
+* os/exec: add Cmd.Waitmsg.
+* os/signal: revive this package.
+* regexp/syntax: add package and Parse commentary.
+* regexp: allow substitutions in Replace, ReplaceString.
+* runtime, pprof: add profiling of thread creation.
+* runtime, time: accelerate tests in short mode (thanks Rémy Oudompheng).
+* runtime: exit early on OABI systems (thanks Shenghou Ma),
+ drop to 32 bit malloc if 64 bit will not work,
+ fix "SysReserve returned unaligned address" bug on 32-bit systems (thanks Shenghou Ma),
+ fix grsec support (thanks Gustavo Niemeyer),
+ on 386, fix FP control word on all threads, not just initial thread,
+ put lockorder before pollorder in Select memory block,
+ use startpanic so that only one thread handles an incoming SIGQUIT.
+* spec: add forward links from 'method set' to where it gets used,
+ clarify implementation restrictions on untyped floats,
+ disallow recursive embedded interfaces,
+ method names must be unique,
+ send on closed channel counts as "proceeding",
+ strings are more slices than arrays.
+* strconv: handle very large inputs.
+* strings: add Seek and ReadAt methods to Reader.
+* sync/atomic: disable hammer pointer tests on wrong size system.
+* testing: let runtime catch the panic.
+* text/template: refer HTML users to html/template.
+* text/template/parse: deep Copy method for nodes.
+* time: clean up MarshalJSON, add RFC3339 method,
+ use "2006-01-02 15:04:05.999999999 -0700 MST" as String format.
+</pre>
+
+<h2 id="2012-02-07">2012-02-07</h2>
+
+<pre>
+This weekly snapshot includes a re-organization of the Go tools.
+
+Only the go, godoc, and gofmt tools are installed to $GOROOT/bin (or $GOBIN).
+The remainder are installed to $GOROOT/bin/tool.
+This puts the lesser-used tools (6g, cgo, govet, etc.) outside the user PATH.
+Instead these tools may be called through the go tool with 'go tool command'.
+For example, to vet hello.go you would type 'go tool vet hello.go'.
+Type 'go tool' see the list of available tools.
+
+With the move, some tools were given simpler names:
+ 6cov -> cov
+ 6nm -> nm
+ goapi -> api
+ gofix -> fix
+ gopack -> pack
+ gopprof -> pprof
+ govet -> vet
+ goyacc -> yacc
+
+The os/signal package has been moved to exp/signal.
+
+A new tool named 'dist' has been introduced to handle building the gc tool
+chain and to bootstrap the go tool. The old build scripts and make files
+have been removed.
+
+Other changes:
+* 5a, 6a, 8a, cc: check in y.tab.[ch].
+* 5l, 6l, 8l, ld: remove memory leaks (thanks Shenghou Ma).
+* 5l, 6l, 8l: implement -X flag.
+* 5l: make -v option output less nonessential clutter (thanks Shenghou Ma),
+ optimize the common case in patch() (thanks Shenghou Ma).
+* 8a, 8l: implement support for RDTSC instruction (thanks Shenghou Ma).
+* 8g: use uintptr for local pc.
+* archive/zip: support full range of FileMode flags (thanks Gustavo Niemeyer).
+* bufio: remove special error type, update docs.
+* build: move the "-c" flag into HOST_CFLAGS (thanks Anthony Martin),
+ remove unnecessary pragmas (thanks Anthony Martin).
+* builder: drop recover blocks.
+* bytes: API tweaks.
+* cgo: accept null pointers in gccgo flavour of C.GoString (thanks Rémy Oudompheng),
+ print line numbers in fatal errors when relevant (thanks Rémy Oudompheng).
+* cmd/dist: add GOBIN to env's output (thanks Gustavo Niemeyer),
+ fix bug in bsubst (thanks Alex Brainman),
+ fix build on openbsd (thanks Mikio Hara),
+ generate files for package runtime,
+ ignore file names beginning with . or _,
+ prevent race on VERSION creation (thanks Gustavo Niemeyer).
+* cmd/gc: another special (%hhS) case for method names,
+ describe debugging flags (thanks Anthony Martin),
+ diagnose \ in import path,
+ disallow switch _ := v.(type),
+ don't print implicit type on struct literal in export,
+ fix codegen reordering for expressions involving && and ||,
+ use octal escapes in mkopnames (thanks Anthony Martin).
+ use original constant expression in error messages (thanks Rémy Oudompheng).
+* cmd/go: add support for release tags via git branches (thanks Gustavo Niemeyer),
+ build: print import errors when invoked on files (thanks Kyle Lemons),
+ clean test directories as they complete,
+ fix error message on non-existing tools (thanks Rémy Oudompheng),
+ fix handling of gccgo standard library (thanks Rémy Oudompheng),
+ fixed panic on `go clean -n` and `go clean -x` (thanks Sanjay Menakuru),
+ introduce support for "go build" with gccgo (thanks Rémy Oudompheng),
+ make vcs command actually gather output (thanks Roger Peppe),
+ pass env CGO_CFLAGS to cgo (thanks Jeff Hodges),
+ record location of failed imports for error reporting (thanks Rémy Oudompheng).
+* cmd/goapi: expand embedded interfaces.
+* cmd/goinstall: remove now that 'go get' works (thanks Gustavo Niemeyer).
+* cmd/ld: fix gdbscript (thanks Wei Guangjing).
+* cmd/pack: change gopack to pack in error messages.
+* codereview: miscellaneous fixes and improvements.
+* crypto/elliptic: p224Contract could produce a non-minimal representation.
+* crypto/tls: better error message when connecting to SSLv3 servers.
+* crypto/x509: use case-insensitive hostname matching.
+* dashboard: support for sub-repositories, update to go1beta.
+* database/sql: permit scanning into interface{}.
+* doc: update go1.html for recent changes.
+* encoding/base32: add DecodeString and EncodeToString helper methods,
+ ignore new line characters during decode.
+* encoding/base64: ignore new line characters during decode.
+* encoding/gob: document CommonType.
+* encoding/hex: canonicalize error type names.
+* encoding/json: call (*T).MarshalJSON for addressable T values.
+* encoding/xml: fix decoding of xml.Name with sub-elements (thanks Gustavo Niemeyer),
+ fix documentation for Decoder.Skip.
+* exp/norm: Added some benchmarks for form-specific performance measurements,
+ a few minor changes in prepration for a table format change.
+* expvar: revise API.
+* fix: add image/{bmp,tiff} to go1pkgrename.
+* flag: allow a FlagSet to not write to os.Stderr,
+ describe valid input for Duration flags.
+* fmt: add test of NaN map keys,
+ fix caching bug in Scan.
+* go/build: put a space between 'generated by make' and package statement,
+ update syslist.go package comment.
+* go/doc: fix URL linking in ToHTML (thanks Gary Burd),
+ added error, rune to list of predeclared types,
+ don't lose factory functions of non-exported types,
+ don't show methods of exported anonymous fields,
+ enable AllMethods flag (and fix logic).
+* go/printer: don't print incorrect programs.
+* go/scanner: idiomatic receiver names.
+* go/spec: update language on map types.
+* go/token: remove dependency on encoding/gob.
+* gob: fuzz testing, plus a fix for very large type names.
+* gobuilder: use go tool to build and test sub-repositories.
+* godoc: add URL mode m=methods,
+ diagnostic for empty FS tree,
+ fix identifier search,
+ fix redirect loop for URL "/",
+ provide link to subdirectories, if any,
+ sort list of "other packages",
+ update metadata in appinit.go.
+* gophertool: fix link to the build status dashboard (thanks Jongmin Kim).
+* hgignore: add VERSION.cache (thanks Gustavo Niemeyer),
+ delete dregs, ignore tmpltohtml.
+* html: add package doc.
+* image: add package docs, rename s/UnknownFormatError/ErrFormat/ and,
+ delete the image.Repeated type,
+ remove image/bmp and image/tiff from std.
+* io/ioutil: document EOF behavior in ReadFile and ReadAll.
+* io: API tweaks.
+* libmach: add stubs for Plan 9 (thanks Anthony Martin).
+* make.bash: don't remove hgpatch.
+* math/big: add raw access to Int bits,
+ API and documentation cleanup.
+* misc/goplay: use go tool "run" (thanks Olivier Duperray).
+* misc/osx: don't set GOROOT or modify profile files,
+ update for dist tool, drop image.bash, update readme.
+* net, syscall: add IPv4 multicast helpers for windows (thanks Mikio Hara).
+* net/http/httputil: fix race in DumpRequestOut,
+ preserve query params in reverse proxy.
+* net/http: don't set Content-Type header for HEAD requests by default (thanks Patrick Mylund Nielsen),
+ fix nil pointer dereference in error case (thanks Volker Dobler),
+ close client fd sooner on response read error,
+ set cookies in client jar on POST requests (thanks Volker Dobler).
+* net/rpc: fix data race on Call.Error.
+* net: ListenMulticastUDP to listen concurrently across multiple listeners (thanks Mikio Hara),
+ disable normal multicast testing on linux/arm (thanks Mikio Hara),
+ fix Plan 9 build (thanks Anthony Martin),
+ fix windows build (thanks Alex Brainman),
+ move DNSConfigError to a portable file,
+ remove types InvalidConnError and UnknownSocketError,
+ replace error variable name e, errno with err (thanks Mikio Hara),
+ run TestDialTimeout on windows (thanks Alex Brainman),
+ update comments to remove redundant "net" prefix (thanks Mikio Hara).
+* os/exec: TestExtraFiles - close any leaked file descriptors,
+ make sure file is not closed early in leaked fd test.
+* os/signal: move to exp/signal.
+* os/user: windows implementation (thanks Alex Brainman).
+* os: Process.handle use syscall.Handle (thanks Wei Guangjing),
+ file windows use syscall.InvalidHandle instead of -1 (thanks Wei Guangjing),
+ remove SIGXXX signals variables,
+ turn FileStat.Sys into a method on FileInfo (thanks Gustavo Niemeyer).
+* path/filepath: repair and simplify the symlink test.
+* reflect: add comment about Type.Field allocation,
+ test that PtrTo returns types that match program types.
+* runtime: add runtime.cputicks() and seed fastrand with it (thanks Damian Gryski),
+ delete UpdateMemStats, replace with ReadMemStats(&stats) (thanks Rémy Oudompheng),
+ fix float64 hash,
+ use GOTRACEBACK to decide whether to show runtime frames,
+ use per-map hash seeds (thanks Damian Gryski).
+* spec: add number to the fibonacci sequence.
+* std: add struct field tags to untagged literals.
+* strings: add Fields example.
+* syscall: add Timeval.Nano, Timespec.Nano, for conversion to Duration,
+ cache environment variables on Plan 9 (thanks Anthony Martin),
+ fix // +build comments in types_*.go,
+ fix build directive in types_linux.go,
+ update bootstrap scripts to sync with new go command (thanks Mikio Hara).
+* test: add import test that caused an incorrect gccgo error,
+ add test for receiver named _,
+ add test of NaN in map,
+ add test which crashed gccgo compiler,
+ don't use package main for files without a main function,
+ fix bug headers,
+ float to integer test case,
+ make map nan timing test more robust,
+ match gccgo error messages,
+ test append with two different named types with same element type,
+ test method expressions with parameters, and with import,
+ test slice beyond len,
+ test that x := <-c accepts a general expression.
+* testing: capture panics, present them, and mark the test as a failure.
+* unicode: document large var blocks and the SpecialCase vars.
+* vet: add a check for untagged struct literals.
+</pre>
+
+<h2 id="2012-01-27">2012-01-27</h2>
+
+<pre>
+This weekly snapshot renamed the html package to exp/html. The package will not
+be present in the Go 1 distribution, but will be installable from source.
+
+Error variables in the archive/tar, archive/zip, compress/gzip, compress/zlib,
+and crypto/bcrypt packages have been renamed from FooError to ErrFoo.
+There is no gofix, but the compiler will flag code that needs updating.
+
+This weekly snapshot relocates many packages to sub-repositories of the main
+Go repository. These are the old and new import paths:
+
+ crypto/bcrypt code.google.com/p/go.crypto/bcrypt
+ crypto/blowfish code.google.com/p/go.crypto/blowfish
+ crypto/cast5 code.google.com/p/go.crypto/cast5
+ crypto/md4 code.google.com/p/go.crypto/md4
+ crypto/ocsp code.google.com/p/go.crypto/ocsp
+ crypto/openpgp code.google.com/p/go.crypto/openpgp
+ crypto/openpgp/armor code.google.com/p/go.crypto/openpgp/armor
+ crypto/openpgp/elgamal code.google.com/p/go.crypto/openpgp/elgamal
+ crypto/openpgp/errors code.google.com/p/go.crypto/openpgp/errors
+ crypto/openpgp/packet code.google.com/p/go.crypto/openpgp/packet
+ crypto/openpgp/s2k code.google.com/p/go.crypto/openpgp/s2k
+ crypto/ripemd160 code.google.com/p/go.crypto/ripemd160
+ crypto/twofish code.google.com/p/go.crypto/twofish
+ crypto/xtea code.google.com/p/go.crypto/xtea
+ exp/ssh code.google.com/p/go.crypto/ssh
+ net/dict code.google.com/p/go.net/dict
+ net/websocket code.google.com/p/go.net/websocket
+ exp/spdy code.google.com/p/go.net/spdy
+ encoding/git85 code.google.com/p/go.codereview/git85
+ patch code.google.com/p/go.codereview/patch
+
+Gofix will update imports of these packages to use the new import paths.
+Installations that depend on these packages will need to install them using a
+'go get' command.
+
+Other changes:
+* 6c, 8c: make floating point code NaN-safe.
+* 6l, 8l: remove unused macro definition (thanks Shenghou Ma).
+* archive/tar: fix race in TestNonSeekable.
+* archive/zip: add functions to convert between os.FileInfo & FileHeader.
+* build: do not build all C compilers (thanks Shenghou Ma),
+ remove code now in subrepositories.
+* bytes: remove dead code, complete documentation,
+ restore panic on out-of-memory,
+ turn buffer size overflows into errors.
+* cgo: -cdefs should translate unsafe.Pointer to void * (thanks Shenghou Ma).
+* cmd/gc: forgotten recursion on ninit itself in order.c.
+* cmd/go: bug fixes, implement go get,
+ correctly handle -n and -x flags for 'go run' (thanks Shenghou Ma),
+ solve ambiguity of get lp.net/project/foo (thanks Gustavo Niemeyer),
+ update doc.go with text generated from the usage strings.
+* cmd/goapi: new tool for tracking exported API over time.
+* codereview: support for subrepositories.
+* compress/flate: fix a typo, improve compression rate by 3-4%,
+ increase the length of hash table from 1<<15 to 1<<17. 0%-16% speedup,
+ make lazy matching work,
+ reduce memory pressure at cost of additional arithmetic operation,
+ use append instead of slice+counter.
+* crypto: rename some FooError to ErrFoo.
+* dashboard: fix -commit for new xml package.
+* database/sql: add NullInt64, NullFloat64, NullBool (thanks James P. Cooper),
+ convert SQL null values to []byte as nil (thanks James P. Cooper),
+ fix Tx.Query (thanks Blake Mizerany).
+* doc: expand FAQ on GOMAXPROCS, update to Go 1.
+* doc/go1: add encoding/xml and net/url changes (thanks Gustavo Niemeyer),
+ add more info about hash and net changes, delete reference to html,
+ add flag, runtime, testing, image , mime, filepath.Walk,
+ document sub-repositories.
+* encoding/binary: document that PutVarint, PutUvarint may panic.
+* encoding/varint: deleted WriteXvarint.
+* encoding/xml: add docs for ignoring tag (thanks Gustavo Niemeyer),
+ bring API closer to other packages (thanks Gustavo Niemeyer),
+ improve []byte handling (thanks Gustavo Niemeyer),
+ remove Marshaler support (thanks Gustavo Niemeyer),
+ support ignoring fields with "-" (thanks Gustavo Niemeyer).
+* exp/ebnflint: test spec during 'go test'.
+* exp/norm: fixes a subtle bug introduced by change 10087: random offset.
+* gc, runtime: handle floating point map keys.
+* gc: avoid DOT in error messages,
+ do not try to add a key with incorrect type to a hash (thanks Jeff R. Allen),
+ fix order of evaluation,
+ fix recursion loop in interface comparison,
+ handle function calls in arguments to builtin complex operations,
+ missed typecheck in subscripting a const string,
+ permit unsafe.Pointer for inlined functions,
+ softer criteria for inlinability,
+ static implements check on typeswitches only applies to concrete case types,
+ test case for recursive interface bug.
+* go/ast: respect ImportSpec.EndPos (thanks Scott Lawrence).
+* go/build: add BuildTags to Context, allow !tag.
+* go/doc: rewrite and add lots of tests.
+* go/parser: use explicit parser.Mode type.
+* go/printer, gofmt: respect line breaks in signatures.
+* go/scanner: use explicit scanner.Mode type.
+* gob: annotate debug.go so it's not normally built,
+ reduce the maximum message size.
+* godoc: log node printing error,
+ move overview before API TOC,
+ update metadata upon launch.
+* gofix: add -debug flag for quicker diagnosis of internal errors,
+ handle xml.Unmarshal in xmlapi fix (thanks Gustavo Niemeyer),
+ update go1pkgrename for subrepositories.
+* goyacc: fix indexing bug when yydebug >= 2.
+* ld: fix Mach-O code signing for non-cgo binaries (thanks Mikkel Krautz).
+* libmach: cross compiling support (thanks Shenghou Ma).
+* math/big: assembly versions of bitLen for x86-64, 386, and ARM (thanks David G. Andersen),
+ return type of bitLen is an int; use MOVL on amd64 (thanks David G. Andersen),
+ add examples for Rat and Int's SetString and Scan methods,
+ slight improvement to algorithm used for internal bitLen function (thanks David G. Andersen),
+ test both bitLen and bitLen_g.
+* net/http: add Request.RequestURI field,
+ disabled test for Transport race / deadlock bug,
+ fix Transport deadlock (thanks Yoshiyuki Kanno),
+ make ParseForm ignore unknown content types (thanks Roger Peppe),
+ parse CONNECT requests (thanks Andrew Balholm).
+* net/rpc: fix data race in benchmark,
+ fix race in TestClientWriteError test,
+ log Call reply discard.
+* net: Dial, ListenPacket with "ip:protocol" network for raw IP sockets (thanks Mikio Hara),
+ actually reset deadline when time is zero,
+ consistent OpError message (thanks Mikio Hara),
+ fix dialing google test (thanks Mikio Hara),
+ make WriteTo fail when UDPConn is already connected (thanks Mikio Hara).
+* regexp: remove vestigial Error type.
+* runtime: add type algorithms for zero-sized types,
+ move NumCPU declaration into debug.go.
+* spec: function invocation, panic on *nil.
+* syscall: add NOTE_* constants on OS X (thanks Robert Figueiredo).
+* test: explicitly use variables to avoid gccgo "not used" error.
+* text/template: add example for Template.
+</pre>
+
+<h2 id="2012-01-20">2012-01-20</h2>
+
+<pre>
+This weekly snapshot renamed the exp/sql package to database/sql, and moved
+utf8.String from unicode/utf8 to exp/utf8string.
+
+Package net's SetTimeout methods were changed to SetDeadline.
+
+Many functions in package os now take a os.FileMode argument instead of a
+plain uint32. An os.ModeSticky constant is also now defined.
+
+The meaning of the first buffer element for image.YCbCr has changed to match
+the semantics of the other image types like image.RGBA.
+
+The NewMD5, NewSHA1 and NewSHA256 functions in crypto/hmac have been
+deprecated. Use New instead, explicitly passing the hash function.
+
+Other changes:
+* buildscripts: move to buildscript directory (thanks Shenghou Ma).
+* bytes: add the usual copyright notice to example_test.go (thanks Olivier Duperray).
+* cmd/go: remove mentions of 'gotest' from the documentation,
+ skip _obj directories in package scans.
+* container/heap: better package documentation.
+* crypto/elliptic: add constant-time P224.
+* crypto/hmac: Add HMAC-SHA224 and HMAC-SHA384/512 (thanks Luit van Drongelen),
+* crypto/tls: add FreeBSD root certificate location (thanks Shenghou Ma).
+* crypto/x509: remove explicit uses of rsa.
+* doc: various updates (thanks Jongmin Kim, Scott Lawrence, Shenghou Ma, Stefan Nilsson).
+* encoding/json: allow / and % in tag names,
+ document angle bracket escaping,
+ fix comments, tweak tests for tag names (thanks Mikio Hara).
+* encoding/xml: marshal/unmarshal xml.Name in field (thanks Gustavo Niemeyer).
+* exp/inotify: fix data race in linux tests.
+* exp/proxy: fix build after URL changes (thanks Gustavo Niemeyer).
+* exp/sql: copy when scanning into []byte by default,
+ rename NullableString to NullString and allow its use as a parameter.
+* exp/ssh: add marshal functions for uint32 and uint64 types,
+ handle versions with just '\n',
+ rename (some) fields (thanks Christopher Wedgwood).
+* exp/terminal: fix build on non-Linux using Makefiles.
+* fmt: enable and fix malloc test,
+* gc: don't emit pkgpath for error type,
+ don't fault on return outside function (thanks Scott Lawrence),
+ fieldnames in structliterals in exported inlines should not be qualified if they're embedded builtin types,
+ fix infinite recursion for embedded interfaces,
+ give esc.c's sink an orig so -mm diagnostics work again,
+ handle printing of string/arrayrune conversions.
+ remove redundant code (thanks Shenghou Ma).
+* go/build: no back slash in FindTree returned pkg name (thanks Alex Brainman).
+* go/doc: collect imports,
+ don't shadow receiver.
+ rewrote and completed test framework.
+ print only one newline between paragraphs
+* go/parser: expressions may have comments.
+* go/scanner: fix example (thanks Olivier Duperray).
+* go/token: replaced Files() with Iterate().
+* godoc: add anchors to cmd documentation headings,
+ remove "need more packages?" link,
+ specify HTML page metadata with a JSON blob,
+ support canonical Paths in HTML metadata.
+* html/template: fix docs after API changes (thanks Gustavo Niemeyer).
+* html: in foreign content, check for HTML integration points in breakout.
+* image/color: rename modelYCbCr to yCbCrModel (thanks Benny Siegert),
+ simplify documentation (thanks David Crawshaw).
+* image: add PixOffset methods.
+* math/rand: decrease test duration in short mode,
+ document default initial seed for global generator (thanks Scott Lawrence).
+* mime: make FormatMediaType take full type for consistency.
+* misc/cgo/test: make tests run on windows (thanks Alex Brainman).
+* net/http/cgi: increase a flaky test timeout.
+* net/http: change test to use override param instead of chan,
+ log handler panic before closing HTTP connection,
+ send cookies in jar on redirect (thanks Jeff Hodges),
+ the documentation should call NewRequest with the right signature (thanks Christoph Hack),
+ update the Client docs a bit.
+* net/url: cleaned up URL interface (v2) (thanks Gustavo Niemeyer).
+* net: consistent log format in test (thanks Mikio Hara),
+ various build fixes (thanks Mikio Hara),
+ use NewTimer, not NewTicker, in fd_windows.go.
+* old/netchan: fix data race on client hashmap.
+* os/exec: trivial allocation removal in LookPath (thanks Gustavo Niemeyer).
+* os: remove old note about NewSyscallError being special (thanks Alex Brainman),
+* path: added examples (thanks Sanjay Menakuru).
+* pkg: Add and fix Copyright of "hand generated" files (thanks Olivier Duperray),
+ add missing godoc comments to windows versions (thanks Alex Brainman).
+* regexp: add SubexpNames.
+* runtime: implement runtime.usleep for FreeBSD/386 and amd64 (thanks Shenghou Ma),
+ madvise and SysUnused for Darwin (thanks Dave Cheney).
+* sync/atomic: fix data race in tests.
+* syscall: add Unix method to TimeSpec, TimeVal,
+ fix plan9 build (thanks Mikio Hara).
+* test: change several tests to not print,
+ fix bug364 to actually run,
+ match gccgo error messages for bug345,
+ split golden.out into expected output per test.
+* testing: do not recover example's panic (thanks Shenghou Ma),
+ document examples.
+* text/template/parse: use human error prints.
+* text/template: fix nil error on redefinition.
+* time: add Since, which returns the time elapsed since some past time t.
+</pre>
+
+<h2 id="2012-01-15">2012-01-15</h2>
+
+<pre>
+This weekly snapshot includes two package changes that may require changes to
+client code.
+
+The image package's Tiled type has been renamed to Repeated.
+
+The encoding/xml package has been changed to make more idiomatic use of struct
+tags, among other things. If you use the xml package please read the change
+description to see if your code is affected:
+ http://code.google.com/p/go/source/detail?r=70e914beb409
+
+Function inlining is now enabled by default in the gc compiler.
+
+Other changes:
+* bytes: Buffer read of 0 bytes at EOF shouldn't be an EOF.
+* cgo: if value for constant did not parse, get it from DWARF info,
+ write _cgo_export.h to object directory, not source dir.
+* cmd/go: add -p flag for parallelism (like make -j),
+ add -v flag to build and install,
+ add ... patterns in import path arguments,
+ fix data race during build,
+ fix import directory list for compilation,
+ fix linker arguments,
+ handle cgo pkg-config pragmas,
+ handle path to cmd directory,
+ include test files in fmt, vet, and fix (thanks Sanjay Menakuru),
+ kill test processes after 10 minutes,
+ pass arguments to command for run (thanks Eric Eisner),
+ rely on exit code to tell if test passed,
+ use relative paths in go fix, go fmt, go vet output.
+* cmd/gofmt: fix simplify.go by running gofmt on cmd/gofmt (thanks Olivier Duperray).
+* crypto/openpgp: assorted cleanups,
+ truncate hashes before checking DSA signatures.
+* crypto/tls: improve TLS Client Authentication (thanks Jeff R. Allen),
+ update generate_cert.go for new time package.
+* dashboard: better caching, bug fixes.
+* doc: update "How to Write Go Code" to use the go tool.
+ fix broken function codewalk examples.
+* encoding/asn1: document support for *big.Int (thanks Florian Weimer).
+* encoding/gob: fix panic when decoding []byte to incompatible slice types (thanks Alexey Borzenkov).
+* encoding/json: don't marshal special float values (thanks Evan Shaw).
+* encoding/xml: major Go 1 fixup (thanks Gustavo Niemeyer).
+* exp/proxy: new package.
+* exp/sql: add time.Time support,
+ close Rows on EOF,
+ fix potential corruption in QueryRow.Scan into a *[]byte.
+* exp/ssh: various small fixes (thanks Dave Cheney).
+* exp/terminal: add SetPrompt and handle large pastes,
+ add to level Makefile for the (non-Linux?) systems that need it.
+* flag: add Duration flag type,
+ change Set method Value interface to return error instead of bool.
+* gc: better errors messages,
+ avoid false positives when using scalar struct fields (thanks Rémy Oudompheng),
+ closure code gen improvements,
+ disallow declaration of variables outside package,
+ fix switch on interface values (thanks Rémy Oudompheng),
+ inlining bug fixes,
+ improve unsafe.Pointer type-check error messages (thanks Ryan Hitchman),
+ put limit on size of exported recursive interface (thanks Lorenzo Stoakes),
+* go-mode.el: fix syntax highlighting of backticks (thanks Florian Weimer).
+* go/ast: remove unnecessary result value from ast.Fprint/Print.
+* go/build: allow colon in #cgo flags,
+ pass CgoLDFLAGS at end of link command.
+* go/doc: new API, don't ignore anonymous non-exported fields, initial testing support.
+* go/parser: remove unused Parse* functions. Simplified ParseExpr signature.
+* go/printer: don't crash if AST contains BadXXX nodes.
+* go/scanner: 17% faster scanning, remove InsertSemis mode.
+* goinstall: use correct checkout URL for Google Code svn repos.
+* gotest: make _testmain.go conform to gofmt rules (thanks Benny Siegert).
+* goyacc: fix units.y build breakage (thanks Shenghou Ma).
+* html/template: reenable testcases and fix mis-escaped sequences (thanks Mike Samuel).
+* html: "in select in table" insertion mode (thanks Andrew Balholm),
+ adjust foreign attributes,
+ foreign element HTML integration points, tag name adjustment,
+ parse <frameset> inside body (thanks Andrew Balholm),
+ propagate foreign namespaces only when adding foreign content.
+* json: better error messages when the ,string option is misused.
+* ld: parse but do not implement -X flag.
+* log/syslog: add Alert method (thanks Vadim Vygonets).
+* make.bash: remove old dregs (thanks Alex Brainman).
+* math/big: simplify fast string conversion.
+* math: fix typo in all_test.go (thanks Charles L. Dorian).
+* misc/windows: add src/pkg/runtime/z* files to installation script (thanks Alex Brainman).
+* net/http: don't ignore Request.Write's Flush error,
+ allow cookies with negative Max-Age attribute as these are (thanks Volker Dobler).
+* net/textproto: avoid corruption when reading a single header.
+* net: add IP-level socket option helpers for Unix variants (thanks Mikio Hara),
+ fix incorrect mode on ListenIP, ListenUDP (thanks Mikio Hara),
+ make use of the kernel state to listen on TCP, Unix (thanks Mikio Hara),
+ platform-dependent default socket options (thanks Mikio Hara).
+* os: add ModeCharDevice.
+* runtime: add NumCPU,
+ delete duplicate implementation of pcln walker,
+ distinct panic message for call of nil func value,
+ enable runtime.ncpu on FreeBSD (thanks Devon H. O'Dell),
+ make garbage collector faster by deleting code,
+ regenerate defs_darwin_{386,amd64}.h (thanks Dave Cheney),
+ runtime.usleep() bugfix on darwin/amd64 and linux/arm (thanks Shenghou Ma).
+* spec: pointer comparison for pointers to 0-sized variables,
+ change the wording regarding select statement choice.
+* strconv: fix round up corner case,
+ faster FormatFloat(x, *, -1, 64) using Grisu3 algorithm (thanks Rémy Oudompheng),
+ implement fast path for rounding already short numbers (thanks Rémy Oudompheng),
+ return ErrSyntax when unquoting illegal octal sequences.
+* syscall: linux-only support for parent death signal (thanks Albert Strasheim),
+ make Environ return original order.
+* testing: fix defer race,
+ use flag.Duration for -timeout flag.
+* text/template: handle panic values that are not errors (thanks Rémy Oudompheng),
+ for range on a map, sort the keys if feasible.
+* time: add ParseDuration,
+ fix docs for After and NewTicker.
+* windows: use ArbitraryUserPointer as TLS slot (thanks Wei Guangjing).
+</pre>
+
+<h2 id="2011-12-22">2011-12-22</h2>
+
+<pre>
+This snapshot includes changes to the images/ycbcr and testing packages, and
+changes to the build system.
+
+The types for managing Y'CbCr images in the image/ycbcr have been moved to the
+image and image/color packages. A gofix module will rewrite affected code.
+
+The testing package's B type (used when running benchmarks) now has the same
+methods as T (used in tests), such as Print, Error, and Fatal.
+
+This weekly adds a new command named 'go' for building and testing go programs.
+For Go 1, the go command will replace the makefile-based approach that we have
+been using. It is not yet ready for general use, but all.bash does use it to
+build the tree. If you have problems building the weekly, you can 'export
+USE_GO_TOOL=false' before running all.bash to fall back to the makefiles.
+
+Other changes:
+* archive/zip: add SetModTime method to FileHeader.
+* build: make use of env (thanks Mikio Hara),
+ fixes to make "go install" work on windows (thanks Alex Brainman).
+* bytes: add two Buffer examples.
+* cgo: support export for built-in types (thanks Maxim Pimenov).
+* cmd/go: avoid infinite loop with package specific flags (thanks Mikio Hara),
+ fixes to build standard library,
+ implement test command,
+ make sure use of pthread for gcc-4.5 and beyond (thanks Mikio Hara),
+ respect $GCFLAGS,
+ use spaces consistently in help message (thanks Roger Peppe),
+ many other improvements.
+* codereview: initialize "found" in codereview.py (thanks Miki Tebeka).
+* crypto/mime/net/time: add netbsd to +build tags (thanks Joel Sing).
+* crypto/tls: don't assume an RSA private key in the API.
+* crypto/x509: don't crash with nil receiver in accessor method.
+* doc/effective_go: discuss redeclaration.
+* doc: delete go course notes,
+ refer to http://build.golang.org/ where applicable (thanks Robert Hencke),
+ suggest code.google.com/p/go instead of go.googlecode.com/hg.
+* encoding/binary: add Write and Read examples,
+ add more benchmarks (thanks Roger Peppe).
+* encoding/gob: arrays are zero only if their elements are zero.
+* encoding/json: cleanup leftover variables in array decoding (thanks Rémy Oudompheng),
+ examples for Marshal and Unmarshal.
+* exp/ssh: rename ClientAuthPublicKey helper ClientAuthKeyring (thanks Dave Cheney),
+ simplify Stdin/out/errPipe methods (thanks Dave Cheney).
+* fmt: speed up floating point print, clean up some code,
+ make the malloc test check its counts.
+* gc: allow use of unsafe.Pointer in generated code,
+ avoid unsafe in defn of package runtime,
+ better linenumbers for inlined functions,
+ better loopdepth analysis for labels,
+ implement and test \r in raw strings,
+ inlining, allow empty bodies, fix _ arguments,
+ omit argument names from function types in error messages.
+* go/ast, parser: remember short variable decls. w/ correspoding ident objects.
+* go/build: add new +build tags 'cgo' and 'nocgo'.
+* go/doc, godoc: move export filtering into go/doc
+* go/printer, gofmt: fine tuning of line spacing.
+* go/scanner: strip CRs from raw literals.
+* gob: isZero for struct values.
+* godoc: allow examples for methods (thanks Volker Dobler),
+ show methods of anonymous fields.
+* goinstall: only suggest -fix for bad imports when appropriate.
+* govet: add checking for printf verbs,
+ divide the program into one file per vetting suite.
+* html: more parser improvements (thanks Andrew Balholm).
+* json: some tests to demonstrate bad error messages,
+ use strconv.Append variants to avoid allocations in encoding.
+* ld: add support for netbsd signature note section (thanks Joel Sing),
+ allow for IMAGE_REL_AMD64_ADDR32NB relocation type (thanks Alex Brainman).
+* math/big: Rand shouldn't hang if argument is also receiver.
+* misc/builder: set default builder host to build.golang.org.
+* misc/dashboard: delete old build dashboard code ,
+ improvements and fixes for the go implementation.
+* misc/vim: fix go filetype detection (thanks Paul Sbarra).
+* net, syscall, os: set CLOEXEC flag on epoll/kqueue descriptor.
+* net, syscall: interface address and mask (thanks Mikio Hara).
+* net/http: added interface for a cookie jar (thanks Volker Dobler),
+ test fixes (thanks Alex Brainman).
+* net: add DialTimeout,
+ sort Makefile entries (thanks Mikio Hara).
+* os, syscall: beginnings of NetBSD support (thanks Christopher Nielsen).
+* os/exec: add test to verify net package's epoll fd doesn't go to child,
+ disable the ExtraFiles test on darwin.
+* os: don't trust O_CLOEXEC on OS X,
+ make sure Remove returns correct error on windows (thanks Alex Brainman).
+* path, path/filepath: add Dir to complement Base.
+* path/filepath.Rel: document that the returned path is always relative.
+* runtime: don't panic on SIGILL, just crash.
+* spec: be precise about newlines.
+* sql: add Rows.Columns.
+* strconv: fix bug in extended-float based conversion,
+ implement faster parsing of decimal numbers, and
+ reduce buffer size for multi-precision decimals (thanks Rémy Oudompheng).
+* syscall: regenerate z-files for linux/arm (thanks Mikio Hara),
+ sort Makefile, mkall.sh and mkerrors.sh entries (thanks Mikio Hara).
+* test/bench/go1: first draft of Go 1 benchmark suite.
+* testing: compare Log to Println (thanks Robert Hencke),
+ make signalling safer for parallel tests.
+* text/template: better error message for empty templates,
+ fix handing of nil arguments to functions (thanks Gustavo Niemeyer).
+* time: add JSON marshaler for Time (thanks Robert Hencke),
+ new AddDate method (thanks Roger Peppe).
+* various: use $GCFLAGS and $GCIMPORTS like Make does (thanks Maxim Pimenov).
+</pre>
+
+<h2 id="2011-12-14">2011-12-14</h2>
+
+<pre>
+This snapshot includes language changes and changes to goinstall and gofmt.
+
+Equality and inequality (== and !=) are now defined for struct and array
+values, respectively, provided the elements of the data structures can
+themselves be compared. See the Go 1 release notes for the details:
+ http://weekly.golang.org/doc/go1.html#equality
+
+The rune type is now an alias for int32 and character literals have the default
+type of rune. Code that uses int where it should use rune will break.
+See the Go 1 release notes for the details:
+ http://weekly.golang.org/doc/go1.html#rune
+
+Goinstall now expects Google Code import paths to be of the form:
+ "code.google.com/p/go-tour/tree"
+It will reject imports in the old style "go-tour.googlecode.com/hg/tree".
+There is a gofix module to rename such imports.
+Use goinstall -fix to update broken packages.
+
+Gofmt's flags have been modified slightly.
+The -tabintent flag has been renamed -tabs.
+The -spaces flag has been removed.
+
+Other changes:
+* 5c, 6c, 8c: support 64-bit switch value (thanks Anthony Martin).
+* 8c: handle 64-bit switch value.
+* archive/tar: use struct comparison not DeepEqual (thanks Christopher Wedgwood).
+* archive/zip: make zip understand os.FileMode (thanks Roger Peppe).
+* bufio: make the minimum read buffer size 16 bytes.
+* build: disable cgo on Windows/amd64,
+ regularize packages so they may be built without Makefiles.
+* bytes: faster Count, Index, Equal.
+* cgo: add basic gccgo support (thanks Rémy Oudompheng).
+* codereview: fix path slash issue (thanks Yasuhiro Matsumoto).
+* compress/flate: fix out of bounds error.
+* contribute.html: do not fill in the reviewer field (thanks Florian Weimer).
+* crypto/aes: made faster by eliminating some indirection (thanks Taru Karttunen).
+* crypto/dsa: don't truncate input hashes.
+* doc/go_tutorial: make clear the file example is Unix-specific.
+* doc: add Defer, Panic, and Recover article,
+ add Error Handling article,
+ add Go 1 release notes document.
+* encoding/gob: better error messages when types mismatch.
+* env.bash: export CGO_ENABLED so cgo tests run (thanks Alex Brainman).
+* exp/sql: simplify some string conversions.
+* exp/ssh: Wait returns an *ExitError (thanks Gustav Paul).
+* exp/ssh: improve client channel close behavior (thanks Dave Cheney).
+* fmt: don't recur if String method (etc.) misbehaves.
+* gc: better error messages,
+ inlining (disabled without -l),
+ many bug fixes (thanks Lucio De Re and Rémy Oudompheng).
+* go/printer, godoc: print comments in example code.
+* go: implement doc, fmt, fix, list, vet, build, and install.
+* gobuilder: goinstall packages after building go tree.
+* godoc: <pre> must not occur inside <p> (thanks Olivier Duperray),
+ added an opensearch description document (thanks Christoph Hack),
+ text wrapping.
+* gofix: add httputil fix (thanks Yasuhiro Matsumoto).
+* gotest: use go/build more (thanks Robert Hencke).
+* gzip: convert between Latin-1 and Unicode (thanks Vadim Vygonets).
+* html/template: define the FuncMap type locally.
+* html: a first step at parsing foreign content (MathML, SVG),
+ more parser improvements (thanks Andrew Balholm).
+* http: close connection after printing panic stack trace (thanks Roger Peppe),
+ fix failing Transport HEAD request with gzip-looking response.
+* json: treat renamed byte slices the same as []byte.
+* ld: first pass at linker support for NetBSD binaries (thanks Christopher Nielsen),
+ fix memory leaks (thanks Scott Lawrence),
+ increase default stack size on Windows for cgo.
+* math: delete non-Sqrt-based Hypot,
+ implement, document, and fix special cases (thanks Charles L. Dorian),
+* misc/benchcmp: don't require "Benchmark" at beginning of line.
+* misc/osx: rename profile.go to profile_go (thanks Scott Lawrence).
+* net/http: fix trivial example server (thanks Olivier Duperray),
+ net/http: make test remove temporary file and directory.
+* net/smtp: add CRAM-MD5 authentication (thanks Vadim Vygonets).
+* reflect: fix Slice cap (thanks Gustavo Niemeyer).
+* regexp: performance improvements; avoid allocation of input interface.
+* runtime: bump gc 'extra bytes' check (thanks Christopher Wedgwood),
+ madvise and SysUnused for Linux (thanks Sébastien Paolacci),
+ make gc_test test extra allocated space, not total space,
+ support for NetBSD (thanks Christopher Nielsen).
+* spec: adjust complex constant example (thanks Robert Hencke),
+ values of underlying type uintptr can be converted to unsafe.Pointer,
+ var x = 'a' defaults to type rune.
+* strconv: include package and function name in error strings,
+ make QuoteRune etc. take a rune argument,
+ some performance improvements.
+* syscall: add constants for flock() system call under Linux,
+ regenerate z-files for darwin, freebsd (thanks Mikio Hara),
+ regenerate z-files for openbsd,
+ return error, not uintptr, when function returns error (thanks Alex Brainman).
+* test/bench: move to test/bench/shootout.
+* test/garbage: move to test/bench/garbage.
+* test: make array smaller in nilptr test.
+* time: allow sleep tests to run for 200% too long,
+ fix Time.Add (thanks Hector Chu),
+ fix daysIn for December (thanks Peter Mundy),
+ gob marshaler for Time (thanks Robert Hencke),
+ use Duration for AfterFunc.
+* various: a grab-bag of time.Duration cleanups.
+</pre>
+
+<h2 id="2011-12-06">2011-12-06</h2>
+
+<pre>
+This snapshot includes a language change and changes to the strconv and go/doc
+packages. The package changes require changes to client code.
+The language change is backwards-compatible.
+
+Type elision in arrays, slices, or maps of composite literals has been
+extended to include pointers to composite literals. Code like this
+ var t = []*T{&T{}, &T{}}
+may now be written as
+ var t = []*T{{}, {}}
+You can use gofmt -s to simplify such code.
+
+The strconv package has been given a more idiomatic and efficient interface.
+Client code can be updated with gofix. See the docs for the details:
+ http://weekly.golang.org/pkg/strconv/
+
+The go/doc package's ToHTML function now takes a []byte argument instead of a
+string.
+
+Other changes:
+* crypto/aes: eliminate some bounds checking and truncation (thanks Rémy Oudompheng).
+* crypto/x509: if a parent cert has a raw subject, use it.
+* encoding/gob: don't send type info for unexported fields.
+* exp/ssh: allow for msgUserAuthBanner during authentication (thanks Gustav Paul).
+* fmt: benchmark floating point,
+ only use Stringer or Error for strings.
+* gc: changes in export format in preparation of inlining,
+ disallow map/func equality via interface comparison,
+ use gofmt spacing when printing map type.
+* go/doc: exclude lines ending in ':' from possible headings.
+* gobuilder: -commit mode for packages,
+ cripple -package mode temporarily,
+ use new dashboard protocol.
+* godoc: improved output of examples in html (thanks Volker Dobler).
+* gofmt: handle &T in composite literal simplify.
+* goinstall: honour -install=false flag when -make=true.
+* hash: rewrite comment on Hash.Sum method.
+* html: more parser improvements (thanks Andrew Balholm).
+* image: avoid func comparison during ColorModel comparison.
+* math: add special-cases comments to Sinh and Tanh (thanks Charles L. Dorian).
+* misc/dashboard: further implementation work.
+* net, syscall: remove BindToDevice from UDPConn, IPConn (thanks Mikio Hara).
+* net/mail: correctly compare parsed times in the test.
+* os/exec: make LookPath always search CWD under Windows (thanks Benny Siegert).
+* runtime: prep for type-specific algorithms.
+* strconv: 34% to 63% faster conversions.
+</pre>
+
+<h2 id="2011-12-02">2011-12-02</h2>
+
+<pre>
+This weekly snapshot includes changes to the hash package and a gofix for the
+time and os.FileInfo changes in the last snapshot.
+
+The hash.Hash's Sum method has been given a []byte argument,
+permitting the user to append the hash to an existing byte slice.
+Existing code that uses Sum can pass nil as the argument.
+Gofix will make this change automatically.
+
+Other changes:
+* crypto/tls: cleanup certificate load on windows (thanks Alex Brainman).
+* exp/ssh: add Std{in,out,err}Pipe methods to Session (thanks Dave Cheney).
+* dashboard: don't choke on weird builder names.
+* exp/ssh: export type signal, now Signal (thanks Gustav Paul).
+* os: add ModeType constant to mask file type bits (thanks Gustavo Niemeyer).
+* text/template: replace Add with AddParseTree.
+* go/doc: detect headings and format them in html (thanks Volker Dobler).
+</pre>
+
+<h2 id="2011-12-01">2011-12-01</h2>
+
+<pre>
+This weekly snapshot includes changes to the time, os, and text/template
+packages. The changes to the time and os packages are significant and related.
+Code that uses package time, package text/template, or package os's FileInfo
+type will require changes.
+
+In package time, there is now one type - time.Time - to represent times.
+Note that time.Time should be used as a value, in contrast to old code
+which typically used a *time.Time, a pointer to a large struct. (Drop the *.)
+Any function that previously accepted a *time.Time, an int64
+number of seconds since 1970, or an int64 number of nanoseconds
+since 1970 should now accept a time.Time. Especially as a replacement
+for the int64s, the type is good documentation about the meaning of
+its value.
+
+Whether you were previously calling time.Seconds, time.Nanoseconds,
+time.LocalTime, or time.UTC, the replacement is the new function
+time.Now.
+
+If you previously wrote code like:
+
+ t0 := time.Nanoseconds()
+ myFunction()
+ t1 := time.Nanoseconds()
+ delta := t1 - t0
+ fmt.Printf("That took %.2f seconds\n", float64(t1-t0)/1e9)
+
+you can now write:
+
+ t0 := time.Now()
+ myFunction()
+ t1 := time.Now()
+ delta := t1.Sub(t0)
+ fmt.Printf("That took %s\n", delta)
+
+In this snippet, the variable delta is of the new type time.Duration, the
+replacement for the many int64 parameters that were nanosecond
+counts (but not since 1970).
+
+Gofix can do the above conversions and some others, but it does not
+rewrite explicit int64 types as time.Time. It is very likely that you will
+need to edit your program to change these types after running gofix.
+As always, be sure to read the changes that gofix makes using your
+version control system's diff feature.
+
+See http://weekly.golang.org/pkg/time/ for details.
+
+In package os, the FileInfo struct is replaced by a FileInfo interface,
+admitting implementations by code beyond the operating system.
+Code that refers to *os.FileInfo (a pointer to the old struct) should
+instead refer to os.FileInfo (the new interface).
+The interface has just a few methods:
+
+ 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()
+ }
+
+If you need access to the underlying stat_t provided by the operating
+system kernel, you can access it by assuming that the FileInfo you are
+holding is actually an *os.FileStat, and that it's Sys field is actually a
+*syscall.Stat_t, as in:
+
+ dev := fi.(*os.FileStat).Sys.(*syscall.Stat_t).Dev
+
+Of course, this is not necessarily portable across different operating
+systems.
+
+Gofix will take care of rewriting *os.FileInfo to os.FileInfo for you,
+and it will also rewrite expressions like fi.Name into calls like fi.Name().
+
+See http://weekly.golang.org/pkg/os/#FileInfo for details.
+
+The template package has been changed to export a new, simpler API.
+The Set type is gone. Instead, templates are automatically associated by
+being parsed together; nested definitions implicitly create associations.
+Only associated templates can invoke one another.
+This approach dramatically reduces the breadth of the construction API.
+The html/template package has been updated also.
+There's a gofix for the simplest and most common uses of the old API.
+Code that doesn't mention the Set type is likely to work after running gofix;
+code that uses Set will need to be updated by hand.
+The template definition language itself is unchanged.
+
+See http://weekly.golang.org/pkg/text/template/ for details.
+
+
+Other changes:
+* cgo: add support for callbacks from dynamic libraries.
+* codereview: gofmt check for non-src/ files (thanks David Crawshaw).
+* crypto/openpgp/packet: fix private key checksum.
+* crypto/tls: add openbsd root certificate location,
+ don't rely on map iteration order.
+* crypto/x509, crypto/tls: support PKCS#8 private keys.
+* dashboard: start of reimplementation in Go for App Engine.
+* encoding/xml: fix copy bug.
+* exp/gui: move exp/gui and exp/gui/x11 to http://code.google.com/p/x-go-binding
+* exp/ssh: various improvements (thanks Dave Cheney and Gustav Paul).
+* filepath/path: fix Rel buffer sizing (thanks Gustavo Niemeyer).
+* gc: fix Nconv bug (thanks Rémy Oudompheng) and other fixes.
+* go/printer, gofmt: performance improvements.
+* gofix: test and fix missorted renames.
+* goinstall: add -fix flag to run gofix on packages on build failure,
+ better error reporting,
+ don't hit network unless a checkout or update is required,
+ support Google Code sub-repositories.
+* html: parser improvements (thanks Andrew Balholm).
+* http: fix sniffing bug causing short writes.
+* json: speed up encoding, caching reflect calls.
+* ld: align ELF data sections.
+* math/big: fix destination leak into result value (thanks Roger Peppe),
+ use recursive subdivision for significant speedup.
+* math: faster Cbrt and Sincos (thanks Charles L. Dorian).
+* misc/osx: scripts to make OS X package and disk image (thanks Scott Lawrence).
+* os: fail if Open("") is called on windows (thanks Alex Brainman).
+* runtime: make sure stack is 16-byte aligned on syscall (thanks Alex Brainman).
+* spec, gc: allow direct conversion between string and named []byte, []rune.
+* sql: add Tx.Stmt to use an existing prepared stmt in a transaction,
+ more driver docs & tests; no functional changes.
+* strings: add ContainsAny and ContainsRune (thanks Scott Lawrence).
+* syscall: add SUSv3 RLIMIT/RUSAGE constants (thanks Sébastien Paolacci),
+ fix openbsd sysctl hostname/domainname workaround,
+ implement Syscall15 (thanks Alex Brainman).
+* time: fix Timer stop.
+</pre>
+
+<h2 id="2011-11-18">2011-11-18</h2>
+
+<pre>
+This snapshot includes some language changes.
+
+Map and function value comparisons are now disallowed (except for comparison
+with nil) as per the Go 1 plan. Function equality was problematic in some
+contexts and map equality compares pointers, not the maps' content.
+
+As an experiment, structs are now allowed to be copied even if they contain
+unexported fields. This gives packages the ability to return opaque values in
+their APIs.
+
+Other changes:
+* 6a, 8a: allow $(-1) for consistency with $1, $(1), $-1.
+* 6l: code generation fixes (thanks Michał Derkacz).
+* build: fix check for selinux allow_execstack on Fedora (thanks Bobby Powers).
+* builtin: document delete.
+* cgo: don't panic on undeclared enums/structs (thanks Rémy Oudompheng),
+ fix g0 stack guard.
+* crypto/tls: fix handshake message test.
+* crypto: update incorrect references to Cipher interface; should be Block.
+* doc: clean ups, additions, and fixes to several documents.
+* doc/install: add openbsd (thanks Joel Sing!).
+* doc: link to Chinese translation of A Tour of Go.
+* encoding/json: add marshal/unmarshal benchmark,
+ decode [] as empty slice, not nil slice,
+ make BenchmarkSkipValue more consistent.
+* env.bash: check for presence of make/gmake (thanks Scott Lawrence).
+* exp/sql: NumInput() allow -1 to ignore checking (thanks Yasuhiro Matsumoto),
+ add DB.Close, fix bugs, remove Execer on Driver (only Conn),
+ document that for drivers, io.EOF means no more rows,
+ add client side support for publickey auth (thanks Dave Cheney),
+ add direct-tcpip client support (thanks Dave Cheney),
+ change test listen address, also exit test if fails,
+ other fixes and improvements (thanks Dave Cheney).
+* exp/terminal: rename shell to terminal and add SetSize.
+* fcgi: fix server capability discovery.
+* fmt: distinguish empty vs nil slice/map in %#v.
+* gc: better error, type checks, and many fixes,
+ remove m[k] = x, false syntax (use delete(m, k) instead),
+ support for building with Plan 9 yacc (thanks Anthony Martin).
+* go/printer: make //line formatting idempotent.
+* godefs: delete, replaced by cgo -godefs.
+* godoc: document -templates flag, fix remote search,
+ provide mode for flat (non-indented) directory listings.
+* gofmt: leave nil nodes of the AST unchanged (thanks Rémy Oudompheng).
+* html/template: indirect top-level values before printing.
+* html: more parser improvements (thanks Andrew Balholm).
+* http: fix serving from CWD with http.ServeFile,
+ make Dir("") equivalent to Dir(".").
+* ld: fix .bss for ldpe (thanks Wei Guangjing).
+* math/big: replace nat{} -> nat(nil).
+* math: faster Lgamma (thanks Charles L. Dorian).
+* mime: implement TypeByExtension for windows.
+* misc/bbedit: error and rune support (thanks Anthony Starks).
+* misc/benchcmp: benchmark comparison script.
+* misc/emacs: add delete builtin (thanks Bobby Powers).
+* misc/kate: add error and rune (thanks Evan Shaw).
+* misc/notepadplus: error and rune support (thanks Anthony Starks).
+* misc/windows: Windows installer in MSI format (thanks Joe Poirier).
+* net, io/ioutil: remove use of os.Time (thanks Anthony Martin).
+* net/http: fix EOF handling on response body (thanks Gustavo Niemeyer),
+ fix sniffing when using ReadFrom,
+ use t.Errorf from alternate goroutine in test.
+* os: remove undocumented Envs (use os.Environ instead).
+* reflect: empty slice/map is not DeepEqual to nil,
+ make Value an opaque struct.
+* runtime, syscall: convert from godefs to cgo.
+* runtime: add nanotime for Plan 9 (thanks Anthony Martin),
+ add timer support, use for package time,
+ avoid allocation for make([]T, 0).
+* strconv: add Ftoa benchmarks, make Ftoa faster.
+* syscall: delete syscall.Sleep, take over env implementation, use error.
+* testing: add file:line stamps to messages, print results to standard output.
+* text/template: refactor set parsing.
+* time: add ISOWeek method to Time (thanks Volker Dobler).
+* various: avoid func compare, reduce overuse of os.EINVAL + others.
+</pre>
+
+<h2 id="2011-11-09">2011-11-09</h2>
+
+<pre>
+This weekly snapshot renames various Go packages as described in the Go 1 plan.
+Import statements in client code can be updated automatically with gofix.
+
+The changes are:
+ asn1 -> encoding/asn1
+ big -> math/big
+ cmath -> math/cmplx
+ csv -> encoding/csv
+ exec -> os/exec
+ exp/template/html -> html/template
+ gob -> encoding/gob
+ http -> net/http
+ http/cgi -> net/http/cgi
+ http/fcgi -> net/http/fcgi
+ http/httptest -> net/http/httptest
+ http/pprof -> net/http/pprof
+ json -> encoding/json
+ mail -> net/mail
+ rpc -> net/rpc
+ rpc/jsonrpc -> net/rpc/jsonrpc
+ scanner -> text/scanner
+ smtp -> net/smtp
+ syslog -> log/syslog
+ tabwriter -> text/tabwriter
+ template -> text/template
+ template/parse -> text/template/parse
+ rand -> math/rand
+ url -> net/url
+ utf16 -> unicode/utf16
+ utf8 -> unicode/utf8
+ xml -> encoding/xml
+</pre>
+
+<h2 id="2011-11-08">2011-11-08</h2>
+
+<pre>
+This weekly snapshot includes some package changes.
+
+In preparation for the Go 1 package reorganziation the sources for various
+packages have been moved, but the import paths remain unchanged. This
+inconsistency breaks goinstall at this snapshot. If you use goinstall, please
+stay synced to the previous weekly snapshot until the next one is tagged.
+
+The Error methods in the html, bzip2, and sql packages that return error values
+have been renamed to Err.
+
+Some non-core parts of the http package have been moved to net/http/httputil.
+The Dump* and NewChunked* functions and ClientConn, ServerConn, and
+ReverseProxy types have been moved from http to httputil.
+
+The API for html/template is now a direct copy of the template API, instead of
+exposing a single Escape function. For HTML templates, use the
+html/template package as you would the template package.
+
+Other changes:
+* all: rename os.EOF to io.EOF in non-code contexts (thanks Vincent Vanackere),
+ sort imports with gofix.
+* archive/zip: close file opened with OpenReader (thanks Dmitry Chestnykh).
+* bufio: return nil line from ReadLine on error, as documented.
+* builtin: document basic types and the built-in error type.
+* bytes: add Contains function.
+* exp/sql: finish implementation of transactions, flesh out types, docs.
+* exp/ssh: improved client authentication support (thanks Dave Cheney).
+* gc: better error message for range over non-receive channel,
+ bug fixes and clean-ups,
+ detect type switch variable not used cases,
+ fix escaping of package paths in symbol names,
+ helpful error message on method call on pointer to pointer,
+ portably read archive headers (thanks Ron Minnich).
+* gob: fix bug when registering the same type multiple times.
+* gofix: avoid panic on body-less functions in netudpgroup,
+ make fix order implicit by date.
+* gofmt, gofix: sort imports.
+* goinstall: support launchpad.net/~user branches (thanks Jani Monoses).
+* gopack: do not look for Go metadata in non-Go objects.
+* gotest: don't run examples that have no expected output.
+* html: the parser bug fixing campaign continues (thanks Andrew Balholm).
+* http: fix whitespace handling in sniffer,
+ only recognize application/x-www-form-urlencoded in ParseForm,
+ support Trailers in ReadRequest.
+* lib9: add ctime.
+* math: faster Gamma (thanks Charles L. Dorian),
+ improved accuracy for Tan (thanks Charles L. Dorian),
+ improved high-angle test for Cos, Sin and Tan (thanks Charles L. Dorian).
+* net: implement LookupTXT for windows (thanks Alex Brainman).
+* os,text,unicode: renamings.
+* runtime/cgo: fix data declaration to be extern.
+* runtime: add timespec definition for freebsd,
+ add windows callback tests (thanks Alex Brainman),
+ fix prototype for openbsd thrsleep,
+ fix set and not used,
+ unify mutex code across OSes,
+ windows_386 sighandler to use correct g (thanks Alex Brainman).
+* template: format error with pointer receiver,
+ make redefinition of a template in a set more consistent.
+* test: clear execute bit from source file (thanks Mikio Hara),
+ make closedchan.go exit with failure if something fails.
+* time: faster Nanoseconds call.
+* websocket: return an error HTTP response for bad websocket request.
+* xml: allow parsing of <_> </_>. (thanks David Crawshaw).
+</pre>
+
+<h2 id="2011-11-02">2011-11-02 (new error type)</h2>
+
+<pre>
+This snapshot introduces the built-in error type, defined as
+
+ type error interface {
+ Error() string
+ }
+
+The error type replaces os.Error. Notice that the method name has changed from
+String to Error. Package fmt's Print formats both Stringers and errors:
+in general there is no need to implement both String and Error methods.
+
+Gofix can update most code. If you have split your package across many files,
+it may help to use the -force=error command-line option, which forces gofix to
+apply the error fix even if it is not obvious that a particular file needs it.
+As always, it is a good idea to read and test the changes that gofix made
+before committing them to your version control system.
+</pre>
+
+<h2 id="2011-11-01">2011-11-01</h2>
+
+<pre>
+* 6l: remove mention of -e flag - it does nothing.
+* cc: change cas to newcase (thanks Ron Minnich).
+* crypto/openpgp/error: use Error in names of error impl types.
+* crypto/rsa: change public exponent from 3 to 65537.
+* crypto/tls: add Error method to alert.
+* doc: add link to A Tour of Go in Japanese,
+ add 'all' make rule to build all docs,
+ refer to tour.golang.org instead of go-tour.appspot.com.
+* exp/norm: fixed bug that crept in with moving to the new regexp.
+* exp/ssh: fix length header leaking into channel data (thanks Dave Cheney).
+* fmt: handle os.Error values explicity (as distinct from Stringer).
+* gc: clean up printing,
+ fix [568]g -V crash (thanks Mikio Hara),
+ test + fix escape analysis bug.
+* go/build: avoid os.Error in tests.
+* go/doc: remove os.NewError anti-heuristic.
+* go/parser: test and fix := scoping bug.
+* gob: split uses of gobError, remove unnecessary embedding.
+* gofix: test import insertion, deletion.
+* goinstall: intelligent vcs selection for common sites (thanks Julian Phillips).
+* gopack: change archive file name length back to 16.
+* html: fix print argument in test,
+ more parser improvements (thanks Andrew Balholm).
+* json: properly handle nil slices (thanks Alexander Reece).
+* math: improved accuracy for Sin and Cos (thanks Charles L. Dorian).
+* misc/emacs: fix restoration of windows after gofmt (thanks Jan Newmarch).
+* misc/vim: add rune keyword (thanks Jongmin Kim).
+* misc/windows: can be used for amd64 (thanks Alex Brainman).
+* net: document why we do not use SO_REUSEADDR on windows (thanks Alex Brainman).
+* os: do not interpret 0-length read as EOF.
+* pkg: remove .String() from some print arguments.
+* rpc: avoid infinite loop on input error.
+* runtime/pprof: document OS X being broken.
+* runtime: lock the main goroutine to the main OS thread during init.
+* spec: define that initialization is sequential.
+* strconv: use better errors than os.EINVAL, os.ERANGE.
+* syscall: fix Await msg on Plan 9 (thanks Andrey Mirtchovski).
+* template: do not use error as stringer,
+ fix error checking on execute without parse (thanks Scott Lawrence).
+* test/alias.go: additional tests.
+* test: error-related fixes.
+* textproto: prevent long lines in HTTP headers from causing HTTP 400 responses.
+* time: add RFC1123 with numeric timezone format (thanks Scott Lawrence).
+</pre>
+
+<h2 id="2011-10-26">2011-10-26 (new rune type)</h2>
+
+<pre>
+This snapshot introduces the rune type, an alias for int that
+should be used for Unicode code points.
+
+A future release of Go (after Go 1) will change rune to be an
+alias for int32 instead of int. Using rune consistently is the way
+to make your code build both before and after this change.
+
+To test your code for rune safety, you can rebuild the Go tree with
+
+ GOEXPERIMENT=rune32 ./all.bash
+
+which builds a compiler in which rune is an alias for int32 instead of int.
+
+Also, run govet on your code to identify methods that might need to have their
+signatures updated.
+</pre>
+
+<h2 id="2011-10-25">2011-10-25</h2>
+
+<pre>
+* big: make SetString return nil if an error occurs,
+ new Rat.Inv method,
+ usable zero Rat values without need for explicit initialization.
+* codereview: show LGTMs in hg p.
+* crypto/x509: fix names in certificate generation.
+* exp/ssh: add experimental ssh client,
+ introduce Session to replace Cmd for interactive commands,
+ server cleanups (thanks Dave Cheney).
+* exp/types: fix crash in parseBasicType on unknown type.
+* fmt: don't panic formatting nil interfaces (thanks Gustavo Niemeyer).
+* go/ast, go/token: actually run tests; fix go/ast test.
+* gotest: explicit -help flag, use $GCFLAGS like make does.
+* govet: check canonical dynamic method signatures.
+* html: improved parsing (thanks Andrew Balholm),
+ parse <select> tags, parse and render comment nodes,
+ remove the Tokenizer.ReturnComments option.
+* http: Transport: with TLS InsecureSkipVerify, skip hostname check.
+* misc/vim: add highlighting for delete (thanks Dave Cheney).
+* net: do not set SO_REUSEADDR for windows (thanks Alex Brainman).
+* os/inotify: move to exp/inotify (thanks Mikio Hara).
+* runtime: include bootstrap m in mcpu accounting (thanks Hector Chu).
+* syscall: use uintptr for Mount flags.
+</pre>
+
+<h2 id="2011-10-18">2011-10-18</h2>
+
+<pre>
+This weekly snapshot includes some language and package changes that may
+require code changes. Please read these notes carefully, as there are many
+changes and your code will likely be affected.
+
+The syntax for map deletion has been changed. Code that looks like:
+ m[x] = 0, false
+should be written as:
+ delete(m, x)
+The compiler still accepts m[x] = 0, false for now; even so, you can use gofix
+to rewrite such assignments into delete(m, x).
+
+The Go compiler will reject a return statement without arguments when any of
+the result variables has been shadowed. Code rejected as a result of this
+change is likely to be buggy.
+
+Receive-only channels (<-chan T) cannot be closed.
+The compiler will diagnose such attempts.
+
+The first element of a map iteration is chosen at random. Code that depends on
+iteration order will need to be updated.
+
+Goroutines may be run during program initialization.
+
+A string may be appended to a byte slice. This code is now legal:
+ var b []byte
+ var s string
+ b = append(b, s...)
+
+The gotry command and its associated try package have been deleted.
+It was a fun experiment that - in the end - didn't carry its weight.
+
+The gotype tool has been moved to exp/gotype and its associated go/types
+package has been moved to exp/types. The deprecated go/typechecker package has
+been deleted.
+
+The enbflint tool has been moved to pkg/exp/ebnflint and its associated ebnf
+package has been moved to pkg/exp/ebnf.
+
+The netchan package has been moved to old/netchan.
+
+The http/spdy package has been moved to exp/spdy.
+
+The exp/datafmt package has been deleted.
+
+The container/vector package has been deleted. Slices are better:
+ http://code.google.com/p/go-wiki/wiki/SliceTricks
+
+Other changes:
+* 5l/6l/8l: correct ELFRESERVE diagnostic (thanks Anthony Martin).
+* 6l/8l: support OS X code signing (thanks Mikkel Krautz).
+* asn1: accept UTF8 strings as ASN.1 ANY values.
+* big: handle aliasing correctly for Rat.SetFrac.
+* build: add missing nuke target (thanks Anthony Martin),
+ catch future accidental dependencies to exp or old packages,
+ more robustly detect gold 2.20 (thanks Christopher Wedgwood),
+ pass $GCFLAGS to compiler,
+ stop on failed deps.bash.
+* crypto/tls: add 3DES ciphersuites,
+ add server side SNI support,
+ fetch root CA from Windows store (thanks Mikkel Krautz),
+ fetch root certificates using Mac OS API (thanks Mikkel Krautz),
+ fix broken looping code in windows root CA fetcher (thanks Mikkel Krautz),
+ more Unix root certificate locations.
+* crypto/x509: add code for dealing with PKIX public keys,
+ keep the raw Subject and Issuer.
+* csv: fix overly aggressive TrimLeadingSpace.
+* exp/ssh: general cleanups for client support (thanks Dave Cheney).
+* exp/template/html: fix bug in cssEscaper.
+* exp/terminal: split terminal handling from exp/ssh.
+* exp/winfsnotify: filesystem watcher for Windows (thanks Hector Chu).
+* fmt: fix test relying on map iteration order.
+* gc: changes to export format in preparation for inlining,
+ pass FlagNoPointers to runtime.new,
+ preserve uint8 and byte distinction in errors and import data,
+ stricter multiple assignment + test,
+ treat uintptr as potentially containing a pointer.
+* go/scanner: remove AllowIllegalChars mode.
+* go/token: document deserialization property.
+* gob: avoid one copy for every message written.
+* godefs: add enum/const testdata (thanks Dave Cheney).
+* godoc: generate package toc in template, not in JavaScript,
+ show "unexported" declarations when executing "godoc builtin",
+ show correct source name with -path.
+* gofix: make fix order explicit, add mapdelete.
+* gofmt: fix //line handling,
+ disallow rewrites for incomplete programs.
+* gotest: avoid conflicts with the name of the tested package (thanks Esko Luontola),
+ test example code.
+* goyacc: clean up after units (thanks Anthony Martin),
+ make more gofmt-compliant.
+* html: add a Render function, various bug fixes and improvements,
+ parser improvements (thanks Andrew Balholm).
+* http: DoS protection: cap non-Handler Request.Body reads,
+ RoundTrippers shouldn't mutate Request,
+ avoid panic caused by nil URL (thanks Anthony Martin),
+ fix read timeouts and closing,
+ remove Request.RawURL.
+* image/tiff: implement PackBits decoding (thanks Benny Siegert).
+* ld: fix "cannot create 8.out.exe" (thanks Jaroslavas Počepko).
+* misc/emacs: add a "godoc" command, like M-x man (thanks Evan Martin).
+* misc/swig: delete binaries (thanks Anthony Martin).
+* misc/windows: automated toolchain packager (thanks Joe Poirier).
+* net/windows: implement ip protocol name to number resolver (thanks Alex Brainman).
+* net: add File method to IPConn (thanks Mikio Hara),
+ allow LookupSRV on non-standard DNS names,
+ fix "unexpected socket family" error from WriteToUDP (thanks Albert Strasheim),
+ fix socket leak in case of Dial failure (thanks Chris Farmiloe),
+ remove duplicate error information in Dial (thanks Andrey Mirtchovski),
+ return error from CloseRead and CloseWrite (thanks Albert Strasheim),
+ skip ICMP test on Windows too unless uid 0.
+* reflect: disallow Interface method on Value obtained via unexported name,
+ make unsafe use of SliceHeader gc-friendly.
+* rpc: don't panic on write error.
+* runtime: faster strings,
+ fix crash if user sets MemProfileRate=0,
+ fix crash when returning from syscall during gc (thanks Hector Chu),
+ fix memory leak in parallel garbage collector.
+* scanner: invalidate scanner.Position when no token is present.
+* spec: define order of multiple assignment.
+* syscall/windows: dll function load and calling changes (thanks Alex Brainman).
+* syscall: add #ifdefs to fix the manual corrections in ztypes_linux_arm.go (thanks Dave Cheney),
+ adjust Mount to accommodate stricter FS implementations.
+* testing: fix time reported for failing tests.
+* utf8: add Valid and ValidString.
+* websocket: tweak hybi ReadHandshake to support Firefox (thanks Luca Greco).
+* xml: match Marshal's XMLName behavior in Unmarshal (thanks Chris Farmiloe).
+</pre>
+
+<h2 id="2011-10-06">2011-10-06</h2>
+
+<pre>
+This weekly snapshot includes changes to the io, image, and math packages that
+may require changes to client code.
+
+The io package's Copyn function has been renamed to CopyN.
+
+The math package's Fabs, Fdim, Fmax, Fmin and Fmod functions
+have been renamed to Abs, Dim, Max, Min, and Mod.
+
+Parts of the image package have been moved to the new image/color package.
+The spin-off renames some types. The new names are simply better:
+ image.Color -> color.Color
+ image.ColorModel -> color.Model
+ image.ColorModelFunc -> color.ModelFunc
+ image.PalettedColorModel -> color.Palette
+ image.RGBAColor -> color.RGBA
+ image.RGBAColorModel -> color.RGBAModel
+ image.RGBA64Color -> color.RGBA64
+ image.RGBA64ColorModel -> color.RGBA64Model
+(similarly for NRGBAColor, GrayColorModel, etc)
+The image.ColorImage type stays in the image package, but is renamed:
+ image.ColorImage -> image.Uniform
+The image.Image implementations (image.RGBA, image.RGBA64, image.NRGBA,
+image.Alpha, etc) do not change their name, and gain a nice symmetry:
+an image.RGBA is an image of color.RGBA, etc.
+The image.Black, image.Opaque uniform images remain unchanged (although their
+type is renamed from image.ColorImage to image.Uniform).
+The corresponding color types (color.Black, color.Opaque, etc) are new.
+Nothing in the image/ycbcr is renamed yet. The ycbcr.YCbCrColor and
+ycbcr.YCbCrImage types will eventually migrate to color.YCbCr and image.YCbCr,
+at a later date.
+
+* 5g/6g/8g: fix loop finding bug, fix -f(), registerize variables again.
+* 5l/6l/8l: add a DT_DEBUG dynamic tag to a dynamic ELF binary.
+* archive/zip: read and write unix file modes (thanks Gustavo Niemeyer).
+* build: clear execute bit from source files (thanks Mikio Hara).
+* bytes: add EqualFold.
+* cgo: allow Windows path characters in flag directives (thanks Joe Poirier),
+ support for mingw-w64 4.5.1 and newer (thanks Wei Guangjing).
+* codereview: extra repo sanity check,
+ fix for Mercurial 1.9.2,
+ fix hg change in Windows console (thanks Yasuhiro Matsumoto).
+* crypto/elliptic: use %x consistently in error print.
+* doc/spec: remove notes about gccgo limitations, now fixed.
+* doc: add 'Debugging Go code with GDB' tutorial,
+ fix memory model read visibility bug.
+* encoding/binary: PutX functions require buffer of sufficient size,
+ added benchmarks, support for varint encoding.
+* exec: add Command.ExtraFiles.
+* exp/sql{,/driver}: new database packages.
+* exp/ssh: move common code to common.go (thanks Dave Cheney).
+* exp/template/html: work continues.
+* fmt: replace channel cache with slice.
+* gc: limit helper threads based on ncpu.
+* go/doc, godoc, gotest: support for reading example documentation.
+* go: documentation and skeleton implementation of new command.
+* gob: protect against invalid message length,
+ allow sequential decoders on the same input stream.
+* hgpatch: do not use hg exit status (thanks Yasuhiro Matsumoto).
+* http: add Location method to Response,
+ don't send a 400 Bad Request after a client shutdown.
+* index/suffixarray: 4.5x faster index serialization (to memory).
+* io/ioutil: add a comment on why devNull is a ReaderFrom.
+* json: use strings.EqualFold instead of strings.ToLower.
+* misc/emacs: fix indent bug.
+* net: add shutdown: TCPConn.CloseWrite and CloseRead.
+* net: use AF_UNSPEC instead of individual address family (thanks Mikio Hara).
+* path/filepath: added Rel as the complement of Abs (thanks Gustavo Niemeyer).
+* pkg/syscall: add Mkfifo for linux platforms.
+* regexp: move to old/regexp, replace with exp/regexp, speedups.
+* runtime/gdb: fix pretty printing of channels,
+ gracefully handle not being able to find types.
+* runtime: check for nil value pointer in select syncsend case,
+ faster finalizers,
+ fix malloc sampling bug,
+ fix map memory leak,
+ fix spurious deadlock reporting,
+ fix usleep on linux/386 and re-enable parallel gc (thanks Hector Chu),
+ parallelize garbage collector mark + sweep.
+* strconv: faster Unquote in common case.
+* strings: add EqualFold, Replacer, NewReplacer.
+* suffixarray: add benchmarks for construction (thanks Eric Eisner).
+* syscall: add GetsockoptByte, SetsockoptByte for openbsd (thanks Mikio Hara),
+ add IPv4 ancillary data for linux (thanks Mikio Hara),
+ mark stdin, stdout, stderr non-inheritable by child processes (thanks Alex Brainman),
+ mksyscall_windows.pl creates non-syscall packages (thanks Jaroslavas Počepko),
+ update multicast socket options (thanks Mikio Hara).
+* testing: support for running tests in parallel (thanks Miki Tebeka).
+* time: make month/day name comparisons case insenstive.
+* unicode: fix make tables.
+* vim: Send GoFmt errors to a location list (thanks Paul Sbarra).
+* websocket: add hybi-13 support, add mutex to make websocket full-duplex.
+</pre>
+
+<h2 id="2011-09-21">2011-09-21</h2>
+
+<pre>
+This weekly contains several improvements, bug fixes, and new packages.
+
+* archive/tar: document Header fields and Type flags (thanks Mike Rosset).
+* bytes: fix Replace so it actually copies (thanks Gustavo Niemeyer).
+* cgo: use GOARCH from the environment (thanks Jaroslavas Počepko).
+* codereview: save CL messages in $(hg root)/last-change.
+* crypto/bcrypt: new package (thanks Jeff Hodges).
+* crypto/blowfish: exposing the blowfish key schedule (thanks Jeff Hodges).
+* doc: link to golang-france.
+* doc: when configuring gold for gccgo, use --enable-gold=default.
+* exp/norm: changed trie to produce smaller tables.
+* exp/ssh: new package,
+ refactor halfConnection to transport (thanks Dave Cheney).
+* exp/template/html: more fixes and improvements.
+* filepath: fix Glob to return no error on nonmatching patterns.
+* gc: disallow invalid map keys,
+ handle complex CONVNOP.
+* gob: allocation fixes.
+* godoc: simplify internal FileSystem interface.
+* http/cgi: clean up environment (thanks Yasuhiro Matsumoto).
+* http: always include Content-Length header, even for 0 (thanks Dave Grijalva),
+ check explicit wrong Request.ContentLength values,
+ fix TLS handshake blocking server accept loop,
+ prevent DumpRequest from adding implicit headers.
+* httptest: add NewUnstartedServer.
+* json: clearer Unmarshal doc,
+ skip nil in UnmarshalJSON and (for symmetry) MarshalJSON.
+* net: use /etc/hosts first when looking up IP addresses (thanks Andrey Mirtchovski).
+* reflect: add comment about the doubled semantics of Value.String.
+* runtime: implement pprof support for windows (thanks Hector Chu),
+ increase stack system space on windows/amd64 (thanks Hector Chu).
+* suffixarray: generate less garbage during construction (thanks Eric Eisner),
+ improved serialization code using gob instead of encoding/binary.
+* sync/atomic: replace MFENCE with LOCK XADD.
+</pre>
+
+<h2 id="2011-09-16">2011-09-16</h2>
+
+<pre>
+This weekly snapshot includes changes to the image, path/filepath, and time
+packages. Code that uses these packages may need to be updated.
+
+The image package's NewX functions (NewRGBA, NewNRGBA, etc) have been changed
+to take a Rectangle argument instead of a width and height.
+Gofix can make these changes automatically.
+
+The path/filepath package's Walk function has been changed to take a WalkFunc
+function value instead of a Visitor interface value. WalkFunc is like the
+Visitor's VisitDir and VisitFile methods except it handles both files and
+directories:
+ func(path string, info *os.FileInfo, err os.Error) os.Error
+To skip walking a directory (like returning false from VisitDir) the WalkFunc
+must return SkipDir.
+
+The time package's Time struct's Weekday field has been changed to a method.
+The value is calculated on demand, avoiding the need to re-parse
+programmatically-constructed Time values to find the correct weekday.
+
+There are no gofixes for the filepath or time API changes, but instances of the
+old APIs will be caught by the compiler. The Weekday one is easy to update by
+hand. The Walk one may take more consideration, but will have fewer instances
+to fix.
+
+* build: add build comments to core packages.
+* codereview: Mercurial 1.9 fix for hg diff @nnn.
+* crypto/tls: handle non-TLS more robustly,
+ support SSLv3.
+* debug/elf: permit another case of SHT_NOBITS section overlap in test.
+* exm/template/html: more work on this auto-escaping HTML template package.
+* exp/norm: added regression test tool for the standard Unicode test set.
+* exp/regexp/syntax: fix invalid input parser crash,
+ import all RE2 parse tests + fix bugs.
+* exp/regexp: add MustCompilePOSIX, CompilePOSIX, leftmost-longest matching.
+* flag: make zero FlagSet useful.
+* gc: clean up if grammar.
+* go/build: handle cgo, // +build comments.
+* go/printer: use panic/defer instead of goroutine for handling errors.
+* go/token: support to serialize file sets.
+* godoc, suffixarray: switch to exp/regexp.
+* godoc: show packages matching a query at the top,
+ support for complete index serialization,
+ use go/build to find files in a package.
+* gofmt: accept program fragments on standard input, add else test.
+* http/cgi: add openbsd environment configuration.
+* http: document that Response.Body is non-nil.
+* image/png: don't use a goroutine to decode, to permit decode during init.
+* json: if a field's tag is "-", ignore the field for encoding and decoding.
+* ld: grow dwarf includestack on demand.
+* net, syscall: implement SetsockoptIPMReq(), and
+ move to winsock v2.2 for multicast support (thanks Paul Lalonde).
+* net: add a LookupTXT function.
+* os: os.RemoveAll to check for wboth error codes on Windows (thanks Jaroslavas Počepko).
+* path/filepath: fix Visitor doc (thanks Gustavo Niemeyer),
+ make UNC file names work (thanks Yasuhiro Matsumoto).
+* runtime: optimizations to channels on Windows (thanks Hector Chu),
+ syscall to return both AX and DX for windows/386 (thanks Alex Brainman).
+* sync/atomic: add 64-bit Load and Store.
+* syscall: add route flags for linux (thanks Mikio Hara).
+* test: add test for inheriting private method from anonymous field.
+* websocket: fix infinite recursion in Addr.String() (thanks Tarmigan Casebolt),
+ rename websocket.WebSocketAddr to *websocket.Addr.
+</pre>
+
+<h2 id="2011-09-07">2011-09-07</h2>
+
+<pre>
+This weekly snapshot consists of improvements and bug fixes, including fixes
+for issues introduced by escape analysis changes in the gc compiler.
+
+* build: clear execute bit from Go files (thanks Mike Rosset),
+ error out if problem with sudo.bash /usr/local/bin (thanks Mike Rosset).
+* exp/norm: add Reader and Writer,
+ performance improvements of quickSpan.
+* exp/regexp: bug fixes and RE2 tests.
+* exp/template/html: string replacement refactoring,
+ tweaks to js{,_test}.go.
+* gc: add -p flag to catch import cycles earlier,
+ fix label recursion bugs,
+ fix zero-length struct eval,
+ zero stack-allocated slice backing arrays,
+* gc, ld: fix Windows file paths (thanks Hector Chu).
+* go/parser: accept corner cases of signature syntax.
+* gobuilder: ignore _test.go files when looking for docs, more logging.
+* godoc: minor tweaks for App Engine use.
+* gofix: do not convert url in field names (thanks Gustavo Niemeyer).
+* gofmt: indent multi-line signatures.
+* gopprof: regexp fixes (thanks Hector Chu).
+* image/png: check zlib checksum during Decode.
+* libmach: fix incorrect use of memset (thanks Dave Cheney).
+* misc/goplay: fix template output.
+* net: ParseCIDR returns IPNet instead of IPMask (thanks Mikio Hara),
+ sync CIDRMask code, doc.
+* os: use GetFileAttributesEx to implement Stat on windows (thanks Alex Brainman).
+* runtime: fix openbsd 386 raisesigpipe,
+ implement exception handling on windows/amd64 (thanks Hector Chu),
+ test for concurrent channel consumers (thanks Christopher Wedgwood).
+* sort: use heapsort to bail out quicksort (thanks Ziad Hatahet).
+* sync/atomic: add LoadUintptr, add Store functions.
+* syscall: update routing message attributes handling (thanks Mikio Hara).
+* template: fix deadlock,
+ indirect or dereference function arguments if necessary,
+ slightly simplify the test for assignability of arguments.
+* url: handle ; in ParseQuery.
+* websocket: fix incorrect prints found by govet (thanks Robert Hencke).
+</pre>
+
+<h2 id="2011-09-01">2011-09-01</h2>
+
+<pre>
+This weekly contains performance improvements and bug fixes.
+
+The gc compiler now does escape analysis, which improves program performance
+by placing variables on the call stack instead of the heap when it is safe to
+do so.
+
+The container/vector package is deprecated and will be removed at some point
+in the future.
+
+Other changes:
+* archive/tar: support symlinks. (thanks Mike Rosset)
+* big: fix nat.scan bug. (thanks Evan Shaw)
+* bufio: handle a "\r\n" that straddles the buffer.
+ add openbsd.
+ avoid redundant bss declarations.
+ fix unused parameters.
+ fix windows/amd64 build with newest mingw-w64. (thanks Hector Chu)
+* bytes: clarify that NewBuffer is not for beginners.
+* cgo: explain how to free something.
+ fix GoBytes. (thanks Gustavo Niemeyer)
+ fixes callback for windows amd64. (thanks Wei Guangjing)
+ note that CString result must be freed. (thanks Gustavo Niemeyer)
+* cov: remove tautological #defines. (thanks Lucio De Re)
+* dashboard: yet another utf-8 fix.
+* doc/codelab/wiki: fix Makefile.
+* doc/progs: fix windows/amd64. (thanks Jaroslavas Počepko)
+* doc/tmpltohtml: update to new template package.
+* doc: emphasize that environment variables are optional.
+* effective_go: convert to use tmpltohtml.
+* exp/norm: reduced the size of the byte buffer used by reorderBuffer by half by reusing space when combining.
+ a few minor fixes to support the implementation of norm.
+ added implementation for []byte versions of methods.
+* exp/template/html: add some tests for ">" attributes.
+ added handling for URL attributes.
+ differentiate URL-valued attributes (such as href).
+ reworked escapeText to recognize attr boundaries.
+* exp/wingui: made compatible with windows/amd64. (thanks Jaroslavas Počepko)
+* flag: add Parsed, restore Usage.
+* gc: add openbsd.
+ escape analysis.
+ fix build on Plan 9. (thanks Lucio De Re)
+ fix div bug.
+ fix pc/line table. (thanks Julian Phillips)
+ fix some spurious leaks.
+ make static initialization more static.
+ remove JCXZ; add JCXZW, JCXZL, and JCXZQ instructions. (thanks Jaroslavas Počepko)
+ shuffle #includes.
+ simplify escape analysis recursion.
+ tweak and enable escape analysis.
+* go/ast cleanup: base File/PackageExports on FilterFile/FilterPackage code.
+ adjustments to filter function.
+ fix ast.MergePackageFiles to collect infos about imports. (thanks Sebastien Binet)
+ generalize ast.FilterFile.
+* go/build: add test support & use in gotest.
+ separate test imports out when scanning. (thanks Gustavo Niemeyer)
+* go/parser: fix type switch scoping.
+ fix type switch scoping.
+* gob: explain that Debug isn't useful unless it's compiled in.
+* gobuilder: increase log limit.
+* godashboard: fix utf-8 in user names.
+* godoc: first step towards reducing index size.
+ add dummy playground.js to silence godoc warning at start-up.
+ added systematic throttling to indexing goroutine.
+ fix bug in zip.go.
+ support for reading/writing (splitted) index files.
+ use virtual file system when generating package synopses.
+* gofix: forgot to rename the URL type.
+ osopen: fixed=true when changing O_CREAT. (thanks Tarmigan Casebolt)
+* goinstall: error out with paths that end with '/'. (thanks Tarmigan Casebolt)
+ report lack of $GOPATH on errors. (thanks Gustavo Niemeyer)
+ select the tag that is closest to runtime.Version.
+* gotry: add missing $. (thanks Tarmigan Casebolt)
+* http: add MaxBytesReader to limit request body size.
+ add file protocol transport.
+ adjust test threshold for larger suse buffers.
+ delete error kludge.
+ on invalid request, send 400 response.
+ return 413 instead of 400 when the request body is too large. (thanks Dave Cheney)
+ support setting Transport's TLS client config.
+* image/tiff: add a decode benchmark. (thanks Benny Siegert)
+ decoder optimization. (thanks Benny Siegert)
+* image: add PalettedImage interface, and make image/png recognize it. (thanks Jaroslavas Počepko)
+* io: add TeeReader. (thanks Hector Chu)
+* json: add struct tag option to wrap literals in strings.
+ calculate Offset for Indent correctly. (thanks Jeff Hodges)
+ fix decode bug with struct tag names with ,opts being ignored.
+* ld: handle Plan 9 ar format. (thanks Lucio De Re)
+ remove duplicate bss definitions.
+* libmach: support reading symbols from Windows .exe for nm. (thanks Mateusz Czapliński)
+* math: fix Pow10 loop. (thanks Volker Dobler)
+* mime: ParseMediaType returns os.Error now, not a nil map.
+ media type formatter. (thanks Pascal S. de Kloe)
+ text charset defaults. (thanks Pascal S. de Kloe)
+* misc/dashboard: remove limit for json package list.
+* misc/emacs: refine label detection.
+* net: add ParseMAC function. (thanks Paul Borman)
+ change the internal form of IPMask for IPv4. (thanks Mikio Hara)
+ disable "tcp" test on openbsd.
+ fix windows build. (thanks Alex Brainman)
+ join and leave a IPv6 group address, on a specific interface. (thanks Mikio Hara)
+ make use of IPv4len, IPv6len. (thanks Mikio Hara)
+ move internal string manipulation routines to parse.go. (thanks Mikio Hara)
+* os: disable Hostname test on OpenBSD.
+ fix WNOHANG Waitmsg. (thanks Gustavo Niemeyer)
+* reflect: add Value.Bytes, Value.SetBytes methods.
+* rpc: add benchmark for async rpc calls.
+* runtime: add openbsd 386 defs.h.
+ add runtime support for openbsd 386.
+ add runtime· prefix to showframe.
+ ctrlhandler for windows amd64. (thanks Wei Guangjing)
+ fix stack cleanup on windows/amd64. (thanks Hector Chu)
+ fix void warnings.
+ go interface to cdecl calbacks. (thanks Jaroslavas Počepko)
+ handle string + char literals in goc2c.
+ make arm work on Ubuntu Natty qemu.
+ openbsd thread tweaks.
+ simplify stack traces.
+ speed up cgo calls. (thanks Alex Brainman)
+ use cgo runtime functions to call windows syscalls. (thanks Alex Brainman)
+ windows/amd64 callbacks fixed and syscall fixed to allow using it in callbacks. (thanks Jaroslavas Počepko)
+* strconv: put decimal on stack.
+* spec: update section on Implementation Differences.
+* syscall: SOMAXCONN should be 0x7fffffff at winsock2. (thanks Yasuhiro Matsumoto)
+ add openbsd 386.
+ handle RTM_NEWROUTE in ParseNetlinkRouteAttr on Linux. (thanks Albert Strasheim)
+ handle routing entry in ParseRoutingSockaddr on BSD variants. (thanks Mikio Hara)
+ openbsd amd64 syscall support.
+ use the vdso page on linux x86 for faster syscalls instead of int $0x80. (thanks Yuval Pavel Zholkover)
+* template/parse: give if, range, and with a common representation.
+* template: grammar fix for template documentation. (thanks Bill Neubauer)
+ range over channel.
+ remove else and end nodes from public view.
+* test: put GOROOT/bin before all others in run.
+* time: fix Plan 9 build. (thanks Fazlul Shahriar)
+ fix zone during windows test.
+* type switches: test for pathological case.
+* version.bash: update VERSION on -save if already present. (thanks Gustavo Niemeyer)
+* websocket: implements new version of WebSocket protocol. (thanks Fumitoshi Ukai)
+* windows/386: clean stack after syscall. (thanks Jaroslavas Počepko)
+* xml: marshal "parent>child" tags correctly. (thanks Ross Light)
+</pre>
+
+<h2 id="2011-08-17">2011-08-17 (<a href="release.html#r60">base for r60</a>)</h2>
+
+<pre>
+This weekly contains some package re-shuffling. Users of the http and
+template packages may be affected.
+
+This weekly replaces the template package with exp/template.
+The original template package is still available as old/template.
+The old/template package is deprecated and will be removed at some point
+in the future. The Go tree has been updated to use the new template package.
+We encourage users of the old template package to switch to the new one.
+Code that uses template or exp/template will need to change
+its import lines to "old/template" or "template", respectively.
+
+The http package's URL parsing and query escaping code (such as ParseURL and
+URLEscape) has been moved to the new url package, with several simplifications
+to the names. Client code can be updated automatically with gofix.
+
+* asn1: support unmarshalling structs with int32 members (thanks Dave Cheney).
+* build: allow builds without cgo or hg,
+ support versioning without hg (thanks Gustavo Niemeyer).
+* builtin: add documentation for builtins.
+* cgo: omit duplicate symbols in writeDefs (thanks Julian Phillips).
+* misc: add support for OpenBSD.
+* doc/codewalk: new Markov chain codewalk.
+* exp/norm: added trie lookup code and associated tests,
+ generate trie struct in triegen.go for better encapsulation,
+ implementation of decomposition and composing functionality.
+* exp/template/html: new experimental package for auto-escaping HTML templates.
+* exp/template: don't panic on range of nil interface,
+ rename Parse*File and Parse*Files for clarity,
+ support field syntax on maps (thanks Gustavo Niemeyer), and
+ many other fixes and changes.
+* gc: implement nil chan and nil map support.
+* go/parser: range clause and type literal fixes.
+* godoc: show all top-level decls for (fake) package builtin.
+* goinstall: really report all newly-installed public packages.
+* html: parse more malformed tags.
+* http: fix ParseMultipartForm after MultipartReader error,
+ fix side effects in DefaultTransport's RoundTrip method (thanks Dave Grijalva).
+* json: fix []unmarshaler case.
+* ld: make addaddrplus4 static (thanks Lucio De Re).
+* syscall: move multicast address handling to the net package.
+* net: Plan 9 support (thanks Fazlul Shahriar),
+ add SetTimeout to Listener interface (thanks Aleksandar Dezelin),
+ add multicast stubs for OpenBSD,
+ return correct local address for an accepted TCP connection (thanks Mikio Hara).
+* reflect: panic on Invalid Interface call (thanks Gustavo Niemeyer).
+* rpc: implement ServeRequest to synchronously serve a single request,
+ make Server.Mutex unexported.
+* runtime: better checks for syscall.NewCallback parameter (thanks Alex Brainman),
+ correct SEH installation during callbacks (thanks Alex Brainman),
+ fix GC bitmap corruption,
+ fix pseudo-randomness on some selects (thanks Gustavo Niemeyer).
+* syscall: make LazyDLL/LazyProc.Mutex unexported.
+* test: allow multiple patterns in errchk,
+ new nil semantics.
+* time: take fractional seconds even if not in the format string.
+* url: new package.
+* utf8: rename some internal constants to remove leading underscores.
+* xml: escape string chardata in xml.Marshal.
+</pre>
+
+<h2 id="2011-08-10">2011-08-10</h2>
+
+<pre>
+This weekly contains performance improvements and bug fixes.
+
+There are no outward-facing changes, but imports of the old-style
+container/vector package have also been removed from the core library (thanks
+John Asmuth, Kyle Consalus).
+
+Other changes:
+
+* 5g: fix set but not used error (thanks Dave Cheney).
+* cmd/ld: Corrected mismatched print formats and variables (thanks Lucio De Re).
+* errchk: add -0 flag.
+* exp/norm: fix build by adding a test placeholder,
+ maketables tool for generating tables for normalization.
+* exp/template: bug fixes,
+ ensure that a valid Set is returned even on error (thanks Roger Peppe),
+ make index on maps return zero when key not present (thanks Roger Peppe),
+ split the parse tree into a separate package exp/template/parse,
+ add url query formatting filter.
+* faq: lots of small tweaks plus a couple of new discussions,
+ variant types, unions.
+* fmt: call UpdateMemStats in malloc counter.
+* go/build: use GOBIN as binary path for GOROOT.
+* gob: add UpdateMemStats calls to malloc counter,
+ avoid a couple of init-time allocations,
+ don't invoke GobEncoder on zero values.
+* gofmt: update test script so 'make test' succeeds.
+* html: parse doctype tokens; merge adjacent text nodes.
+* http: add more MPEG-4 MIME types to sniffer, and disable MP4 sniffing,
+ add test to serve content in index.html (thanks Yasuhiro Matsumoto),
+ configurable and default request header size limit,
+ correct format flags when printing errors in tests (thanks Alex Brainman),
+ correct path to serve index.html (thanks Yasuhiro Matsumoto),
+* ld: add one empty symbol into pe to make dumpbin works (thanks Wei Guangjing),
+ fail linking if the top-level package is not main.
+* misc/vim: godoc command (thanks Yasuhiro Matsumoto).
+* net: add support for openbsd (thanks Joel Sing),
+ fix /proc/net/igmp,igmp6 reading bug on linux (thanks Mikio Hara),
+ implement windows LookupMX and LookupAddr (thanks Mikio Hara),
+ sort SRV records before returning from LookupSRV (thanks Alex Brainman),
+* os: add support for openbsd (thanks Joel Sing).
+* runtime: add more specialized type algorithms,
+ correct Note documentation,
+ faster chan creation on Linux/FreeBSD/Plan9,
+ openbsd amd64 runtime support (thanks Joel Sing),
+ remove unnecessary locking (thanks Hector Chu).
+* scanner: correct error position for illegal UTF-8 encodings.
+* syscall: delay load of dll functions on Windows (thanks Alex Brainman),
+ move BSD mmap syscall (thanks Joel Sing),
+ update routing message support for BSD variants (thanks Mikio Hara).
+* test/bench: note changes after recent improvements to locking and runtime.
+* time: add nanoseconds to the Time structure,
+ parse and format fractional seconds.
+</pre>
+
+<h2 id="2011-07-29">2011-07-29</h2>
+
+<pre>
+This weekly contains performance improvements and many bug fixes.
+
+* 6l: OpenBSD support.
+* archive/zip: handle zip files with more than 65535 files,
+ more efficient reader and bug fix.
+* big: refine printf formatting and optimize string conversion.
+* build: fixes for mingw-w64 (thanks Wei Guangjing),
+ miscellaneous fixes.
+* cgo: add GoBytes, fix gmp example.
+* exp/norm: API for normalization library.
+* exp/regexp: implement regexp API using exp/regexp/syntax.
+* exp/template: more tweaks and fixes, convert the tree to use exp/template.
+* fmt: handle precision 0 format strings in standard way.
+* gc: a raft of bug fixes.
+* go/parser: report illegal label declarations at ':'.
+* gob: send empty but non-nil maps.
+* godoc: allow form feed in text files,
+ app engine configuration and updated documentation.
+* goinstall: abort and warn when using any url scheme, not just 'http://',
+ write to goinstall.log in respective GOPATH.
+* html: handle character entities without semicolons (thanks Andrew Balholm),
+ parse misnested formatting tags according to the HTML5 spec,
+ sync html/testdata/webkit with upstream WebKit.
+* http: content-type sniffing,
+ make serveFile redirects relative (thanks Andrew Balholm),
+ other fixes.
+* image/tiff: Do not panic when RowsPerStrip is missing (thanks Benny Siegert).
+* io/ioutil: improve performance of ioutil.Discard (thanks Mike Solomon).
+* ld: detect all import cycles,
+ ldpe fixes (thanks Wei Guangjing),
+ remove cseekend and redo pe writing (thanks Alex Brainman),
+ remove overlap of ELF sections on dynamic binaries (thanks Gustavo Niemeyer).
+* net/textproto: avoid 1 copy in ReadLine, ReadContinuedLine.
+* net: fix memory corruption in windows *netFD.ReadFrom (thanks Alex Brainman).
+* runtime: faster entersyscall/exitsyscall,
+ fix scheduler races (thanks Hector Chu),
+ higher goroutine arg limit, clearer error,
+ parallelism-related performance optimizations and fixes,
+ replace byte-at-a-time zeroing loop with memclr (thanks Quan Yong Zhai).
+* sort: fix Float64Slice sort; NaN smallest value (thanks Florian Uekermann).
+* src: removed some uses of container/vector (thanks John Asmuth).
+* sync: improve Once fast path.
+* unicode: fix case-mapping for roman numerals.
+</pre>
+
+<h2 id="2011-07-19">2011-07-19</h2>
+
+<pre>
+This weekly snapshot includes a language change and a change to the image
+package that may require changes to client code.
+
+The language change is that an "else" block is now required to have braces
+except if the body of the "else" is another "if". Since gofmt always puts those
+braces in anyway, programs will not be affected unless they contain "else for",
+"else switch", or "else select". Run gofmt to fix any such programs.
+
+The image package has had significant changes made to the Pix field of struct
+types such as image.RGBA and image.NRGBA. The image.Image interface type has
+not changed, though, and you should not need to change your code if you don't
+explicitly refer to Pix fields. For example, if you decode a number of images
+using the image/jpeg package, compose them using image/draw, and then encode
+the result using image/png, then your code should still work as before.
+
+If you do explicitly refer to Pix fields, there are two changes. First, Pix[0]
+now refers to the pixel at Bounds().Min instead of the pixel at (0, 0). Second,
+the element type of the Pix slice is now uint8 instead of image.FooColor. For
+example, for an image.RGBA, the channel values will be packed R, G, B, A, R, G,
+B, A, etc. For 16-bits-per-channel color types, the pixel data will be stored
+as big-endian uint8s.
+
+Most Pix field types have changed, and so if your code still compiles after
+this change, then you probably don't need to make any further changes (unless
+you use an image.Paletted's Pix field). If you do get compiler errors, code
+that used to look like this:
+
+ // Get the R, G, B, A values for the pixel at (x, y).
+ var m *image.RGBA = loadAnImage()
+ c := m.Pix[y*m.Stride + x]
+ r, g, b, a := c.R, c.G, c.B, c.A
+
+should now look like this:
+
+ // Get the R, G, B, A values for the pixel at (x, y).
+ var m *image.RGBA = loadAnImage()
+ i := (y-m.Rect.Min.Y)*m.Stride + (x-m.Rect.Min.X)*4
+ r := m.Pix[i+0]
+ g := m.Pix[i+1]
+ b := m.Pix[i+2]
+ a := m.Pix[i+3]
+
+This image package change will not be fixed by gofix: how best to translate
+code into something efficient and idiomatic depends on the surrounding context,
+and is not easily automatable. Examples of what to do can be found in the
+changes to image/draw/draw.go in http://codereview.appspot.com/4675076/
+
+Other changes:
+* 6l: change default output name to 6.out.exe on windows (thanks Alex Brainman).
+* archive/zip: add Writer,
+ add Mtime_ns function to get modified time in sensible format.
+* cc, ld, gc: fixes for Plan 9 build (thanks Lucio De Re).
+* cgi: close stdout reader pipe when finished.
+* cgo: add missing semicolon in generated struct,
+ windows amd64 port (thanks Wei Guangjing).
+* codereview: fix for Mercurial 1.9.
+* dashboard: list "most installed this week" with rolling count.
+* debug/elf: read ELF Program headers (thanks Matthew Horsnell).
+* debug/pe: fixes ImportedSymbols for Win64 (thanks Wei Guangjing).
+* debug/proc: remove unused package.
+* doc/talks/io2010: update with gofix and handle the errors.
+* exp/eval, exp/ogle: remove packages eval and ogle.
+* exp/regexp/syntax: add Prog.NumCap.
+* exp/template: API changes, bug fixes, and tweaks.
+* flag: make -help nicer.
+* fmt: Scan(&int) was mishandling a lone digit.
+* gc: fix closure bug,
+ fix to build with clang (thanks Dave Cheney),
+ make size of struct{} and [0]byte 0 bytes (thanks Robert Hencke),
+ some enhancements to printing debug info.
+* gif: fix local color map and coordinates.
+* go/build: fixes for windows (thanks Alex Brainman),
+ include processing of .c files for cgo packages (thanks Alex Brainman),
+ less aggressive failure when GOROOT not found.
+* go/printer: changed max. number of newlines from 3 to 2.
+* gob: register more slice types (thanks Bobby Powers).
+* godoc: support for file systems stored in .zip files.
+* goinstall, dashboard: Google Code now supports git (thanks Tarmigan Casebolt).
+* hash/crc32: add SSE4.2 support.
+* html: update section references in comments to the latest HTML5 spec.
+* http: drain the pipe output in TestHandlerPanic to avoid logging deadlock,
+ fix Content-Type of file extension (thanks Yasuhiro Matsumoto),
+ implement http.FileSystem for zip files,
+ let FileServer work when path doesn't begin with a slash,
+ support for periodic flushing in ReverseProxy.
+* image/draw: add benchmarks.
+* json: add omitempty struct tag option,
+ allow using '$' and '-' as the struct field's tag (thanks Mikio Hara),
+ encode \r and \n in strings as e.g. "\n", not "\u000A" (thanks Evan Martin),
+ escape < and > in any JSON string for XSS prevention.
+* ld: allow seek within write buffer<
+ add a PT_LOAD PHDR entry for the PHDR (thanks David Anderson).
+* net: windows/amd64 port (thanks Wei Guangjing).
+* os: plan9: add Process.Signal as a way to send notes (thanks Yuval Pavel Zholkover).
+* os: don't permit Process.Signal after a successful Wait.
+* path/filepath: fixes for windows paths (thanks Alex Brainman).
+* reflect: add Value.NumMethod,
+ panic if Method index is out of range for a type.
+* runtime: faster entersyscall, exitsyscall,
+ fix panic for make(chan [0]byte),
+ fix subtle select bug (thanks Hector Chu),
+ make goc2c build on Plan 9 (thanks Lucio De Re),
+ make TestSideEffectOrder work twice,
+ several parallelism-related optimizations and fixes,
+ stdcall_raw stack 16byte align for Win64 (thanks Wei Guangjing),
+ string-related optimizations (thanks Quan Yong Zhai),
+ track running goroutine count.
+* strconv: handle [-+]Infinity in atof.
+* sync: add fast paths to WaitGroup,
+ improve RWMutex performance.
+* syscall: add Flock on Linux,
+ parse and encode SCM_RIGHTS and SCM_CREDENTIALS (thanks Albert Strasheim).
+</pre>
+
+<h2 id="2011-07-07">2011-07-07 (<a href="release.html#r59">base for r59</a>)</h2>
+
+<pre>
+This weekly snapshot includes changes to the strings, http, reflect, json, and
+xml packages. Code that uses these packages will need changes. Most of these
+changes can be made automatically with gofix.
+
+The strings package's Split function has itself been split into Split and
+SplitN. SplitN is the same as the old Split. The new Split is equivalent to
+SplitN with a final argument of -1.
+
+The http package has a new FileSystem interface that provides access to files.
+The FileServer helper now takes a FileSystem argument instead of an explicit
+file system root. By implementing your own FileSystem you can use the
+FileServer to serve arbitrary data.
+
+The reflect package supports a new struct tag scheme that enables sharing of
+struct tags between multiple packages.
+In this scheme, the tags must be of the form:
+ key:"value" key2:"value2"
+reflect.StructField's Tag field now has type StructTag (a string type), which
+has method Get(key string) string that returns the associated value.
+Clients of json and xml will need to be updated. Code that says
+ type T struct {
+ X int "name"
+ }
+should become
+ type T struct {
+ X int `json:"name"` // or `xml:"name"`
+ }
+Use govet to identify struct tags that need to be changed to use the new syntax.
+
+Other changes:
+* 5l, 6l, 8l: drop use of ed during build.
+* asn1: support T61 and UTF8 string.
+* bufio: do not cache Read errors (thanks Graham Miller).
+* build: make version.bash aware of branches.
+* cgi: don't depend on CGI.pm for tests.
+* codereview: make --ignore_hgpatch_failure work again,
+ restrict sync to default branch.
+* crypto/openpgp: add ability to reserialize keys,
+ bug fix (thanks Gideon Jan-Wessel Redelinghuys).
+* crypto/tls: fix generate_cert.go.
+* crypto/x509: prevent chain cycles in Verify.
+* csv: new package.
+* doc: remove ed from apt-get package list.
+* docs: fold the prog.sh scripting from makehtml into htmlgen itself.
+* ebnflint: better handling of stdin.
+* exp/regexp/syntax: new experimental RE2-based regexp implementation.
+* exp/template: a new experimental templating package.
+* fmt: add SkipSpace to fmt's ScanState interface.
+* fmt: rename errno and error to err for doc consistency.
+* gc: avoid package name ambiguity in error messages,
+ fix package quoting logic,
+ fixes for Plan 9 (thanks Lucio De Re).
+* go/build: evaluate symlinks before comparing path to GOPATH.
+* gob: use exported fields in structs in the package documentation.
+* godoc: ignore directories that begin with '.',
+ search GOPATH for documentation.
+* gofix: os/signal, path/filepath, and sort fixes (thanks Robert Hencke),
+* goinstall: add support for generic hosts (thanks Julian Phillips),
+ only report successfully-installed packages to the dashboard,
+ try to access via https (thanks Yasuhiro Matsumoto).
+* gotest: add -test.benchtime and -test.cpu flags.
+* html: fixes and improvements (thanks Yasuhiro Matsumoto).
+* http/cgi: add Handler.Dir to specify working directory (thanks Yasuhiro Matsumoto).
+* http: add StripPrefix handler wrapper,
+ assume ContentLength 0 on GET requests,
+ better handling of 0-length Request.Body,
+ do TLS handshake explicitly before copying TLS state,
+ document that ServerConn and ClientConn are low-level,
+ make NewChunkedReader public (thanks Andrew Balholm),
+ respect Handlers setting Connection: close in their response.
+* image: more tests, Paletted.Opaque optimization.
+* io.WriteString: if the object has a WriteString method, use it (thanks Evan Shaw).
+* ld: elide the Go symbol table when using -s (thanks Anthony Martin).
+* ld: fix ELF strip by removing overlap of sections (thanks Gustavo Niemeyer).
+* mime/multipart: parse LF-delimited messages, not just CRLF.
+* mime: permit lower-case media type parameters (thanks Pascal S. de Kloe).
+* misc/dashboard: new features and improvements (not yet deployed).
+* misc/emacs: update list of builtins (thanks Quan Yong Zhai).
+* misc/vim: allow only utf-8 for file encoding (thanks Yasuhiro Matsumoto).
+* os: fix documentation for FileInfo.Name,
+ simplify WriteString,
+ use a different symbol from syscall in mkunixsignals.sh.
+* path/filepath: enable TestWalk to run on windows (thanks Alex Brainman).
+* reflect: add MethodByName,
+ allow Len on String values.
+* regexp: document that Regexp is thread-safe.
+* runtime/cgo: check for errors from pthread_create (thanks Albert Strasheim).
+* runtime: add Semacquire/Semrelease benchmarks,
+ improved Semacquire/Semrelease implementation,
+ windows/amd64 port (thanks Wei Guangjing).
+* sync: add fast path to Once,
+ improve Mutex to allow successive acquisitions,
+ new and improved benchmarks.
+* syscall: regenerate zerrors for darwin/linux/freebsd,
+ support for tty options in StartProcess (thanks Ken Rockot).
+* testing: make ResetTimer not start/stop the timer,
+ scale benchmark precision to 0.01ns if needed.
+* time: zero-pad two-digit years.
+* unicode/maketables: update debugging data.
+* windows: define and use syscall.Handle (thanks Wei Guangjing).
+* xml: add Marshal and MarshalIndent.
+</pre>
+
+<h2 id="2011-06-23">2011-06-23</h2>
+
+<pre>
+This snapshot includes a language change that restricts the use of goto.
+In essence, a "goto" statement outside a block cannot jump to a label inside
+that block. Your code may require changes if it uses goto.
+This changeset shows how the new rule affected the Go tree:
+ http://code.google.com/p/go/source/detail?r=dc6d3cf9279d
+
+The os.ErrorString type has been hidden. If your code uses os.ErrorString it
+must be changed. Most uses of os.ErrorString can be replaced with os.NewError.
+
+Other changes:
+* 5c: do not use R9 and R10.
+* 8l: more fixes for Plan 9 (thanks Lucio De Re).
+* build: Make.ccmd: link with mach lib (thanks Joe Poirier).
+* build: exclude packages that fail on Plan 9 (thanks Anthony Martin).
+* cc: nit: silence comment warnings (thanks Dave Cheney).
+* codereview.py: note that hg change -d abandons a change list (thanks Robert Hencke).
+* crypto/openpgp: add ElGamal support.
+* doc/faq: add question about converting from []T to []interface{}.
+* doc: Effective Go: fix variadic function example (thanks Ben Lynn).
+* exec: LookPath should not search %PATH% for files like c:cmd.exe (thanks Alex Brainman),
+ add support for Plan 9 (thanks Anthony Martin),
+ better error message for windows LookPath (thanks Alex Brainman).
+* fmt: catch panics from calls to String etc.
+* gc: descriptive panic for nil pointer -> value method call,
+ implement goto restriction,
+ unsafe.Alignof, unsafe.Offsetof, unsafe.Sizeof now return uintptr.
+* go/build: include Import objects in Script Inputs.
+* godefs: rudimentary tests (thanks Robert Hencke).
+* goinstall: refactor and generalize repo handling code (thanks Julian Phillips),
+ temporarily use Makefiles by default (override with -make=false).
+* gopprof: update list of memory allocators.
+* http: add Server.ListenAndServeTLS,
+ buffer request.Write,
+ fix req.Cookie(name) with cookies in one header,
+ permit handlers to explicitly remove the Date header,
+ write Header keys with empty values.
+* image: basic test for the 16-bits-per-color-channel types.
+* io: clarify Read, ReadAt, Copy, Copyn EOF behavior.
+* ld: don't attempt to build dynamic sections unnecessarily (thanks Gustavo Niemeyer).
+* libmach: fix disassembly of FCMOVcc and FCOMI (thanks Anthony Martin),
+ fix tracing on linux (for cov) (thanks Anthony Martin).
+* mime: fix RFC references (thanks Pascal S. de Kloe).
+* misc/gobuilder: run make single-threaded on windows (thanks Alex Brainman).
+* misc/godashboard: Accept sub-directories for goinstall's report (thanks Yasuhiro Matsumoto).
+* nacl, tiny: remove vestiges (thanks Robert Hencke).
+* net, syscall: interface for windows (thanks Yasuhiro Matsumoto).
+* os: change Waitmsg String method to use pointer receiver (thanks Graham Miller).
+* runtime: don't use twice the memory with grsec-like kernels (thanks Gustavo Niemeyer),
+* spec: disallow goto into blocks.
+* sync: restore GOMAXPROCS during benchmarks.
+* syscall: add LSF support for linux (thanks Mikio Hara),
+ add socket control message support for darwin, freebsd, linux (thanks Mikio Hara),
+ add tty support to StartProcess (thanks Ken Rockot),
+ fix build for Sizeof change.
+* test: test of goto restrictions.
+* time: add support for Plan 9 (thanks Anthony Martin).
+</pre>
+
+<h2 id="2011-06-16">2011-06-16</h2>
+
+<pre>
+This snapshot includes changes to the sort and image/draw packages that will
+require changes to client code.
+
+The sort.IntArray type has been renamed to IntSlice, and similarly for
+StringArray and Float64Array.
+
+The image/draw package's Draw function now takes an additional argument,
+a compositing operator. If in doubt, use draw.Over.
+
+Other changes:
+* build: fix header files for Plan 9 (thanks Lucio De Re).
+* cgo: handle new Apple LLVM-based gcc from Xcode 4.2.
+* crypto/openpgp: add ability to encrypt and sign messages.
+* doc/gopher: add goggled gopher logo for App Engine.
+* doc: Update notes for 3-day Go course.
+* exec: make LookPath work when PATHEXT var not set on Windows (thanks Alex Brainman).
+* exp/regexp/syntax: syntax data structures, parser, escapes, character classes.
+* exp/template: lexical scanner for new template package.
+* fmt: debugging formats for characters: %+q %#U.
+* gc: frame compaction for arm,
+ handle go print() and go println(),
+ work around goto bug.
+* go/build: fixes, self-contained tests.
+* go/printer, gofmt: print "select {}" on one line.
+* godoc: replace OS file system accesses in favor of a FileSystem interface.
+* gofix: fix inconsistent indentation in help output (thanks Scott Lawrence).
+* goinstall: use go/build package to scan and build packages.
+* http/spdy: improve error handling (thanks William Chan).
+* http: use runtime/debug.Stack() to dump stack trace on panic.
+* ld: dwarf emit filenames in debug_line header instead of as extended opcodes,
+ fix link Windows PE __declspec(dllimport) symbol (thanks Wei Guangjing),
+ make .rodata section read-only (thanks Gustavo Niemeyer).
+* mail: decode RFC 2047 "B" encoding.
+* mime/multipart: remove temp files after tests on Windows (thanks Alex Brainman).
+* net: export all fields in Interface (thanks Mikio Hara),
+ rearrange source to run more tests on Windows (thanks Alex Brainman),
+ sendfile for win32 (thanks Yasuhiro Matsumoto).
+* os: Plan 9, fix OpenFile & Chmod, add Process.Kill (thanks Yuval Pavel Zholkover).
+* runtime: fix Plan 9 "lingering goroutines bug" (thanks Yuval Pavel Zholkover).
+* spec: clarify rules for append, scope rules for :=,
+ specify constant conversions,
+ unsafe.Alignof/Offsetof/Sizeof return uintptr.
+* syscall, os, exec: add *syscall.SysProcAttr field to os.ProcAttr and exec.Cmd.
+* syscall: add ptrace on darwin (thanks Jeff Hodges),
+ mksyscall_windows.pl should output unix newline (thanks Yasuhiro Matsumoto).
+ update BPF support for BSD variants (thanks Mikio Hara),
+ use strict in perl scripts (thanks Yasuhiro Matsumoto).
+* xml: handle non-string attribute fields (thanks Maxim Ushakov).
+</pre>
+
+<h2 id="2011-06-09">2011-06-09 (<a href="release.html#r58">base for r58</a>)</h2>
+
+<pre>
+This snapshot includes changes to the strconv, http, and exp/draw packages.
+Client code that uses the http or exp/draw packages will need to be changed,
+and code that uses strconv or fmt's "%q" formatting directive merits checking.
+
+The strconv package's Quote function now escapes only those Unicode code points
+not classified as printable by unicode.IsPrint. Previously Quote would escape
+all non-ASCII characters. This also affects the fmt package's "%q" formatting
+directive. The previous quoting behavior is still available via strconv's new
+QuoteToASCII function.
+
+Most instances of the type map[string][]string in the http package have been
+replaced with the new Values type. The http.Values type has the Get, Set, Add,
+and Del helper methods to make working with query parameters and form values
+more convenient.
+
+The exp/draw package has been split into the image/draw and exp/gui packages.
+
+Other changes:
+* 8l, ld: initial adjustments for Plan 9 native compilation of 8l (thanks Lucio De Re).
+* arm: floating point improvements (thanks Fan Hongjian).
+* big: Improved speed of nat-to-string conversion (thanks Michael T. Jones),
+ Rat outputs the requested precision from FloatString (thanks Graham Miller),
+ gobs for big.Rats.
+* cgo: support non intel gcc machine flags (thanks Dave Cheney).
+* compress/lzw: do not use background goroutines,
+ reduce decoder buffer size from 3*4096 to 2*4096.
+* crypto/twofish: fix Reset index overflow bug.
+* crypto: reorg, cleanup and add function for generating CRLs.
+* exec: export the underlying *os.Process in Cmd.
+* gc: enable building under clang/2.9 (thanks Dave Cheney),
+ preparatory work toward escape analysis, compact stack frames.
+* go/build: new incomplete package for building go programs.
+* godefs: do not assume forward type references are enums (thanks Robert Hencke).
+* gofix, gofmt: fix diff regression from exec change.
+* html: improve attribute parsing, note package status.
+* http: don't fail on accept hitting EMFILE,
+ fix handling of 0-length HTTP requests.
+* image/draw: fix clipping bug where sp/mp were not shifted when r.Min was.
+* image/gif: fix buglet in graphics extension.
+* image/tiff: support for bit depths other than 8 (thanks Benny Siegert).
+* ld: fix and simplify ELF symbol generation (thanks Anthony Martin)
+* libmach: use the standardized format for designated initializers (thanks Jeff Hodges)
+* mail: address list parsing.
+* net: add network interface identification API (thanks Mikio Hara),
+ fix bug in net.Interfaces: handle elastic sdl_data size correctly (thanks Mikio Hara).
+* netchan: added drain method to importer (thanks David Jakob Fritz).
+* os: add Process.Kill and Process.Signal (thanks Evan Shaw),
+ fix Getenv for Plan 9 (thanks Yuval Pavel Zholkover).
+* runtime: improve memmove by checking memory overlap (thanks Quan Yong Zhai),
+ support for Linux grsecurity systems (thanks Jonathan Mark).
+* spec: handle a corner case for shifts.
+* testing: check that tests and benchmarks do not affect GOMAXPROCS (thanks Dmitriy Vyukov).
+* unicode: add IsPrint and related properties, general categories.
+</pre>
+
+<h2 id="2011-06-02">2011-06-02</h2>
+
+<pre>
+This snapshot includes changes to the exec package that will require changes
+to client code.
+
+The exec package has been re-designed with a more convenient and succinct API.
+This code:
+ args := []string{"diff", "-u", "file1.txt", "file2.txt"}
+ p, err := exec.Run("/usr/bin/diff", args, os.Environ(), "",
+ exec.DevNull, exec.Pipe, exec.DevNull)
+ if err != nil {
+ return nil, err
+ }
+ var buf bytes.Buffer
+ io.Copy(&buf, p.Stdout)
+ w, err := p.Wait(0)
+ p.Close()
+ if err != nil {
+ return nil, err
+ }
+ return buf.Bytes(), err
+can be rewritten as:
+ return exec.Command("diff", "-u", "file1.txt", "file2.txt").Output()
+See the exec package documentation for the details ("godoc exec").
+
+By setting the GOPATH environment variable you can use goinstall to build and
+install your own code and external libraries outside of the Go tree (and avoid
+writing Makefiles).
+See the goinstall command documentation for the details ("godoc goinstall").
+
+Other changes:
+* 5g: alignment fixes.
+* 6l, 8l: fix Mach-O binaries with many dynamic libraries.
+* 8l: emit resources (.rsrc) in Windows PE. (thanks Wei Guangjing).
+* asn1: fix marshalling of empty optional RawValues (thanks Mikkel Krautz).
+* big: make Int and Rat implement fmt.Scanner (thanks Evan Shaw),
+ ~8x faster number scanning,
+ remove some unnecessary conversions.
+* cgo: restrict #cgo directives to prevent shell expansion (thanks Gustavo Niemeyer),
+ support pkg-config for flags and libs (thanks Gustavo Niemeyer).
+* compress/flate: fix Huffman tree bug,
+ do not use background goroutines.
+* crypto/openpgp: add support for symmetrically encrypting files.
+* crypto/tls/generate_cert.go: fix misspelling of O_CREATE.
+* dashboard: send notification emails when the build breaks.
+* doc: mention go/printer instead of container/vector in effective go,
+ put Release History link on 'Documentation' page,
+ put Weekly Snapshot History link on 'Contributing' page.
+* encoding/base64: add DecodeString and EncodeToString.
+* encoding/binary: add a non-reflect fast path for Read,
+ add a non-reflect fast path for Write.
+* encoding/hex: add hex dumping.
+* encoding/line: delete package. Its functionality is now in bufio.
+* filepath: Abs must always return a clean path (thanks Gustavo Niemeyer).
+* fmt: fix bug in UnreadRune,
+ make %q work for integers, printing a quoted character literal,
+ return EOF when out of input in Scan*.
+* gc: check parameter declarations in interface fields (thanks Anthony Martin),
+ disallow ... in type conversions (thanks Anthony Martin),
+ do not force heap allocation on referencing outer variable in a closure,
+ fix m[x], _ = y.(T),
+ implement new shift rules,
+ patch y.tab.c to fix build when using Bison 2.5,
+ relax assignability of method receivers (thanks Anthony Martin),
+ typecheck the whole tree before walking.
+* go/scanner: don't allow "0x" and "0X" as integers (thanks Evan Shaw).
+* gobuilder: fixes for windows (thanks Alex Brainman).
+* godoc: basic setup for running godoc on local app engine emulator,
+ display advert for the package dashboard on package list page.
+* goinstall: fixes for windows (thanks Alex Brainman),
+ more verbose logging with -v.
+* gotest, pkg/exec: use bash to run shell scripts on windows (thanks Alex Brainman).
+* http/spdy: redo interfaces, flesh out implementation & frame types (thanks William Chan).
+* http: Transport hook to register non-http(s) protocols,
+ add client+server benchmark,
+ catch Handler goroutine panics,
+ fix Set-Cookie date parsing,
+ have client set Content-Length when possible,
+ let Transport use a custom net.Dial function,
+ propagate Set-Cookie in reverse proxy,
+ ServeFile shouldn't send Content-Length when Content-Encoding is set.
+* image: add a SubImage method.
+* image/gif: simplify blockReader.Read.
+* image/png: fix encoding of images that don't start at (0, 0).
+* io, net, http: sendfile support.
+* io: add ByteScanner, RuneScanner interfaces.
+* ld: add -w to disable dwarf, make errors obviously from dwarf.
+* mail: new package.
+* mime/multipart: misc code/doc fixes.
+* misc/cgo: remove reference to 'destroy' function.
+* misc/emacs: don't select the mark after gofmt (thanks Eric Eisner).
+* misc/gophertool: Chrome extension to aid in Go development
+* misc/vim: limit Fmt command to Go buffers (thanks Yasuhiro Matsumoto).
+* net: if we stop polling, remove any pending events for the socket,
+ update IP multicast socket options (thanks Mikio Hara).
+* os: Fix test to work on Solaris,
+ fix Readdir(0) on EOF,
+ fix Readdir, Readdirnames (thanks Yuval Pavel Zholkover),
+ fix os.MkdirAll with backslash path separator (thanks Yasuhiro Matsumoto),
+ handle OpenFile flag parameter properly on Windows (thanks Alex Brainman).
+* path/filepath: remove string constants.
+* pkg: spelling tweaks, I-Z (thanks Robert Hencke).
+* quietgcc: fix typo, respect $TMPDIR.
+* runtime: do not garbage collect windows callbacks (thanks Alex Brainman),
+ fix mmap error return on linux (thanks Dmitry Chestnykh),
+ reset GOMAXPROCS during tests,
+ save cdecl registers in Windows SEH handler (thanks Alexey Borzenkov).
+* spec: be precise with the use of the informal ellipsis and the Go token,
+ clarify rules for shifts.
+* strconv: add QuoteRune; analogous to Quote but for runes rather than strings.
+* strings: implement UnreadByte, UnreadRune.
+* sync: always wake up sleeping goroutines on Cond.Signal (thanks Gustavo Niemeyer).
+* sync/atomic: fix check64.
+* syscall: add ProcAttr field to pass an unescaped command line on windows (thanks Vincent Vanackere),
+ add routing messages support for Linux and BSD (thanks Mikio Hara).
+* template: fixes and clean-ups (thanks Gustavo Niemeyer).
+* time: fix Format bug: midnight/noon are 12AM/PM not 0AM/PM.
+* unicode: make the tables smaller.
+</pre>
+
+<h2 id="2011-05-22">2011-05-22</h2>
+
+<pre>
+This snapshot includes changes to the http package that will require changes to
+client code.
+
+The finalURL return value of the Client.Get method has been removed.
+This value is now accessible via the new Request field on http.Response.
+For example, this code:
+
+ res, finalURL, err := http.Get(...)
+
+should be rewritten as:
+
+ res, err := http.Get(...)
+ if err != nil {
+ // ...
+ }
+ finalURL := res.Request.URL.String()
+
+Uses of http.Get that assign the finalURL value to _ can be rewritten
+automatically with gofix.
+
+This snapshot also includes an optimization to the append function that makes it
+between 2 and 5 times faster in typical use cases.
+
+Other changes:
+* 5a, 6a, 8a, cc: remove old environment variables.
+* 5c, 5g: fix build with too-smart gcc.
+* 5l, 8l: add ELF symbol table to binary.
+* 5l: delete pre-ARMv4 instruction implementations, other fixes.
+* 6l, 8l: emit windows dwarf sections like other platforms (thanks Alex Brainman).
+* 6l: fix emit windows dwarf sections (thanks Wei Guangjing).
+* 8g: fix conversion from float to uint64 (thanks Anthony Martin).
+* Make.cmd: create TARGDIR if necessary (thanks Gustavo Niemeyer).
+* asn1: add big support.
+* big: add Int methods to act on numbered bits (thanks Roger Peppe),
+ better support for string conversions,
+ support %v and # modifier, better handling of unknown formats.
+* cgi: export RequestFromMap (thanks Evan Shaw),
+ set Request.TLS and Request.RemoteAddr for children.
+* cgo: use packed struct to fix Windows behavior.
+* codereview: add release branch support,
+ fetch metadata using JSON API, not XML scraping,
+ handle 'null as missing field' in rietveld json.
+* compress/lzw: silently drop implied codes that are too large.
+* compress/zlib: actually use provided dictionary in NewWriterDict
+* crypto/openpgp: add key generation support,
+ change PublicKey.Serialize to include the header.
+* crypto/rand: add utility functions for number generation (thanks Anthony Martin).
+* crypto/tls: export the verified chains.
+* crypto/x509/crl: add package.
+* crypto/x509: export raw SubjectPublicKeyInfo,
+ support DSA public keys in X.509 certs,
+ support parsing and verifying DSA signatures (thanks Jonathan Allie).
+* doc/roadmap: put "App Engine support" under "Done".
+* doc: add I/O 2011 talks to talks/, docs.html, and front page.
+* effective go: explain about values/pointers in String() example,
+ update to new Open signature.
+* exp/draw: fast paths for drawing a YCbCr or an NRGBA onto an RGBA.
+* filepath: make EvalSymlinks work on Windows (thanks Alex Brainman).
+* flag: allow distinct sets of flags.
+* gc: fix type switch error message for invalid cases (thanks Lorenzo Stoakes),
+ fix unsafe.Sizeof,
+ preserve original expression for errors.
+* go/ast, go/doc, godoc: consider struct fields and interface methods when filtering ASTs.
+* go/ast: consider anonymous fields and set Incomplete bit when filtering ASTs,
+ properly maintain map of package global imports.
+* go/doc, godoc: when filtering for godoc, don't remove elements of a declaration.
+* go/parser: accept parenthesized receive operations in select statements,
+ always introduce an ast.Object when declaring an identifier.
+* go/printer, gofmt: fix alignment of "=" in const/var declarations,
+ fix formatting of expression lists (missing blank).
+* go/printer: added simple performance benchmark,
+ make tests follow syntactic restrictions,
+ more accurate comment for incomplete structs/interfaces,
+* go/token: faster FileSet.Position implementation.
+* go/types: type checker API + testing infrastructure.
+* godoc: added -index flag to enable/disable search index,
+ if there is no search box, don't run the respective JS code.
+* gofmt: update test.sh (exclude a file w/ incorrect syntax).
+* html: parse empty, unquoted, and single-quoted attribute values.
+* http/cgi: correctly set request Content-Type (thanks Evan Shaw),
+ pass down environment variables for IRIX and Solaris.
+* http/pprof: fix POST reading bug.
+* http/spdy: new incomplete package (thanks Ross Light).
+* http: Client.Do should follow redirects for GET and HEAD,
+ add Header.Write method (thanks Evan Shaw),
+ add Request.SetBasicAuth method,
+ add Transport.ProxySelector,
+ add http.SetCookie(ResponseWriter, *Cookie),
+ don't Clean query string in relative redirects,
+ fix FormFile nil pointer dereference on missing multipart form,
+ fix racy test with a simpler version,
+ fix two Transport gzip+persist crashes,
+ include Host header in requests,
+ make HEAD client request follow redirects (thanks Eivind Uggedal).
+ update cookie doc to reference new RFC 6265,
+ write cookies according to RFC 6265 (thanks Christian Himpel).
+* image/bmp: implement a BMP decoder.
+* image/gif: new package provides a GIF decoder.
+* image/jpeg: decode grayscale images, not just color images.
+ optimizations and tweaks.
+* image/png: encode paletted images with alpha channel (thanks Dmitry Chestnykh),
+ speed up opaque RGBA encoding.
+* image/tiff: implement a decoder (thanks Benny Siegert).
+* image: add type-specific Set methods and use them when decoding PNG,
+ make AlphaColor.Set conform to usual signature (thanks Roger Peppe),
+ png & jpeg encoding benchmarks.
+* ld: do not emit reference to dynamic library named "",
+ fix alignment of rodata section on Plan 9 (thanks Anthony Martin),
+ make ELF binaries with no shared library dependencies static binaries.
+* make.bash: remove old bash version of gotest on Windows (thanks Alex Brainman).
+* make: add nuke target for C commands and libs (thanks Anthony Martin).
+* mime/multipart: add FileName accessor on Part,
+ add Writer,
+ return an error on Reader EOF, not (nil, nil).
+* misc/cgo/test: run tests.
+* misc/emacs: use UTF-8 when invoking gofmt as a subprocess (thanks Sameer Ajmani).
+* misc/vim: new Vim indentation script.
+* net, http: add and make use of IP address scope identification API (thanks Mikio Hara).
+* net: default to 127.0.0.1, not localhost, in TestICMP,
+ don't crash on unexpected DNS SRV responses,
+ enable SO_REUSEPORT on BSD variants (thanks Mikio Hara),
+ protocol family adaptive address family selection (thanks Mikio Hara),
+ re-enable wildcard listening (thanks Mikio Hara),
+ sort records returned by LookupSRV (thanks Gary Burd).
+* os: make Readdir & Readdirnames return os.EOF at end,
+ make Setenv update C environment variables.
+* reflect: allow unexported key in Value.MapIndex.
+* runtime, sync/atomic: fix arm cas.
+* runtime: add newline to "finalizer already set" error (thanks Albert Strasheim),
+ handle out-of-threads on Linux gracefully (thanks Albert Strasheim),
+ fix function args not checked warning on ARM (thanks Dave Cheney),
+ make StackSystem part of StackGuard (thanks Alexey Borzenkov),
+ maybe fix Windows build broken by cgo setenv CL.
+* spec: clarify semantics of integer division,
+ clarify semantics of range clause,
+ fix error in production syntax,
+ narrow syntax for expression and select statements,
+ newlines cannot be used inside a char or "" string literal,
+ restricted expressions may still be parenthesized.
+* strings: make Reader.Read use copy instead of an explicit loop.
+* syscall: add Windows file mapping functions and constants (thanks Evan Shaw),
+ add IPv6 scope zone ID support (thanks Mikio Hara),
+ add netlink support for linux/386, linux/amd64, linux/arm (thanks Mikio Hara),
+ add Sendfile,
+ adjust freebsd syscalls.master URL properly (thanks Mikio Hara),
+ change Overlapped.HEvent type, it is a handle (thanks Alex Brainman).
+* syslog: fix skipping of net tests (thanks Gustavo Niemeyer).
+* template: support string, int and float literals (thanks Gustavo Niemeyer).
+* xml: fix reflect error.
+</pre>
+
+<h2 id="2011-04-27">2011-04-27 (<a href="release.html#r57">base for r57</a>)</h2>
+
+<pre>
+This snapshot includes revisions to the reflect package to make it more
+efficient, after the last weekly's major API update. If your code uses reflect
+it may require further changes, not all of which can be made automatically by
+gofix. For the full details of the change, see
+ http://codereview.appspot.com/4435042
+Also, the Typeof and NewValue functions have been renamed to TypeOf and ValueOf.
+
+Other changes:
+* 5c: make alignment rules match 5g, just like 6c matches 6g.
+* 8g, 8l: fix "set but not used" gcc error (thanks Fazlul Shahriar).
+* all-qemu.bash: remove DISABLE_NET_TESTS.
+* build: remove DISABLE_NET_TESTS.
+* builder: build multiple targets in parallel.
+* cgo: avoid "incompatible pointer type" warning (thanks Albert Strasheim).
+* codereview: add 'hg undo' command, various other fixes.
+* compress/flate: dictionary support.
+* compress/zlib: add FDICT flag in Reader/Writer (thanks Ross Light).
+* container/heap: fix circular dependency in test.
+* crypto/openpgp: better handling of keyrings.
+* crypto/rsa: support > 3 primes.
+* crypto/tls: add server-side OCSP stapling support.
+* crypto/x509: memorize chain building.
+* crypto: move certificate verification into x509.
+* dashboard: build most recent revision first.
+* doc: mention make version in install.html.
+* expvar: add Func for functions that return values that are JSON marshalable.
+* fmt: decrease recursion depth in tests to permit them to run under gccgo,
+ tweak the doc for %U.
+* gc: allow complex types to be receiver types (thanks Robert Hencke),
+ correct handling of unexported method names in embedded interfaces,
+ explain why invalid receiver types are invalid,
+ fix copy([]int, string) error message (thanks Quan Yong Zhai),
+ fix 'invalid recursive type' error (thanks Lorenzo Stoakes),
+ many bug fixes.
+* go spec: attempt at clarifying language for "append",
+ for map types, mention indexing operations.
+* go/types: update for export data format change.
+* gob: fix handling of indirect receivers for GobDecoders,
+ fix trivial bug in map marshaling,
+ have errorf always prefix the message with "gob: ",
+ test case for indirection to large field,
+ use new Implements and AssignableTo methods in reflect,
+ when decoding a string, allocate a string, not a []byte.
+* gobuilder: permit builders of the form goos-goarch-foo,
+ respect MAKEFLAGS if provided (thanks Dave Cheney).
+* godoc: use "search" input type for search box (thanks Dmitry Chestnykh).
+* gofix: add support for reflect rename.
+* gofmt: add -d (diff) (thanks David Crawshaw),
+ don't crash when rewriting nil interfaces in AST,
+ exclude test case that doesn't compile w/o errors,
+ gofmt test harness bug fix.
+* goinstall: support GOPATH; building and installing outside the Go tree,
+ support building executable commands.
+* gopack: fix prefix bug,
+ preserve safe flag when not adding unsafe objects to archive.
+* gotest: add timing, respect $GOARCH,
+ generate gofmt-compliant code.
+* http/cgi: copy some PATH environment variables to child,
+ improve Location response handling,
+ pass some default environment variables.
+* http/fcgi: new package (thanks Evan Shaw).
+* http: add NewRequest helper,
+ add MultipartForm, ParseMultipartForm, and FormFile to Request,
+ be clear when failing to connect to a proxy,
+ bug fixes and new tests,
+ consume request bodies before replying,
+ don't quote Set-Cookie Domain and Path (thanks Petar Maymounkov),
+ fix IP confusion in TestServerTimeouts,
+ handler timeout support,
+ ServerConn, ClientConn: add real Close (thanks Petar Maymounkov),
+ make Client redirect policy configurable,
+ put a limit on POST size,
+ reverse proxy handler.
+* image/jpeg: add an encoder,
+ decode to a YCbCr image instead of an RGBA image.
+* ioutil: add Discard.
+* json: keep track of error offset in SyntaxError.
+* ld: defend against some broken object files,
+ do not emit empty dwarf pe sections (thanks Alex Brainman),
+ fix 6l -d on Mac, diagnose invalid use of -d,
+ fix Plan 9 symbol table (thanks Anthony Martin),
+ remove MachoLoad limit.
+* make: prevent rm provoking 'text file busy' errors (thanks Lorenzo Stoakes).
+* mime/multipart: add ReadForm for parsing multipart forms,
+ limit line length to prevent abuse.
+* mime: RFC 2231 continuation / non-ASCII support,
+ bunch more tests, few minor parsing fixes.
+* misc/goplay: fix Tab and Shift+Enter in Firefox (thanks Dmitry Chestnykh).
+* net: disable one more external network test,
+ fix EAI_BADFLAGS error on freebsd (thanks Mikio Hara),
+ fix ParseIP (thanks Quan Yong Zhai),
+ fix dialgoogle_test.go (thanks Quan Yong Zhai),
+ try /etc/hosts before loading DNS config (thanks Dmitry Chestnykh),
+ use C library resolver on FreeBSD, Linux, OS X / amd64, 386.
+* os/user: new package to look up users.
+* os: Open with O_APPEND|O_CREATE to append on Windows (thanks Alex Brainman),
+ fix race in ReadAt/WriteAt on Windows (thanks Alex Brainman),
+ turn EPIPE exit into panic.
+* rc/env.bash: fix to build on windows under msys (thanks Joe Poirier).
+* reflect: allow Slice of arrays,
+ fix Copy of arrays (thanks Gustavo Niemeyer),
+ require package qualifiers to match during interface check,
+ add Type.Implements, Type.AssignableTo, Value.CallSlice,
+ make Set match Go.
+* rpc: allow the first argument of a method to be a value rather than a pointer,
+ run benchmarks over HTTP as well as direct network connections.
+* run.bash: remove redundant rebuilds.
+* runtime/plan9: warning remediation for Plan 9 (thanks Lucio De Re),
+* runtime: many bug fixes,
+ fix GOMAXPROCS vs garbage collection bug (thanks Dmitriy Vyukov),
+ fix mkversion to output valid path separators (thanks Peter Mundy),
+ more graceful out-of-memory crash,
+ require package qualifiers to match during interface check,
+ skip functions with no lines when building src line table,
+ turn "too many EPIPE" into real SIGPIPE.
+* src/pkg: make package doc comments consistently start with "Package foo".
+* syscall: Madvise and Mprotect for Linux (thanks Albert Strasheim),
+ Mlock, Munlock, Mlockall, Munlockall on Linux (thanks Albert Strasheim),
+ add BPF support for darwin/386, darwin/amd64 (thanks Mikio Hara),
+ correct Windows CreateProcess input parameters (thanks Alex Brainman),
+ fix Ftruncate under linux/arm5 (thanks Dave Cheney),
+ permit StartProcess to hide the executed program on windows (thanks Vincent Vanackere).
+* test/bench: update timings; moving to new machine.
+* time: support Irix 6 location for zoneinfo files.
+* tutorial: modernize the definition and use of Open,
+ replace the forever loops with finite counts in sieve programs.
+* websocket: include *http.Request in websocket.Conn.
+* xml: Parser hook for non-UTF-8 charset converters.
+</pre>
+
+<h2 id="2011-04-13">2011-04-13</h2>
+
+<pre>
+weekly.2011-04-13
+
+This weekly snapshot includes major changes to the reflect package and the
+os.Open function. Code that uses reflect or os.Open will require updating,
+which can be done mechanically using the gofix tool.
+
+The reflect package's Type and Value types have changed. Type is now an
+interface that implements all the possible type methods. Instead of a type
+switch on a reflect.Type t, switch on t.Kind(). Value is now a struct value
+that implements all the possible value methods. Instead of a type switch on a
+reflect.Value v, switch on v.Kind(). See the change for the full details:
+ http://code.google.com/p/go/source/detail?r=843855f3c026
+
+The os package's Open function has been replaced by three functions:
+ OpenFile(name, flag, perm) // same as old Open
+ Open(name) // same as old Open(name, O_RDONLY, 0)
+ Create(name) // same as old Open(name, O_RDWR|O_TRUNC|O_CREAT, 0666)
+
+To update your code to use the new APIs, run "gofix path/to/code". Gofix can't
+handle all situations perfectly, so read and test the changes it makes before
+committing them.
+
+Other changes:
+* archive/zip: add func OpenReader, type ReadCloser (thanks Dmitry Chestnykh).
+* asn1: Implement correct marshaling of length octets (thanks Luit van Drongelen).
+* big: don't crash when printing nil ints.
+* bufio: add ReadLine, to replace encoding/line.
+* build: make the build faster, quieter.
+* codereview: automatically port old diffs forward,
+ drop Author: line on self-clpatch,
+ recognize code URL without trailing slash.
+* crypto/block: remove deprecated package.
+* crypto/des: new package implementating DES and TDEA (thanks Yasuhiro Matsumoto).
+* crypto/ecdsa, crypto/rsa: use io.ReadFull to read from random source (thanks Dmitry Chestnykh).
+* crypto/rsa: add 3-prime support,
+ add support for precomputing CRT values,
+ flip the CRT code over so that it matches PKCS#1.
+* crypto/x509: expose complete DER data (thanks Mikkel Krautz).
+* doc: new "Functions" codewalk (thanks John DeNero).
+* doc/roadmap: add sections on tools, packages.
+* fmt: allow %U for unsigned integers.
+* gc: fixes and optimizations.
+* go/printer, gofmt: use blank to separate import rename from import path.
+* go/scanner: better TokenString output.
+* go/types: new Go type hierarchy implementation for AST.
+* godashboard: show packages at launchpad.net (thanks Gustavo Niemeyer).
+* gofix: add -diff, various fixes and helpers.
+* gotest: fix a bug in error handling,
+ fixes for [^.]_test file pattern (thanks Peter Mundy),
+ handle \r\n returned by gomake on Windows (thanks Alex Brainman).
+* gotype: use go/types GcImporter.
+* govet: make name-matching for printf etc. case-insensitive.
+* http: allow override of Content-Type for ServeFile,
+ client gzip support,
+ do not listen on 0.0.0.0 during test,
+ flesh out server Expect handling + tests.
+* image/ycbcr: new package.
+* image: allow "?" wildcards when registering image formats.
+* io: fixes for Read with n > 0, os.EOF (thanks Robert Hencke).
+* ld: correct Plan 9 compiler warnings (thanks Lucio De Re),
+ ELF header function declarations (thanks Lucio De Re),
+ fix Mach-O X86_64_RELOC_SIGNED relocations (thanks Mikkel Krautz),
+ fix Mach-O bss bug (thanks Mikkel Krautz),
+ fix dwarf decoding of strings for struct's fieldnames (thanks Luuk van Dijk),
+ fixes and optimizations (25% faster).
+* log: generalize getting and setting flags and prefix.
+* misc/cgo/life: enable build and test on Windows (thanks Alex Brainman).
+* misc/vim: add plugin with Fmt command (thanks Dmitry Chestnykh),
+ update type highlighting for new reflect package.
+* net: disable multicast tests by default (thanks Dave Cheney),
+ sort records returned by LookupMX (thanks Corey Thomasson).
+* openpgp: Fix improper := shadowing (thanks Gustavo Niemeyer).
+* os: rename Open to OpenFile, add new Open, Create,
+ fix Readdir in Plan 9 (thanks Fazlul Shahriar).
+* os/inotify: use _test for test files, not _obj.
+* pkg/path: enable tests on Windows (thanks Alex Brainman).
+* reflect: new Type and Value API.
+* src/pkg/Makefile: trim per-directory make output except on failure.
+* syscall: Add DT_* and MADV_* constants on Linux (thanks Albert Strasheim),
+ add Mmap, Munmap on Linux, FreeBSD, OS X,
+ fix StartProcess in Plan 9 (thanks Fazlul Shahriar),
+ fix Windows Signaled (thanks Alex Brainman).
+* test/bench: enable build and test on Windows (thanks Alex Brainman).
+</pre>
+
+<h2 id="2011-04-04">2011-04-04</h2>
+
+<pre>
+This snapshot includes changes to the net package. Your code will require
+changes if it uses the Dial or LookupHost functions.
+
+The laddr argument has been removed from net.Dial, and the cname return value
+has been removed from net.LookupHost. The new net.LookupCNAME function can be
+used to find the canonical host for a given name. You can update your
+networking code with gofix.
+
+The gotest shell script has been replaced by a Go program, making testing
+significantly faster.
+
+Other changes:
+* asn1: extensions needed for parsing Kerberos.
+* bufio: Write and WriteString cleanup (thanks Evan Shaw).
+* bytes, strings: simplify Join (thanks Evan Shaw).
+* crypto/cipher: bad CTR IV length now triggers panic.
+* crypto/tls: extend NPN support to the client,
+ added X509KeyPair function to parse a Certificate from memory.
+* crypto/x509: parse Extended Key Usage extension (thanks Mikkel Krautz).
+* debug/gosym: remove need for gotest to run preparatory commands.
+* fmt: implement precision (length of input) values for %q: %.20q.
+* go/parser: fix scoping for local type declarations (thanks Roger Peppe),
+ package name must not be the blank identifier.
+* go/printer, gofmt: remove special case for multi-line raw strings.
+* gopack: add P flag to remove prefix from filename information.
+* gotest: add -test.timeout option,
+ replace the shell script with the compiled program written in go,
+ execute gomake properly on Windows (thanks Alex Brainman).
+* gotry: move into its own directory, separate from gotest.
+* gotype: support for more tests, added one new test.
+* http: add Transport.MaxIdleConnsPerHost,
+ use upper case hex in URL escaping (thanks Matt Jones).
+* httptest: add NewTLSServer.
+* misc/kate: reorganize, remove closed() (thanks Evan Shaw).
+* misc/notepadplus: support for notepad++ (thanks Anthony Starks).
+* net: implement non-blocking connect (thanks Alexey Borzenkov).
+* os: fix MkdirAll("/thisdoesnotexist") (thanks Albert Strasheim),
+ Plan 9 support (thanks Yuval Pavel Zholkover),
+ add a few missing Plan 9 errors (thanks Andrey Mirtchovski),
+ fix FileInfo.Name returned by Stat (thanks David Forsythe).
+* path/filepath.Glob: add an error return,
+ don't drop known matches on error.
+* path/filepath: add support for Plan 9 (thanks Andrey Mirtchovski).
+* scanner: treat line comments like in Go.
+* syscall: Plan 9 support (thanks Yuval Pavel Zholkover),
+ StartProcess Chroot and Credential (thanks Albert Strasheim),
+ add BPF support for freebsd/386, freebsd/amd64 (thanks Mikio Hara),
+ make [Raw]Syscall6 pass 6th arg on linux/386 (thanks Evan Shaw).
+</pre>
+
+<h2 id="2011-03-28">2011-03-28</h2>
+
+<pre>
+This weekly release includes improved support for testing.
+
+Memory and CPU profiling is now available via the gotest tool. Gotest will
+produce memory and CPU profiling data when invoked with the -test.memprofile
+and -test.cpuprofile flags. Run "godoc gotest" for details.
+
+We have also introduced a way for tests to run quickly when an exhaustive test
+is unnecessary. Gotest's new -test.short flag in combination with the testing
+package's new Short function allows you to write tests that can be run in
+normal or "short" mode; short mode is now used by all.bash to reduce
+installation time.
+The Makefiles know about the flag - you can just run "make testshort".
+
+Other changes:
+* .hgignore: Ignore all goinstalled packages (thanks Evan Shaw).
+* build: add all-qemu.bash, handful of arm fixes,
+ add support for SWIG, and add two SWIG examples,
+ diagnose Ubuntu's buggy copy of gold,
+ handle broken awk in version.bash (thanks Dave Cheney),
+ reenable clean.bash without gomake (thanks Gustavo Niemeyer).
+* cgo: fix index-out-of-bounds bug.
+* codereview: permit CLs of the form weekly.DATE
+* crypto/ecdsa: truncate hash values.
+* crypto/openpgp: add DSA signature support.
+* dashboard: remove old python/bash builder, update README.
+* doc: explain release and weekly tags in install.html.
+* exec: document dir option for Run (thanks Gustavo Niemeyer).
+* flag: document Nflag function (thanks Fazlul Shahriar).
+* gc: remove interim ... error which rejects valid code.
+* go/ast: implemented NewPackage,
+ merge CaseClause and TypeCaseClause.
+* go/parser: fix memory leak by making a copy of token literals,
+ resolve identifiers properly.
+* go/printer, gofmt: avoid exponential layout algorithm,
+ gofmt: simplify struct formatting and respect line breaks.
+* go/scanner: to interpret line comments with Windows filenames (thanks Alex Brainman).
+* go/token: use array instead of map for token->string table.
+* gob: optimizations to reduce allocations,
+ use pointers in bootstrapType so interfaces behave properly.
+* gobuilder: recognize CLs of the form weekly.DATE.
+* godefs: handle volatile.
+* godoc: add -template flag to specify custom templates,
+ fix path problem for windows (thanks Yasuhiro Matsumoto).
+* gofix: httpserver - rewrite rw.SetHeader to rw.Header.Set.
+* gofmt: add profiling flag.
+* gopprof: fix bug: do not rotate 180 degrees for large scrolls,
+ update list of memory allocation functions.
+* gotest: fix gofmt issue in generated _testmain.go.
+* http: add NewProxyClientConn,
+ avoid crash when asked for multiple file ranges,
+ don't chunk 304 responses,
+ export Transport, add keep-alive support.
+* ld: return > 0 exit code on unsafe import.
+* misc/bbedit: remove closed keyword (thanks Anthony Starks).
+* misc/emacs: gofmt: don't clobber the current buffer on failure.
+* misc/vim: remove 'closed' as a builtin function.
+* net: add FileConn, FilePacketConn, FileListener (thanks Albert Strasheim),
+ don't force epoll/kqueue to wake up in order to add new events,
+ let OS-specific AddFD routine wake up polling thread,
+ use preallocated buffer for epoll and kqueue/kevent.
+* path/filepath: add EvalSymlinks function,
+ fix TestEvalSymlinks when run under symlinked GOROOT.
+* path: work for windows (thanks Yasuhiro Matsumoto).
+* rpc: increase server_test timeout (thanks Gustavo Niemeyer),
+ optimizations to reduce allocations.
+* runtime: fix darwin/amd64 thread VM footprint (thanks Alexey Borzenkov),
+ fix gdb support for goroutines,
+ more stack split fixes,
+ os-specific types and code for setitimer,
+ update defs.h for freebsd-386 (thanks Devon H. O'Dell).
+* strings: Map: avoid allocation when string is unchanged.
+* syscall: GetsockoptInt (thanks Albert Strasheim),
+ StartProcess fixes for windows (thanks Alex Brainman),
+ permit non-blocking syscalls,
+ rename from .sh to .pl, because these files are in Perl.
+* test: enable tests using v, ok := <-ch syntax (thanks Robert Hencke).
+* time: give a helpful message when we can't set the time zone for testing.
+ isolate syscall reference in sys.go.
+</pre>
+
+<h2 id="2011-03-15">2011-03-15</h2>
+
+<pre>
+This week's release introduces a new release tagging scheme. We intend to
+continue with our weekly releases, but have renamed the existing tags from
+"release" to "weekly". The "release" tag will now be applied to one hand-picked
+stable release each month or two.
+
+The revision formerly tagged "release.2011-03-07.1" (now "weekly.2011-03-07.1")
+has been nominated our first stable release, and has been given the tag
+"release.r56". As we tag each stable release we will post an announcement to
+the new golang-announce mailing list:
+ http://groups.google.com/group/golang-announce
+
+You can continue to keep your Go installation updated using "hg update
+release", but now you should only need to update once we tag a new stable
+release, which we will announce here. If you wish to stay at the leading edge,
+you should switch to the weekly tag with "hg update weekly".
+
+
+This weekly release includes significant changes to the language spec and the
+http, os, and syscall packages. Your code may need to be changed. It also
+introduces the new gofix tool.
+
+The closed function has been removed from the language. The syntax for channel
+receives has been changed to return an optional second value, a boolean value
+indicating whether the channel is closed. This code:
+ v := <-ch
+ if closed(ch) {
+ // channel is closed
+ }
+should now be written as:
+ v, ok := <-ch
+ if !ok {
+ // channel is closed
+ }
+
+It is now illegal to declare unused labels, just as it is illegal to declare
+unused local variables.
+
+The new gofix tool finds Go programs that use old APIs and rewrites them to use
+newer ones. After you update to a new Go release, gofix helps make the
+necessary changes to your programs. Gofix will handle the http, os, and syscall
+package changes described below, and we will update the program to keep up with
+future changes to the libraries.
+
+The Hijack and Flush methods have been removed from the http.ResponseWriter
+interface and are accessible via the new http.Hijacker and http.Flusher
+interfaces. The RemoteAddr and UsingTLS methods have been moved from
+http.ResponseWriter to http.Request.
+
+The http.ResponseWriter interface's SetHeader method has been replaced by a
+Header() method that returns the response's http.Header. Caller code needs to
+change. This code:
+ rw.SetHeader("Content-Type", "text/plain")
+should now be written as:
+ rw.Header().Set("Content-Type", "text/plain")
+The os and syscall packages' StartProcess functions now take their final three
+arguments as an *os.ProcAttr and *syscall.ProcAttr values, respectively. This
+code:
+ os.StartProcess(bin, args, env, dir, fds)
+should now be written as:
+ os.StartProcess(bin, args, &os.ProcAttr{Files: fds, Dir: dir, Env: env})
+
+The gob package will now encode and decode values of types that implement the
+gob.GobEncoder and gob.GobDecoder interfaces. This allows types with unexported
+fields to transmit self-consistent descriptions; one instance is big.Int and
+big.Rat.
+
+Other changes:
+* 5l, 6l, 8l: reduce binary size about 40% by omitting symbols for type, string, go.string.
+* 5l, 8l: output missing section symbols (thanks Anthony Martin).
+* 6l, 8l: fix gdb crash.
+* Make.cmd: also clean _test* (thanks Gustavo Niemeyer).
+* big: implemented custom Gob(En/De)coder for Int type.
+* build: remove duplicate dependency in Make.cmd (thanks Robert Hencke),
+ run gotest in misc/cgo/test.
+* codereview.py: don't suggest change -d if user is not CL author (thanks Robert Hencke).
+* compress/lzw: benchmark a range of input sizes.
+* crypto/ecdsa: add package.
+* crypto/elliptic: add the N value of each curve.
+* crypto/openpgp: bug fixes and fix misnamed function.
+* crypto/tls: fix compile error (thanks Dave Cheney).
+* doc: Effective Go: some small cleanups,
+ update FAQ. hello, world is now 1.1MB, down from 1.8MB,
+ update codelab wiki to fix template.Execute argument order.
+* flag: visit the flags in sorted order, for nicer messages.
+* fmt: do not export EOF = -1.
+* fmt: make ScanState.Token more general (thanks Roger Peppe).
+* gc: diagnose unused labels,
+ fix handling of return values named _,
+ include all dependencies in export metadata,
+ make unsafe.Pointer its own kind of type, instead of an equivalent to *any.
+* go/ast, go/parser: populate identifier scopes at parse time.
+* go/ast: add FileSet parameter to ast.Print and ast.Fprint.
+* go/parser: first constant in a constant declaration must have a value.
+* gob: efficiency and reliability fixes.
+* gofmt: remove -trace and -ast flags.
+* goinstall: handle $(GOOS) and $(GOARCH) in filenames,
+ handle .c files with gc when cgo isn't used, and
+ handle .s files with gc (thanks Gustavo Niemeyer).
+* gopack: omit time stamps, makes output deterministic.
+* gotype: commandline tool to typecheck go programs.
+* govet: handle '*' in print format strings.
+* hash: new FNV-1a implementation (thanks Pascal S. de Kloe).
+* http/cgi: child support (e.g. Go CGI under Apache).
+* http: adapt Cookie code to follow IETF draft (thanks Petar Maymounkov),
+ add test for fixed HTTP/1.0 keep-alive issue,
+ don't hit external network in client_test.go,
+ fix transport crash when request URL is nil,
+ rename interface Transport to RoundTripper,
+ run tests even with DISABLE_NET_TESTS=1.
+* httptest: default the Recorder status code to 200 on a Write.
+* io/ioutil: clean-up of ReadAll and ReadFile.
+* ioutil: add NopCloser.
+* ld: preserve symbol sizes during data layout.
+* lib9, libmach: Change GOOS references to GOHOSTOS (thanks Evan Shaw).
+* libmach: correct string comparison to revive 6cov on darwin (thanks Dave Cheney).
+* misc/vim: Add indent script for Vim (thanks Ross Light).
+* net, os, syslog: fixes for Solaris support.
+* net: don't loop to drain wakeup pipe.
+* nm: document -S flag.
+* openpgp: add PublicKey KeyId string accessors.
+* rpc: optimizations, add benchmarks and memory profiling,
+ use httptest.Server for tests (thanks Robert Hencke).
+* runtime: reduce lock contention via wakeup on scheduler unlock,
+ scheduler, cgo reorganization,
+ split non-debugging malloc interface out of debug.go into mem.go.
+* spec: clarify return statement rules.
+* strings: add IndexRune tests, ASCII fast path,
+ better benchmark names; add BenchmarkIndex.
+* syscall: implement Mount and Unmount for linux,
+ implement Reboot for linux.
+* time: fix Time.ZoneOffset documentation (thanks Peter Mundy).
+* tls: move PeerCertificates to ConnectionState.
+</pre>
+
+<h2 id="2011-03-07">2011-03-07 (<a href="release.html#r56">base for r56</a>)</h2>
+
+<pre>
+This release includes changes to the reflect and path packages.
+Code that uses reflect or path may need to be updated.
+
+The reflect package's Value.Addr method has been renamed to Value.UnsafeAddr.
+Code that uses the Addr method will have to call UnsafeAddr instead.
+
+The path package has been split into two packages: path and path/filepath.
+Package path manipulates slash-separated paths, regardless of operating system.
+Package filepath implements the local operating system's native file paths.
+OS-specific functioanlity in pacakge path, such as Walk, moved to filepath.
+
+Other changes:
+* build: fixes and simplifications (thanks Dave Cheney),
+ move $GOBIN ahead of /bin, /usr/bin in build $PATH.
+* bzip2: speed up decompression.
+* cgo: fix dwarf type parsing (thanks Gustavo Niemeyer),
+ put temporary source files in _obj (thanks Roger Peppe),
+ fix bug involving 0-argument callbacks.
+* compress/lzw: optimizations.
+* doc: add FAQ about "implements",
+ add FAQ about large binaries ,
+ add FAQ about stack vs heap allocation,
+ add internationalization to roadmap,
+ describe platform-specific conventions in code.html.
+* fmt: allow recursive calls to Fscan etc (thanks Roger Peppe),
+ make %#p suppress leading 0x.
+* gc, gopack: add some missing flags to the docs.
+* gc: fix init of packages named main (thanks Gustavo Niemeyer),
+* gob: make recursive map and slice types work, and other fixes.
+ tentative support for GobEncoder/GobDecoder interfaces.
+* gobuilder: add -package flag to build external packages and -v for verbose.
+* gofmt: exclude test file that is not legal Go.
+* goinstall: protect against malicious filenames (thanks Roger Peppe).
+* goyacc: provide -p flag to set prefix for names, documentation update.
+* http: add cookie support (thanks Petar Maymounkov),
+ allow handlers to send non-chunked responses,
+ export ParseHTTPVersion,
+ expose Client's Transport,
+ use WriteProxy,
+ rename ClientTransport to Transport.
+* http/cgi: new package.
+* http/httptest: new package.
+* image: add a decoding test for common file formats.
+* io/ioutil: add TempDir.
+* mime/multipart: Header changed from map to MIMEHeader
+* path/filepath: new OS-specific path support (thanks Gustavo Niemeyer).
+* reflect: add PtrTo, add Value.Addr (old Addr is now UnsafeAddr).
+* runtime: use kernel-supplied compare-and-swap on linux/arm.
+* spec: minor clarification of scope rule for functions.
+* sync/atomic: new package to expose atomic operations.
+* syscall: regenerate zerrors_freebsd_amd64.go (thanks Mikio Hara),
+ work around FreeBSD execve kernel bug (thanks Devon H. O'Dell).
+* template: document the delimiters.
+* testing: run GC before each benchmark run (thanks Roger Peppe).
+* unsafe: fix the documentation.
+* websocket: use httptest.Server for tests (thanks Robert Hencke).
+* xml: permit nested directives (thanks Chris Dollin).
+</pre>
+
+<h2 id="2011-02-24">2011-02-24</h2>
+
+<pre>
+This release includes changes to the http package and a small language change.
+Your code will require changes if it manipulates http Headers or omits the
+condition in if statements.
+
+The new http.Header type replaces map[string]string in the Header and Trailer
+fields of http.Request and http.Response.
+A Header value can be manipulated via its Get, Set, Add, and Del methods.
+See http://golang.org/pkg/http/#Header
+
+The condition is now mandatory in if statements.
+Previously it would default to true, as in switch and for statements.
+This code is now illegal:
+ if x := foo(); {
+ // code that is always executed
+ }
+The same effect can be achieved like this:
+ if x := foo(); true {
+ // code
+ }
+Or, in a simpler form:
+ {
+ x := foo()
+ // code
+ }
+
+Other changes:
+* 6l: new -Hwindowsgui flag allows to build windows gui pe (thanks Alex Brainman),
+ pe fixes (thanks Wei Guangjing).
+* 8l, 6l: allow for more os threads to be created on Windows (thanks Alex Brainman),
+* build: reduce the use of subshells in recursive make, and
+ remove unused NaCl conditional from make.bash (thanks Dave Cheney).
+* codereview: fix clpatch with empty diffs (thanks Gustavo Niemeyer).
+* compress/bzip2: add package.
+* compress/lzw: implement a decoder.
+* crypto/openpgp: add package.
+* crypto/rand: add read buffer to speed up small requests (thanks Albert Strasheim).
+* crypto/rsa: left-pad OAEP results when needed.
+* crypto/tls: make protocol negotiation failure fatal.
+* fmt: stop giving characters to the Scan method of Scanner when we hit a newline in Scanln.
+* gc: interface error message fixes,
+ make string const comparison unsigned (thanks Jeff R. Allen).
+* go spec: minor clarification on channel types.
+* go/ast, parser: condition in if statement is mandatory.
+* gob: compute information about a user's type once.
+ protect against pure recursive types.
+* godoc: accept symbolic links as path names provided to -path,
+ add robots.txt, log errors when reading filter files.
+* html: tokenize HTML comments.
+* http: add proxy support (thanks Yasuhiro Matsumoto),
+ implement with net/textproto (thanks Petar Maymounkov),
+ send full URL in proxy requests,
+ introduce start of Client and ClientTransport.
+* image/png: support for more formats (thanks Mikael Tillenius).
+* json: only use alphanumeric tags,
+ use base64 to encode []byte (thanks Roger Peppe).
+* ld: detect stack overflow due to NOSPLIT, drop rpath, support weak symbols.
+* misc/dashboard/builder: talk to hg with utf-8 encoding.
+* misc/dashboard: notify golang-dev on build failure.
+* net: *netFD.Read to return os.EOF on eof under windows (thanks Alex Brainman),
+ add IPv4 multicast to UDPConn (thanks Dave Cheney),
+ more accurate IPv4-in-IPv6 API test (thanks Mikio Hara),
+ reject invalid net:proto network names (thanks Olivier Antoine).
+* netchan: allow use of arbitrary connections (thanks Roger Peppe).
+* os: add ENODATA and ENOTCONN (thanks Albert Strasheim).
+* reflect: add a couple of sentences explaining how Methods operate,
+ add a secret method to ArrayOrSliceType to ensure it's only implemented by arrays and slices,
+ add pointer word to CommonType (placeholder for future work).
+* runtime-gdb.py: gdb pretty printer for go strings properly handles length.
+* runtime: various bug fixes, more complete stack traces,
+ record $GOROOT_FINAL for runtime.GOROOT.
+* spec: delete incorrect mention of selector working on pointer to interface type.
+* sync: add Cond (thanks Gustavo Niemeyer).
+* syscall: add MCL_* flags for mlockall (thanks Albert Strasheim),
+ implement chmod() for win32 (thanks Yasuhiro Matsumoto).
+* test/bench: update timings for new GC.
+* testing: rename cmdline flags to avoid conflicts (thanks Gustavo Niemeyer).
+* textproto: introduce Header type (thanks Petar Maymounkov).
+* websocket: use new interface to access Header.
+</pre>
+
+<h2 id="2011-02-15">2011-02-15</h2>
+
+<pre>
+This release includes changes to the io, os, and template packages.
+You may need to update your code.
+
+The io.ReadByter and io.ReadRuner interface types have been renamed to
+io.ByteReader and io.RuneReader respectively.
+
+The os package's ForkExec function has been superseded by the new StartProcess
+function and an API built around the Process type:
+ http://golang.org/pkg/os/#Process
+
+The order of arguments to template.Execute has been reversed to be consistent
+the notion of "destination first", as with io.Copy, fmt.Fprint, and others.
+
+Gotest now works for package main in directories using Make.cmd-based makefiles.
+
+The memory allocation runtime problems from the last release are not completely
+fixed. The virtual memory exhaustion problems encountered by people using
+ulimit -v have been fixed, but there remain known garbage collector problems
+when using GOMAXPROCS > 1.
+
+Other changes:
+* 5l: stopped generating 64-bit eor.
+* 8l: more work on plan9 support (thanks Yuval Pavel Zholkover).
+* archive/zip: handle files with data descriptors.
+* arm: working peep-hole optimizer.
+* asn1: marshal true as 255, not 1.
+* buffer.go: minor optimization, expanded comment.
+* build: drop syslog on DISABLE_NET_TESTS=1 (thanks Gustavo Niemeyer),
+ allow clean.bash to work on fresh checkout,
+ change "all tests pass" message to be more obvious,
+ fix spaces in GOROOT (thanks Christopher Nielsen).
+* bytes: fix bug in buffer.ReadBytes (thanks Evan Shaw).
+* 5g: better int64 code,
+ don't use MVN instruction.
+* cgo: don't run cgo when not compiling (thanks Gustavo Niemeyer),
+ fix _cgo_run timestamp file order (thanks Gustavo Niemeyer),
+ fix handling of signed enumerations (thanks Gustavo Niemeyer),
+ os/arch dependent #cgo directives (thanks Gustavo Niemeyer),
+ rename internal f to avoid conflict with possible C global named f.
+* codereview: fix hgpatch on windows (thanks Yasuhiro Matsumoto),
+ record repository, base revision,
+ use cmd.communicate (thanks Yasuhiro Matsumoto).
+* container/ring: replace Iter() with Do().
+* crypto/cipher: add resync open to OCFB mode.
+* crypto/openpgp/armor: bug fixes.
+* crypto/openpgp/packet: new subpackage.
+* crypto/tls: load a chain of certificates from a file,
+ select best cipher suite, not worst.
+* crypto/x509: add support for name constraints.
+* debug/pe: ImportedSymbols fixes (thanks Wei Guangjing).
+* doc/code: update to reflect that package names need not be unique.
+* doc/codelab/wiki: a bunch of fixes (thanks Andrey Mirtchovski).
+* doc/install: update for new versions of Mercurial.
+* encoding/line: fix line returned after EOF.
+* flag: allow hexadecimal (0xFF) and octal (0377) input for integer flags.
+* fmt.Scan: scan binary-exponent floating format, 2.4p-3,
+ hexadecimal (0xFF) and octal (0377) integers.
+* fmt: document %%; also %b for floating point.
+* gc, ld: detect stale or incompatible object files,
+ package name main no longer reserved.
+* gc: correct receiver in method missing error (thanks Lorenzo Stoakes),
+ correct rounding of denormal constants (thanks Eoghan Sherry),
+ select receive bug fix.
+* go/printer, gofmt: smarter handling of multi-line raw strings.
+* go/printer: line comments must always end in a newline,
+ remove notion of "Styler", remove HTML mode.
+* gob: allow Decode(nil) and have it just discard the next value.
+* godoc: use IsAbs to test for absolute paths (fix for win32) (thanks Yasuhiro Matsumoto),
+ don't hide package lookup error if there's no command with the same name.
+* gotest: enable unit tests for main programs.
+* http: add Server type supporting timeouts,
+ add pipelining to ClientConn, ServerConn (thanks Petar Maymounkov),
+ handle unchunked, un-lengthed HTTP/1.1 responses.
+* io: add RuneReader.
+* json: correct Marshal documentation.
+* netchan: graceful handling of closed connection (thanks Graham Miller).
+* os: implement new Process API (thanks Alex Brainman).
+* regexp tests: make some benchmarks more meaningful.
+* regexp: add support for matching against text read from RuneReader interface.
+* rpc: make more tolerant of errors, properly discard values (thanks Roger Peppe).
+* runtime: detect failed thread creation on Windows,
+ faster allocator, garbage collector,
+ fix virtual memory exhaustion,
+ implemented windows console ctrl handler (SIGINT) (thanks Hector Chu),
+ more detailed panic traces, line number work,
+ improved Windows callback handling (thanks Hector Chu).
+* spec: adjust notion of Assignability,
+ allow import of packages named main,
+ clarification re: method sets of newly declared pointer types,
+ fix a few typos (thanks Anthony Martin),
+ fix Typeof() return type (thanks Gustavo Niemeyer),
+ move to Unicode 6.0.
+* sync: diagnose Unlock of unlocked Mutex,
+ new Waitgroup type (thanks Gustavo Niemeyer).
+* syscall: add SetsockoptIpMreq (thanks Dave Cheney),
+ add sockaddr_dl, sysctl with routing message support for darwin, freebsd (thanks Mikio Hara),
+ do not use NULL for zero-length read, write,
+ implement windows version of Fsync (thanks Alex Brainman),
+ make ForkExec acquire the ForkLock under windows (thanks Hector Chu),
+ make windows API return errno instead of bool (thanks Alex Brainman),
+ remove obsolete socket IO control (thanks Mikio Hara).
+* template: add simple formatter chaining (thanks Kyle Consalus),
+ allow a leading '*' to indirect through a pointer.
+* testing: include elapsed time in test output
+* windows: replace remaining __MINGW32__ instances with _WIN32 (thanks Joe Poirier).
+</pre>
+
+<h2 id="2011-02-01">2011-02-01</h2>
+
+<pre>
+This release includes significant changes to channel operations and minor
+changes to the log package. Your code will require modification if it uses
+channels in non-blocking communications or the log package's Exit functions.
+
+Non-blocking channel operations have been removed from the language.
+The equivalent operations have always been possible using a select statement
+with a default clause. If a default clause is present in a select, that clause
+will execute (only) if no other is ready, which allows one to avoid blocking on
+a communication.
+
+For example, the old non-blocking send operation,
+
+ if ch <- v {
+ // sent
+ } else {
+ // not sent
+ }
+
+should be rewritten as,
+
+ select {
+ case ch <- v:
+ // sent
+ default:
+ // not sent
+ }
+
+Similarly, this receive,
+
+ v, ok := <-ch
+ if ok {
+ // received
+ } else {
+ // not received
+ }
+
+should be rewritten as,
+
+ select {
+ case v := <-ch:
+ // received
+ default:
+ // not received
+ }
+
+This change is a prelude to redefining the 'comma-ok' syntax for a receive.
+In a later release, a receive expression will return the received value and an
+optional boolean indicating whether the channel has been closed. These changes
+are being made in two stages to prevent this semantic change from silently
+breaking code that uses 'comma-ok' with receives.
+There are no plans to have a boolean expression form for sends.
+
+Sends to a closed channel will panic immediately. Previously, an unspecified
+number of sends would fail silently before causing a panic.
+
+The log package's Exit, Exitf, and Exitln functions have been renamed Fatal,
+Fatalf, and Fatalln respectively. This brings them in line with the naming of
+the testing package.
+
+The port to the "tiny" operating system has been removed. It is unmaintained
+and untested. It was a toy to show that Go can run on raw hardware and it
+served its purpose. The source code will of course remain in the repository
+history, so it could be brought back if needed later.
+
+This release also changes some of the internal structure of the memory
+allocator in preparation for other garbage collector changes.
+If you run into problems, please let us know.
+There is one known issue that we are aware of but have not debugged yet:
+ http://code.google.com/p/go/issues/detail?id=1464&.
+
+Other changes in this release:
+* 5l: document -F, force it on old ARMs (software floating point emulation)
+* 6g: fix registerization of temporaries (thanks Eoghan Sherry),
+ fix uint64(uintptr(unsafe.Pointer(&x))).
+* 6l: Relocate CMOV* instructions (thanks Gustavo Niemeyer),
+ windows/amd64 port (thanks Wei Guangjing).
+* 8l: add PE dynexport, emit DWARF in Windows PE, and
+ code generation fixes (thanks Wei Guangjing).
+* bufio: make Flush a no-op when the buffer is empty.
+* bytes: Add Buffer.ReadBytes, Buffer.ReadString (thanks Evan Shaw).
+* cc: mode to generate go-code for types and variables.
+* cgo: define CGO_CFLAGS and CGO_LDFLAGS in Go files (thanks Gustavo Niemeyer),
+ windows/386 port (thanks Wei Guangjing).
+* codereview: fix windows (thanks Hector Chu),
+ handle file patterns better,
+ more ASCII vs. Unicode nonsense.
+* crypto/dsa: add support for DSA.
+* crypto/openpgp: add s2k.
+* crypto/rand: use defer to unlock mutex (thanks Anschel Schaffer-Cohen).
+* crypto/rsa: correct docstring for SignPKCS1v15.
+* crypto: add package, a common place to store identifiers for hash functions.
+* doc/codelab/wiki: update to work with template changes, add to run.bash.
+* doc/spec: clarify address operators.
+* ebnflint: exit with non-zero status on error.
+* encoding/base32: new package (thanks Miek Gieben).
+* encoding/line: make it an io.Reader too.
+* exec: use custom error for LookPath (thanks Gustavo Niemeyer).
+* fmt/doc: define width and precision for strings.
+* gc: clearer error for struct == struct,
+ fix send precedence,
+ handle invalid name in type switch,
+ special case code for single-op blocking and non-blocking selects.
+* go/scanner: fix build (adjust scanner EOF linecount).
+* gob: better debugging, commentary,
+ make nested interfaces work,
+ report an error when encoding a non-empty struct with no public fields.
+* godoc: full text index for whitelisted non-Go files,
+ show line numbers for non-go files (bug fix).
+* gofmt -r: match(...) arguments may be nil; add missing guards.
+* govet: add Panic to the list of functions.
+* http: add host patterns (thanks Jose Luis Vázquez González),
+ follow relative redirect in Get.
+* json: handle capital floating point exponent (1E100) (thanks Pieter Droogendijk).
+* ld: add -I option to set ELF interpreter,
+ more robust decoding of reflection type info in generating dwarf.
+* lib9: update to Unicode 6.0.0.
+* make.bash: stricter selinux test (don't complain unless it is enabled).
+* misc/vim: Import/Drop commands (thanks Gustavo Niemeyer),
+ set 'syntax sync' to a large value (thanks Yasuhiro Matsumoto).
+* net: fix race condition in test,
+ return cname in LookupHost.
+* netchan: avoid race condition in test,
+ fixed documentation for import (thanks Anschel Schaffer-Cohen).
+* os: add ETIMEDOUT (thanks Albert Strasheim).
+* runtime: generate Go defs for C types,
+ implementation of callback functions for windows (thanks Alex Brainman),
+ make Walk web browser example work (thanks Hector Chu),
+ make select fairer,
+ prefer fixed stack allocator over general memory allocator,
+ simpler heap map, memory allocation.
+* scanner: fix Position returned by Scan, Pos,
+ don't read ahead in Init.
+* suffixarray: use binary search for both ends of Lookup (thanks Eric Eisner).
+* syscall: add missing network interface constants (thanks Mikio Hara).
+* template: treat map keys as zero, not non-existent (thanks Roger Peppe).
+* time: allow cancelling of After events (thanks Roger Peppe),
+ support Solaris zoneinfo directory.
+* token/position: added SetLinesForContent.
+* unicode: update to unicode 6.0.0.
+* unsafe: add missing case to doc for Pointer.
+</pre>
+
+<h2 id="2011-01-20">2011-01-20</h2>
+
+<pre>
+This release removes the float and complex types from the language.
+
+The default type for a floating point literal is now float64, and
+the default type for a complex literal is now complex128.
+
+Existing code that uses float or complex must be rewritten to
+use explicitly sized types.
+
+The two-argument constructor cmplx is now spelled complex.
+</pre>
+
+<h2 id="2011-01-19">2011-01-19</h2>
+
+<pre>
+The 5g (ARM) compiler now has registerization enabled. If you discover it
+causes bugs, use 5g -N to disable the registerizer and please let us know.
+
+The xml package now allows the extraction of nested XML tags by specifying
+struct tags of the form "parent>child". See the XML documentation for an
+example: http://golang.org/pkg/xml/
+
+* 5a, 5l, 6a, 6l, 8a, 8l: handle out of memory, large allocations (thanks Jeff R. Allen).
+* 8l: pe changes (thanks Alex Brainman).
+* arm: fixes and improvements.
+* cc: fix vlong condition.
+* cgo: add complex float, complex double (thanks Sebastien Binet),
+ in _cgo_main.c define all provided symbols as functions.
+* codereview: don't mail change lists with no files (thanks Ryan Hitchman).
+* crypto/cipher: add OFB mode.
+* expvar: add Float.
+* fmt: document %X of string, []byte.
+* gc, runtime: make range on channel safe for multiple goroutines.
+* gc: fix typed constant declarations (thanks Anthony Martin).
+* go spec: adjust language for constant typing.
+* go/scanner: Make Init take a *token.File instead of a *token.FileSet.
+* godoc: bring back "indexing in progress" message,
+ don't double HTML-escape search result snippets,
+ enable qualified identifiers ("math.Sin") as query strings again,
+ peephole optimization for generated HTML,
+ remove tab before formatted section.
+* gofmt, go/printer: do not insert extra line breaks where they may break the code.
+* http: fix Content-Range and Content-Length in response (thanks Clement Skau),
+ fix scheme-relative URL parsing; add ParseRequestURL,
+ handle HEAD requests correctly,
+ support for relative URLs.
+* math: handle denormalized numbers in Frexp, Ilogb, Ldexp, and Logb (thanks Eoghan Sherry).
+* net, syscall: return source address in Recvmsg (thanks Albert Strasheim).
+* net: add LookupAddr (thanks Kyle Lemons),
+ add unixpacket (thanks Albert Strasheim),
+ avoid nil dereference if /etc/services can't be opened (thanks Corey Thomasson),
+ implement windows timeout (thanks Wei Guangjing).
+* netchan: do not block sends; implement flow control (thanks Roger Peppe).
+* regexp: reject bare '?'. (thanks Ben Lynn)
+* runtime/cgo: don't define crosscall2 in dummy _cgo_main.c.
+* runtime/debug: new package for printing stack traces from a running goroutine.
+* runtime: add per-pause gc stats,
+ fix arm reflect.call boundary case,
+ print signal information during panic.
+* spec: specify that int and uint have the same size.
+* syscall: correct WSTOPPED on OS X,
+ correct length of GNU/Linux abstract Unix domain sockaddr,
+ correct length of SockaddrUnix.
+* tutorial: make stdin, stdout, stderr work on Windows.
+* windows: implement exception handling (thanks Hector Chu).
+</pre>
+
+<h2 id="2011-01-12">2011-01-12</h2>
+
+<pre>
+The json, gob, and template packages have changed, and code that uses them
+may need to be updated after this release. They will no longer read or write
+unexported struct fields. When marshalling a struct with json or gob the
+unexported fields will be silently ignored. Attempting to unmarshal json or
+gob data into an unexported field will generate an error. Accessing an
+unexported field from a template will cause the Execute function to return
+an error.
+
+Godoc now supports regular expression full text search, and this
+functionality is now available on golang.org.
+
+Other changes:
+* arm: initial cut at arm optimizer.
+* bytes.Buffer: Fix bug in UnreadByte.
+* cgo: export unsafe.Pointer as void*, fix enum const conflict,
+ output alignment fix (thanks Gustavo Niemeyer).
+* crypto/block: mark as deprecated.
+* crypto/openpgp: add error and armor.
+* crypto: add twofish package (thanks Berengar Lehr).
+* doc/spec: remove Maxalign from spec.
+* encoding/line: new package for reading lines from an io.Reader.
+* go/ast: correct end position for Index and TypeAssert expressions.
+* gob: make (en|dec)code(Ui|I)nt methods rather than functions.
+* godefs: better handling of enums.
+* gofmt: don't attempt certain illegal rewrites,
+ rewriter matches apply to expressions only.
+* goinstall: preliminary support for cgo packages (thanks Gustavo Niemeyer).
+* hg: add cgo/_cgo_* to .hgignore.
+* http: fix text displayed in Redirect.
+* ld: fix exported dynamic symbols on Mach-O,
+ permit a Mach-O symbol to be exported in the dynamic symbol table.
+* log: add methods for exit and panic.
+* net: use closesocket api instead of CloseHandle on Windows (thanks Alex Brainman).
+* netchan: make fields exported for gob change.
+* os: add Sync to *File, wraps syscall.Fsync.
+* runtime/cgo: Add callbacks to support SWIG.
+* runtime: Restore scheduler stack position if cgo callback panics.
+* suffixarray: faster creation algorithm (thanks Eric Eisner).
+* syscall: fix mksysnum_linux.sh (thanks Anthony Martin).
+* time.NewTicker: panic for intervals <= 0.
+* time: add AfterFunc to call a function after a duration (thanks Roger Peppe),
+ fix tick accuracy when using multiple Tickers (thanks Eoghan Sherry).</pre>
+
+<h2 id="2011-01-06">2011-01-06</h2>
+
+<pre>
+This release includes several fixes and changes:
+
+* build: Make.pkg: use installed runtime.h for cgo.
+* cgo: disallow use of C.errno.
+* crypto/cipher: fix OCFB,
+ make NewCBCEncrypter return BlockMode.
+* doc: 6l: fix documentation of -L flag,
+ add golanguage.ru to foreign-language doc list,
+ effective go: explain the effect of repanicking better,
+ update Effective Go for template API change,
+ update contribution guidelines to prefix the change description.
+* encoding/binary: reject types with implementation-dependent sizes (thanks Patrick Gavlin).
+* exp/evalsimple fix handling of slices like s[:2] (thanks Sebastien Binet).
+* fmt: made format string handling more efficient,
+ normalize processing of format string.
+* gc: return constant floats for parts of complex constants (thanks Anthony Martin),
+ rewrite complex /= to l = l / r (thanks Patrick Gavlin),
+ fix &^=.
+* go/ast: provide complete node text range info.
+* gob: generate a better error message in one confusing place.
+* godoc: fix godoc -src (thanks Icarus Sparry).
+* goinstall: add -clean flag (thanks Kyle Lemons),
+ add checkout concept (thanks Caine Tighe),
+ fix -u for bzr (thanks Gustavo Niemeyer).
+* http: permit empty Reason-Phrase in response Status-Line.
+* io: fix Copyn EOF handling.
+* net: fix close of Listener (thanks Michael Hoisie).
+* regexp: fix performance bug, make anchored searches fail fast,
+ fix prefix bug.
+* runtime/cgo: fix stackguard on FreeBSD/amd64 (thanks Anthony Martin).
+* strconv: atof: added 'E' as valid token for exponent (thanks Stefan Nilsson),
+ update ftoa comment for 'E' and 'G'.
+* strings: fix description of FieldsFunc (thanks Roger Peppe).
+* syscall: correct Linux Splice definition,
+ make Access second argument consistently uint32.
+</pre>
+
+<h2 id="2010-12-22">2010-12-22</h2>
+
+<pre>
+A small release this week. The most significant change is that some
+outstanding cgo issues were resolved.
+
+* cgo: handle references to symbols in shared libraries.
+* crypto/elliptic: add serialisation and key pair generation.
+* crypto/hmac: add HMAC-SHA256 (thanks Anthony Martin).
+* crypto/tls: add ECDHE support ("Elliptic Curve Diffie Hellman Ephemeral"),
+ add support code for generating handshake scripts for testing.
+* darwin, freebsd: ignore write failure (during print, panic).
+* exp/draw: remove Border function.
+* expvar: quote StringFunc output, same as String output.
+* hash/crc64: fix typo in Sum.
+* ld: allow relocations pointing at ELF .bss symbols, ignore stab symbols.
+* misc/cgo/life: fix, add to build.
+* regexp: add HasMeta, HasOperator, and String methods to Regexp.
+* suffixarray: implemented FindAllIndex regexp search.
+* test/bench: update numbers for regex-dna after speedup to regexp.
+* time: explain the formats a little better.
+</pre>
+
+<h2 id="2010-12-15">2010-12-15</h2>
+
+<pre>
+Package crypto/cipher has been started, to replace crypto/block.
+As part of the changes, rc4.Cipher's XORKeyStream method signature has changed from
+ XORKeyStream(buf []byte)
+to
+ XORKeyStream(dst, src []byte)
+to implement the cipher.Stream interface. If you use crypto/block, you'll need
+to switch to crypto/cipher once it is complete.
+
+Package smtp's StartTLS now takes a *tls.Config argument.
+
+Package reflect's ArrayCopy has been renamed to Copy. There are new functions
+Append and AppendSlice.
+
+The print/println bootstrapping functions now write to standard error.
+To write to standard output, use fmt.Print[ln].
+
+A new tool, govet, has been added to the Go distribution. Govet is a static
+checker for Go programs. At the moment, and for the foreseeable future,
+it only checks arguments to print calls.
+
+The cgo tool for writing Go bindings for C code has changed so that it no
+longer uses stub .so files (like cgo_stdio.so). Cgo-based packages using the
+standard Makefiles should build without any changes. Any alternate build
+mechanisms will need to be updated.
+
+The C and Go compilers (6g, 6c, 8g, 8c, 5g, 5c) now align structs according to
+the maximum alignment of the fields they contain; previously they aligned
+structs to word boundaries. This may break non-cgo-based code that attempts to
+mix C and Go.
+
+NaCl support has been removed. The recent linker changes broke NaCl support
+a month ago, and there are no known users of it.
+If necessary, the NaCl code can be recovered from the repository history.
+
+* 5g/8g, 8l, ld, prof: fix output of 32-bit values (thanks Eoghan Sherry).
+* [68]l and runtime: GDB support for interfaces and goroutines.
+* 6l, 8l: support for linking ELF and Mach-O .o files.
+* all: simplify two-variable ranges with unused second variable (thanks Ryan Hitchman).
+* arm: updated soft float support.
+* codereview: keep quiet when not in use (thanks Eoghan Sherry).
+* compress/flate: implement Flush, equivalent to zlib's Z_SYNC_FLUSH.
+* crypto/tls: use rand.Reader in cert generation example (thanks Anthony Martin).
+* dashboard: fix project tag filter.
+* debug/elf, debug/macho: add ImportedLibraries, ImportedSymbols.
+* doc/go_mem: goroutine exit is not special.
+* event.go: another print glitch from gocheck.
+* gc: bug fixes,
+ syntax error for incomplete chan type (thanks Ryan Hitchman).
+* go/ast: fix ast.Walk.
+* gob: document the byte count used in the encoding of values,
+ fix bug sending zero-length top-level slices and maps,
+ Register should use the original type, not the indirected one.
+* godashboard: support submitting projects with non-ascii names (thanks Ryan Hitchman)
+* godefs: guard against structs with pad fields
+* godoc: added textual search, to enable use -fulltext flag.
+* gofmt: simplify "x, _ = range y" to "x = range y".
+* gopack: allow ELF/Mach-O objects in .a files without clearing allobj.
+* go/token,scanner: fix comments so godoc aligns properly.
+* govet: on error continue to the next file (thanks Christopher Wedgwood).
+* html: improved parsing.
+* http: ServeFile handles Range header for partial requests.
+* json: check for invalid UTF-8.
+* ld: allow .o files with no symbols,
+ reading of ELF object files,
+ reading of Mach-O object files.
+* math: change float64 bias constant from 1022 to 1023 (thanks Eoghan Sherry),
+ rename the MinFloat constant to SmallestNonzeroFloat.
+* nm: silently ignore .o files in .a files.
+* os: fix test of RemoveAll.
+* os/inotify: new package (thanks Balazs Lecz).
+* os: make MkdirAll work with symlinks (thanks Ryan Hitchman).
+* regexp: speed up by about 30%; also simplify code for brackets.
+* runtime/linux/386: set FPU to 64-bit precision.
+* runtime: remove paranoid mapping at 0.
+* suffixarray: add Bytes function.
+* syscall: add network interface constants for linux/386, linux/amd64 (thanks Mikio Hara).
+* syscall/windows: restrict access rights param of OpenProcess(),
+ remove \r and \n from error messages (thanks Alex Brainman).
+* test/bench: fixes to timing.sh (thanks Anthony Martin).
+* time: fix bug in Ticker: shutdown using channel rather than memory.
+* token/position: provide FileSet.File, provide files iterator.
+* xml: disallow invalid Unicode code points (thanks Nigel Kerr).
+</pre>
+
+<h2 id="2010-12-08">2010-12-08</h2>
+
+<pre>
+This release includes some package changes. If you use the crypto/tls or
+go/parser packages your code may require changes.
+
+The crypto/tls package's Dial function now takes an additional *Config
+argument. Most uses will pass nil to get the same default behavior as before.
+See the documentation for details:
+ http://golang.org/pkg/crypto/tls/#Config
+ http://golang.org/pkg/crypto/tls/#Dial
+
+The go/parser package's ParseFile function now takes a *token.FileSet as its
+first argument. This is a pointer to a data structure used to store
+position information. If you don't care about position information you
+can pass "token.NewFileSet()". See the documentation for details:
+ http://golang.org/pkg/go/parser/#ParseFile
+
+This release also splits the patent grant text out of the LICENSE file into a
+separate PATENTS file and changes it to be more like the WebM grant.
+These clarifications were made at the request of the Fedora project.
+
+Other changes:
+* [68]l: generate debug info for builtin structured types, prettyprinting in gdb.
+* 8l: add dynimport to import table in Windows PE (thanks Wei Guangjing).
+* 8l, runtime: fix Plan 9 386 build (thanks Yuval Pavel Zholkover).
+* all: fix broken calls to Printf etc.
+* bufio: make Reader.Read implement io.Reader semantics (thanks Roger Peppe).
+* build: allow archiver to be specified by HOST_AR (thanks Albert Strasheim).
+* bytes: add Buffer.UnreadRune, Buffer.UnreadByte (thanks Roger Peppe).
+* crypto/tls: fix build of certificate generation example (thanks Christian Himpel).
+* doc/install: describe GOHOSTOS and GOHOSTARCH.
+* errchk: accept multiple source files (thanks Eoghan Sherry).
+* exec.LookPath: return os.PathError instad of os.ENOENT (thanks Michael Hoisie)..
+* flag: fix format error in boolean error report,
+ handle multiple calls to flag.Parse.
+* fmt: add %U format for standard Unicode representation of code point values.
+* gc: fix method offsets of anonymous interfaces (thanks Eoghan Sherry),
+ skip undefined symbols in import . (thanks Eoghan Sherry).
+* go/scanner: remove Tokenize - was only used in tests
+* gobuilder: add buildroot command-line flag (thanks Devon H. O'Dell).
+* html: unescape numeric entities (thanks Ryan Hitchman).
+* http: Add EncodeQuery, helper for constructing query strings.
+* ld: fix dwarf decoding of 64-bit reflect values (thanks Eoghan Sherry).
+* math: improve accuracy of Exp2 (thanks Eoghan Sherry).
+* runtime: add Goroutines (thanks Keith Rarick).
+* sync: small naming fix for armv5 (thanks Dean Prichard).
+* syscall, net: Add Recvmsg and Sendmsg on Linux (thanks Albert Strasheim).
+* time: make After use fewer goroutines and host processes (thanks Roger Peppe).
+</pre>
+
+<h2 id="2010-12-02">2010-12-02</h2>
+
+<pre>
+Several package changes in this release may require you to update your code if
+you use the bytes, template, or utf8 packages. In all cases, any outdated code
+will fail to compile rather than behave erroneously.
+
+The bytes package has changed. Its Add and AddByte functions have been removed,
+as their functionality is provided by the recently-introduced built-in function
+"append". Any code that uses them will need to be changed:
+s = bytes.Add(s, b) -> s = append(s, b...)
+s = bytes.AddByte(b, c) -> s = append(s, b)
+s = bytes.Add(nil, c) -> append([]byte(nil), c)
+
+The template package has changed. Your code will need to be updated if it calls
+the HTMLFormatter or StringFormatter functions, or implements its own formatter
+functions. The function signature for formatter types has changed to:
+ func(wr io.Writer, formatter string, data ...interface{})
+to allow multiple arguments to the formatter. No templates will need updating.
+See the change for examples:
+ http://code.google.com/p/go/source/detail?r=2c2be793120e
+
+The template change permits the implementation of multi-word variable
+instantiation for formatters. Before one could say
+ {field}
+or
+ {field|formatter}
+Now one can also say
+ {field1 field2 field3}
+or
+ {field1 field2 field3|formatter}
+and the fields are passed as successive arguments to the formatter,
+by analogy to fmt.Print.
+
+The utf8 package has changed. The order of EncodeRune's arguments has been
+reversed to satisfy the convention of "destination first".
+Any code that uses EncodeRune will need to be updated.
+
+Other changes:
+* [68]l: correct dwarf location for globals and ranges for arrays.
+* big: fix (*Rat) SetFrac64(a, b) when b < 0 (thanks Eoghan Sherry).
+* compress/flate: fix typo in comment (thanks Mathieu Lonjaret).
+* crypto/elliptic: use a Jacobian transform for better performance.
+* doc/code.html: fix reference to "gomake build" (thanks Anschel Schaffer-Cohen).
+* doc/roadmap: update gdb status.
+* doc/spec: fixed some omissions and type errors.
+* doc: some typo fixes (thanks Peter Mundy).
+* exp/eval: build fix for parser.ParseFile API change (thanks Anschel Schaffer-Cohen).
+* fmt: Scan accepts Inf and NaN,
+ allow "% X" as well as "% x".
+* go/printer: preserve newlines in func parameter lists (thanks Jamie Gennis).
+* http: consume request body before next request.
+* log: ensure writes are atomic (thanks Roger Peppe).
+* path: Windows support for Split (thanks Benny Siegert).
+* runtime: fix SysFree to really free memory on Windows (thanks Alex Brainman),
+ parallel definitions in Go for all C structs.
+* sort: avoid overflow in pivot calculation,
+ reduced stack depth to lg(n) in quickSort (thanks Stefan Nilsson).
+* strconv: Atof on Infs and NaNs.
+</pre>
+
+<h2 id="2010-11-23">2010-11-23</h2>
+
+<pre>
+This release includes a backwards-incompatible package change to the
+sort.Search function (introduced in the last release).
+See the change for details and examples of how you might change your code:
+ http://code.google.com/p/go/source/detail?r=102866c369
+
+* build: automatically #define _64BIT in 6c.
+* cgo: print required space after parameter name in wrapper function.
+* crypto/cipher: new package to replace crypto/block (thanks Adam Langley).
+* crypto/elliptic: new package, implements elliptic curves over prime fields (thanks Adam Langley).
+* crypto/x509: policy OID support and fixes (thanks Adam Langley).
+* doc: add link to codewalks,
+ fix recover() documentation (thanks Anschel Schaffer-Cohen),
+ explain how to write Makefiles for commands.
+* exec: enable more tests on windows (thanks Alex Brainman).
+* gc: adjustable hash code in typecheck of composite literals
+ (thanks to vskrap, Andrey Mirtchovski, and Eoghan Sherry).
+* gc: better error message for bad type in channel send (thanks Anthony Martin).
+* godoc: bug fix in relativePath,
+ compute search index for all file systems under godoc's observation,
+ use correct time stamp to indicate accuracy of search result.
+* index/suffixarray: use sort.Search.
+* net: add ReadFrom and WriteTo windows version (thanks Wei Guangjing).
+* reflect: remove unnecessary casts in Get methods.
+* rpc: add RegisterName to allow override of default type name.
+* runtime: free memory allocated by windows CommandLineToArgv (thanks Alex Brainman).
+* sort: simplify Search (thanks Roger Peppe).
+* strings: add LastIndexAny (thanks Benny Siegert).
+</pre>
+
+<h2 id="2010-11-10">2010-11-10</h2>
+
+<pre>
+The birthday release includes a new Search capability inside the sort package.
+It takes an unusual but very general and easy-to-use approach to searching
+arbitrary indexable sorted data. See the documentation for details:
+ http://golang.org/pkg/sort/#Search
+
+The ARM port now uses the hardware floating point unit (VFP). It still has a
+few bugs, mostly around conversions between unsigned integer and floating-point
+values, but it's stabilizing.
+
+In addition, there have been many smaller fixes and updates:
+
+* 6l: generate dwarf variable names with disambiguating suffix.
+* container/list: make Remove return Value of removed element.
+ makes it easier to remove first or last item.
+* crypto: add cast5 (default PGP cipher),
+ switch block cipher methods to be destination first.
+* crypto/tls: use pool building for certificate checking
+* go/ast: change embedded token.Position fields to named fields
+ (preparation for a different position representation)
+* net: provide public access to file descriptors (thanks Keith Rarick)
+* os: add Expand function to evaluate environment variables.
+* path: add Glob (thanks Benny Siegert)
+* runtime: memequal optimization (thanks Graham Miller)
+ prefix all external symbols with "runtime·" to avoid
+ conflicts linking with external C libraries.
+</pre>
+
+<h2 id="2010-11-02">2010-11-02</h2>
+
+<pre>
+This release includes a language change: the new built-in function, append.
+Append makes growing slices much simpler. See the spec for details:
+ http://golang.org/doc/go_spec.html#Appending_and_copying_slices
+
+Other changes:
+* 8l: pe generation fixes (thanks Alex Brainman).
+* doc: Effective Go: append and a few words about "..." args.
+* build: fiddle with make variables.
+* codereview: fix sync and download in Python 2.7 (thanks Fazlul Shahriar).
+* debug/pe, cgo: add windows support (thanks Wei Guangjing).
+* go/ast: add Inspect function for easy AST inspection w/o a visitor.
+* go/printer: do not remove parens around composite literals starting with
+ a type name in control clauses.
+* go/scanner: bug fixes, revisions, and more tests.
+* gob: several fixes and documentation updates.
+* godoc: bug fix (bug introduced with revision 3ee58453e961).
+* gotest: print empty benchmark list in a way that gofmt will leave alone.
+* http server: correctly respond with 304 NotModified (thanks Michael Hoisie).
+* kate: update list of builtins (thanks Evan Shaw).
+* libutf: update to Unicode 5.2.0 to match pkg/unicode (thanks Anthony Martin).
+* misc/bbedit: update list of builtins (thanks Anthony Starks).
+* misc/vim: update list of builtins.
+* mkrunetype: install a Makefile and tweak it slightly so it can be built.
+* netchan: fix locking bug.
+* pidigits: minor improvements (thanks Evan Shaw).
+* rpc: fix client deadlock bug.
+* src: use append where appropriate (often instead of vector).
+* strings: add Contains helper function (thanks Brad Fitzpatrick).
+* syscall: SIO constants for Linux (thanks Albert Strasheim),
+ Stat(path) on windows (thanks Alex Brainman).
+* test/ken/convert.go: add conversion torture test.
+* testing: add Benchmark (thanks Roger Peppe).
+</pre>
+
+<h2 id="2010-10-27">2010-10-27</h2>
+
+<pre>
+*** This release changes the encoding used by package gob.
+ If you store gobs on disk, see below. ***
+
+The ARM port (5g) now passes all tests. The optimizer is not yet enabled, and
+floating point arithmetic is performed entirely in software. Work is underway
+to address both of these deficiencies.
+
+The syntax for arrays, slices, and maps of composite literals has been
+simplified. Within a composite literal of array, slice, or map type, elements
+that are themselves composite literals may elide the type if it is identical to
+the outer literal's element type. For example, these expressions:
+ [][]int{[]int{1, 2, 3}, []int{4, 5}}
+ map[string]Point{"x": Point{1.5, -3.5}, "y": Point{0, 0}}
+can be simplified to:
+ [][]int{{1, 2, 3}, {4, 5}}
+ map[string]Point{"x": {1.5, -3.5}, "y": {0, 0}}
+Gofmt can make these simplifications mechanically when invoked with the
+new -s flag.
+
+The built-in copy function can now copy bytes from a string value to a []byte.
+Code like this (for []byte b and string s):
+ for i := 0; i < len(s); i++ {
+ b[i] = s[i]
+ }
+can be rewritten as:
+ copy(b, s)
+
+The gob package can now encode and decode interface values containing types
+registered ahead of time with the new Register function. These changes required
+a backwards-incompatible change to the wire format. Data written with the old
+version of the package will not be readable with the new one, and vice versa.
+(Steps were made in this change to make sure this doesn't happen again.)
+We don't know of anyone using gobs to create permanent data, but if you do this
+and need help converting, please let us know, and do not update to this release
+yet. We will help you convert your data.
+
+Other changes:
+* 5g, 6g, 8g: generate code for string index instead of calling function.
+* 5l, 6l, 8l: introduce sub-symbols.
+* 6l/8l: global and local variables and type info.
+* Make.inc: delete unnecessary -fno-inline flag to quietgcc.
+* arm: precise float64 software floating point, bug fixes.
+* big: arm assembly, faster software mulWW, divWW.
+* build: only print "You need to add foo to PATH" when needed.
+* container/list: fix Remove bug and use pointer to self as identifier.
+* doc: show page title in browser title bar,
+ update roadmap.
+* encoding/binary: give LittleEndian, BigEndian specific types.
+* go/parser: consume auto-inserted semi when calling ParseExpr().
+* gobuilder: pass GOHOSTOS and GOHOSTARCH to build,
+ write build and benchmarking logs to disk.
+* goinstall: display helpful message when encountering a cgo package,
+ fix test for multiple package names (thanks Fazlul Shahriar).
+* gotest: generate correct gofmt-formatted _testmain.go.
+* image/png: speed up paletted encoding ~25% (thanks Brad Fitzpatrick).
+* misc: update python scripts to specify python2 as python3 is now "python".
+* net: fix comment on Dial to mention unix/unixgram.
+* rpc: expose Server type to allow multiple RPC Server instances.
+* runtime: print unknown types in panic.
+* spec: append built-in (not yet implemented).
+* src: gofmt -s -w src misc.
+ update code to use copy-from-string.
+* test/bench: update numbers.
+* websocket: fix short Read.
+</pre>
+
+<h2 id="2010-10-20">2010-10-20</h2>
+
+<pre>
+This release removes the log package's deprecated functions.
+Code that has not been updated to use the new interface will break.
+See the previous release notes for details:
+ http://golang.org/doc/devel/release.html#2010-10-13
+
+Also included are major improvements to the linker. It is now faster,
+uses less memory, and more parallelizable (but not yet parallel).
+
+The nntp package has been removed from the standard library.
+Its new home is the nntp-go project at Google Code:
+ http://code.google.com/p/nntp-go
+You can install it with goinstall:
+ goinstall nntp-go.googlecode.com/hg/nntp
+And import it in your code like so:
+ import "nntp-go.googlecode.com/hg/nntp"
+
+Other changes:
+* 6g: avoid too-large immediate constants.
+* 8l, runtime: initial support for Plan 9 (thanks Yuval Pavel Zholkover).
+* 6l, 8l: more improvements on exporting debug information (DWARF).
+* arm: code gen fixes. Most tests now pass, except for floating point code.
+* big: add random number generation (thanks Florian Uekermann).
+* gc: keep track of real actual type of identifiers,
+ report that shift must be unsigned integer,
+ select receive with implicit conversion.
+* goplay: fix to run under windows (thanks Yasuhiro Matsumoto).
+* http: do not close connection after sending HTTP/1.0 request.
+* netchan: add new method Hangup to terminate transmission on a channel.
+* os: change TestForkExec so it can run on windows (thanks Yasuhiro Matsumoto).
+* runtime: don't let select split stack.
+* syscall/arm: correct 64-bit system call arguments.
+</pre>
+
+<h2 id="2010-10-13">2010-10-13</h2>
+
+<pre>
+This release includes changes to the log package, the removal of exp/iterable,
+two new tools (gotry and goplay), one small language change, and many other
+changes and fixes. If you use the log or iterable packages, you need to make
+changes to your code.
+
+The log package has changed. Loggers now have only one output, and output to
+standard error by default. The names have also changed, although the old names
+are still supported. They will be deleted in the next release, though, so it
+would be good to update now if you can. For most purposes all you need to do
+is make these substitutions:
+ log.Stderr -> log.Println or log.Print
+ log.Stderrf -> log.Printf
+ log.Crash -> log.Panicln or log.Panic
+ log.Crashf -> log.Panicf
+ log.Exit -> log.Exitln or log.Exit
+ log.Exitf -> log.Exitf (no change)
+Calls to log.New() must drop the second argument.
+Also, custom loggers with exit or panic properties will need to be reworked.
+For full details, see the change description:
+ http://code.google.com/p/go/source/detail?r=d8a3c7563d
+
+The language change is that uses of pointers to interface values no longer
+automatically dereference the pointer. A pointer to an interface value is more
+often a beginner's bug than correct code.
+
+The package exp/iterable has been removed. It was an interesting experiment,
+but it encourages writing inefficient code and has outlived its utility.
+
+The new tools:
+* gotry: an exercise in reflection and an unusual tool. Run 'gotry' for details.
+* goplay: a stand-alone version of the Go Playground. See misc/goplay.
+
+Other changes:
+* 6l: Mach-O fixes, and fix to work with OS X nm/otool (thanks Jim McGrath).
+* [568]a: correct line numbers for statements.
+* arm: code generation and runtime fixes,
+ adjust recover for new reflect.call,
+ enable 6 more tests after net fix.
+* big: fix panic and round correctly in Rat.FloatString (thanks Anthony Martin).
+* build: Make.cmd: remove $(OFILES) (thanks Eric Clark),
+ Make.pkg: remove .so before installing new one,
+ add GOHOSTOS and GOHOSTARCH environment variables.
+* crypto/tls: better error messages for certificate issues,
+ make SetReadTimeout work.
+* doc: add Sydney University video,
+ add The Expressiveness of Go talk.
+* exp/draw/x11: support X11 vendors other than "The X.Org Foundation".
+* expvar: add (*Int).Set (thanks Sam Thorogood).
+* fmt: add Errorf helper function,
+ allow %d on []byte.
+* gc: O(1) string comparison when lengths differ,
+ various bug fixes.
+* http: return the correct error if a header line is too long.
+* image: add image.Tiled type, the Go equivalent of Plan 9's repl bit.
+* ld: be less picky about bad line number info.
+* misc/cgo/life: fix for new slice rules (thanks Graham Miller).
+* net: allow _ in DNS names.
+* netchan: export before import when testing, and
+ zero out request to ensure correct gob decoding. (thanks Roger Peppe).
+* os: make tests work on windows (thanks Alex Brainman).
+* runtime: bug fix: serialize mcache allocation,
+ correct iteration of large map values,
+ faster strequal, memequal (thanks Graham Miller),
+ fix argument dump in traceback,
+ fix tiny build.
+* smtp: new package (thanks Evan Shaw).
+* syscall: add sockaddr_ll support for linux/386, linux/amd64 (thanks Mikio Hara),
+ add ucred structure for SCM_CREDENTIALS over UNIX sockets. (thanks Albert Strasheim).
+* syscall: implement WaitStatus and Wait4() for windows (thanks Wei Guangjing).
+* time: add After.
+* websocket: enable tests on windows (thanks Alex Brainman).
+</pre>
+
+<h2 id="2010-09-29">2010-09-29</h2>
+
+<pre>
+This release includes some minor language changes and some significant package
+changes. You may need to change your code if you use ...T parameters or the
+http package.
+
+The semantics and syntax of forwarding ...T parameters have changed.
+ func message(f string, s ...interface{}) { fmt.Printf(f, s) }
+Here, s has type []interface{} and contains the parameters passed to message.
+Before this language change, the compiler recognized when a function call
+passed a ... parameter to another ... parameter of the same type, and just
+passed it as though it was a list of arguments. But this meant that you
+couldn't control whether to pass the slice as a single argument and you
+couldn't pass a regular slice as a ... parameter, which can be handy. This
+change gives you that control at the cost of a few characters in the call.
+If you want the promotion to ..., append ... to the argument:
+ func message(f string, s ...interface{}) { fmt.Printf(f, s...) }
+Without the ..., s would be passed to Printf as a single argument of type
+[]interface{}. The bad news is you might need to fix up some of your code,
+but the compiler will detect the situation and warn you.
+
+Also, the http.Handler and http.HandlerFunc types have changed. Where http
+handler functions previously accepted an *http.Conn, they now take an interface
+type http.ResponseWriter. ResponseWriter implements the same methods as *Conn,
+so in most cases the only change required will be changing the type signature
+of your handler function's first parameter. See:
+ http://golang.org/pkg/http/#Handler
+
+The utf8 package has a new type, String, that provides efficient indexing
+into utf8 strings by rune (previously an expensive conversion to []int
+was required). See:
+ http://golang.org/pkg/utf8/#String
+
+The compiler will now automatically insert a semicolon at the end of a file if
+one is not found. This effect of this is that Go source files are no longer
+required to have a trailing newline.
+
+Other changes:
+* 6prof: more accurate usage message.
+* archive/zip: new package for reading Zip files.
+* arm: fix code generation, 10 more package tests pass.
+* asn1: make interface consistent with json.
+* bufio.UnreadRune: fix bug at EOF.
+* build: clear custom variables like GREP_OPTIONS,
+ silence warnings generated by ubuntu gcc,
+ use full path when compiling libraries.
+* bytes, strings: change lastIndexFunc to use DecodeLastRune (thanks Roger Peppe).
+* doc: add to and consolidate non-english doc references,
+ consolidate FAQs into a single file, go_faq.html,
+ updates for new http interface.
+* fmt/Printf: document and tweak error messages produced for bad formats.
+* gc: allow select case expr = <-c,
+ eliminate duplicates in method table,
+ fix reflect table method receiver,
+ improve error message for x \= 0.
+* go/scanner: treat EOF like a newline for purposes of semicolon insertion.
+* gofmt: stability improvements.
+* gotest: leave _testmain.go for "make clean" to clean up.
+* http: correct escaping of different parts of URL,
+ support HTTP/1.0 Keep-Alive.
+* json: do not write to unexported fields.
+* libcgo: don't build for NaCl,
+ set g, m in thread local storage for windows 386 (thanks Wei Guangjing).
+* math: Fix off-by-one error in Ilogb and Logb. (thanks Charles L. Dorian).
+* misc/dashboard/builder: remove build files after benchmarking.
+* nacl: update instructions for new SDK.
+* net: enable v4-over-v6 on ip sockets,
+ fix crash in DialIP.
+* os: check for valid arguments in windows Readdir (thanks Peter Mundy).
+* runtime: add mmap of null page just in case,
+ correct stats in SysFree,
+ fix unwindstack crash.
+* syscall: add IPPROTO_IPV6 and IPV6_V6ONLY const to fix nacl and windows build,
+ add inotify on Linux (thanks Balazs Lecz),
+ fix socketpair in syscall_bsd,
+ fix windows value of IPV6_V6ONLY (thanks Alex Brainman),
+ implement windows version of Utimes (thanks Alex Brainman),
+ make mkall.sh work for nacl.
+* test: Add test that causes incorrect error from gccgo.
+* utf8: add DecodeLastRune and DecodeLastRuneInString (thanks Roger Peppe).
+* xml: Allow entities inside CDATA tags (thanks Dan Sinclair).
+</pre>
+
+<h2 id="2010-09-22">2010-09-22</h2>
+
+<pre>
+This release includes new package functionality, and many bug fixes and changes.
+It also improves support for the arm and nacl platforms.
+
+* 5l: avoid fixed buffers in list.
+* 6l, 8l: clean up ELF code, fix NaCl.
+* 6l/8l: emit DWARF frame info.
+* Make.inc: make GOOS detection work on windows (thanks Alex Brainman).
+* build: fixes for native arn build,
+ make all.bash run on Ubuntu ARM.
+* cgo: bug fixes,
+ show preamble gcc errors (thanks Eric Clark).
+* crypto/x509, crypto/tls: improve root matching and observe CA flag.
+* crypto: Fix certificate validation.
+* doc: variable-width layout.
+* env.bash: fix building in directory with spaces in the path (thanks Alex Brainman).
+* exp/4s, exp/nacl/av: sync to recent exp/draw changes.
+* exp/draw/x11: mouse location is a signed integer.
+* exp/nacl/av: update color to max out at 1<<16-1 instead of 1<<32-1.
+* fmt: support '*' for width or precision (thanks Anthony Martin).
+* gc: improvements to static initialization,
+ make sure path names are canonical.
+* gob: make robust when decoding a struct with non-struct data.
+* gobuilder: add -cmd for user-specified build command,
+ add -rev= flag to build specific revision and exit,
+ fix bug that caused old revisions to be rebuilt.
+* godoc: change default filter file name to "",
+ don't use quadratic algorithm to filter paths,
+ show "Last update" info for directory listings.
+* http: new redirect test,
+ URLEscape now escapes all reserved characters as per the RFC.
+* nacl: fix zero-length writes.
+* net/dict: parse response correctly (thanks Fazlul Shahriar).
+* netchan: add a cross-connect test,
+ handle closing of channels,
+ provide a method (Importer.Errors()) to recover protocol errors.
+* os: make Open() O_APPEND flag work on windows (thanks Alex Brainman),
+ make RemoveAll() work on windows (thanks Alex Brainman).
+* pkg/Makefile: disable netchan test to fix windows build (thanks Alex Brainman).
+* regexp: delete Iter methods.
+* runtime: better panic for send to nil channel.
+* strings: fix minor bug in LastIndexFunc (thanks Roger Peppe).
+* suffixarray: a package for creating suffixarray-based indexes.
+* syscall: Use vsyscall for syscall.Gettimeofday and .Time on linux amd64.
+* test: fix NaCl build.
+* windows: fix netchan test by using 127.0.0.1.
+</pre>
+
+<h2 id="2010-09-15">2010-09-15</h2>
+
+<pre>
+This release includes a language change: the lower bound of a subslice may
+now be omitted, in which case the value will default to 0.
+For example, s[0:10] may now be written as s[:10], and s[0:] as s[:].
+
+The release also includes important bug fixes for the ARM architecture,
+as well as the following fixes and changes:
+
+* 5g: register allocation bugs
+* 6c, 8c: show line numbers in -S output
+* 6g, 6l, 8g, 8l: move read-only data to text segment
+* 6l, 8l: make etext accurate; introduce rodata, erodata.
+* arm: fix build bugs.
+ make libcgo build during OS X cross-compile
+ remove reference to deleted file syntax/slice.go
+ use the correct stat syscalls
+ work around reg allocator bug in 5g
+* bufio: add UnreadRune.
+* build: avoid bad environment interactions
+ fix build for tiny
+ generate, clean .exe files on Windows (thanks Joe Poirier)
+ test for _WIN32, not _MINGW32 (thanks Joe Poirier)
+ work with GNU Make 3.82 (thanks Jukka-Pekka Kekkonen)
+* cgo: add typedef for uintptr in generated headers
+ silence warning for C call returning const pointer
+* codereview: convert email address to lower case before checking CONTRIBUTORS
+* crypto/tls: don't return an error from Close()
+* doc/tutorial: update for slice changes.
+* exec: separate LookPath implementations for unix/windows (thanks Joe Poirier)
+* exp/draw/x11: allow clean shutdown when the user closes the window.
+* exp/draw: clip destination rectangle to the image bounds.
+ fast path for drawing overlapping image.RGBAs.
+ fix double-counting of pt.Min for the src and mask points.
+ reintroduce the MouseEvent.Nsec timestamp.
+ rename Context to Window, and add a Close method.
+* exp/debug: preliminary support for 'copy' function (thanks Sebastien Binet)
+* fmt.Fscan: use UnreadRune to preserve data across calls.
+* gc: better printing of named constants, func literals in errors
+ many bug fixes
+ fix line number printing with //line directives
+ fix symbol table generation on windows (thanks Alex Brainman)
+ implement comparison rule from spec change 33abb649cb63
+ implement new slice spec (thanks Scott Lawrence)
+ make string x + y + z + ... + w efficient
+ more accurate line numbers for ATEXT
+ remove &[10]int -> []int conversion
+* go-mode.el: fix highlighting for 'chan' type (thanks Scott Lawrence)
+* godoc: better support for directory trees for user-supplied paths
+ use correct delay time (bug fix)
+* gofmt, go/printer: update internal estimated position correctly
+* goinstall: warn when package name starts with http:// (thanks Scott Lawrence)
+* http: check https certificate against host name
+ do not cache CanonicalHeaderKey (thanks Jukka-Pekka Kekkonen)
+* image: change a ColorImage's minimum point from (0, 0) to (-1e9, -1e9).
+ introduce Intersect and Union rectangle methods.
+* ld: handle quoted spaces in package path (thanks Dan Sinclair)
+* libcgo: fix NaCl build.
+* libmach: fix build on arm host
+ fix new thread race with Linux
+* math: make portable Tan(Pi/2) return NaN
+* misc/dashboard/builder: gobuilder, a continuous build client
+* net: disable tests for functions not available on windows (thanks Alex Brainman)
+* netchan: make -1 unlimited, as advertised.
+* os, exec: rename argv0 to name
+* path: add IsAbs (thanks Ivan Krasin)
+* runtime: fix bug in tracebacks
+ fix crash trace on amd64
+ fix windows build (thanks Alex Brainman)
+ use manual stack for garbage collection
+* spec: add examples for slices with omitted index expressions.
+ allow omission of low slice bound (thanks Scott Lawrence)
+* syscall: fix windows Gettimeofday (thanks Alex Brainman)
+* test(arm): disable zerodivide.go because compilation fails.
+* test(windows): disable tests that cause the build to fail (thanks Joe Poirier)
+* test/garbage/parser: sync with recent parser changes
+* test: Add test for //line
+ Make gccgo believe that the variables can change.
+ Recognize gccgo error messages.
+ Reduce race conditions in chan/nonblock.go.
+ Run garbage collector before testing malloc numbers.
+* websocket: Add support for secure WebSockets (thanks Jukka-Pekka Kekkonen)
+* windows: disable unimplemented tests (thanks Joe Poirier)
+</pre>
+
+<h2 id="2010-09-06">2010-09-06</h2>
+
+<pre>
+This release includes the syntactic modernization of more than 100 files in /test,
+and these additions, changes, and fixes:
+* 6l/8l: emit DWARF in macho.
+* 8g: use FCHS, not FMUL, for minus float.
+* 8l: emit DWARF in ELF,
+ suppress emitting DWARF in Windows PE (thanks Alex Brainman).
+* big: added RatString, some simplifications.
+* build: create bin and pkg directories as needed; drop from hg,
+ delete Make.386 Make.amd64 Make.arm (obsoleted by Make.inc),
+ fix cgo with -j2,
+ let pkg/Makefile coordinate building of Go commands,
+ never use quietgcc in Make.pkg,
+ remove more references to GOBIN and GOROOT (thanks Christian Himpel).
+* codereview: Fix uploading for Mercurial 1.6.3 (thanks Evan Shaw),
+ consistent indent, cut dead code,
+ fix hang on standard hg commands,
+ print status when tasks take longer than 30 seconds,
+ really disable codereview when not available,
+ upload files in parallel (5x improvement on large CLs).
+* crypto/hmac: make Sum idempotent (thanks Jukka-Pekka Kekkonen).
+* doc: add links to more German docs,
+ add round-robin flag to io2010 balance example,
+ fix a bug in the example in Constants subsection (thanks James Fysh),
+ various changes for validating HTML (thanks Scott Lawrence).
+* fmt: delete erroneous sentence about return value for Sprint*.
+* gc: appease bison version running on FreeBSD builder,
+ fix spurious syntax error.
+* go/doc: use correct escaper for URL.
+* go/printer: align ImportPaths in ImportDecls (thanks Scott Lawrence).
+* go/typechecker: 2nd step towards augmenting AST with full type information.
+* gofmt: permit omission of first index in slice expression.
+* goinstall: added -a flag to mean "all remote packages" (thanks Scott Lawrence),
+ assume go binaries are in path (following new convention),
+ use https for Google Code checkouts.
+* gotest: allow make test of cgo packages (without make install).
+* http: add Date to server, Last-Modified and If-Modified-Since to file server,
+ add PostForm function to post url-encoded key/value data,
+ obscure passwords in return value of URL.String (thanks Scott Lawrence).
+* image: introduce Config type and DecodeConfig function.
+* libcgo: update Makefile to use Make.inc.
+* list: update comment to state that the zero value is ready to use.
+* math: amd64 version of Sincos (thanks Charles L. Dorian).
+* misc/bash: add *.go completion for gofmt (thanks Scott Lawrence).
+* misc/emacs: make _ a word symbol (thanks Scott Lawrence).
+* misc: add zsh completion (using compctl),
+ syntax highlighting for Fraise.app (OS X) (thanks Vincent Ambo).
+* net/textproto: Handle multi-line responses (thanks Evan Shaw).
+* net: add LookupMX (thanks Corey Thomasson).
+* netchan: Fix race condition in test,
+ rather than 0, make -1 mean infinite (a la strings.Split et al),
+ use acknowledgements on export send.
+ new methods Sync and Drain for clean teardown.
+* regexp: interpret all Go characer escapes \a \b \f \n \r \t \v.
+* rpc: fix bug that caused private methods to attempt to be registered.
+* runtime: Correct commonType.kind values to match compiler,
+ add GOOS, GOARCH; fix FuncLine,
+ special case copy, equal for one-word interface values (thanks Kyle Consalus).
+* scanner: fix incorrect reporting of error in Next (thanks Kyle Consalus).
+* spec: clarify that arrays must be addressable to be sliceable.
+* template: fix space handling around actions.
+* test/solitaire: an exercise in backtracking and string conversions.
+* test: Recognize gccgo error messages and other fixes.
+* time: do not crash in String on nil Time.
+* tutorial: regenerate HTML to pick up change to progs/file.go.
+* websocket: fix missing Sec-WebSocket-Protocol on server response (thanks Jukka-Pekka Kekkonen).
+</pre>
+
+<h2 id="2010-08-25">2010-08-25</h2>
+
+<pre>
+This release includes changes to the build system that will likely require you
+to make changes to your environment variables and Makefiles.
+
+All environment variables are now optional:
+ - $GOOS and $GOARCH are now optional; their values should now be inferred
+ automatically by the build system,
+ - $GOROOT is now optional, but if you choose not to set it you must run
+ 'gomake' instead of 'make' or 'gmake' when developing Go programs
+ using the conventional Makefiles,
+ - $GOBIN remains optional and now defaults to $GOROOT/bin;
+ if you wish to use this new default, make sure it is in your $PATH
+ and that you have removed the existing binaries from $HOME/bin.
+
+As a result of these changes, the Go Makefiles have changed. If your Makefiles
+inherit from the Go Makefiles, you must change this line:
+ include ../../Make.$(GOARCH)
+to this:
+ include ../../Make.inc
+
+This release also removes the deprecated functions in regexp and the
+once package. Any code that still uses them will break.
+See the notes from the last release for details:
+ http://golang.org/doc/devel/release.html#2010-08-11
+
+Other changes:
+* 6g: better registerization for slices, strings, interface values
+* 6l: line number information in DWARF format
+* build: $GOBIN defaults to $GOROOT/bin,
+ no required environment variables
+* cgo: add C.GoStringN (thanks Eric Clark).
+* codereview: fix issues with leading tabs in CL descriptions,
+ do not send "Abandoned" mail if the CL has not been mailed.
+* crypto/ocsp: add missing Makefile.
+* crypto/tls: client certificate support (thanks Mikkel Krautz).
+* doc: update gccgo information for recent changes.
+ fix errors in Effective Go.
+* fmt/print: give %p priority, analogous to %T,
+ honor Formatter in Print, Println.
+* gc: fix parenthesization check.
+* go/ast: facility for printing AST nodes,
+ first step towards augmenting AST with full type information.
+* go/printer: do not modify tabwriter.Escape'd text.
+* gofmt: do not modify multi-line string literals,
+ print AST nodes by setting -ast flag.
+* http: fix typo in http.Request documentation (thanks Scott Lawrence)
+ parse query string always, not just in GET
+* image/png: support 16-bit color.
+* io: ReadAtLeast now errors if min > len(buf).
+* jsonrpc: use `error: null` for success, not `error: ""`.
+* libmach: implement register fetch for 32-bit x86 kernel.
+* net: make IPv6 String method standards-compliant (thanks Mikio Hara).
+* os: FileInfo.Permission() now returns uint32 (thanks Scott Lawrence),
+ implement env using native Windows API (thanks Alex Brainman).
+* reflect: allow PtrValue.PointTo(nil).
+* runtime: correct line numbers for .goc files,
+ fix another stack split bug,
+ fix freebsd/386 mmap.
+* syscall: regenerate syscall/z* files for linux/386, linux/amd64, linux/arm.
+* tabwriter: Introduce a new flag StripEscape.
+* template: fix handling of space around actions,
+ vars preceded by white space parse correctly (thanks Roger Peppe).
+* test: add test case that crashes gccgo.
+* time: parse no longer requires minutes for time zone (thanks Jan H. Hosang)
+* yacc: fix bounds check in error recovery.
+</pre>
+
+<h2 id="2010-08-11">2010-08-11</h2>
+
+<pre>
+This release introduces some package changes. You may need to change your
+code if you use the once, regexp, image, or exp/draw packages.
+
+The type Once has been added to the sync package. The new sync.Once will
+supersede the functionality provided by the once package. We intend to remove
+the once package after this release. See:
+ http://golang.org/pkg/sync/#Once
+All instances of once in the standard library have been replaced with
+sync.Once. Reviewing these changes may help you modify your existing code.
+The relevant changeset:
+ http://code.google.com/p/go/source/detail?r=fa2c43595119
+
+A new set of methods has been added to the regular expression package, regexp.
+These provide a uniformly named approach to discovering the matches of an
+expression within a piece of text; see the package documentation for details:
+ http://golang.org/pkg/regexp/
+These new methods will, in a later release, replace the old methods for
+matching substrings. The following methods are deprecated:
+ Execute (use FindSubmatchIndex)
+ ExecuteString (use FindStringSubmatchIndex)
+ MatchStrings(use FindStringSubmatch)
+ MatchSlices (use FindSubmatch)
+ AllMatches (use FindAll; note that n<0 means 'all matches'; was n<=0)
+ AllMatchesString (use FindAllString; note that n<0 means 'all matches'; was n<=0)
+(Plus there are ten new methods you didn't know you wanted.)
+Please update your code to use the new routines before the next release.
+
+An image.Image now has a Bounds rectangle, where previously it ranged
+from (0, 0) to (Width, Height). Loops that previously looked like:
+ for y := 0; y < img.Height(); y++ {
+ for x := 0; x < img.Width(); x++ {
+ // Do something with img.At(x, y)
+ }
+ }
+should instead be:
+ b := img.Bounds()
+ for y := b.Min.Y; y < b.Max.Y; y++ {
+ for x := b.Min.X; x < b.Max.X; x++ {
+ // Do something with img.At(x, y)
+ }
+ }
+The Point and Rectangle types have also moved from exp/draw to image.
+
+Other changes:
+* arm: bugfixes and syscall (thanks Kai Backman).
+* asn1: fix incorrect encoding of signed integers (thanks Nicholas Waples).
+* big: fixes to bitwise functions (thanks Evan Shaw).
+* bytes: add IndexRune, FieldsFunc and To*Special (thanks Christian Himpel).
+* encoding/binary: add complex (thanks Roger Peppe).
+* exp/iterable: add UintArray (thanks Anschel Schaffer-Cohen).
+* godoc: report Status 404 if a pkg or file is not found.
+* gofmt: better reporting for unexpected semicolon errors.
+* html: new package, an HTML tokenizer.
+* image: change image representation from slice-of-slices to linear buffer,
+ introduce Decode and RegisterFormat,
+ introduce Transparent and Opaque,
+ replace Width and Height by Bounds, add the Point and Rect types.
+* libbio: fix Bprint to address 6g issues with large data structures.
+* math: fix amd64 Hypot (thanks Charles L. Dorian).
+* net/textproto: new package, with example net/dict.
+* os: fix ForkExec() handling of envv == nil (thanks Alex Brainman).
+* png: grayscale support (thanks Mathieu Lonjaret).
+* regexp: document that backslashes are the escape character.
+* rpc: catch errors from ReadResponseBody.
+* runtime: memory free fix (thanks Alex Brainman).
+* template: add ParseFile method to template.Template.
+* test/peano: use directly recursive type def.
+</pre>
+
+<h2 id="2010-08-04">2010-08-04</h2>
+
+<pre>
+This release includes a change to os.Open (and co.). The file permission
+argument has been changed to a uint32. Your code may require changes - a simple
+conversion operation at most.
+
+Other changes:
+* amd64: use segment memory for thread-local storage.
+* arm: add gdb support to android launcher script,
+ bugfixes (stack clobbering, indices),
+ disable another flaky test,
+ remove old qemu dependency from gotest.
+* bufio: introduce Peek.
+* bytes: added test case for explode with blank string (thanks Scott Lawrence).
+* cgo: correct multiple return value function invocations (thanks Christian Himpel).
+* crypto/x509: unwrap Subject Key Identifier (thanks Adam Langley).
+* gc: index bounds tests and other fixes.
+* gofmt/go/parser: strengthen syntax checks.
+* goinstall: check for error from exec.*Cmd.Wait() (thanks Alex Brainman).
+* image/png: use image-specific methods for checking opacity.
+* image: introduce Gray and Gray16 types,
+ remove the named colors except for Black and White.
+* json: object members must have a value (thanks Anthony Martin).
+* misc/vim: highlight misspelled words only in comments (thanks Christian Himpel).
+* os: Null device (thanks Peter Mundy).
+* runtime: do not fall through in SIGBUS/SIGSEGV.
+* strings: fix Split("", "", -1) (thanks Scott Lawrence).
+* syscall: make go errors not clash with windows errors (thanks Alex Brainman).
+* test/run: diff old new,
+* websocket: correct challenge response (thanks Tarmigan Casebolt),
+ fix bug involving spaces in header keys (thanks Bill Neubauer).
+</pre>
+
+<h2 id="2010-07-29">2010-07-29</h2>
+
+<pre>
+* 5g: more soft float support and several bugfixes.
+* asn1: Enumerated, Flag and GeneralizedTime support.
+* build: clean.bash to check that GOOS and GOARCH are set.
+* bytes: add IndexFunc and LastIndexFunc (thanks Fazlul Shahriar),
+ add Title.
+* cgo: If CC is set in environment, use it rather than "gcc",
+ use new command line syntax: -- separates cgo flags from gcc flags.
+* codereview: avoid crash if no config,
+ don't run gofmt with an empty file list,
+ make 'hg submit' work with Mercurial 1.6.
+* crypto/ocsp: add package to parse OCSP responses.
+* crypto/tls: add client-side SNI support and PeerCertificates.
+* exp/bignum: delete package - functionality subsumed by package big.
+* fmt.Print: fix bug in placement of spaces introduced when ...T went in.
+* fmt.Scanf: handle trailing spaces.
+* gc: fix smaller-than-pointer-sized receivers in interfaces,
+ floating point precision/normalization fixes,
+ graceful exit on seg fault,
+ import dot shadowing bug,
+ many fixes including better handling of invalid input,
+ print error detail about failure to open import.
+* gccgo_install.html: add description of the port to RTEMS (thanks Vinu Rajashekhar).
+* gobs: fix bug in singleton arrays.
+* godoc: display synopses for all packages that have some kind of documentation..
+* gofmt: fix some linebreak issues.
+* http: add https client support (thanks Fazlul Shahriar),
+ write body when content length unknown (thanks James Whitehead).
+* io: MultiReader and MultiWriter (thanks Brad Fitzpatrick),
+ fix another race condition in Pipes.
+* ld: many fixes including better handling of invalid input.
+* libmach: correct handling of .5 files with D_REGREG addresses.
+* linux/386: use Xen-friendly ELF TLS instruction sequence.
+* mime: add AddExtensionType (thanks Yuusei Kuwana).
+* misc/vim: syntax file recognizes constants like 1e9 (thanks Petar Maymounkov).
+* net: TCPConn.SetNoDelay, back by popular demand.
+* net(windows): fix crashing Read/Write when passed empty slice on (thanks Alex Brainman),
+ implement LookupHost/Port/SRV (thanks Wei Guangjing),
+ properly handle EOF in (*netFD).Read() (thanks Alex Brainman).
+* runtime: fix bug introduced in revision 4a01b8d28570 (thanks Alex Brainman),
+ rename cgo2c, *.cgo to goc2c, *.goc (thanks Peter Mundy).
+* scanner: better comment.
+* strings: add Title.
+* syscall: add ForkExec, Syscall12 on Windows (thanks Daniel Theophanes),
+ improve windows errno handling (thanks Alex Brainman).
+* syscall(windows): fix FormatMessage (thanks Peter Mundy),
+ implement Pipe() (thanks Wei Guangjing).
+* time: fix parsing of minutes in time zones.
+* utf16(windows): fix cyclic dependency when testing (thanks Peter Mundy).
+</pre>
+
+<h2 id="2010-07-14">2010-07-14</h2>
+
+<pre>
+This release includes a package change. In container/vector, the Iter method
+has been removed from the Vector, IntVector, and StringVector types. Also, the
+Data method has been renamed to Copy to better express its actual behavior.
+Now that Vector is just a slice, any for loops ranging over v.Iter() or
+v.Data() can be changed to range over v instead.
+
+Other changes:
+* big: Improvements to Rat.SetString (thanks Evan Shaw),
+ add sign, abs, Rat.IsInt.
+* cgo: various bug fixes.
+* codereview: Fix for Mercurial >= 1.6 (thanks Evan Shaw).
+* crypto/rand: add Windows implementation (thanks Peter Mundy).
+* crypto/tls: make HTTPS servers easier,
+ add client OCSP stapling support.
+* exp/eval: converted from bignum to big (thanks Evan Shaw).
+* gc: implement new len spec, range bug fix, optimization.
+* go/parser: require that '...' parameters are followed by a type.
+* http: fix ParseURL to handle //relative_path properly.
+* io: fix SectionReader Seek to seek backwards (thanks Peter Mundy).
+* json: Add HTMLEscape (thanks Micah Stetson).
+* ld: bug fixes.
+* math: amd64 version of log (thanks Charles L. Dorian).
+* mime/multipart: new package to parse multipart MIME messages
+ and HTTP multipart/form-data support.
+* os: use TempFile with default TempDir for test files (thanks Peter Mundy).
+* runtime/tiny: add docs for additional VMs, fix build (thanks Markus Duft).
+* runtime: better error for send/recv on nil channel.
+* spec: clarification of channel close(),
+ lock down some details about channels and select,
+ restrict when len(x) is constant,
+ specify len/cap for nil slices, maps, and channels.
+* windows: append .exe to binary names (thanks Joe Poirier).
+</pre>
+
+<h2 id="2010-07-01">2010-07-01</h2>
+
+<pre>
+This release includes some package changes that may require changes to
+client code.
+
+The Split function in the bytes and strings packages has been changed.
+The count argument, which limits the size of the return, previously treated
+zero as unbounded. It now treats 0 as 0, and will return an empty slice.
+To request unbounded results, use -1 (or some other negative value).
+The new Replace functions in bytes and strings share this behavior.
+This may require you change your existing code.
+
+The gob package now allows the transmission of non-struct values at the
+top-level. As a result, the rpc and netchan packages have fewer restrictions
+on the types they can handle. For example, netchan can now share a chan int.
+
+The release also includes a Code Walk: "Share Memory By Communicating".
+It describes an idiomatic Go program that uses goroutines and channels:
+ http://golang.org/doc/codewalk/sharemem/
+
+There is now a Projects page on the Go Dashboard that lists Go programs,
+tools, and libraries:
+ http://godashboard.appspot.com/project
+
+Other changes:
+* 6a, 6l: bug fixes.
+* bytes, strings: add Replace.
+* cgo: use slash-free relative paths for .so references.
+* cmath: correct IsNaN for argument cmplx(Inf, NaN) (thanks Charles L. Dorian).
+* codereview: allow multiple email addresses in CONTRIBUTORS.
+* doc/codewalk: add Share Memory By Communicating.
+* exp/draw/x11: implement the mapping from keycodes to keysyms.
+* fmt: Printf: fix bug in handling of %#v, allow other verbs for slices
+ Scan: fix handling of EOFs.
+* gc: bug fixes and optimizations.
+* gob: add DecodeValue and EncodeValue,
+ add support for complex numbers.
+* goinstall: support for Bazaar+Launchpad (thanks Gustavo Niemeyer).
+* io/ioutil: add TempFile for Windows (thanks Peter Mundy).
+* ld: add -u flag to check safe bits; discard old -u, -x flags.
+* math: amd64 versions of Exp and Fabs (thanks Charles L. Dorian).
+* misc/vim: always override filetype detection for .go files.
+* net: add support for DNS SRV requests (thanks Kirklin McDonald),
+ initial attempt to implement Windows version (thanks Alex Brainman).
+* netchan: allow chan of basic types now that gob can handle such,
+ eliminate the need for a pointer value in Import and Export.
+* os/signal: only catch all signals if os/signal package imported.
+* regexp: bug fix: need to track whether match begins with fixed prefix.
+* rpc: allow non-struct args and reply (they must still be pointers).
+* runtime: bug fixes and reorganization.
+* strconv: fix bugs in floating-point and base 2 conversions
+* syscall: add syscall_bsd.go to zsycall_freebsd_386.go (thanks Peter Mundy),
+ add socketpair (thanks Ivan Krasin).
+* time: implement time zones for Windows (thanks Alex Brainman).
+* x509: support non-self-signed certs.
+</pre>
+
+<h2 id="2010-06-21">2010-06-21</h2>
+
+<pre>
+This release includes a language change. The "..." function parameter form is
+gone; "...T" remains. Typically, "...interface{}" can be used instead of "...".
+
+The implementation of Printf has changed in a way that subtly affects its
+handling of the fmt.Stringer interface. You may need to make changes to your
+code. For details, see:
+ https://groups.google.com/group/golang-nuts/msg/6fffba90a3e3dc06
+
+The reflect package has been changed. If you have code that uses reflect,
+it will need to be updated. For details, see:
+ https://groups.google.com/group/golang-nuts/msg/7a93d07c590e7beb
+
+Other changes:
+* 8l: correct test for sp == top of stack in 8l -K code.
+* asn1: allow '*' in PrintableString.
+* bytes.Buffer.ReadFrom: fix bug.
+* codereview: avoid exception in match (thanks Paolo Giarrusso).
+* complex divide: match C99 implementation.
+* exp/draw: small draw.drawGlyphOver optimization.
+* fmt: Print*: reimplement to switch on type first,
+ Scanf: improve error message when input does not match format.
+* gc: better error messages for interface failures, conversions, undefined symbols.
+* go/scanner: report illegal escape sequences.
+* gob: substitute slice for map.
+* goinstall: process dependencies for package main (thanks Roger Peppe).
+* gopack: add S flag to force marking a package as safe,
+ simplify go metadata code.
+* html: sync testdata/webkit to match WebKit tip.
+* http: reply to Expect 100-continue requests automatically (thanks Brad Fitzpatrick).
+* image: add an Alpha16 type.
+* ld: pad Go symbol table out to page boundary (fixes cgo crash).
+* misc/vim: reorganize plugin to be easier to use (thanks James Whitehead).
+* path: add Base, analogous to Unix basename.
+* pkg/Makefile: allow DISABLE_NET_TESTS=1 to disable network tests.
+* reflect: add Kind, Type.Bits, remove Int8Type, Int8Value, etc.
+* runtime: additional Windows support (thanks Alex Brainman),
+ correct fault for 16-bit divide on Leopard,
+ fix 386 signal handler bug.
+* strconv: add AtofN, FtoaN.
+* string: add IndexFunc and LastIndexFunc (thanks Roger Peppe).
+* syslog: use local network for tests.
+</pre>
+
+<h2 id="2010-06-09">2010-06-09</h2>
+
+<pre>
+This release contains many fixes and improvements, including several
+clarifications and consolidations to the Language Specification.
+
+The type checking rules around assignments and conversions are simpler but more
+restrictive: assignments no longer convert implicitly from *[10]int to []int
+(write x[0:] instead of &x), and conversions can no longer change the names of
+types inside composite types.
+
+The fmt package now includes flexible type-driven (fmt.Scan) and
+format-driven (fmt.Scanf) scanners for all basic types.
+
+* big: bug fix for Quo aliasing problem.
+* bufio: change ReadSlice to match description.
+* cgo: bug fixes.
+* doc: add Google I/O talk and programs,
+ codereview + Mercurial Queues info (thanks Peter Williams).
+* exp/draw: Draw fast paths for the Over operator,
+ add Rectangle.Eq and Point.In, fix Rectangle.Clip (thanks Roger Peppe).
+* fmt: Scan fixes and improvements.
+* gc: backslash newline is not a legal escape sequence in strings,
+ better error message when ~ operator is found,
+ fix export of complex types,
+ new typechecking rules.
+* go/parser: correct position of empty statement ';'.
+* gofmt: fix test script.
+* goinstall: use 'git pull' instead of 'git checkout' (thanks Michael Hoisie).
+* http: add Head function for making HTTP HEAD requests,
+ handle status 304 correctly.
+* image: add Opaque method to the image types.
+ make Color.RGBA return 16 bit color instead of 32 bit color.
+* io/ioutil: add TempFile.
+* math: Pow special cases and additional tests (thanks Charles L. Dorian).
+* netchan: improve closing and shutdown.
+* os: implement os.FileInfo.*time_ns for windows (thanks Alex Brainman).
+* os/signal: correct the regexp for finding Unix signal names (thanks Vinu Rajashekhar).
+* regexp: optimizations (thanks Kyle Consalus).
+* runtime: fix printing -Inf (thanks Evan Shaw),
+ finish pchw -> tiny, added gettime for tiny (thanks Daniel Theophanes).
+* spec: clean-ups and consolidation.
+* syscall: additional Windows compatibility fixes (thanks Alex Brainman).
+* test/bench: added regex-dna-parallel.go (thanks Kyle Consalus).
+* vector: type-specific Do functions now take f(type) (thanks Michael Hoisie).
+</pre>
+
+<h2 id="2010-05-27">2010-05-27</h2>
+
+<pre>
+A sizeable release, including standard library improvements and a slew of
+compiler bug fixes. The three-week interval was largely caused by the team
+preparing for Google I/O.
+
+* big: add Rat type (thanks Evan Shaw),
+ new features, much performance tuning, cleanups, and more tests.
+* bignum: deprecate by moving into exp directory.
+* build: allow MAKEFLAGS to be set outside the build scripts (thanks Christopher Wedgwood).
+* bytes: add Trim, TrimLeft, TrimRight, and generic functions (thanks Michael Hoisie).
+* cgo: fix to permit cgo callbacks from init code.
+* cmath: update range of Phase and Polar due to signed zero (thanks Charles L. Dorian).
+* codereview: work better with mq (thanks Peter Williams).
+* compress: renamings
+ NewDeflater -> NewWriter
+ NewInflater -> NewReader
+ Deflater -> Compressor
+ Inflater -> Decompressor
+* exp/draw/x11: respect $XAUTHORITY,
+ treat $DISPLAY the same way x-go-bindings does.
+* exp/draw: fast path for glyph images, other optimizations,
+ fix Rectangle.Canon (thanks Roger Peppe).
+* fmt: Scan, Scanln: Start of a simple scanning API in the fmt package,
+ fix Printf crash when given an extra nil argument (thanks Roger Peppe).
+* gc: better error when computing remainder of non-int (thanks Evan Shaw),
+ disallow middot in Go programs,
+ distinguish array, slice literal in error messages,
+ fix shift/reduce conflict in go.y export syntax,
+ fix unsafe.Sizeof on ideal constants,
+ handle use of builtin function outside function call,
+ many other bug fixes.
+* gob: add support for maps,
+ add test for indirect maps, slices, arrays.
+* godoc: collect package comments from all package files.
+* gofmt: don't lose mandatory semicolons,
+ exclude test w/ illegal syntax from test cases,
+ fix printing of labels.
+* http: prevent crash if remote server is not responding with "HTTP/".
+* json: accept escaped slash in string scanner (thanks Michael Hoisie),
+ fix array -> non-array decoding.
+* libmach: skip __nl_symbol_ptr section on OS X.
+* math: amd64 versions of Fdim, Fmax, Fmin,
+ signed zero Sqrt special case (thanks Charles L. Dorian).
+* misc/kate: convert isn't a built in function (thanks Evan Shaw).
+* net: implement BindToDevice,
+ implement raw sockets (thanks Christopher Wedgwood).
+* netFD: fix race between Close and Read/Write (thanks Michael Hoisie).
+* os: add Chtimes function (thanks Brad Fitzpatrick).
+* pkg/Makefile: add netchan to standard package list.
+* runtime: GOMAXPROCS returns previous value,
+ allow large map values,
+ avoid allocation for fixed strings,
+ correct tracebacks for nascent goroutines, even closures,
+ free old hashmap pieces during resizing.
+* spec: added imaginary literal to semicolon rules (was missing),
+ fix and clarify syntax of conversions,
+ simplify section on channel types,
+ other minor tweaks.
+* strconv: Btoui64 optimizations (thanks Kyle Consalus).
+* strings: use copy instead of for loop in Map (thanks Kyle Consalus).
+* syscall: implement BindToDevice (thanks Christopher Wedgwood),
+ add Utimes on Darwin/FreeBSD, add Futimes everywhere,
+ regenerate syscalls for some platforms.
+* template: regularize name lookups of interfaces, pointers, and methods.
+</pre>
+
+<h2 id="2010-05-04">2010-05-04</h2>
+
+<pre>
+In this release we renamed the Windows OS target from 'mingw' to 'windows'.
+If you are currently building for 'mingw' you should set GOOS=windows instead.
+
+* 5l, 6l, 8l, runtime: make -s binaries work.
+* 5l, 6l, 8l: change ELF header so that strip doesn't destroy binary.
+* 8l: fix absolute path detection on Windows.
+* big: new functions, optimizations, and cleanups,
+ add bitwise methods for Int (thanks Evan Shaw).
+* bytes: Change IndexAny to look for UTF-8 encoded characters.
+* darwin: bsdthread_create can fail; print good error.
+* fmt: %T missing print <nil> for nil (thanks Christopher Wedgwood).
+* gc: many fixes.
+* misc/cgo/gmp: fix bug in SetString.
+* net: fix resolv.conf EOF without newline bug (thanks Christopher Wedgwood).
+* spec: some small clarifications (no language changes).
+* syscall: add EWOULDBLOCK to sycall_nacl.go,
+ force O_LARGEFILE in Linux open system call,
+ handle EOF on pipe - special case on Windows (thanks Alex Brainman),
+ mingw Sleep (thanks Joe Poirier).
+* test/bench: import new fasta C reference, update Go, optimizations.
+* test: test of static initialization (fails).
+* vector: use correct capacity in call to make.
+* xml: allow text segments to end at EOF.
+</pre>
+
+<h2 id="2010-04-27">2010-04-27</h2>
+
+<pre>
+This release includes a new Codelab that illustrates the construction of a
+simple wiki web application:
+ http://golang.org/doc/codelab/wiki/
+
+It also includes a Codewalk framework for documenting code. See:
+ http://golang.org/doc/codewalk/
+
+Other changes:
+* 6g: fix need for parens around array index expression.
+* 6l, 8l: include ELF header in PT_LOAD mapping for text segment.
+* arm: add android runner script,
+ support for printing floats.
+* big: implemented Karatsuba multiplication,
+ many fixes and improvements (thanks Evan Shaw).
+* bytes: add Next method to Buffer, simplify Read,
+ shuffle implementation, making WriteByte 50% faster.
+* crypto/tls: simpler implementation of record layer.
+* exp/eval: fixes (thanks Evan Shaw).
+* flag: eliminate unnecessary structs.
+* gc: better windows support,
+ cmplx typecheck bug fix,
+ more specific error for statements at top level.
+* go/parser: don't require unnecessary parens.
+* godoc: exclude duplicate entries (thanks Andrei Vieru),
+ use int64 for timestamps (thanks Christopher Wedgwood).
+* gofmt: fine-tune stripping of parentheses,
+* json: Marshal, Unmarshal using new scanner,
+ preserve field name case by default,
+ scanner, Compact, Indent, and tests,
+ support for streaming.
+* libmach: disassemble MOVLQZX correctly.
+* math: more special cases for signed zero (thanks Charles L. Dorian).
+* net: add Pipe,
+ fix bugs in packStructValue (thanks Michael Hoisie),
+ introduce net.Error interface.
+* os: FileInfo: regularize the types of some fields,
+ create sys_bsd.go (thanks Giles Lean),
+ mingw bug fixes (thanks Alex Brainman).
+* reflect: add FieldByNameFunc (thanks Raif S. Naffah),
+ implement Set(nil), SetValue(nil) for PtrValue and MapValue.
+* regexp: allow escaping of any punctuation.
+* rpc/jsonrpc: support for jsonrpc wire encoding.
+* rpc: abstract client and server encodings,
+ add Close() method to rpc.Client.
+* runtime: closures, defer bug fix for Native Client,
+ rename cgo2c, *.cgo to goc2c, *.goc to avoid confusion with real cgo.
+ several other fixes.
+* scanner: implement Peek() to look at the next char w/o advancing.
+* strings: add ReadRune to Reader, add FieldsFunc (thanks Kyle Consalus).
+* syscall: match linux Setsid function signature to darwin,
+ mingw bug fixes (thanks Alex Brainman).
+* template: fix handling of pointer inside interface.
+* test/bench: add fannkuch-parallel.go (thanks Kyle Consalus),
+ pidigits ~10% performance win by using adds instead of shifts.
+* time: remove incorrect time.ISO8601 and add time.RFC3339 (thanks Micah Stetson).
+* utf16: add DecodeRune, EncodeRune.
+* xml: add support for XML marshalling embedded structs (thanks Raif S. Naffah),
+ new "innerxml" tag to collect inner XML.
+</pre>
+
+<h2 id="2010-04-13">2010-04-13</h2>
+
+<pre>
+This release contains many changes:
+
+* 8l: add DOS stub to PE binaries (thanks Evan Shaw).
+* cgo: add //export.
+* cmath: new complex math library (thanks Charles L. Dorian).
+* docs: update to match current coding style (thanks Christopher Wedgwood).
+* exp/eval: fix example and add target to Makefile (thanks Evan Shaw).
+* fmt: change behaviour of format verb %b to match %x when negative (thanks Andrei Vieru).
+* gc: compile s == "" as len(s) == 0,
+ distinguish fatal compiler bug from error+exit,
+ fix alignment on non-amd64,
+ good syntax error for defer func() {} - missing fina (),
+ implement panic and recover,
+ zero unnamed return values on entry if func has defer.
+* goyacc: change to be reentrant (thanks Roger Peppe).
+* io/ioutil: fix bug in ReadFile when Open succeeds but Stat fails.
+* kate: update for recent language changes (thanks Evan Shaw).
+* libcgo: initial mingw port work - builds but untested (thanks Joe Poirier).
+* math: new functions and special cases (thanks Charles L. Dorian)
+* net: use chan bool instead of chan *netFD to avoid cycle.
+* netchan: allow client to send as well as receive.
+* nntp: new package, NNTP client (thanks Conrad Meyer).
+* os: rename os.Dir to os.FileInfo.
+* rpc: don't log normal EOF,
+ fix ServeConn to block as documented.
+* runtime: many bug fixes, better ARM support.
+* strings: add IndexRune, Trim, TrimLeft, TrimRight, etc (thanks Michael Hoisie).
+* syscall: implement some mingw syscalls required by os (thanks Alex Brainman).
+* test/bench: add k-nucleotide-parallel (thanks Kyle Consalus).
+* Unicode: add support for Turkish case mapping.
+* xgb: move from the main repository to http://code.google.com/p/x-go-binding/
+</pre>
+
+<h2 id="2010-03-30">2010-03-30</h2>
+
+<pre>
+This release contains three language changes:
+
+1. Accessing a non-existent key in a map is no longer a run-time error.
+It now evaluates to the zero value for that type. For example:
+ x := myMap[i] is now equivalent to: x, _ := myMap[i]
+
+2. It is now legal to take the address of a function's return value.
+The return values are copied back to the caller only after deferred
+functions have run.
+
+3. The functions panic and recover, intended for reporting and recovering from
+failure, have been added to the spec:
+ http://golang.org/doc/go_spec.html#Handling_panics
+In a related change, panicln is gone, and panic is now a single-argument
+function. Panic and recover are recognized by the gc compilers but the new
+behavior is not yet implemented.
+
+The ARM build is broken in this release; ARM users should stay at release.2010-03-22.
+
+Other changes:
+* bytes, strings: add IndexAny.
+* cc/ld: Add support for #pragma dynexport,
+ Rename dynld to dynimport throughout. Cgo users will need to rerun cgo.
+* expvar: default publishings for cmdline, memstats
+* flag: add user-defined flag types.
+* gc: usual bug fixes
+* go/ast: generalized ast filtering.
+* go/printer: avoid reflect in print.
+* godefs: fix handling of negative constants.
+* godoc: export pprof debug information, exported variables,
+ support for filtering of command-line output in -src mode,
+ use http GET for remote search instead of rpc.
+* gofmt: don't convert multi-line functions into one-liners,
+ preserve newlines in multiline selector expressions (thanks Risto Jaakko Saarelma).
+* goinstall: include command name in error reporting (thanks Andrey Mirtchovski)
+* http: add HandleFunc as shortcut to Handle(path, HandlerFunc(func))
+* make: use actual dependency for install
+* math: add J1, Y1, Jn, Yn, J0, Y0 (Bessel functions) (thanks Charles L. Dorian)
+* prof: add pprof from google-perftools
+* regexp: don't return non-nil *Regexp if there is an error.
+* runtime: add Callers,
+ add malloc sampling, pprof interface,
+ add memory profiling, more statistics to runtime.MemStats,
+ implement missing destroylock() (thanks Alex Brainman),
+ more malloc statistics,
+ run all finalizers in a single goroutine,
+ Goexit runs deferred calls.
+* strconv: add Atob and Btoa,
+ Unquote could wrongly return a nil error on error (thanks Roger Peppe).
+* syscall: add IPV6 constants,
+ add syscall_bsd.go for Darwin and other *BSDs (thanks Giles Lean),
+ implement SetsockoptString (thanks Christopher Wedgwood).
+* websocket: implement new protocol (thanks Fumitoshi Ukai).
+* xgb: fix request length and request size (thanks Firmansyah Adiputra).
+* xml: add CopyToken (thanks Kyle Consalus),
+ add line numbers to syntax errors (thanks Kyle Consalus),
+ use io.ReadByter in place of local readByter (thanks Raif S. Naffah).
+</pre>
+
+<h2 id="2010-03-22">2010-03-22</h2>
+
+<pre>
+With this release we announce the launch of the Go Blog:
+ http://blog.golang.org/
+The first post is a brief update covering what has happened since the launch.
+
+This release contains some new packages and functionality, and many fixes:
+* 6g/8g: fix issues with complex data types, other bug fixes.
+* Makefiles: refactored to make writing external Makefiles easier.
+* crypto/rand: new package.
+* godoc: implemented command-line search via RPC,
+ improved comment formatting: recognize URLs.
+* gofmt: more consistent formatting of const/var decls.
+* http: add Error helper function,
+ add ParseQuery (thanks Petar Maymounkov),
+ change RawPath to mean raw path, not raw everything-after-scheme.
+* image/jpeg: fix typos.
+* json: add MarshalIndent (accepts user-specified indent string).
+* math: add Gamma function (thanks Charles L. Dorian).
+* misc/bbedit: support for cmplx, real, imag (thanks Anthony Starks).
+* misc/vim: add new complex types, functions and literals.
+* net: fix IPMask.String not to crash on all-0xff mask.
+* os: drop File finalizer after normal Close.
+* runtime: add GOROOT and Version,
+ lock finalizer table accesses.
+* sha512: add sha384 (truncated version) (thanks Conrad Meyer).
+* syscall: add const ARCH, analogous to OS.
+* syscall: further additions to mingw port (thanks Alex Brainman).
+* template: fixed html formatter []byte input bug.
+* utf16: new package.
+* version.bash: cope with ancient Mercurial.
+* websocket: use URL.RawPath to construct WebSocket-Location: header.
+</pre>
+
+<h2 id="2010-03-15">2010-03-15</h2>
+
+<pre>
+This release includes a language change: support for complex numbers.
+ http://golang.org/doc/go_spec.html#Imaginary_literals
+ http://golang.org/doc/go_spec.html#Complex_numbers
+There is no library support as yet.
+
+This release also includes the goinstall command-line tool.
+ http://golang.org/cmd/goinstall/
+ http://groups.google.com/group/golang-nuts/t/f091704771128e32
+
+* 5g/6g/8g: fix double function call in slice.
+* arm: cleanup build warnings. (thanks Dean Prichard)
+* big: fix mistakes with probablyPrime.
+* bufio: add WriteRune.
+* bytes: add ReadRune and WriteRune to bytes.Buffer.
+* cc: stack split bug fix.
+* crypto: add SHA-224 to sha256, add sha512 package. (thanks Conrad Meyer)
+* crypto/ripemd160: new package. (thanks Raif S. Naffah)
+* crypto/rsa: don't use safe primes.
+* gc: avoid fixed length buffer cleanbuf. (thanks Dean Prichard)
+ better compilation of floating point +=
+ fix crash on complicated arg to make slice.
+ remove duplicate errors, give better error for I.(T)
+* godoc: support for multiple packages in a directory, other fixes.
+* gofmt: bug fixes.
+* hash: add Sum64 interface.
+* hash/crc32: add Update function.
+* hash/crc64: new package implementing 64-bit CRC.
+* math: add ilogb, logb, remainder. (thanks Charles L. Dorian)
+* regexp: add ReplaceAllFunc, ReplaceAllStringFunc.
+* runtime: clock garbage collection on bytes allocated, not pages in use.
+* strings: make Split(s, "", n) faster. (thanks Spring Mc)
+* syscall: minimal mingw version of syscall. (thanks Alex Brainman)
+* template: add ParseFile, MustParseFile.
+</pre>
+
+<h2 id="2010-03-04">2010-03-04</h2>
+
+<pre>
+There is one language change: the ability to convert a string to []byte or
+[]int. This deprecates the strings.Bytes and strings.Runes functions.
+You can convert your existing sources using these gofmt commands:
+ gofmt -r 'strings.Bytes(x) -> []byte(x)' -w file-or-directory-list
+ gofmt -r 'strings.Runes(x) -> []int(x)' -w file-or-directory-list
+After running these you might need to delete unused imports of the "strings"
+package.
+
+Other changes and fixes:
+* 6l/8l/5l: add -r option
+* 8g: make a[byte(x)] truncate x
+* codereview.py: fix for compatibility with hg >=1.4.3
+* crypto/blowfish: new package (thanks Raif S. Naffah)
+* dashboard: more performance tuning
+* fmt: use String method in %q to get the value to quote.
+* gofmt: several cosmetic changes
+* http: fix handling of Connection: close, bug in http.Post
+* net: correct DNS configuration,
+ fix network timeout boundary condition,
+ put [ ] around IPv6 addresses for Dial.
+* path: add Match,
+ fix bug in Match with non-greedy stars (thanks Kevin Ballard)
+* strings: delete Bytes, Runes (see above)
+* tests: an Eratosthenesque concurrent prime sieve (thanks Anh Hai Trinh)
+</pre>
+
+<h2 id="2010-02-23">2010-02-23</h2>
+
+<pre>
+This release is mainly bug fixes and a little new code.
+There are no language changes.
+
+6g/5g/8g: bug fixes
+8a/8l: Added FCMOVcc instructions (thanks Evan Shaw and Charles Dorian)
+crypto/x509: support certificate creation
+dashboard: caching to avoid datastore queries
+exec: add dir argument to Run
+godoc: bug fixes and code cleanups
+http: continued implementation and bug fixes (thanks Petar Maymounkov)
+json: fix quoted strings in Marshal (thanks Sergei Skorobogatov)
+math: more functions, test cases, and benchmarks (thanks Charles L. Dorian)
+misc/bbedit: treat predeclared identifiers as "keywords" (thanks Anthony Starks)
+net: disable UDP server test (flaky on various architectures)
+runtime: work around Linux kernel bug in futex,
+ pchw is now tiny
+sync: fix to work on armv5 (thanks Dean Prichard)
+websocket: fix binary frame size decoding (thanks Timo Savola)
+xml: allow unquoted attribute values in non-Strict mode (thanks Amrut Joshi)
+ treat bool as value in Unmarshal (thanks Michael Hoisie)
+</pre>
+
+<h2 id="2010-02-17">2010-02-17</h2>
+
+<pre>
+There are two small language changes:
+* NUL bytes may be rejected in souce files, and the tools do reject them.
+* Conversions from string to []int and []byte are defined but not yet implemented.
+
+Other changes and fixes:
+* 5a/6a/8a/5c/6c/8c: remove fixed-size arrays for -I and -D options (thanks Dean Prichard)
+* 5c/6c/8c/5l/6l/8l: add -V flag to display version number
+* 5c/6c/8c: use "cpp" not "/bin/cpp" for external preprocessor (thanks Giles Lean)
+* 8a/8l: Added CMOVcc instructions (thanks Evan Shaw)
+* 8l: pe executable building code changed to include import table for kernel32.dll functions (thanks Alex Brainman)
+* 5g/6g/8g: bug fixes
+* asn1: bug fixes and additions (incl marshalling)
+* build: fix build for Native Client, Linux/ARM
+* dashboard: show benchmarks, add garbage collector benchmarks
+* encoding/pem: add marshalling support
+* exp/draw: fast paths for a nil mask
+* godoc: support for directories outside $GOROOT
+* http: sort header keys when writing Response or Request to wire (thanks Petar Maymounkov)
+* math: special cases and new functions (thanks Charles Dorian)
+* mime: new package, used in http (thanks Michael Hoisie)
+* net: dns bug fix - use random request id
+* os: finalize File, to close fd.
+* path: make Join variadic (thanks Stephen Weinberg)
+* regexp: optimization bug fix
+* runtime: misc fixes and optimizations
+* syscall: make signature of Umask on OS X, FreeBSD match Linux. (thanks Giles Lean)
+</pre>
+
+<h2 id="2010-02-04">2010-02-04</h2>
+
+<pre>
+There is one language change: support for ...T parameters:
+ http://golang.org/doc/go_spec.html#Function_types
+
+You can now check build status on various platforms at the Go Dashboard:
+ http://godashboard.appspot.com
+
+* 5l/6l/8l: several minor fixes
+* 5a/6a/8a/5l/6l/8l: avoid overflow of symb buffer (thanks Dean Prichard)
+* compress/gzip: gzip deflater (i.e., writer)
+* debug/proc: add mingw specific build stubs (thanks Joe Poirier)
+* exp/draw: separate the source-point and mask-point in Draw
+* fmt: handle nils safely in Printf
+* gccgo: error messages now match those of gc
+* godoc: several fixes
+* http: bug fixes, revision of Request/Response (thanks Petar Maymounkov)
+* image: new image.A type to represent anti-aliased font glyphs
+ add named colors (e.g. image.Blue), suitable for exp/draw
+* io: fixed bugs in Pipe
+* malloc: merge into package runtime
+* math: fix tests on FreeBSD (thanks Devon H. O'Dell)
+ add functions; update tests and special cases (thanks Charles L. Dorian)
+* os/signal: send SIGCHLDs to Incoming (thanks Chris Wedgwood)
+* reflect: add StringHeader to reflect
+* runtime: add SetFinalizer
+* time: Sleep through interruptions (thanks Chris Wedgwood)
+ add RFC822 formats
+ experimental implemenation of Ticker using two goroutines for all tickers
+* xml: allow underscores in XML element names (thanks Michael Hoisie)
+ allow any scalar type in xml.Unmarshal
+</pre>
+
+<h2 id="2010-01-27">2010-01-27</h2>
+
+<pre>
+There are two small language changes: the meaning of chan <- chan int
+is now defined, and functions returning functions do not need to
+parenthesize the result type.
+
+There is one significant implementation change: the compilers can
+handle multiple packages using the same name in a single binary.
+In the gc compilers, this comes at the cost of ensuring that you
+always import a particular package using a consistent import path.
+In the gccgo compiler, the cost is that you must use the -fgo-prefix
+flag to pass a unique prefix (like the eventual import path).
+
+5a/6a/8a: avoid use of fixed-size buffers (thanks Dean Prichard)
+5g, 6g, 8g: many minor bug fixes
+bufio: give Writer.WriteString same signature as bytes.Buffer.WriteString.
+container/list: PushFrontList, PushBackList (thanks Jan Hosang)
+godoc: trim spaces from search query (thanks Christopher Wedgwood)
+hash: document that Sum does not change state, fix crypto hashes
+http: bug fixes, revision of Request/Response (thanks Petar Maymounkov)
+math: more handling of IEEE 754 special cases (thanks Charles Dorian)
+misc/dashboard: new build dashboard
+net: allow UDP broadcast,
+ use /etc/hosts to resolve names (thanks Yves Junqueira, Michael Hoisie)
+netchan: beginnings of new package for connecting channels across a network
+os: allow FQDN in Hostname test (thanks Icarus Sparry)
+reflect: garbage collection bug in Call
+runtime: demo of Go on raw (emulated) hw in runtime/pchw,
+ performance fix on OS X
+spec: clarify meaning of chan <- chan int,
+ func() func() int is allowed now,
+ define ... T (not yet implemented)
+template: can use interface values
+time: fix for +0000 time zone,
+ more robust tick.Stop.
+xgb: support for authenticated connections (thanks Firmansyah Adiputra)
+xml: add Escape (thanks Stephen Weinberg)
+</pre>
+
+<h2 id="2010-01-13">2010-01-13</h2>
+
+<pre>
+This release is mainly bug fixes with a little new code.
+There are no language changes.
+
+build: $GOBIN should no longer be required in $PATH (thanks Devon H. O'Dell),
+ new package target "make bench" to run benchmarks
+8g: faster float -> uint64 conversion (thanks Evan Shaw)
+5g, 6g, 8g:
+ clean opnames.h to avoid stale errors (thanks Yongjian Xu),
+ a handful of small compiler fixes
+5g, 6g, 8g, 5l, 6l, 8l: ignore $GOARCH, which is implied by name of tool
+6prof: support for writing input files for google-perftools's pprof
+asn1: fix a few structure-handling bugs
+cgo: many bug fixes (thanks Devon H. O'Dell)
+codereview: repeated "hg mail" sends "please take another look"
+gob: reserve ids for future expansion
+godoc: distinguish HTML generation from plain text HTML escaping (thanks Roger Peppe)
+gofmt: minor bug fixes, removed -oldprinter flag
+http: add CanonicalPath (thanks Ivan Krasin),
+ avoid header duplication in Response.Write,
+ correctly escape/unescape URL sections
+io: new interface ReadByter
+json: better error, pointer handling in Marshal (thanks Ivan Krasin)
+libmach: disassembly of FUCOMI, etc (thanks Evan Shaw)
+math: special cases for most functions and 386 hardware Sqrt (thanks Charles Dorian)
+misc/dashboard: beginning of a build dashboard at godashboard.appspot.com.
+misc/emacs: handling of new semicolon rules (thanks Austin Clements),
+ empty buffer bug fix (thanks Kevin Ballard)
+misc/kate: highlighting improvements (tahnks Evan Shaw)
+os/signal: add signal names: signal.SIGHUP, etc (thanks David Symonds)
+runtime: preliminary Windows support (thanks Hector Chu),
+ preemption polling to reduce garbage collector pauses
+scanner: new lightweight scanner package
+template: bug fix involving spaces before a delimited block
+test/bench: updated timings
+time: new Format, Parse functions
+</pre>
+
+<h2 id="2010-01-05">2010-01-05</h2>
+
+<pre>
+This release is mainly bug fixes. There are no language changes.
+
+6prof: now works on 386
+8a, 8l: add FCOMI, FCOMIP, FUCOMI, and FUCOMIP (thanks Evan Shaw)
+big: fix ProbablyPrime on small numbers
+container/vector: faster []-based implementation (thanks Jan Mercl)
+crypto/tls: extensions and Next Protocol Negotiation
+gob: one encoding bug fix, one decoding bug fix
+image/jpeg: support for RST markers
+image/png: support for transparent paletted images
+misc/xcode: improved support (thanks Ken Friedenbach)
+net: return nil Conn on error from Dial (thanks Roger Peppe)
+regexp: add Regexp.NumSubexp (thanks Peter Froehlich)
+syscall: add Nanosleep on FreeBSD (thanks Devon H. O'Dell)
+template: can use map in .repeated section
+
+There is now a public road map, in the repository and online
+at <a href="http://golang.org/doc/devel/roadmap.html">http://golang.org/doc/devel/roadmap.html</a>.
+</pre>
+
+<h2 id="2009-12-22">2009-12-22</h2>
+
+<pre>
+Since the last release there has been one large syntactic change to
+the language, already discussed extensively on this list: semicolons
+are now implied between statement-ending tokens and newline characters.
+See http://groups.google.com/group/golang-nuts/t/5ee32b588d10f2e9 for
+details.
+
+By default, gofmt now parses and prints the new lighter weight syntax.
+To convert programs written in the old syntax, you can use:
+
+ gofmt -oldparser -w *.go
+
+Since everything was being reformatted anyway, we took the opportunity to
+change the way gofmt does alignment. Now gofmt uses tabs at the start
+of a line for basic code alignment, but it uses spaces for alignment of
+interior columns. Thus, in an editor with a fixed-width font, you can
+choose your own tab size to change the indentation, and no matter what
+tab size you choose, columns will be aligned properly.
+
+
+In addition to the syntax and formatting changes, there have been many
+smaller fixes and updates:
+
+6g,8g,5g: many bug fixes, better registerization,
+ build process fix involving mkbuiltin (thanks Yongjian Xu),
+ method expressions for concrete types
+8l: support for Windows PE files (thanks Hector Chu)
+bytes: more efficient Buffer handling
+bytes, strings: new function Fields (thanks Andrey Mirtchovski)
+cgo: handling of enums (thanks Moriyoshi Koizumi),
+ handling of structs with bit fields, multiple files (thanks Devon H. O'Dell),
+ installation of .so to non-standard locations
+crypto/sha256: new package for SHA 256 (thanks Andy Davis)
+encoding/binary: support for slices of fixed-size values (thanks Maxim Ushakov)
+exp/vector: experimental alternate vector representation (thanks Jan Mercl)
+fmt: %p for chan, map, slice types
+gob: a couple more bug fixes
+http: support for basic authentication (thanks Ivan Krasin)
+image/jpeg: basic JPEG decoder
+math: correct handling of Inf and NaN in Pow (thanks Charles Dorian)
+misc/bash: completion file for bash (thanks Alex Ray)
+os/signal: support for handling Unix signals (thanks David Symonds)
+rand: Zipf-distributed random values (thanks William Josephson)
+syscall: correct error return bug on 32-bit machines (thanks Christopher Wedgwood)
+syslog: new package for writing to Unix syslog daemon (thanks Yves Junqueira)
+template: will automatically invoke niladic methods
+time: new ISO8601 format generator (thanks Ben Olive)
+xgb: converted generator to new syntax (thanks Tor Andersson)
+xml: better mapping of tag names to Go identifiers (thanks Kei Son),
+ better handling of unexpected EOF (thanks Arvindh Rajesh Tamilmani)
+</pre>
+
+<h2 id="2009-12-09">2009-12-09</h2>
+
+<pre>
+Since the last release there are two changes to the language:
+
+* new builtin copy(dst, src) copies n = min(len(dst), len(src))
+ elements to dst from src and returns n. It works correctly
+ even if dst and src overlap. bytes.Copy is gone.
+ Convert your programs using:
+ gofmt -w -r 'bytes.Copy(d, s) -> copy(d, s)' *.go
+
+* new syntax x[lo:] is shorthand for x[lo:len(x)].
+ Convert your programs using:
+ gofmt -w -r 'a[b:len(a)] -> a[b:]' *.go
+
+In addition, there have been many smaller fixes and updates:
+
+* 6g/8g/5g: many bug fixes
+* 8g: fix 386 floating point stack bug (thanks Charles Dorian)
+* all.bash: now works even when $GOROOT has spaces (thanks Sergio Luis O. B. Correia),
+ starting to make build work with mingw (thanks Hector Chu),
+ FreeBSD support (thanks Devon O'Dell)
+* big: much faster on 386.
+* bytes: new function IndexByte, implemented in assembly
+ new function Runes (thanks Peter Froehlich),
+ performance tuning in bytes.Buffer.
+* codereview: various bugs fixed
+* container/vector: New is gone; just declare a Vector instead.
+ call Resize to set len and cap.
+* cgo: many bug fixes (thanks Eden Li)
+* crypto: added MD4 (thanks Chris Lennert),
+ added XTEA (thanks Adrian O'Grady).
+* crypto/tls: basic client
+* exp/iterable: new functions (thanks Michael Elkins)
+* exp/nacl: native client tree builds again
+* fmt: preliminary performance tuning
+* go/ast: more powerful Visitor (thanks Roger Peppe)
+* gob: a few bug fixes
+* gofmt: better handling of standard input, error reporting (thanks Fazlul Shahriar)
+ new -r flag for rewriting programs
+* gotest: support for Benchmark functions (thanks Trevor Strohman)
+* io: ReadFile, WriteFile, ReadDir now in separate package io/ioutil.
+* json: new Marshal function (thanks Michael Hoisie),
+ better white space handling (thanks Andrew Skiba),
+ decoding into native data structures (thanks Sergey Gromov),
+ handling of nil interface values (thanks Ross Light).
+* math: correct handling of sin/cos of large angles
+* net: better handling of Close (thanks Devon O'Dell and Christopher Wedgwood)
+ support for UDP broadcast (thanks Jonathan Wills),
+ support for empty packets
+* rand: top-level functions now safe to call from multiple goroutines
+(thanks Roger Peppe).
+* regexp: a few easy optimizations
+* rpc: better error handling, a few bug fixes
+* runtime: better signal handling on OS X, malloc fixes,
+ global channel lock is gone.
+* sync: RWMutex now allows concurrent readers (thanks Péter Szabó)
+* template: can use maps as data (thanks James Meneghello)
+* unicode: updated to Unicode 5.2.
+* websocket: new package (thanks Fumitoshi Ukai)
+* xgb: preliminary X Go Bindings (thanks Tor Andersson)
+* xml: fixed crash (thanks Vish Subramanian)
+* misc: bbedit config (thanks Anthony Starks),
+ kate config (thanks Evan Shaw)
+</pre>
diff --git a/doc/docs.html b/doc/docs.html
new file mode 100644
index 0000000..7eb3a3a
--- /dev/null
+++ b/doc/docs.html
@@ -0,0 +1,199 @@
+<!--{
+ "Title": "Documentation",
+ "Path": "/doc/"
+}-->
+
+<p>
+The Go programming language is an open source project to make programmers more
+productive.
+</p>
+
+<p>
+Go is expressive, concise, clean, and efficient. Its concurrency
+mechanisms make it easy to write programs that get the most out of multicore
+and networked machines, while its novel type system enables flexible and
+modular program construction. Go compiles quickly to machine code yet has the
+convenience of garbage collection and the power of run-time reflection. It's a
+fast, statically typed, compiled language that feels like a dynamically typed,
+interpreted language.
+</p>
+
+<div id="manual-nav"></div>
+
+<h2>Installing Go</h2>
+
+<h3><a href="/doc/install">Getting Started</a></h3>
+<p>
+Instructions for downloading and installing the Go compilers, tools, and
+libraries.
+</p>
+
+
+<h2 id="learning">Learning Go</h2>
+
+<img class="gopher" src="/doc/gopher/doc.png"/>
+
+<h3 id="go_tour"><a href="//tour.golang.org/">A Tour of Go</a></h3>
+<p>
+An interactive introduction to Go in three sections.
+The first section covers basic syntax and data structures; the second discusses
+methods and interfaces; and the third introduces Go's concurrency primitives.
+Each section concludes with a few exercises so you can practice what you've
+learned. You can <a href="//tour.golang.org/">take the tour online</a> or
+<a href="//code.google.com/p/go-tour/">install it locally</a>.
+</p>
+
+<h3 id="code"><a href="code.html">How to write Go code</a></h3>
+<p>
+Also available as a
+<a href="//www.youtube.com/watch?v=XCsL89YtqCs">screencast</a>, this doc
+explains how to use the <a href="/cmd/go/">go command</a> to fetch, build, and
+install packages, commands, and run tests.
+</p>
+
+<h3 id="effective_go"><a href="effective_go.html">Effective Go</a></h3>
+<p>
+A document that gives tips for writing clear, idiomatic Go code.
+A must read for any new Go programmer. It augments the tour and
+the language specification, both of which should be read first.
+</p>
+
+<h3 id="faq"><a href="/doc/faq">Frequently Asked Questions (FAQ)</a></h3>
+<p>
+Answers to common questions about Go.
+</p>
+
+<h3 id="wiki"><a href="/wiki">The Go Wiki</a></h3>
+<p>A wiki maintained by the Go community.</p>
+
+<h4 id="learn_more">More</h4>
+<p>
+See the <a href="/wiki/Learn">Learn</a> page at the <a href="/wiki">Wiki</a>
+for more Go learning resources.
+</p>
+
+
+<h2 id="references">References</h2>
+
+<h3 id="pkg"><a href="/pkg/">Package Documentation</a></h3>
+<p>
+The documentation for the Go standard library.
+</p>
+
+<h3 id="cmd"><a href="/doc/cmd">Command Documentation</a></h3>
+<p>
+The documentation for the Go tools.
+</p>
+
+<h3 id="spec"><a href="/ref/spec">Language Specification</a></h3>
+<p>
+The official Go Language specification.
+</p>
+
+<h3 id="go_mem"><a href="/ref/mem">The Go Memory Model</a></h3>
+<p>
+A document that specifies the conditions under which reads of a variable in
+one goroutine can be guaranteed to observe values produced by writes to the
+same variable in a different goroutine.
+</p>
+
+<h3 id="release"><a href="/doc/devel/release.html">Release History</a></h3>
+<p>A summary of the changes between Go releases.</p>
+
+
+<h2 id="articles">Articles</h2>
+
+<h3 id="blog"><a href="//blog.golang.org/">The Go Blog</a></h3>
+<p>The official blog of the Go project, featuring news and in-depth articles by
+the Go team and guests.</p>
+
+<h4>Codewalks</h4>
+<p>
+Guided tours of Go programs.
+</p>
+<ul>
+<li><a href="/doc/codewalk/functions">First-Class Functions in Go</a></li>
+<li><a href="/doc/codewalk/markov">Generating arbitrary text: a Markov chain algorithm</a></li>
+<li><a href="/doc/codewalk/sharemem">Share Memory by Communicating</a></li>
+<li><a href="/doc/articles/wiki/">Writing Web Applications</a> - building a simple web application.</li>
+</ul>
+
+<h4>Language</h4>
+<ul>
+<li><a href="/blog/json-rpc-tale-of-interfaces">JSON-RPC: a tale of interfaces</a></li>
+<li><a href="/blog/gos-declaration-syntax">Go's Declaration Syntax</a></li>
+<li><a href="/blog/defer-panic-and-recover">Defer, Panic, and Recover</a></li>
+<li><a href="/blog/go-concurrency-patterns-timing-out-and">Go Concurrency Patterns: Timing out, moving on</a></li>
+<li><a href="/blog/go-slices-usage-and-internals">Go Slices: usage and internals</a></li>
+<li><a href="/blog/gif-decoder-exercise-in-go-interfaces">A GIF decoder: an exercise in Go interfaces</a></li>
+<li><a href="/blog/error-handling-and-go">Error Handling and Go</a></li>
+<li><a href="/blog/organizing-go-code">Organizing Go code</a></li>
+</ul>
+
+<h4>Packages</h4>
+<ul>
+<li><a href="/blog/json-and-go">JSON and Go</a> - using the <a href="/pkg/encoding/json/">json</a> package.</li>
+<li><a href="/blog/gobs-of-data">Gobs of data</a> - the design and use of the <a href="/pkg/encoding/gob/">gob</a> package.</li>
+<li><a href="/blog/laws-of-reflection">The Laws of Reflection</a> - the fundamentals of the <a href="/pkg/reflect/">reflect</a> package.</li>
+<li><a href="/blog/go-image-package">The Go image package</a> - the fundamentals of the <a href="/pkg/image/">image</a> package.</li>
+<li><a href="/blog/go-imagedraw-package">The Go image/draw package</a> - the fundamentals of the <a href="/pkg/image/draw/">image/draw</a> package.</li>
+</ul>
+
+<h4>Tools</h4>
+<ul>
+<li><a href="/doc/articles/go_command.html">About the Go command</a> - why we wrote it, what it is, what it's not, and how to use it.</li>
+<li><a href="/blog/c-go-cgo">C? Go? Cgo!</a> - linking against C code with <a href="/cmd/cgo/">cgo</a>.</li>
+<li><a href="/doc/gdb">Debugging Go Code with GDB</a></li>
+<li><a href="/blog/godoc-documenting-go-code">Godoc: documenting Go code</a> - writing good documentation for <a href="/cmd/godoc/">godoc</a>.</li>
+<li><a href="/blog/profiling-go-programs">Profiling Go Programs</a></li>
+<li><a href="/doc/articles/race_detector.html">Data Race Detector</a> - a manual for the data race detector.</li>
+<li><a href="/blog/race-detector">Introducing the Go Race Detector</a> - an introduction to the race detector.</li>
+<li><a href="/doc/asm">A Quick Guide to Go's Assembler</a> - an introduction to the assembler used by Go.</li>
+</ul>
+
+<h4 id="articles_more">More</h4>
+<p>
+See the <a href="/wiki/Articles">Articles page</a> at the
+<a href="/wiki">Wiki</a> for more Go articles.
+</p>
+
+
+<h2 id="talks">Talks</h2>
+
+<img class="gopher" src="/doc/gopher/talks.png"/>
+
+<h3 id="video_tour_of_go"><a href="http://research.swtch.com/gotour">A Video Tour of Go</a></h3>
+<p>
+Three things that make Go fast, fun, and productive:
+interfaces, reflection, and concurrency. Builds a toy web crawler to
+demonstrate these.
+</p>
+
+<h3 id="go_code_that_grows"><a href="//vimeo.com/53221560">Code that grows with grace</a></h3>
+<p>
+One of Go's key design goals is code adaptability; that it should be easy to take a simple design and build upon it in a clean and natural way. In this talk Andrew Gerrand describes a simple "chat roulette" server that matches pairs of incoming TCP connections, and then use Go's concurrency mechanisms, interfaces, and standard library to extend it with a web interface and other features. While the function of the program changes dramatically, Go's flexibility preserves the original design as it grows.
+</p>
+
+<h3 id="go_concurrency_patterns"><a href="//www.youtube.com/watch?v=f6kdp27TYZs">Go Concurrency Patterns</a></h3>
+<p>
+Concurrency is the key to designing high performance network services. Go's concurrency primitives (goroutines and channels) provide a simple and efficient means of expressing concurrent execution. In this talk we see how tricky concurrency problems can be solved gracefully with simple Go code.
+</p>
+
+<h3 id="advanced_go_concurrency_patterns"><a href="//www.youtube.com/watch?v=QDDwwePbDtw">Advanced Go Concurrency Patterns</a></h3>
+<p>
+This talk expands on the <i>Go Concurrency Patterns</i> talk to dive deeper into Go's concurrency primitives.
+</p>
+
+<h4 id="talks_more">More</h4>
+<p>
+See the <a href="/talks">Go Talks site</a> and <a href="/wiki/GoTalks">wiki page</a> for more Go talks.
+</p>
+
+
+<h2 id="nonenglish">Non-English Documentation</h2>
+
+<p>
+See the <a href="/wiki/NonEnglish">NonEnglish</a> page
+at the <a href="/wiki">Wiki</a> for localized
+documentation.
+</p>
diff --git a/doc/effective_go.html b/doc/effective_go.html
new file mode 100644
index 0000000..4dd1a3e
--- /dev/null
+++ b/doc/effective_go.html
@@ -0,0 +1,3664 @@
+<!--{
+ "Title": "Effective Go",
+ "Template": true
+}-->
+
+<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—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="//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/">Go package sources</a>
+are intended to serve not
+only as the core library but also as examples of how to
+use the language.
+Moreover, many of the packages contain working, self-contained
+executable examples you can run directly from the
+<a href="//golang.org">golang.org</a> web site, such as
+<a href="//golang.org/pkg/strings/#example_Map">this one</a> (if
+necessary, click on the word "Example" to open it up).
+If you have a question about how to approach a problem or how something
+might be implemented, the documentation, code and examples in the
+library 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 than C and Java: 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<<8 + y<<16
+</pre>
+ means what the spacing implies, unlike in the other languages.
+ </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, but
+are useful within an expression or 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—<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.
+One adjustment <code>godoc</code> does do is to display indented
+text in a fixed-width font, suitable for program snippets.
+The package comment for the
+<a href="/pkg/fmt/"><code>fmt</code> package</a> uses this to good effect.
+</p>
+
+<p>
+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>
+If the name always begins the comment, the output of <code>godoc</code>
+can usefully be run through <code>grep</code>.
+Imagine you couldn't remember the name "Compile" but were looking for
+the parsing function for regular expressions, so you ran
+the command,
+</p>
+
+<pre>
+$ godoc regexp | grep parse
+</pre>
+
+<p>
+If all the doc comments in the package began, "This function...", <code>grep</code>
+wouldn't help you remember the name. But because the package starts each
+doc comment with the name, you'd see something like this,
+which recalls the word you're looking for.
+</p>
+
+<pre>
+$ godoc regexp | grep parse
+ Compile parses a regular expression and returns, if successful, a Regexp
+ parsed. It simplifies safe initialization of global variables holding
+ cannot be parsed. It simplifies safe initialization of global variables
+$
+</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>
+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.
+They even have semantic effect:
+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/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,
+so exported names in the package can use that fact
+to avoid stutter.
+(Don't use the <code>import .</code> notation, which can simplify
+tests that must run outside the package they are testing, but should otherwise be avoided.)
+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>—which
+is the definition of a <em>constructor</em> in Go—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.
+A helpful doc comment can often be more valuable than an extra long 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 an -er suffix or similar modification
+to construct an agent noun: <code>Reader</code>,
+<code>Writer</code>, <code>Formatter</code>,
+<code>CloseNotifier</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,
+but unlike in 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, “if the newline comes
+after a token that could end a statement, insert a semicolon”.
+</p>
+
+<p>
+A semicolon can also be omitted immediately before a closing brace,
+so a statement such as
+</p>
+<pre>
+ go func() { for { dst <- <-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 consequence of the semicolon insertion rules
+is that you cannot 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 < f() {
+ g()
+}
+</pre>
+<p>
+not like this
+</p>
+<pre>
+if i < 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>;
+<code>break</code> and <code>continue</code> statements
+take an optional label to identify what to break or continue;
+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 > 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 and reassignment</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>
+
+<p>
+§ It's worth noting here that in Go the scope of function parameters and return values
+is the same as the function body, even though they appear lexically outside the braces
+that enclose the body.
+</p>
+
+<h3 id="for">For</h3>
+
+<p>
+The Go <code>for</code> loop is similar to—but not the same as—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 < 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>
+for key, value := range oldMap {
+ newMap[key] = value
+}
+</pre>
+
+<p>
+If you only need the first item in the range (the key or index), drop the second:
+</p>
+<pre>
+for key := range m {
+ if key.expired() {
+ delete(m, key)
+ }
+}
+</pre>
+
+<p>
+If you only need the second item in the range (the value), use the <em>blank identifier</em>, an underscore, to discard the first:
+</p>
+<pre>
+sum := 0
+for _, value := range array {
+ sum += value
+}
+</pre>
+
+<p>
+The blank identifier has many uses, as described in <a href="#blank">a later section</a>.
+</p>
+
+<p>
+For strings, the <code>range</code> does more work for you, breaking out individual
+Unicode code points by parsing the UTF-8.
+Erroneous encodings consume one byte and produce the
+replacement rune U+FFFD.
+(The name (with associated builtin type) <code>rune</code> is Go terminology for a
+single Unicode code point.
+See <a href="/ref/spec#Rune_literals">the language specification</a>
+for details.)
+The loop
+</p>
+<pre>
+for pos, char := range "日本\x80語" { // \x80 is an illegal UTF-8 encoding
+ fmt.Printf("character %#U starts at byte position %d\n", char, pos)
+}
+</pre>
+<p>
+prints
+</p>
+<pre>
+character U+65E5 '日' starts at byte position 0
+character U+672C '本' starts at byte position 3
+character U+FFFD '�' starts at byte position 6
+character U+8A9E '語' starts at byte position 7
+</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 (although that precludes <code>++</code> and <code>--</code>).
+</p>
+<pre>
+// Reverse a
+for i, j := 0, len(a)-1; i < j; i, j = i+1, j-1 {
+ a[i], a[j] = a[j], a[i]
+}
+</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—and idiomatic—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' <= c && c <= '9':
+ return c - '0'
+ case 'a' <= c && c <= 'f':
+ return c - 'a' + 10
+ case 'A' <= c && c <= 'F':
+ return c - 'A' + 10
+ }
+ return 0
+}
+</pre>
+
+<p>
+There is no automatic fall through, but cases can be presented
+in comma-separated lists.
+</p>
+<pre>
+func shouldEscape(c byte) bool {
+ switch c {
+ case ' ', '?', '&', '=', '#', '+', '%':
+ return true
+ }
+ return false
+}
+</pre>
+
+<p>
+Although they are not nearly as common in Go as some other C-like
+languages, <code>break</code> statements can be used to terminate
+a <code>switch</code> early.
+Sometimes, though, it's necessary to break out of a surrounding loop,
+not the switch, and in Go that can be accomplished by putting a label
+on the loop and "breaking" to that label.
+This example shows both uses.
+</p>
+
+<pre>
+Loop:
+ for n := 0; n < len(src); n += size {
+ switch {
+ case src[n] < sizeOne:
+ if validateOnly {
+ break
+ }
+ size = 1
+ update(src[n])
+
+ case src[n] < sizeTwo:
+ if n+1 >= len(src) {
+ err = errShortInput
+ break Loop
+ }
+ if validateOnly {
+ break
+ }
+ size = 2
+ update(src[n] + src[n+1]<<shift)
+ }
+ }
+</pre>
+
+<p>
+Of course, the <code>continue</code> statement also accepts an optional label
+but it applies only to loops.
+</p>
+
+<p>
+To close this section, here's a comparison routine for byte slices that uses two
+<code>switch</code> statements:
+</p>
+<pre>
+// Compare returns an integer comparing the two byte slices,
+// lexicographically.
+// The result will be 0 if a == b, -1 if a < b, and +1 if a > b
+func Compare(a, b []byte) int {
+ for i := 0; i < len(a) && i < len(b); i++ {
+ switch {
+ case a[i] > b[i]:
+ return 1
+ case a[i] < b[i]:
+ return -1
+ }
+ }
+ switch {
+ case len(a) > len(b):
+ return 1
+ case len(a) < len(b):
+ return -1
+ }
+ return 0
+}
+</pre>
+
+<h3 id="type_switch">Type switch</h3>
+
+<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.
+It's also idiomatic to reuse the name in such cases, in effect declaring
+a new variable with the same name but a different type in each case.
+</p>
+<pre>
+var t interface{}
+t = functionOfSomeType()
+switch t := t.(type) {
+default:
+ fmt.Printf("unexpected type %T", t) // %T prints whatever type t has
+case bool:
+ fmt.Printf("boolean %t\n", t) // t has type bool
+case int:
+ fmt.Printf("integer %d\n", t) // t has type int
+case *bool:
+ fmt.Printf("pointer to boolean %t\n", *t) // t has type *bool
+case *int:
+ fmt.Printf("pointer to integer %d\n", *t) // t has type *int
+}
+</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 passed by address.
+</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: “Yes, you wrote some
+bytes but not all of them because you filled the device”.
+The signature of the <code>Write</code> method on files from
+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 slice, returning the number
+and the next position.
+</p>
+
+<pre>
+func nextInt(b []byte, i int) (int, int) {
+ for ; i < len(b) && !isDigit(b[i]); i++ {
+ }
+ x := 0
+ for ; i < len(b) && isDigit(b[i]); i++ {
+ x = x*10 + int(b[i]) - '0'
+ }
+ return x, i
+}
+</pre>
+
+<p>
+You could use it to scan the numbers in an input slice <code>b</code> like this:
+</p>
+
+<pre>
+ for i := 0; i < len(b); {
+ x, i = nextInt(b, 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) > 0 && 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 < 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>zeros</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 < 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 < 0 {
+ return nil
+ }
+ f := File{fd, name, nil, 0}
+ return &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 &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 &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>&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 represent, 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>
+
+<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> or take the address
+of a variable explicitly.
+</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(&array) // Note the explicit address-of operator
+</pre>
+
+<p>
+But even this style isn't idiomatic Go.
+Use slices instead.
+</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 hold references to an underlying array, and if you assign one
+slice to another, both refer to the same array.
+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>buf</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, the following snippet would also read the first 32 bytes of the buffer.
+</p>
+<pre>
+ var n int
+ var err error
+ for i := 0; i < 32; i++ {
+ nbytes, e := f.Read(buf[i:i+1]) // Read one byte.
+ if nbytes == 0 || e != nil {
+ err = e
+ break
+ }
+ n += nbytes
+ }
+</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) > 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>
+
+<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="two_dimensional_slices">Two-dimensional slices</h3>
+
+<p>
+Go's arrays and slices are one-dimensional.
+To create the equivalent of a 2D array or slice, it is necessary to define an array-of-arrays
+or slice-of-slices, like this:
+</p>
+
+<pre>
+type Transform [3][3]float64 // A 3x3 array, really an array of arrays.
+type LinesOfText [][]byte // A slice of byte slices.
+</pre>
+
+<p>
+Because slices are variable-length, it is possible to have each inner
+slice be a different length.
+That can be a common situation, as in our <code>LinesOfText</code>
+example: each line has an independent length.
+</p>
+
+<pre>
+text := LinesOfText{
+ []byte("Now is the time"),
+ []byte("for all good gophers"),
+ []byte("to bring some fun to the party."),
+}
+</pre>
+
+<p>
+Sometimes it's necessary to allocate a 2D slice, a situation that can arise when
+processing scan lines of pixels, for instance.
+There are two ways to achieve this.
+One is to allocate each slice independently; the other
+is to allocate a single array and point the individual slices into it.
+Which to use depends on your application.
+If the slices might grow or shrink, they should be allocated independently
+to avoid overwriting the next line; if not, it can be more efficient to construct
+the object with a single allocation.
+For reference, here are sketches of the two methods.
+First, a line at a time:
+</p>
+
+<pre>
+// Allocate the top-level slice.
+picture := make([][]uint8, YSize) // One row per unit of y.
+// Loop over the rows, allocating the slice for each row.
+for i := range picture {
+ picture[i] = make([]uint8, XSize)
+}
+</pre>
+
+<p>
+And now as one allocation, sliced into lines:
+</p>
+
+<pre>
+// Allocate the top-level slice, the same as before.
+picture := make([][]uint8, YSize) // One row per unit of y.
+// Allocate one large slice to hold all the pixels.
+pixels := make([]uint8, XSize*YSize) // Has type []uint8 even though picture is [][]uint8.
+// Loop over the rows, slicing each row from the front of the remaining pixels slice.
+for i := range picture {
+ picture[i], pixels = pixels[:XSize], pixels[XSize:]
+}
+</pre>
+
+<h3 id="maps">Maps</h3>
+
+<p>
+Maps are a convenient and powerful built-in data structure that associate
+values of one type (the <em>key</em>) with values of another type
+(the <em>element</em> or <em>value</em>)
+The key can be of any type for which the equality operator is defined,
+such as integers,
+floating point and complex numbers,
+strings, pointers, interfaces (as long as the dynamic type
+supports equality), structs and arrays.
+Slices cannot be used as map keys,
+because equality is not defined on them.
+Like slices, maps hold references to an underlying data structure.
+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 and slices 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 the empty string 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 “comma ok” 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 <a href="#blank">blank identifier</a> (<code>_</code>)
+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 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>
+The formatted print functions <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<<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 “value”); 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, slices, 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 := &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>
+&{7 -2.35 abc def}
+&{a:7 b:-2.35 c:abc def}
+&main.T{a:7, b:-2.35, c:"abc\tdef"}
+map[string] int{"CST":-21600, "PST":-28800, "EST":-18000, "UTC":0, "MST":-25200}
+</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.
+(The <code>%q</code> format also applies to integers and runes, producing a
+single-quoted rune constant.)
+Also, <code>%x</code> works on strings, byte arrays and byte slices as well as
+on integers, generating a long hexadecimal string, and with
+a space in the format (<code>% 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.
+</p>
+<pre>
+fmt.Printf("%T\n", 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 wrapped this way.
+There is one important detail to understand about this approach,
+however: don't construct a <code>String</code> method by calling
+<code>Sprintf</code> in a way that will recur into your <code>String</code>
+method indefinitely. This can happen if the <code>Sprintf</code>
+call attempts to print the receiver directly as a string, which in
+turn will invoke the method again. It's a common and easy mistake
+to make, as this example shows.
+</p>
+
+<pre>
+type MyString string
+
+func (m MyString) String() string {
+ return fmt.Sprintf("MyString=%s", m) // Error: will recur forever.
+}
+</pre>
+
+<p>
+It's also easy to fix: convert the argument to the basic string type, which does not have the
+method.
+</p>
+
+<pre>
+type MyString string
+func (m MyString) String() string {
+ return fmt.Sprintf("MyString=%s", string(m)) // OK: note conversion.
+}
+</pre>
+
+<p>
+In the <a href="#initialization">initialization section</a> we'll see another technique that avoids this recursion.
+</p>
+
+<p>
+Another printing technique is to 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>
+<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 < 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 ...<i>T</i>) []<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 among initialized objects, even among different packages, are handled
+correctly.
+</p>
+
+<h3 id="constants">Constants</h3>
+
+<p>
+Constants in Go are just that—constant.
+They are created at compile time, even when defined as
+locals in functions,
+and can only be numbers, characters (runes), 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<<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 "/doc/progs/eff_bytesize.go" `/^type ByteSize/` `/^\)/`}}
+<p>
+The ability to attach a method such as <code>String</code> to any
+user-defined type makes it possible for arbitrary values to format themselves
+automatically for printing.
+Although you'll see it most often applied to structs, this technique is also useful for
+scalar types such as floating-point types like <code>ByteSize</code>.
+</p>
+{{code "/doc/progs/eff_bytesize.go" `/^func.*ByteSize.*String/` `/^}/`}}
+<p>
+The expression <code>YB</code> prints as <code>1.00YB</code>,
+while <code>ByteSize(1e13)</code> prints as <code>9.09TB</code>.
+</p>
+
+<p>
+The use here of <code>Sprintf</code>
+to implement <code>ByteSize</code>'s <code>String</code> method is safe
+(avoids recurring indefinitely) not because of a conversion but
+because it calls <code>Sprintf</code> with <code>%f</code>,
+which is not a string format: <code>Sprintf</code> will only call
+the <code>String</code> method when it wants a string, and <code>%f</code>
+wants a floating-point value.
+</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")
+ gopath = os.Getenv("GOPATH")
+)
+</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 = "/home/" + user
+ }
+ if gopath == "" {
+ gopath = home + "/go"
+ }
+ // gopath may be overridden by --gopath flag on command line.
+ flag.StringVar(&gopath, "gopath", gopath, "override default GOPATH")
+}
+</pre>
+
+<h2 id="methods">Methods</h2>
+
+<h3 id="pointers_vs_values">Pointers vs. Values</h3>
+<p>
+As we saw with <code>ByteSize</code>,
+methods can be defined for any named type (except a pointer or an interface);
+the receiver does not have to be a struct.
+</p>
+<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(&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.
+</p>
+
+<p>
+This rule arises because pointer methods can modify the receiver; invoking
+them on a value would cause the method to receive a copy of the value, so
+any modifications would be discarded.
+The language therefore disallows this mistake.
+There is a handy exception, though. When the value is addressable, the
+language takes care of the common case of invoking a pointer method on a
+value by inserting the address operator automatically.
+In our example, the variable <code>b</code> is addressable, so we can call
+its <code>Write</code> method with just <code>b.Write</code>. The compiler
+will rewrite that to <code>(&b).Write</code> for us.
+</p>
+
+<p>
+By the way, the idea of using <code>Write</code> on a slice of bytes
+is central to the implementation of <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 "/doc/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>
+This method is another example of the conversion technique for calling
+<code>Sprintf</code> safely from a <code>String</code> method.
+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="interface_conversions">Interface conversions and type assertions</h3>
+
+<p>
+<a href="#type_switch">Type switches</a> are a form of conversion: they take an interface and, for
+each case in the switch, in a sense convert it to the type of that case.
+Here's a simplified version of how the code under <code>fmt.Printf</code> turns a value into
+a string using a type switch.
+If it's already a string, we want the actual string value held by the interface, while if it has a
+<code>String</code> method we want the result of calling the method.
+</p>
+
+<pre>
+type Stringer interface {
+ String() string
+}
+
+var value interface{} // Value provided by caller.
+switch str := value.(type) {
+case string:
+ return str
+case Stringer:
+ return str.String()
+}
+</pre>
+
+<p>
+The first case finds a concrete value; the second converts the interface into another interface.
+It's perfectly fine to mix types this way.
+</p>
+
+<p>
+What if there's only one type we care about? If we know the value holds a <code>string</code>
+and we just want to extract it?
+A one-case type switch would do, but so would a <em>type assertion</em>.
+A type assertion takes an interface value and extracts from it a value of the specified explicit type.
+The syntax borrows from the clause opening a type switch, but with an explicit
+type rather than the <code>type</code> keyword:
+</p>
+
+<pre>
+value.(typeName)
+</pre>
+
+<p>
+and the result is a new value with the static type <code>typeName</code>.
+That type must either be the concrete type held by the interface, or a second interface
+type that the value can be converted to.
+To extract the string we know is in the value, we could write:
+</p>
+
+<pre>
+str := value.(string)
+</pre>
+
+<p>
+But if it turns out that the value does not contain a string, the program will crash with a run-time error.
+To guard against that, use the "comma, ok" idiom to test, safely, whether the value is a string:
+</p>
+
+<pre>
+str, ok := value.(string)
+if ok {
+ fmt.Printf("string value is: %q\n", str)
+} else {
+ fmt.Printf("value is not a string\n")
+}
+</pre>
+
+<p>
+If the type assertion fails, <code>str</code> will still exist and be of type string, but it will have
+the zero value, an empty string.
+</p>
+
+<p>
+As an illustration of the capability, here's an <code>if</code>-<code>else</code>
+statement that's equivalent to the type switch that opened this section.
+</p>
+
+<pre>
+if str, ok := value.(string); ok {
+ return str
+} else if str, ok := value.(Stringer); ok {
+ return str.String()
+}
+</pre>
+
+<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>
+<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.
+</p>
+<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 <- 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() {
+ fmt.Println(os.Args)
+}
+</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) {
+ fmt.Fprintln(w, os.Args)
+}
+</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="blank">The blank identifier</h2>
+
+<p>
+We've mentioned the blank identifier a couple of times now, in the context of
+<a href="#for"><code>for</code> <code>range</code> loops</a>
+and <a href="#maps">maps</a>.
+The blank identifier can be assigned or declared with any value of any type, with the
+value discarded harmlessly.
+It's a bit like writing to the Unix <code>/dev/null</code> file:
+it represents a write-only value
+to be used as a place-holder
+where a variable is needed but the actual value is irrelevant.
+It has uses beyond those we've seen already.
+</p>
+
+<h3 id="blank_assign">The blank identifier in multiple assignment</h3>
+
+<p>
+The use of a blank identifier in a <code>for</code> <code>range</code> loop is a
+special case of a general situation: multiple assignment.
+</p>
+
+<p>
+If an assignment requires multiple values on the left side,
+but one of the values will not be used by the program,
+a blank identifier on the left-hand-side of
+the assignment avoids the need
+to create a dummy variable and makes it clear that the
+value is to be discarded.
+For instance, when calling a function that returns
+a value and an error, but only the error is important,
+use the blank identifier to discard the irrelevant value.
+</p>
+
+<pre>
+if _, err := os.Stat(path); os.IsNotExist(err) {
+ fmt.Printf("%s does not exist\n", path)
+}
+</pre>
+
+<p>
+Occasionally you'll see code that discards the error value in order
+to ignore the error; this is terrible practice. Always check error returns;
+they're provided for a reason.
+</p>
+
+<pre>
+// Bad! This code will crash if path does not exist.
+fi, _ := os.Stat(path)
+if fi.IsDir() {
+ fmt.Printf("%s is a directory\n", path)
+}
+</pre>
+
+<h3 id="blank_unused">Unused imports and variables</h3>
+
+<p>
+It is an error to import a package or to declare a variable without using it.
+Unused imports bloat the program and slow compilation,
+while a variable that is initialized but not used is at least
+a wasted computation and perhaps indicative of a
+larger bug.
+When a program is under active development, however,
+unused imports and variables often arise and it can
+be annoying to delete them just to have the compilation proceed,
+only to have them be needed again later.
+The blank identifier provides a workaround.
+</p>
+<p>
+This half-written program has two unused imports
+(<code>fmt</code> and <code>io</code>)
+and an unused variable (<code>fd</code>),
+so it will not compile, but it would be nice to see if the
+code so far is correct.
+</p>
+{{code "/doc/progs/eff_unused1.go" `/package/` `$`}}
+<p>
+To silence complaints about the unused imports, use a
+blank identifier to refer to a symbol from the imported package.
+Similarly, assigning the unused variable <code>fd</code>
+to the blank identifier will silence the unused variable error.
+This version of the program does compile.
+</p>
+{{code "/doc/progs/eff_unused2.go" `/package/` `$`}}
+
+<p>
+By convention, the global declarations to silence import errors
+should come right after the imports and be commented,
+both to make them easy to find and as a reminder to clean things up later.
+</p>
+
+<h3 id="blank_import">Import for side effect</h3>
+
+<p>
+An unused import like <code>fmt</code> or <code>io</code> in the
+previous example should eventually be used or removed:
+blank assignments identify code as a work in progress.
+But sometimes it is useful to import a package only for its
+side effects, without any explicit use.
+For example, during its <code>init</code> function,
+the <code><a href="/pkg/net/http/pprof/">net/http/pprof</a></code>
+package registers HTTP handlers that provide
+debugging information. It has an exported API, but
+most clients need only the handler registration and
+access the data through a web page.
+To import the package only for its side effects, rename the package
+to the blank identifier:
+</p>
+<pre>
+import _ "net/http/pprof"
+</pre>
+<p>
+This form of import makes clear that the package is being
+imported for its side effects, because there is no other possible
+use of the package: in this file, it doesn't have a name.
+(If it did, and we didn't use that name, the compiler would reject the program.)
+</p>
+
+<h3 id="blank_implements">Interface checks</h3>
+
+<p>
+As we saw in the discussion of <a href="#interfaces_and_types">interfaces</a> above,
+a type need not declare explicitly that it implements an interface.
+Instead, a type implements the interface just by implementing the interface's methods.
+In practice, most interface conversions are static and therefore checked at compile time.
+For example, passing an <code>*os.File</code> to a function
+expecting an <code>io.Reader</code> will not compile unless
+<code>*os.File</code> implements the <code>io.Reader</code> interface.
+</p>
+
+<p>
+Some interface checks do happen at run-time, though.
+One instance is in the <code><a href="/pkg/encoding/json/">encoding/json</a></code>
+package, which defines a <code><a href="/pkg/encoding/json/#Marshaler">Marshaler</a></code>
+interface. When the JSON encoder receives a value that implements that interface,
+the encoder invokes the value's marshaling method to convert it to JSON
+instead of doing the standard conversion.
+The encoder checks this property at run time with a <a href="#interface_conversions">type assertion</a> like:
+</p>
+
+<pre>
+m, ok := val.(json.Marshaler)
+</pre>
+
+<p>
+If it's necessary only to ask whether a type implements an interface, without
+actually using the interface itself, perhaps as part of an error check, use the blank
+identifier to ignore the type-asserted value:
+</p>
+
+<pre>
+if _, ok := val.(json.Marshaler); ok {
+ fmt.Printf("value %v of type %T implements json.Marshaler\n", val, val)
+}
+</pre>
+
+<p>
+One place this situation arises is when it is necessary to guarantee within the package implementing the type that
+it actually satisfies the interface.
+If a type—for example,
+<code><a href="/pkg/encoding/json/#RawMessage">json.RawMessage</a></code>—needs
+a custom JSON representation, it should implement
+<code>json.Marshaler</code>, but there are no static conversions that would
+cause the compiler to verify this automatically.
+If the type inadvertently fails to satisfy the interface, the JSON encoder will still work,
+but will not use the custom implementation.
+To guarantee that the implementation is correct,
+a global declaration using the blank identifier can be used in the package:
+</p>
+<pre>
+var _ json.Marshaler = (*RawMessage)(nil)
+</pre>
+<p>
+In this declaration, the assignment involving a conversion of a
+<code>*RawMessage</code> to a <code>Marshaler</code>
+requires that <code>*RawMessage</code> implements <code>Marshaler</code>,
+and that property will be checked at compile time.
+Should the <code>json.Marshaler</code> interface change, this package
+will no longer compile and we will be on notice that it needs to be updated.
+</p>
+
+<p>
+The appearance of the blank identifier in this construct indicates that
+the declaration exists only for the type checking,
+not to create a variable.
+Don't do this for every type that satisfies an interface, though.
+By convention, such declarations are only used
+when there are no static conversions already present in the code,
+which is a rare event.
+</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 “borrow” 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>
+<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 <code>Job</code> struct,
+so we can initialize it in the usual way inside the constructor for <code>Job</code>, like this,
+</p>
+<pre>
+func NewJob(command string, logger *log.Logger) *Job {
+ return &Job{command, logger}
+}
+</pre>
+<p>
+or with a composite literal,
+</p>
+<pre>
+job := &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, as it did
+in the <code>Read</code> method of our <code>ReaderWriter</code> struct.
+Here, 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>,
+which 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—threads, coroutines, processes, and so on—convey
+inaccurate connotations. A goroutine has a simple model: it is a
+function executing concurrently 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>&</code> notation for running a command in the
+background.)
+</p>
+<pre>
+go list.Sort() // run list.Sort concurrently; don't wait for it.
+</pre>
+<p>
+A function literal can be handy in a goroutine invocation.
+</p>
+<pre>
+func Announce(message string, delay time.Duration) {
+ 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>
+<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 allocated with <code>make</code>, and
+the resulting value acts as a reference to an underlying data structure.
+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>
+Unbuffered channels combine communication—the exchange of a value—with
+synchronization—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 <- 1 // Send a signal; value does not matter.
+}()
+doSomethingForAWhile()
+<-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
+to ready the “semaphore” for the next consumer.
+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 <- 1 // Wait for active queue to drain.
+ process(r) // May take a long time.
+ <-sem // Done; enable next request to run.
+}
+
+func Serve(queue chan *Request) {
+ for {
+ req := <-queue
+ go handle(req) // Don't wait for handle to finish.
+ }
+}
+</pre>
+
+<p>
+Once <code>MaxOutstanding</code> handlers are executing <code>process</code>,
+any more will block trying to send into the filled channel buffer,
+until one of the existing handlers finishes and receives from the buffer.
+</p>
+
+<p>
+This design has a problem, though: <code>Serve</code>
+creates a new goroutine for
+every incoming request, even though only <code>MaxOutstanding</code>
+of them can run at any moment.
+As a result, the program can consume unlimited resources if the requests come in too fast.
+We can address that deficiency by changing <code>Serve</code> to
+gate the creation of the goroutines.
+Here's an obvious solution, but beware it has a bug we'll fix subsequently:
+</p>
+
+<pre>
+func Serve(queue chan *Request) {
+ for req := range queue {
+ sem <- 1
+ go func() {
+ process(req) // Buggy; see explanation below.
+ <-sem
+ }()
+ }
+}</pre>
+
+<p>
+The bug is that in a Go <code>for</code> loop, the loop variable
+is reused for each iteration, so the <code>req</code>
+variable is shared across all goroutines.
+That's not what we want.
+We need to make sure that <code>req</code> is unique for each goroutine.
+Here's one way to do that, passing the value of <code>req</code> as an argument
+to the closure in the goroutine:
+</p>
+
+<pre>
+func Serve(queue chan *Request) {
+ for req := range queue {
+ sem <- 1
+ go func(req *Request) {
+ process(req)
+ <-sem
+ }(req)
+ }
+}</pre>
+
+<p>
+Compare this version with the previous to see the difference in how
+the closure is declared and run.
+Another solution is just to create a new variable with the same
+name, as in this example:
+</p>
+
+<pre>
+func Serve(queue chan *Request) {
+ for req := range queue {
+ req := req // Create new instance of req for the goroutine.
+ sem <- 1
+ go func() {
+ process(req)
+ <-sem
+ }()
+ }
+}</pre>
+
+<p>
+It may seem odd to write
+</p>
+
+<pre>
+req := req
+</pre>
+
+<p>
+but it's a legal and idiomatic in Go to do this.
+You get a fresh version of the variable with the same name, deliberately
+shadowing the loop variable locally but unique to each goroutine.
+</p>
+
+<p>
+Going back to the general problem of writing the server,
+another approach that manages resources well is to start 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 *Request, quit chan bool) {
+ // Start handlers
+ for i := 0; i < MaxOutstanding; i++ {
+ go handle(clientRequests)
+ }
+ <-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>
+<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 := &Request{[]int{3, 4, 5}, sum, make(chan int)}
+// Send request
+clientRequests <- request
+// Wait for response.
+fmt.Printf("answer: %d\n", <-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 <- 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 that can execute independently, 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 < n; i++ {
+ v[i] += u.Op(v[i])
+ }
+ c <- 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 < NCPU; i++ {
+ go v.DoSome(i*len(v)/NCPU, (i+1)*len(v)/NCPU, u, c)
+ }
+ // Drain the channel.
+ for i := 0; i < NCPU; i++ {
+ <-c // wait for one task to complete
+ }
+ // All done.
+}
+
+</pre>
+
+<p>
+The current implementation of the Go runtime
+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>
+
+<p>
+Be sure not to confuse the ideas of concurrency—structuring a program
+as independently executing components—and parallelism—executing
+calculations in parallel for efficiency on multiple CPUs.
+Although the concurrency features of Go can make some problems easy
+to structure as parallel computations, Go is a concurrent language,
+not a parallel one, and not all parallelization problems fit Go's model.
+For a discussion of the distinction, see the talk cited in
+<a href="//blog.golang.org/2013/01/concurrency-is-not-parallelism.html">this
+blog post</a>.
+
+<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 = <-freeList:
+ // Got one; nothing more to do.
+ default:
+ // None free, so allocate a new one.
+ b = new(Buffer)
+ }
+ load(b) // Read next message from the net.
+ serverChan <- b // Send to server.
+ }
+}
+</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 := <-serverChan // Wait for work.
+ process(b)
+ // Reuse buffer if there's room.
+ select {
+ case freeList <- b:
+ // Buffer on free list; nothing more to do.
+ default:
+ // Free list full, just carry on.
+ }
+ }
+}
+</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.
+It is good style to use this feature to provide detailed error information.
+For example, as we'll see, <code>os.Open</code> doesn't
+just return a <code>nil</code> pointer on failure, it also returns an
+error value that describes what went wrong.
+</p>
+
+<p>
+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.
+As mentioned, alongside the usual <code>*os.File</code>
+return value, <code>os.Open</code> also returns an
+error value.
+If the file is opened successfully, the error will be <code>nil</code>,
+but when there is a problem, it will hold 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 operation or package that generated the error. For example, in package
+<code>image</code>, 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 < 2; try++ {
+ file, err = os.Create(filename)
+ if err == nil {
+ return
+ }
+ if e, ok := err.(*os.PathError); ok && e.Err == syscall.ENOSPC {
+ deleteTempFiles() // Recover some space.
+ continue
+ }
+ return
+}
+</pre>
+
+<p>
+The second <code>if</code> statement here is another <a href="#interface_conversions">type assertion</a>.
+If it 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—often a string—to be printed as the
+program dies. It's also a way to indicate that something impossible has
+happened, such as exiting an infinite loop.
+</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 < 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 a slice 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 <-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 version of a <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>—deferred functions can modify
+named return values. It 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 index out of bounds, the code will fail even though we
+are using <code>panic</code> and <code>recover</code> to handle
+parse errors.
+</p>
+
+<p>
+With error handling in place, the <code>error</code> method (because it's a
+method bound to a type, it's fine, even natural, for it to have the same name
+as the builtin <code>error</code> type)
+makes it easy to report parse errors without worrying about unwinding
+the parse stack by hand:
+</p>
+
+<pre>
+if pos == 0 {
+ re.error("'*' illegal at start of expression")
+}
+</pre>
+
+<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—it's a crash after all—but if you want to
+display only the original value, you can write a little more code to
+filter unexpected problems and re-panic with the original error.
+That's left as an exercise for the reader.
+</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 "/doc/progs/eff_qr.go" `/package/` `$`}}
+<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 <code>html/template</code> is powerful;
+this program just touches on its capabilities.
+In essence, it rewrites a piece of HTML 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 two snippets <code>{{html "{{.}}"}}</code> say to show the data presented to
+the template—the query string—on the web page.
+The HTML template package automatically provides appropriate escaping so the
+text is safe to display.
+</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/html/template/">documentation</a>
+for the template package for a more thorough discussion.
+</p>
+<p>
+And there you have it: a useful web server 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>
+-->
+
diff --git a/doc/gccgo_contribute.html b/doc/gccgo_contribute.html
new file mode 100644
index 0000000..db7d1ab
--- /dev/null
+++ b/doc/gccgo_contribute.html
@@ -0,0 +1,112 @@
+<!--{
+ "Title": "Contributing to the gccgo frontend"
+}-->
+
+<h2>Introduction</h2>
+
+<p>
+These are some notes on contributing to the gccgo frontend for GCC.
+For information on contributing to parts of Go other than gccgo,
+see <a href="/doc/contribute.html">Contributing to the Go project</a>. For
+information on building gccgo for yourself,
+see <a href="/doc/gccgo_install.html">Setting up and using gccgo</a>.
+For more of the gritty details on the process of doing development
+with the gccgo frontend,
+see <a href="https://code.google.com/p/gofrontend/source/browse/HACKING">the
+file HACKING</a> in the gofrontend repository.
+</p>
+
+<h2>Legal Prerequisites</h2>
+
+<p>
+You must follow the <a href="/doc/contribute.html#copyright">Go copyright
+rules</a> for all changes to the gccgo frontend and the associated
+libgo library. Code that is part of GCC rather than gccgo must follow
+the general <a href="http://gcc.gnu.org/contribute.html">GCC
+contribution rules</a>.
+</p>
+
+<h2>Code</h2>
+
+<p>
+The master sources for the gccgo frontend may be found at
+<a href="//code.google.com/p/gofrontend">http://code.google.com/p/gofrontend</a>.
+The master sources are not buildable by themselves, but only in
+conjunction with GCC (in the future, other compilers may be
+supported). Changes made to the gccgo frontend are also applied to
+the GCC source code repository hosted at <code>gcc.gnu.org</code>. In
+the <code>gofrontend</code> repository, the <code>go</code> directory
+is mirrored to the <code>gcc/go/gofrontend</code> directory in the GCC
+repository, and the <code>gofrontend</code> <code>libgo</code>
+directory is mirrored to the GCC <code>libgo</code> directory. In
+addition, the <code>test</code> directory
+from <a href="//code.google.com/p/go">the main Go repository</a>
+is mirrored to the <code>gcc/testsuite/go.test/test</code> directory
+in the GCC repository.
+</p>
+
+<p>
+Changes to these directories always flow from the master sources to
+the GCC repository. The files should never be changed in the GCC
+repository except by changing them in the master sources and mirroring
+them.
+</p>
+
+<p>
+The gccgo frontend is written in C++. It follows the GNU coding
+standards to the extent that they apply to C++. In writing code for
+the frontend, follow the formatting of the surrounding code. Although
+the frontend is currently tied to the rest of the GCC codebase, we
+plan to make it more independent. Eventually all GCC-specific code
+will migrate out of the frontend proper and into GCC proper. In the
+GCC sources this will generally mean moving code
+from <code>gcc/go/gofrontend</code> to <code>gcc/go</code>.
+</p>
+
+<p>
+The run-time library for gccgo is mostly the same as the library
+in <a href="//code.google.com/p/go">the main Go repository</a>.
+The library code in the Go repository is periodically merged into
+the <code>libgo/go</code> directory of the <code>gofrontend</code> and
+then the GCC repositories, using the shell
+script <code>libgo/merge.sh</code>. Accordingly, most library changes
+should be made in the main Go repository. The files outside
+of <code>libgo/go</code> are gccgo-specific; that said, some of the
+files in <code>libgo/runtime</code> are based on files
+in <code>src/runtime</code> in the main Go repository.
+</p>
+
+<h2>Testing</h2>
+
+<p>
+All patches must be tested. A patch that introduces new failures is
+not acceptable.
+</p>
+
+<p>
+To run the gccgo test suite, run <code>make check-go</code> in your
+build directory. This will run various tests
+under <code>gcc/testsuite/go.*</code> and will also run
+the <code>libgo</code> testsuite. This copy of the tests from the
+main Go repository is run using the DejaGNU script found
+in <code>gcc/testsuite/go.test/go-test.exp</code>.
+</p>
+
+<p>
+Most new tests should be submitted to the main Go repository for later
+mirroring into the GCC repository. If there is a need for specific
+tests for gccgo, they should go in
+the <code>gcc/testsuite/go.go-torture</code>
+or <code>gcc/testsuite/go.dg</code> directories in the GCC repository.
+</p>
+
+<h2>Submitting Changes</h2>
+
+<p>
+Changes to the Go frontend should follow the same process as for the
+main Go repository, only for the <code>gofrontend</code> project and
+the<code>gofrontend-dev@googlegroups.com</code> mailing list
+rather than the <code>go</code> project and the
+<code>golang-dev@googlegroups.com</code> mailing list. Those changes
+will then be merged into the GCC sources.
+</p>
diff --git a/doc/gccgo_install.html b/doc/gccgo_install.html
new file mode 100644
index 0000000..acb315a
--- /dev/null
+++ b/doc/gccgo_install.html
@@ -0,0 +1,529 @@
+<!--{
+ "Title": "Setting up and using gccgo",
+ "Path": "/doc/install/gccgo"
+}-->
+
+<p>
+This document explains how to use gccgo, a compiler for
+the Go language. The gccgo compiler is a new frontend
+for GCC, the widely used GNU compiler. Although the
+frontend itself is under a BSD-style license, gccgo is
+normally used as part of GCC and is then covered by
+the <a href="http://www.gnu.org/licenses/gpl.html">GNU General Public
+License</a> (the license covers gccgo itself as part of GCC; it
+does not cover code generated by gccgo).
+</p>
+
+<p>
+Note that gccgo is not the <code>gc</code> compiler; see
+the <a href="/doc/install.html">Installing Go</a> instructions for that
+compiler.
+</p>
+
+<h2 id="Releases">Releases</h2>
+
+<p>
+The simplest way to install gccgo is to install a GCC binary release
+built to include Go support. GCC binary releases are available from
+<a href="http://gcc.gnu.org/install/binaries.html">various
+websites</a> and are typically included as part of GNU/Linux
+distributions. We expect that most people who build these binaries
+will include Go support.
+</p>
+
+<p>
+The GCC 4.7.1 release and all later 4.7 releases include a complete
+<a href="/doc/go1.html">Go 1</a> compiler and libraries.
+</p>
+
+<p>
+Due to timing, the GCC 4.8.0 and 4.8.1 releases are close to but not
+identical to Go 1.1. The GCC 4.8.2 release includes a complete Go
+1.1.2 implementation.
+</p>
+
+<p>
+The GCC 4.9 releases include a complete Go 1.2 implementation.
+</p>
+
+<h2 id="Source_code">Source code</h2>
+
+<p>
+If you cannot use a release, or prefer to build gccgo for
+yourself,
+the gccgo source code is accessible via Subversion. The
+GCC web site
+has <a href="http://gcc.gnu.org/svn.html">instructions for getting the
+GCC source code</a>. The gccgo source code is included. As a
+convenience, a stable version of the Go support is available in
+a branch of the main GCC code
+repository: <code>svn://gcc.gnu.org/svn/gcc/branches/gccgo</code>.
+This branch is periodically updated with stable Go compiler sources.
+</p>
+
+<p>
+Note that although <code>gcc.gnu.org</code> is the most convenient way
+to get the source code for the Go frontend, it is not where the master
+sources live. If you want to contribute changes to the Go frontend
+compiler, see <a href="/doc/gccgo_contribute.html">Contributing to
+gccgo</a>.
+</p>
+
+
+<h2 id="Building">Building</h2>
+
+<p>
+Building gccgo is just like building GCC
+with one or two additional options. See
+the <a href="http://gcc.gnu.org/install/">instructions on the gcc web
+site</a>. When you run <code>configure</code>, add the
+option <code>--enable-languages=c,c++,go</code> (along with other
+languages you may want to build). If you are targeting a 32-bit x86,
+then you will want to build gccgo to default to
+supporting locked compare and exchange instructions; do this by also
+using the <code>configure</code> option <code>--with-arch=i586</code>
+(or a newer architecture, depending on where you need your programs to
+run). If you are targeting a 64-bit x86, but sometimes want to use
+the <code>-m32</code> option, then use the <code>configure</code>
+option <code>--with-arch-32=i586</code>.
+</p>
+
+<h3 id="Gold">Gold</h3>
+
+<p>
+On x86 GNU/Linux systems the gccgo compiler is able to
+use a small discontiguous stack for goroutines. This permits programs
+to run many more goroutines, since each goroutine can use a relatively
+small stack. Doing this requires using the gold linker version 2.22
+or later. You can either install GNU binutils 2.22 or later, or you
+can build gold yourself.
+</p>
+
+<p>
+To build gold yourself, build the GNU binutils,
+using <code>--enable-gold=default</code> when you run
+the <code>configure</code> script. Before building, you must install
+the flex and bison packages. A typical sequence would look like
+this (you can replace <code>/opt/gold</code> with any directory to
+which you have write access):
+</p>
+
+<pre>
+cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src login
+[password is "anoncvs"]
+[The next command will create a directory named src, not binutils]
+cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src co binutils
+mkdir binutils-objdir
+cd binutils-objdir
+../src/configure --enable-gold=default --prefix=/opt/gold
+make
+make install
+</pre>
+
+<p>
+However you install gold, when you configure gccgo, use the
+option <code>--with-ld=<var>GOLD_BINARY</var></code>.
+</p>
+
+<h3 id="Prerequisites">Prerequisites</h3>
+
+<p>
+A number of prerequisites are required to build GCC, as
+described on
+the <a href="http://gcc.gnu.org/install/prerequisites.html">gcc web
+site</a>. It is important to install all the prerequisites before
+running the gcc <code>configure</code> script.
+The prerequisite libraries can be conveniently downloaded using the
+script <code>contrib/download_prerequisites</code> in the GCC sources.
+
+<h3 id="Build_commands">Build commands</h3>
+
+<p>
+Once all the prerequisites are installed, then a typical build and
+install sequence would look like this (only use
+the <code>--with-ld</code> option if you are using the gold linker as
+described above):
+</p>
+
+<pre>
+svn checkout svn://gcc.gnu.org/svn/gcc/branches/gccgo gccgo
+mkdir objdir
+cd objdir
+../gccgo/configure --prefix=/opt/gccgo --enable-languages=c,c++,go --with-ld=/opt/gold/bin/ld
+make
+make install
+</pre>
+
+<h3 id="Ubuntu">A note on Ubuntu</h3>
+
+<p>
+Current versions of Ubuntu and versions of GCC before 4.8 disagree on
+where system libraries and header files are found. This is not a
+gccgo issue. When building older versions of GCC, setting these
+environment variables while configuring and building gccgo may fix the
+problem.
+</p>
+
+<pre>
+LIBRARY_PATH=/usr/lib/x86_64-linux-gnu
+C_INCLUDE_PATH=/usr/include/x86_64-linux-gnu
+CPLUS_INCLUDE_PATH=/usr/include/x86_64-linux-gnu
+export LIBRARY_PATH C_INCLUDE_PATH CPLUS_INCLUDE_PATH
+</pre>
+
+<h2 id="Using_gccgo">Using gccgo</h2>
+
+<p>
+The gccgo compiler works like other gcc frontends. The gccgo
+installation does not currently include a version of
+the <code>go</code> command. However if you have the <code>go</code>
+command from an installation of the <code>gc</code> compiler, you can
+use it with gccgo by passing the option <code>-compiler gccgo</code>
+to <code>go build</code> or <code>go install</code> or <code>go
+test</code>.
+</p>
+
+<p>
+To compile a file without using the <code>go</code> command:
+</p>
+
+<pre>
+gccgo -c file.go
+</pre>
+
+<p>
+That produces <code>file.o</code>. To link files together to form an
+executable:
+</p>
+
+<pre>
+gccgo -o file file.o
+</pre>
+
+<p>
+To run the resulting file, you will need to tell the program where to
+find the compiled Go packages. There are a few ways to do this:
+</p>
+
+<ul>
+<li>
+<p>
+Set the <code>LD_LIBRARY_PATH</code> environment variable:
+</p>
+
+<pre>
+LD_LIBRARY_PATH=${prefix}/lib/gcc/MACHINE/VERSION
+[or]
+LD_LIBRARY_PATH=${prefix}/lib64/gcc/MACHINE/VERSION
+export LD_LIBRARY_PATH
+</pre>
+
+<p>
+Here <code>${prefix}</code> is the <code>--prefix</code> option used
+when building gccgo. For a binary install this is
+normally <code>/usr</code>. Whether to use <code>lib</code>
+or <code>lib64</code> depends on the target.
+Typically <code>lib64</code> is correct for x86_64 systems,
+and <code>lib</code> is correct for other systems. The idea is to
+name the directory where <code>libgo.so</code> is found.
+</p>
+
+</li>
+
+<li>
+<p>
+Passing a <code>-Wl,-R</code> option when you link:
+</p>
+
+<pre>
+gccgo -o file file.o -Wl,-R,${prefix}/lib/gcc/MACHINE/VERSION
+[or]
+gccgo -o file file.o -Wl,-R,${prefix}/lib64/gcc/MACHINE/VERSION
+</pre>
+</li>
+
+<li>
+<p>
+Use the <code>-static-libgo</code> option to link statically against
+the compiled packages.
+</p>
+</li>
+
+<li>
+<p>
+Use the <code>-static</code> option to do a fully static link (the
+default for the <code>gc</code> compiler).
+</p>
+</li>
+</ul>
+
+<h2 id="Options">Options</h2>
+
+<p>
+The gccgo compiler supports all GCC options
+that are language independent, notably the <code>-O</code>
+and <code>-g</code> options.
+</p>
+
+<p>
+The <code>-fgo-prefix=PREFIX</code> option may be used to set a unique
+prefix for the package being compiled. This option is intended for
+use with large programs that contain many packages, in order to allow
+multiple packages to use the same identifier as the package name.
+The <code>PREFIX</code> may be any string; a good choice for the
+string is the directory where the package will be installed.
+</p>
+
+<p>
+The <code>-I</code> and <code>-L</code> options, which are synonyms
+for the compiler, may be used to set the search path for finding
+imports.
+</p>
+
+<h2 id="Imports">Imports</h2>
+
+<p>
+When you compile a file that exports something, the export
+information will be stored directly in the object file. When
+you import a package, you must tell gccgo how to
+find the file.
+
+<p>
+When you import the package <var>FILE</var> with gccgo,
+it will look for the import data in the following files, and use the
+first one that it finds.
+
+<ul>
+<li><code><var>FILE</var>.gox</code>
+<li><code>lib<var>FILE</var>.so</code>
+<li><code>lib<var>FILE</var>.a</code>
+<li><code><var>FILE</var>.o</code>
+</ul>
+
+<p>
+<code><var>FILE</var>.gox</code>, when used, will typically contain
+nothing but export data. This can be generated from
+<code><var>FILE</var>.o</code> via
+</p>
+
+<pre>
+objcopy -j .go_export FILE.o FILE.gox
+</pre>
+
+<p>
+The gccgo compiler will look in the current
+directory for import files. In more complex scenarios you
+may pass the <code>-I</code> or <code>-L</code> option to
+gccgo. Both options take directories to search. The
+<code>-L</code> option is also passed to the linker.
+</p>
+
+<p>
+The gccgo compiler does not currently (2013-06-20) record
+the file name of imported packages in the object file. You must
+arrange for the imported data to be linked into the program.
+</p>
+
+<pre>
+gccgo -c mypackage.go # Exports mypackage
+gccgo -c main.go # Imports mypackage
+gccgo -o main main.o mypackage.o # Explicitly links with mypackage.o
+</pre>
+
+<h2 id="Debugging">Debugging</h2>
+
+<p>
+If you use the <code>-g</code> option when you compile, you can run
+<code>gdb</code> on your executable. The debugger has only limited
+knowledge about Go. You can set breakpoints, single-step,
+etc. You can print variables, but they will be printed as though they
+had C/C++ types. For numeric types this doesn't matter. Go strings
+and interfaces will show up as two-element structures. Go
+maps and channels are always represented as C pointers to run-time
+structures.
+</p>
+
+<h2 id="C_Interoperability">C Interoperability</h2>
+
+<p>
+When using gccgo there is limited interoperability with C,
+or with C++ code compiled using <code>extern "C"</code>.
+</p>
+
+<h3 id="Types">Types</h3>
+
+<p>
+Basic types map directly: an <code>int</code> in Go is an <code>int</code>
+in C, an <code>int32</code> is an <code>int32_t</code>,
+etc. Go <code>byte</code> is equivalent to C <code>unsigned
+char</code>.
+Pointers in Go are pointers in C. A Go <code>struct</code> is the same as C
+<code>struct</code> with the same fields and types.
+</p>
+
+<p>
+The Go <code>string</code> type is currently defined as a two-element
+structure (this is <b style="color: red;">subject to change</b>):
+</p>
+
+<pre>
+struct __go_string {
+ const unsigned char *__data;
+ int __length;
+};
+</pre>
+
+<p>
+You can't pass arrays between C and Go. However, a pointer to an
+array in Go is equivalent to a C pointer to the
+equivalent of the element type.
+For example, Go <code>*[10]int</code> is equivalent to C <code>int*</code>,
+assuming that the C pointer does point to 10 elements.
+</p>
+
+<p>
+A slice in Go is a structure. The current definition is
+(this is <b style="color: red;">subject to change</b>):
+</p>
+
+<pre>
+struct __go_slice {
+ void *__values;
+ int __count;
+ int __capacity;
+};
+</pre>
+
+<p>
+The type of a Go function is a pointer to a struct (this is
+<b style="color: red;">subject to change</b>). The first field in the
+struct points to the code of the function, which will be equivalent to
+a pointer to a C function whose parameter types are equivalent, with
+an additional trailing parameter. The trailing parameter is the
+closure, and the argument to pass is a pointer to the Go function
+struct.
+
+When a Go function returns more than one value, the C function returns
+a struct. For example, these functions are roughly equivalent:
+</p>
+
+<pre>
+func GoFunction(int) (int, float64)
+struct { int i; float64 f; } CFunction(int, void*)
+</pre>
+
+<p>
+Go <code>interface</code>, <code>channel</code>, and <code>map</code>
+types have no corresponding C type (<code>interface</code> is a
+two-element struct and <code>channel</code> and <code>map</code> are
+pointers to structs in C, but the structs are deliberately undocumented). C
+<code>enum</code> types correspond to some integer type, but precisely
+which one is difficult to predict in general; use a cast. C <code>union</code>
+types have no corresponding Go type. C <code>struct</code> types containing
+bitfields have no corresponding Go type. C++ <code>class</code> types have
+no corresponding Go type.
+</p>
+
+<p>
+Memory allocation is completely different between C and Go, as Go uses
+garbage collection. The exact guidelines in this area are undetermined,
+but it is likely that it will be permitted to pass a pointer to allocated
+memory from C to Go. The responsibility of eventually freeing the pointer
+will remain with C side, and of course if the C side frees the pointer
+while the Go side still has a copy the program will fail. When passing a
+pointer from Go to C, the Go function must retain a visible copy of it in
+some Go variable. Otherwise the Go garbage collector may delete the
+pointer while the C function is still using it.
+</p>
+
+<h3 id="Function_names">Function names</h3>
+
+<p>
+Go code can call C functions directly using a Go extension implemented
+in gccgo: a function declaration may be preceded by
+<code>//extern NAME</code>. For example, here is how the C function
+<code>open</code> can be declared in Go:
+</p>
+
+<pre>
+//extern open
+func c_open(name *byte, mode int, perm int) int
+</pre>
+
+<p>
+The C function naturally expects a NUL-terminated string, which in
+Go is equivalent to a pointer to an array (not a slice!) of
+<code>byte</code> with a terminating zero byte. So a sample call
+from Go would look like (after importing the <code>syscall</code> package):
+</p>
+
+<pre>
+var name = [4]byte{'f', 'o', 'o', 0};
+i := c_open(&name[0], syscall.O_RDONLY, 0);
+</pre>
+
+<p>
+(this serves as an example only, to open a file in Go please use Go's
+<code>os.Open</code> function instead).
+</p>
+
+<p>
+Note that if the C function can block, such as in a call
+to <code>read</code>, calling the C function may block the Go program.
+Unless you have a clear understanding of what you are doing, all calls
+between C and Go should be implemented through cgo or SWIG, as for
+the <code>gc</code> compiler.
+</p>
+
+<p>
+The name of Go functions accessed from C is subject to change. At present
+the name of a Go function that does not have a receiver is
+<code>prefix.package.Functionname</code>. The prefix is set by
+the <code>-fgo-prefix</code> option used when the package is compiled;
+if the option is not used, the default is <code>go</code>.
+To call the function from C you must set the name using
+a GCC extension.
+</p>
+
+<pre>
+extern int go_function(int) __asm__ ("myprefix.mypackage.Function");
+</pre>
+
+<h3 id="Automatic_generation_of_Go_declarations_from_C_source_code">
+Automatic generation of Go declarations from C source code</h3>
+
+<p>
+The Go version of GCC supports automatically generating
+Go declarations from C code. The facility is rather awkward, and most
+users should use the <a href="/cmd/cgo">cgo</a> program with
+the <code>-gccgo</code> option instead.
+</p>
+
+<p>
+Compile your C code as usual, and add the option
+<code>-fdump-go-spec=<var>FILENAME</var></code>. This will create the
+file <code><var>FILENAME</var></code> as a side effect of the
+compilation. This file will contain Go declarations for the types,
+variables and functions declared in the C code. C types that can not
+be represented in Go will be recorded as comments in the Go code. The
+generated file will not have a <code>package</code> declaration, but
+can otherwise be compiled directly by gccgo.
+</p>
+
+<p>
+This procedure is full of unstated caveats and restrictions and we make no
+guarantee that it will not change in the future. It is more useful as a
+starting point for real Go code than as a regular procedure.
+</p>
+
+<h2 id="RTEMS_Port">RTEMS Port</h2>
+<p>
+The gccgo compiler has been ported to <a href="http://www.rtems.com/">
+<code>RTEMS</code></a>. <code>RTEMS</code> is a real-time executive
+that provides a high performance environment for embedded applications
+on a range of processors and embedded hardware. The current gccgo
+port is for x86. The goal is to extend the port to most of the
+<a href="http://www.rtems.org/wiki/index.php/SupportedCPUs">
+architectures supported by <code>RTEMS</code></a>. For more information on the port,
+as well as instructions on how to install it, please see this
+<a href="http://www.rtems.org/wiki/index.php/GCCGoRTEMS"><code>RTEMS</code> Wiki page</a>.
diff --git a/doc/go-logo-black.png b/doc/go-logo-black.png
new file mode 100644
index 0000000..3077ebd
--- /dev/null
+++ b/doc/go-logo-black.png
Binary files differ
diff --git a/doc/go-logo-blue.png b/doc/go-logo-blue.png
new file mode 100644
index 0000000..8d43a56
--- /dev/null
+++ b/doc/go-logo-blue.png
Binary files differ
diff --git a/doc/go-logo-white.png b/doc/go-logo-white.png
new file mode 100644
index 0000000..fa29169
--- /dev/null
+++ b/doc/go-logo-white.png
Binary files differ
diff --git a/doc/go1.1.html b/doc/go1.1.html
new file mode 100644
index 0000000..825867f
--- /dev/null
+++ b/doc/go1.1.html
@@ -0,0 +1,1099 @@
+<!--{
+ "Title": "Go 1.1 Release Notes",
+ "Path": "/doc/go1.1",
+ "Template": true
+}-->
+
+<h2 id="introduction">Introduction to Go 1.1</h2>
+
+<p>
+The release of <a href="/doc/go1.html">Go version 1</a> (Go 1 or Go 1.0 for short)
+in March of 2012 introduced a new period
+of stability in the Go language and libraries.
+That stability has helped nourish a growing community of Go users
+and systems around the world.
+Several "point" releases since
+then—1.0.1, 1.0.2, and 1.0.3—have been issued.
+These point releases fixed known bugs but made
+no non-critical changes to the implementation.
+</p>
+
+<p>
+This new release, Go 1.1, keeps the <a href="/doc/go1compat.html">promise
+of compatibility</a> but adds a couple of significant
+(backwards-compatible, of course) language changes, has a long list
+of (again, compatible) library changes, and
+includes major work on the implementation of the compilers,
+libraries, and run-time.
+The focus is on performance.
+Benchmarking is an inexact science at best, but we see significant,
+sometimes dramatic speedups for many of our test programs.
+We trust that many of our users' programs will also see improvements
+just by updating their Go installation and recompiling.
+</p>
+
+<p>
+This document summarizes the changes between Go 1 and Go 1.1.
+Very little if any code will need modification to run with Go 1.1,
+although a couple of rare error cases surface with this release
+and need to be addressed if they arise.
+Details appear below; see the discussion of
+<a href="#int">64-bit ints</a> and <a href="#unicode_literals">Unicode literals</a>
+in particular.
+</p>
+
+<h2 id="language">Changes to the language</h2>
+
+<p>
+<a href="/doc/go1compat.html">The Go compatibility document</a> promises
+that programs written to the Go 1 language specification will continue to operate,
+and those promises are maintained.
+In the interest of firming up the specification, though, there are
+details about some error cases that have been clarified.
+There are also some new language features.
+</p>
+
+<h3 id="divzero">Integer division by zero</h3>
+
+<p>
+In Go 1, integer division by a constant zero produced a run-time panic:
+</p>
+
+<pre>
+func f(x int) int {
+ return x/0
+}
+</pre>
+
+<p>
+In Go 1.1, an integer division by constant zero is not a legal program, so it is a compile-time error.
+</p>
+
+<h3 id="unicode_literals">Surrogates in Unicode literals</h3>
+
+<p>
+The definition of string and rune literals has been refined to exclude surrogate halves from the
+set of valid Unicode code points.
+See the <a href="#unicode">Unicode</a> section for more information.
+</p>
+
+<h3 id="method_values">Method values</h3>
+
+<p>
+Go 1.1 now implements
+<a href="/ref/spec#Method_values">method values</a>,
+which are functions that have been bound to a specific receiver value.
+For instance, given a
+<a href="/pkg/bufio/#Writer"><code>Writer</code></a>
+value <code>w</code>,
+the expression
+<code>w.Write</code>,
+a method value, is a function that will always write to <code>w</code>; it is equivalent to
+a function literal closing over <code>w</code>:
+</p>
+
+<pre>
+func (p []byte) (n int, err error) {
+ return w.Write(p)
+}
+</pre>
+
+<p>
+Method values are distinct from method expressions, which generate functions
+from methods of a given type; the method expression <code>(*bufio.Writer).Write</code>
+is equivalent to a function with an extra first argument, a receiver of type
+<code>(*bufio.Writer)</code>:
+</p>
+
+<pre>
+func (w *bufio.Writer, p []byte) (n int, err error) {
+ return w.Write(p)
+}
+</pre>
+
+<p>
+<em>Updating</em>: No existing code is affected; the change is strictly backward-compatible.
+</p>
+
+<h3 id="return">Return requirements</h3>
+
+<p>
+Before Go 1.1, a function that returned a value needed an explicit "return"
+or call to <code>panic</code> at
+the end of the function; this was a simple way to make the programmer
+be explicit about the meaning of the function. But there are many cases
+where a final "return" is clearly unnecessary, such as a function with
+only an infinite "for" loop.
+</p>
+
+<p>
+In Go 1.1, the rule about final "return" statements is more permissive.
+It introduces the concept of a
+<a href="/ref/spec#Terminating_statements"><em>terminating statement</em></a>,
+a statement that is guaranteed to be the last one a function executes.
+Examples include
+"for" loops with no condition and "if-else"
+statements in which each half ends in a "return".
+If the final statement of a function can be shown <em>syntactically</em> to
+be a terminating statement, no final "return" statement is needed.
+</p>
+
+<p>
+Note that the rule is purely syntactic: it pays no attention to the values in the
+code and therefore requires no complex analysis.
+</p>
+
+<p>
+<em>Updating</em>: The change is backward-compatible, but existing code
+with superfluous "return" statements and calls to <code>panic</code> may
+be simplified manually.
+Such code can be identified by <code>go vet</code>.
+</p>
+
+<h2 id="impl">Changes to the implementations and tools</h2>
+
+<h3 id="gccgo">Status of gccgo</h3>
+
+<p>
+The GCC release schedule does not coincide with the Go release schedule, so some skew is inevitable in
+<code>gccgo</code>'s releases.
+The 4.8.0 version of GCC shipped in March, 2013 and includes a nearly-Go 1.1 version of <code>gccgo</code>.
+Its library is a little behind the release, but the biggest difference is that method values are not implemented.
+Sometime around July 2013, we expect 4.8.2 of GCC to ship with a <code>gccgo</code>
+providing a complete Go 1.1 implementaiton.
+</p>
+
+<h3 id="gc_flag">Command-line flag parsing</h3>
+
+<p>
+In the gc tool chain, the compilers and linkers now use the
+same command-line flag parsing rules as the Go flag package, a departure
+from the traditional Unix flag parsing. This may affect scripts that invoke
+the tool directly.
+For example,
+<code>go tool 6c -Fw -Dfoo</code> must now be written
+<code>go tool 6c -F -w -D foo</code>.
+</p>
+
+<h3 id="int">Size of int on 64-bit platforms</h3>
+
+<p>
+The language allows the implementation to choose whether the <code>int</code> type and
+<code>uint</code> types are 32 or 64 bits. Previous Go implementations made <code>int</code>
+and <code>uint</code> 32 bits on all systems. Both the gc and gccgo implementations
+now make
+<code>int</code> and <code>uint</code> 64 bits on 64-bit platforms such as AMD64/x86-64.
+Among other things, this enables the allocation of slices with
+more than 2 billion elements on 64-bit platforms.
+</p>
+
+<p>
+<em>Updating</em>:
+Most programs will be unaffected by this change.
+Because Go does not allow implicit conversions between distinct
+<a href="/ref/spec#Numeric_types">numeric types</a>,
+no programs will stop compiling due to this change.
+However, programs that contain implicit assumptions
+that <code>int</code> is only 32 bits may change behavior.
+For example, this code prints a positive number on 64-bit systems and
+a negative one on 32-bit systems:
+</p>
+
+<pre>
+x := ^uint32(0) // x is 0xffffffff
+i := int(x) // i is -1 on 32-bit systems, 0xffffffff on 64-bit
+fmt.Println(i)
+</pre>
+
+<p>Portable code intending 32-bit sign extension (yielding <code>-1</code> on all systems)
+would instead say:
+</p>
+
+<pre>
+i := int(int32(x))
+</pre>
+
+<h3 id="heap">Heap size on 64-bit architectures</h3>
+
+<p>
+On 64-bit architectures, the maximum heap size has been enlarged substantially,
+from a few gigabytes to several tens of gigabytes.
+(The exact details depend on the system and may change.)
+</p>
+
+<p>
+On 32-bit architectures, the heap size has not changed.
+</p>
+
+<p>
+<em>Updating</em>:
+This change should have no effect on existing programs beyond allowing them
+to run with larger heaps.
+</p>
+
+<h3 id="unicode">Unicode</h3>
+
+<p>
+To make it possible to represent code points greater than 65535 in UTF-16,
+Unicode defines <em>surrogate halves</em>,
+a range of code points to be used only in the assembly of large values, and only in UTF-16.
+The code points in that surrogate range are illegal for any other purpose.
+In Go 1.1, this constraint is honored by the compiler, libraries, and run-time:
+a surrogate half is illegal as a rune value, when encoded as UTF-8, or when
+encoded in isolation as UTF-16.
+When encountered, for example in converting from a rune to UTF-8, it is
+treated as an encoding error and will yield the replacement rune,
+<a href="/pkg/unicode/utf8/#RuneError"><code>utf8.RuneError</code></a>,
+U+FFFD.
+</p>
+
+<p>
+This program,
+</p>
+
+<pre>
+import "fmt"
+
+func main() {
+ fmt.Printf("%+q\n", string(0xD800))
+}
+</pre>
+
+<p>
+printed <code>"\ud800"</code> in Go 1.0, but prints <code>"\ufffd"</code> in Go 1.1.
+</p>
+
+<p>
+Surrogate-half Unicode values are now illegal in rune and string constants, so constants such as
+<code>'\ud800'</code> and <code>"\ud800"</code> are now rejected by the compilers.
+When written explicitly as UTF-8 encoded bytes,
+such strings can still be created, as in <code>"\xed\xa0\x80"</code>.
+However, when such a string is decoded as a sequence of runes, as in a range loop, it will yield only <code>utf8.RuneError</code>
+values.
+</p>
+
+<p>
+The Unicode byte order mark U+FEFF, encoded in UTF-8, is now permitted as the first
+character of a Go source file.
+Even though its appearance in the byte-order-free UTF-8 encoding is clearly unnecessary,
+some editors add the mark as a kind of "magic number" identifying a UTF-8 encoded file.
+</p>
+
+<p>
+<em>Updating</em>:
+Most programs will be unaffected by the surrogate change.
+Programs that depend on the old behavior should be modified to avoid the issue.
+The byte-order-mark change is strictly backward-compatible.
+</p>
+
+<h3 id="race">Race detector</h3>
+
+<p>
+A major addition to the tools is a <em>race detector</em>, a way to
+find bugs in programs caused by concurrent access of the same
+variable, where at least one of the accesses is a write.
+This new facility is built into the <code>go</code> tool.
+For now, it is only available on Linux, Mac OS X, and Windows systems with
+64-bit x86 processors.
+To enable it, set the <code>-race</code> flag when building or testing your program
+(for instance, <code>go test -race</code>).
+The race detector is documented in <a href="/doc/articles/race_detector.html">a separate article</a>.
+</p>
+
+<h3 id="gc_asm">The gc assemblers</h3>
+
+<p>
+Due to the change of the <a href="#int"><code>int</code></a> to 64 bits and
+a new internal <a href="//golang.org/s/go11func">representation of functions</a>,
+the arrangement of function arguments on the stack has changed in the gc tool chain.
+Functions written in assembly will need to be revised at least
+to adjust frame pointer offsets.
+</p>
+
+<p>
+<em>Updating</em>:
+The <code>go vet</code> command now checks that functions implemented in assembly
+match the Go function prototypes they implement.
+</p>
+
+<h3 id="gocmd">Changes to the go command</h3>
+
+<p>
+The <a href="/cmd/go/"><code>go</code></a> command has acquired several
+changes intended to improve the experience for new Go users.
+</p>
+
+<p>
+First, when compiling, testing, or running Go code, the <code>go</code> command will now give more detailed error messages,
+including a list of paths searched, when a package cannot be located.
+</p>
+
+<pre>
+$ go build foo/quxx
+can't load package: package foo/quxx: cannot find package "foo/quxx" in any of:
+ /home/you/go/src/pkg/foo/quxx (from $GOROOT)
+ /home/you/src/foo/quxx (from $GOPATH)
+</pre>
+
+<p>
+Second, the <code>go get</code> command no longer allows <code>$GOROOT</code>
+as the default destination when downloading package source.
+To use the <code>go get</code>
+command, a <a href="/doc/code.html#GOPATH">valid <code>$GOPATH</code></a> is now required.
+</p>
+
+<pre>
+$ GOPATH= go get code.google.com/p/foo/quxx
+package code.google.com/p/foo/quxx: cannot download, $GOPATH not set. For more details see: go help gopath
+</pre>
+
+<p>
+Finally, as a result of the previous change, the <code>go get</code> command will also fail
+when <code>$GOPATH</code> and <code>$GOROOT</code> are set to the same value.
+</p>
+
+<pre>
+$ GOPATH=$GOROOT go get code.google.com/p/foo/quxx
+warning: GOPATH set to GOROOT (/home/you/go) has no effect
+package code.google.com/p/foo/quxx: cannot download, $GOPATH must not be set to $GOROOT. For more details see: go help gopath
+</pre>
+
+<h3 id="gotest">Changes to the go test command</h3>
+
+<p>
+The <a href="/cmd/go/#hdr-Test_packages"><code>go test</code></a>
+command no longer deletes the binary when run with profiling enabled,
+to make it easier to analyze the profile.
+The implementation sets the <code>-c</code> flag automatically, so after running,
+</p>
+
+<pre>
+$ go test -cpuprofile cpuprof.out mypackage
+</pre>
+
+<p>
+the file <code>mypackage.test</code> will be left in the directory where <code>go test</code> was run.
+</p>
+
+<p>
+The <a href="/cmd/go/#hdr-Test_packages"><code>go test</code></a>
+command can now generate profiling information
+that reports where goroutines are blocked, that is,
+where they tend to stall waiting for an event such as a channel communication.
+The information is presented as a
+<em>blocking profile</em>
+enabled with the
+<code>-blockprofile</code>
+option of
+<code>go test</code>.
+Run <code>go help test</code> for more information.
+</p>
+
+<h3 id="gofix">Changes to the go fix command</h3>
+
+<p>
+The <a href="/cmd/fix/"><code>fix</code></a> command, usually run as
+<code>go fix</code>, no longer applies fixes to update code from
+before Go 1 to use Go 1 APIs.
+To update pre-Go 1 code to Go 1.1, use a Go 1.0 tool chain
+to convert the code to Go 1.0 first.
+</p>
+
+<h3 id="tags">Build constraints</h3>
+
+<p>
+The "<code>go1.1</code>" tag has been added to the list of default
+<a href="/pkg/go/build/#hdr-Build_Constraints">build constraints</a>.
+This permits packages to take advantage of the new features in Go 1.1 while
+remaining compatible with earlier versions of Go.
+</p>
+
+<p>
+To build a file only with Go 1.1 and above, add this build constraint:
+</p>
+
+<pre>
+// +build go1.1
+</pre>
+
+<p>
+To build a file only with Go 1.0.x, use the converse constraint:
+</p>
+
+<pre>
+// +build !go1.1
+</pre>
+
+<h3 id="platforms">Additional platforms</h3>
+
+<p>
+The Go 1.1 tool chain adds experimental support for <code>freebsd/arm</code>,
+<code>netbsd/386</code>, <code>netbsd/amd64</code>, <code>netbsd/arm</code>,
+<code>openbsd/386</code> and <code>openbsd/amd64</code> platforms.
+</p>
+
+<p>
+An ARMv6 or later processor is required for <code>freebsd/arm</code> or
+<code>netbsd/arm</code>.
+</p>
+
+<p>
+Go 1.1 adds experimental support for <code>cgo</code> on <code>linux/arm</code>.
+</p>
+
+<h3 id="crosscompile">Cross compilation</h3>
+
+<p>
+When cross-compiling, the <code>go</code> tool will disable <code>cgo</code>
+support by default.
+</p>
+
+<p>
+To explicitly enable <code>cgo</code>, set <code>CGO_ENABLED=1</code>.
+</p>
+
+<h2 id="performance">Performance</h2>
+
+<p>
+The performance of code compiled with the Go 1.1 gc tool suite should be noticeably
+better for most Go programs.
+Typical improvements relative to Go 1.0 seem to be about 30%-40%, sometimes
+much more, but occasionally less or even non-existent.
+There are too many small performance-driven tweaks through the tools and libraries
+to list them all here, but the following major changes are worth noting:
+</p>
+
+<ul>
+<li>The gc compilers generate better code in many cases, most noticeably for
+floating point on the 32-bit Intel architecture.</li>
+<li>The gc compilers do more in-lining, including for some operations
+in the run-time such as <a href="/pkg/builtin/#append"><code>append</code></a>
+and interface conversions.</li>
+<li>There is a new implementation of Go maps with significant reduction in
+memory footprint and CPU time.</li>
+<li>The garbage collector has been made more parallel, which can reduce
+latencies for programs running on multiple CPUs.</li>
+<li>The garbage collector is also more precise, which costs a small amount of
+CPU time but can reduce the size of the heap significantly, especially
+on 32-bit architectures.</li>
+<li>Due to tighter coupling of the run-time and network libraries, fewer
+context switches are required on network operations.</li>
+</ul>
+
+<h2 id="library">Changes to the standard library</h2>
+
+<h3 id="bufio_scanner">bufio.Scanner</h3>
+
+<p>
+The various routines to scan textual input in the
+<a href="/pkg/bufio/"><code>bufio</code></a>
+package,
+<a href="/pkg/bufio/#Reader.ReadBytes"><code>ReadBytes</code></a>,
+<a href="/pkg/bufio/#Reader.ReadString"><code>ReadString</code></a>
+and particularly
+<a href="/pkg/bufio/#Reader.ReadLine"><code>ReadLine</code></a>,
+are needlessly complex to use for simple purposes.
+In Go 1.1, a new type,
+<a href="/pkg/bufio/#Scanner"><code>Scanner</code></a>,
+has been added to make it easier to do simple tasks such as
+read the input as a sequence of lines or space-delimited words.
+It simplifies the problem by terminating the scan on problematic
+input such as pathologically long lines, and having a simple
+default: line-oriented input, with each line stripped of its terminator.
+Here is code to reproduce the input a line at a time:
+</p>
+
+<pre>
+scanner := bufio.NewScanner(os.Stdin)
+for scanner.Scan() {
+ fmt.Println(scanner.Text()) // Println will add back the final '\n'
+}
+if err := scanner.Err(); err != nil {
+ fmt.Fprintln(os.Stderr, "reading standard input:", err)
+}
+</pre>
+
+<p>
+Scanning behavior can be adjusted through a function to control subdividing the input
+(see the documentation for <a href="/pkg/bufio/#SplitFunc"><code>SplitFunc</code></a>),
+but for tough problems or the need to continue past errors, the older interface
+may still be required.
+</p>
+
+<h3 id="net">net</h3>
+
+<p>
+The protocol-specific resolvers in the <a href="/pkg/net/"><code>net</code></a> package were formerly
+lax about the network name passed in.
+Although the documentation was clear
+that the only valid networks for
+<a href="/pkg/net/#ResolveTCPAddr"><code>ResolveTCPAddr</code></a>
+are <code>"tcp"</code>,
+<code>"tcp4"</code>, and <code>"tcp6"</code>, the Go 1.0 implementation silently accepted any string.
+The Go 1.1 implementation returns an error if the network is not one of those strings.
+The same is true of the other protocol-specific resolvers <a href="/pkg/net/#ResolveIPAddr"><code>ResolveIPAddr</code></a>,
+<a href="/pkg/net/#ResolveUDPAddr"><code>ResolveUDPAddr</code></a>, and
+<a href="/pkg/net/#ResolveUnixAddr"><code>ResolveUnixAddr</code></a>.
+</p>
+
+<p>
+The previous implementation of
+<a href="/pkg/net/#ListenUnixgram"><code>ListenUnixgram</code></a>
+returned a
+<a href="/pkg/net/#UDPConn"><code>UDPConn</code></a> as
+a representation of the connection endpoint.
+The Go 1.1 implementation instead returns a
+<a href="/pkg/net/#UnixConn"><code>UnixConn</code></a>
+to allow reading and writing
+with its
+<a href="/pkg/net/#UnixConn.ReadFrom"><code>ReadFrom</code></a>
+and
+<a href="/pkg/net/#UnixConn.WriteTo"><code>WriteTo</code></a>
+methods.
+</p>
+
+<p>
+The data structures
+<a href="/pkg/net/#IPAddr"><code>IPAddr</code></a>,
+<a href="/pkg/net/#TCPAddr"><code>TCPAddr</code></a>, and
+<a href="/pkg/net/#UDPAddr"><code>UDPAddr</code></a>
+add a new string field called <code>Zone</code>.
+Code using untagged composite literals (e.g. <code>net.TCPAddr{ip, port}</code>)
+instead of tagged literals (<code>net.TCPAddr{IP: ip, Port: port}</code>)
+will break due to the new field.
+The Go 1 compatibility rules allow this change: client code must use tagged literals to avoid such breakages.
+</p>
+
+<p>
+<em>Updating</em>:
+To correct breakage caused by the new struct field,
+<code>go fix</code> will rewrite code to add tags for these types.
+More generally, <code>go vet</code> will identify composite literals that
+should be revised to use field tags.
+</p>
+
+<h3 id="reflect">reflect</h3>
+
+<p>
+The <a href="/pkg/reflect/"><code>reflect</code></a> package has several significant additions.
+</p>
+
+<p>
+It is now possible to run a "select" statement using
+the <code>reflect</code> package; see the description of
+<a href="/pkg/reflect/#Select"><code>Select</code></a>
+and
+<a href="/pkg/reflect/#SelectCase"><code>SelectCase</code></a>
+for details.
+</p>
+
+<p>
+The new method
+<a href="/pkg/reflect/#Value.Convert"><code>Value.Convert</code></a>
+(or
+<a href="/pkg/reflect/#Type"><code>Type.ConvertibleTo</code></a>)
+provides functionality to execute a Go conversion or type assertion operation
+on a
+<a href="/pkg/reflect/#Value"><code>Value</code></a>
+(or test for its possibility).
+</p>
+
+<p>
+The new function
+<a href="/pkg/reflect/#MakeFunc"><code>MakeFunc</code></a>
+creates a wrapper function to make it easier to call a function with existing
+<a href="/pkg/reflect/#Value"><code>Values</code></a>,
+doing the standard Go conversions among the arguments, for instance
+to pass an actual <code>int</code> to a formal <code>interface{}</code>.
+</p>
+
+<p>
+Finally, the new functions
+<a href="/pkg/reflect/#ChanOf"><code>ChanOf</code></a>,
+<a href="/pkg/reflect/#MapOf"><code>MapOf</code></a>
+and
+<a href="/pkg/reflect/#SliceOf"><code>SliceOf</code></a>
+construct new
+<a href="/pkg/reflect/#Type"><code>Types</code></a>
+from existing types, for example to construct the type <code>[]T</code> given
+only <code>T</code>.
+</p>
+
+
+<h3 id="time">time</h3>
+<p>
+On FreeBSD, Linux, NetBSD, OS X and OpenBSD, previous versions of the
+<a href="/pkg/time/"><code>time</code></a> package
+returned times with microsecond precision.
+The Go 1.1 implementation on these
+systems now returns times with nanosecond precision.
+Programs that write to an external format with microsecond precision
+and read it back, expecting to recover the original value, will be affected
+by the loss of precision.
+There are two new methods of <a href="/pkg/time/#Time"><code>Time</code></a>,
+<a href="/pkg/time/#Time.Round"><code>Round</code></a>
+and
+<a href="/pkg/time/#Time.Truncate"><code>Truncate</code></a>,
+that can be used to remove precision from a time before passing it to
+external storage.
+</p>
+
+<p>
+The new method
+<a href="/pkg/time/#Time.YearDay"><code>YearDay</code></a>
+returns the one-indexed integral day number of the year specified by the time value.
+</p>
+
+<p>
+The
+<a href="/pkg/time/#Timer"><code>Timer</code></a>
+type has a new method
+<a href="/pkg/time/#Timer.Reset"><code>Reset</code></a>
+that modifies the timer to expire after a specified duration.
+</p>
+
+<p>
+Finally, the new function
+<a href="/pkg/time/#ParseInLocation"><code>ParseInLocation</code></a>
+is like the existing
+<a href="/pkg/time/#Parse"><code>Parse</code></a>
+but parses the time in the context of a location (time zone), ignoring
+time zone information in the parsed string.
+This function addresses a common source of confusion in the time API.
+</p>
+
+<p>
+<em>Updating</em>:
+Code that needs to read and write times using an external format with
+lower precision should be modified to use the new methods.
+</p>
+
+<h3 id="exp_old">Exp and old subtrees moved to go.exp and go.text subrepositories</h3>
+
+<p>
+To make it easier for binary distributions to access them if desired, the <code>exp</code>
+and <code>old</code> source subtrees, which are not included in binary distributions,
+have been moved to the new <code>go.exp</code> subrepository at
+<code>code.google.com/p/go.exp</code>. To access the <code>ssa</code> package,
+for example, run
+</p>
+
+<pre>
+$ go get code.google.com/p/go.exp/ssa
+</pre>
+
+<p>
+and then in Go source,
+</p>
+
+<pre>
+import "code.google.com/p/go.exp/ssa"
+</pre>
+
+<p>
+The old package <code>exp/norm</code> has also been moved, but to a new repository
+<code>go.text</code>, where the Unicode APIs and other text-related packages will
+be developed.
+</p>
+
+<h3 id="new_packages">New packages</h3>
+
+<p>
+There are three new packages.
+</p>
+
+<ul>
+<li>
+The <a href="/pkg/go/format/"><code>go/format</code></a> package provides
+a convenient way for a program to access the formatting capabilities of the
+<a href="/cmd/go/#hdr-Run_gofmt_on_package_sources"><code>go fmt</code></a> command.
+It has two functions,
+<a href="/pkg/go/format/#Node"><code>Node</code></a> to format a Go parser
+<a href="/pkg/go/ast/#Node"><code>Node</code></a>,
+and
+<a href="/pkg/go/format/#Source"><code>Source</code></a>
+to reformat arbitrary Go source code into the standard format as provided by the
+<a href="/cmd/go/#hdr-Run_gofmt_on_package_sources"><code>go fmt</code></a> command.
+</li>
+
+<li>
+The <a href="/pkg/net/http/cookiejar/"><code>net/http/cookiejar</code></a> package provides the basics for managing HTTP cookies.
+</li>
+
+<li>
+The <a href="/pkg/runtime/race/"><code>runtime/race</code></a> package provides low-level facilities for data race detection.
+It is internal to the race detector and does not otherwise export any user-visible functionality.
+</li>
+</ul>
+
+<h3 id="minor_library_changes">Minor changes to the library</h3>
+
+<p>
+The following list summarizes a number of minor changes to the library, mostly additions.
+See the relevant package documentation for more information about each change.
+</p>
+
+<ul>
+<li>
+The <a href="/pkg/bytes/"><code>bytes</code></a> package has two new functions,
+<a href="/pkg/bytes/#TrimPrefix"><code>TrimPrefix</code></a>
+and
+<a href="/pkg/bytes/#TrimSuffix"><code>TrimSuffix</code></a>,
+with self-evident properties.
+Also, the <a href="/pkg/bytes/#Buffer"><code>Buffer</code></a> type
+has a new method
+<a href="/pkg/bytes/#Buffer.Grow"><code>Grow</code></a> that
+provides some control over memory allocation inside the buffer.
+Finally, the
+<a href="/pkg/bytes/#Reader"><code>Reader</code></a> type now has a
+<a href="/pkg/strings/#Reader.WriteTo"><code>WriteTo</code></a> method
+so it implements the
+<a href="/pkg/io/#WriterTo"><code>io.WriterTo</code></a> interface.
+</li>
+
+<li>
+The <a href="/pkg/compress/gzip/"><code>compress/gzip</code></a> package has
+a new <a href="/pkg/compress/gzip/#Writer.Flush"><code>Flush</code></a>
+method for its
+<a href="/pkg/compress/gzip/#Writer"><code>Writer</code></a>
+type that flushes its underlying <code>flate.Writer</code>.
+</li>
+
+<li>
+The <a href="/pkg/crypto/hmac/"><code>crypto/hmac</code></a> package has a new function,
+<a href="/pkg/crypto/hmac/#Equal"><code>Equal</code></a>, to compare two MACs.
+</li>
+
+<li>
+The <a href="/pkg/crypto/x509/"><code>crypto/x509</code></a> package
+now supports PEM blocks (see
+<a href="/pkg/crypto/x509/#DecryptPEMBlock"><code>DecryptPEMBlock</code></a> for instance),
+and a new function
+<a href="/pkg/crypto/x509/#ParseECPrivateKey"><code>ParseECPrivateKey</code></a> to parse elliptic curve private keys.
+</li>
+
+<li>
+The <a href="/pkg/database/sql/"><code>database/sql</code></a> package
+has a new
+<a href="/pkg/database/sql/#DB.Ping"><code>Ping</code></a>
+method for its
+<a href="/pkg/database/sql/#DB"><code>DB</code></a>
+type that tests the health of the connection.
+</li>
+
+<li>
+The <a href="/pkg/database/sql/driver/"><code>database/sql/driver</code></a> package
+has a new
+<a href="/pkg/database/sql/driver/#Queryer"><code>Queryer</code></a>
+interface that a
+<a href="/pkg/database/sql/driver/#Conn"><code>Conn</code></a>
+may implement to improve performance.
+</li>
+
+<li>
+The <a href="/pkg/encoding/json/"><code>encoding/json</code></a> package's
+<a href="/pkg/encoding/json/#Decoder"><code>Decoder</code></a>
+has a new method
+<a href="/pkg/encoding/json/#Decoder.Buffered"><code>Buffered</code></a>
+to provide access to the remaining data in its buffer,
+as well as a new method
+<a href="/pkg/encoding/json/#Decoder.UseNumber"><code>UseNumber</code></a>
+to unmarshal a value into the new type
+<a href="/pkg/encoding/json/#Number"><code>Number</code></a>,
+a string, rather than a float64.
+</li>
+
+<li>
+The <a href="/pkg/encoding/xml/"><code>encoding/xml</code></a> package
+has a new function,
+<a href="/pkg/encoding/xml/#EscapeText"><code>EscapeText</code></a>,
+which writes escaped XML output,
+and a method on
+<a href="/pkg/encoding/xml/#Encoder"><code>Encoder</code></a>,
+<a href="/pkg/encoding/xml/#Encoder.Indent"><code>Indent</code></a>,
+to specify indented output.
+</li>
+
+<li>
+In the <a href="/pkg/go/ast/"><code>go/ast</code></a> package, a
+new type <a href="/pkg/go/ast/#CommentMap"><code>CommentMap</code></a>
+and associated methods makes it easier to extract and process comments in Go programs.
+</li>
+
+<li>
+In the <a href="/pkg/go/doc/"><code>go/doc</code></a> package,
+the parser now keeps better track of stylized annotations such as <code>TODO(joe)</code>
+throughout the code,
+information that the <a href="/cmd/godoc/"><code>godoc</code></a>
+command can filter or present according to the value of the <code>-notes</code> flag.
+</li>
+
+<li>
+The undocumented and only partially implemented "noescape" feature of the
+<a href="/pkg/html/template/"><code>html/template</code></a>
+package has been removed; programs that depend on it will break.
+</li>
+
+<li>
+The <a href="/pkg/image/jpeg/"><code>image/jpeg</code></a> package now
+reads progressive JPEG files and handles a few more subsampling configurations.
+</li>
+
+<li>
+The <a href="/pkg/io/"><code>io</code></a> package now exports the
+<a href="/pkg/io/#ByteWriter"><code>io.ByteWriter</code></a> interface to capture the common
+functionality of writing a byte at a time.
+It also exports a new error, <a href="/pkg/io/#ErrNoProgress"><code>ErrNoProgress</code></a>,
+used to indicate a <code>Read</code> implementation is looping without delivering data.
+</li>
+
+<li>
+The <a href="/pkg/log/syslog/"><code>log/syslog</code></a> package now provides better support
+for OS-specific logging features.
+</li>
+
+<li>
+The <a href="/pkg/math/big/"><code>math/big</code></a> package's
+<a href="/pkg/math/big/#Int"><code>Int</code></a> type
+now has methods
+<a href="/pkg/math/big/#Int.MarshalJSON"><code>MarshalJSON</code></a>
+and
+<a href="/pkg/math/big/#Int.UnmarshalJSON"><code>UnmarshalJSON</code></a>
+to convert to and from a JSON representation.
+Also,
+<a href="/pkg/math/big/#Int"><code>Int</code></a>
+can now convert directly to and from a <code>uint64</code> using
+<a href="/pkg/math/big/#Int.Uint64"><code>Uint64</code></a>
+and
+<a href="/pkg/math/big/#Int.SetUint64"><code>SetUint64</code></a>,
+while
+<a href="/pkg/math/big/#Rat"><code>Rat</code></a>
+can do the same with <code>float64</code> using
+<a href="/pkg/math/big/#Rat.Float64"><code>Float64</code></a>
+and
+<a href="/pkg/math/big/#Rat.SetFloat64"><code>SetFloat64</code></a>.
+</li>
+
+<li>
+The <a href="/pkg/mime/multipart/"><code>mime/multipart</code></a> package
+has a new method for its
+<a href="/pkg/mime/multipart/#Writer"><code>Writer</code></a>,
+<a href="/pkg/mime/multipart/#Writer.SetBoundary"><code>SetBoundary</code></a>,
+to define the boundary separator used to package the output.
+The <a href="/pkg/mime/multipart/#Reader"><code>Reader</code></a> also now
+transparently decodes any <code>quoted-printable</code> parts and removes
+the <code>Content-Transfer-Encoding</code> header when doing so.
+</li>
+
+<li>
+The
+<a href="/pkg/net/"><code>net</code></a> package's
+<a href="/pkg/net/#ListenUnixgram"><code>ListenUnixgram</code></a>
+function has changed return types: it now returns a
+<a href="/pkg/net/#UnixConn"><code>UnixConn</code></a>
+rather than a
+<a href="/pkg/net/#UDPConn"><code>UDPConn</code></a>, which was
+clearly a mistake in Go 1.0.
+Since this API change fixes a bug, it is permitted by the Go 1 compatibility rules.
+</li>
+
+<li>
+The <a href="/pkg/net/"><code>net</code></a> package includes a new type,
+<a href="/pkg/net/#Dialer"><code>Dialer</code></a>, to supply options to
+<a href="/pkg/net/#Dialer.Dial"><code>Dial</code></a>.
+</li>
+
+<li>
+The <a href="/pkg/net/"><code>net</code></a> package adds support for
+link-local IPv6 addresses with zone qualifiers, such as <code>fe80::1%lo0</code>.
+The address structures <a href="/pkg/net/#IPAddr"><code>IPAddr</code></a>,
+<a href="/pkg/net/#UDPAddr"><code>UDPAddr</code></a>, and
+<a href="/pkg/net/#TCPAddr"><code>TCPAddr</code></a>
+record the zone in a new field, and functions that expect string forms of these addresses, such as
+<a href="/pkg/net/#Dial"><code>Dial</code></a>,
+<a href="/pkg/net/#ResolveIPAddr"><code>ResolveIPAddr</code></a>,
+<a href="/pkg/net/#ResolveUDPAddr"><code>ResolveUDPAddr</code></a>, and
+<a href="/pkg/net/#ResolveTCPAddr"><code>ResolveTCPAddr</code></a>,
+now accept the zone-qualified form.
+</li>
+
+<li>
+The <a href="/pkg/net/"><code>net</code></a> package adds
+<a href="/pkg/net/#LookupNS"><code>LookupNS</code></a> to its suite of resolving functions.
+<code>LookupNS</code> returns the <a href="/pkg/net/#NS">NS records</a> for a host name.
+</li>
+
+<li>
+The <a href="/pkg/net/"><code>net</code></a> package adds protocol-specific
+packet reading and writing methods to
+<a href="/pkg/net/#IPConn"><code>IPConn</code></a>
+(<a href="/pkg/net/#IPConn.ReadMsgIP"><code>ReadMsgIP</code></a>
+and <a href="/pkg/net/#IPConn.WriteMsgIP"><code>WriteMsgIP</code></a>) and
+<a href="/pkg/net/#UDPConn"><code>UDPConn</code></a>
+(<a href="/pkg/net/#UDPConn.ReadMsgUDP"><code>ReadMsgUDP</code></a> and
+<a href="/pkg/net/#UDPConn.WriteMsgUDP"><code>WriteMsgUDP</code></a>).
+These are specialized versions of <a href="/pkg/net/#PacketConn"><code>PacketConn</code></a>'s
+<code>ReadFrom</code> and <code>WriteTo</code> methods that provide access to out-of-band data associated
+with the packets.
+ </li>
+
+ <li>
+The <a href="/pkg/net/"><code>net</code></a> package adds methods to
+<a href="/pkg/net/#UnixConn"><code>UnixConn</code></a> to allow closing half of the connection
+(<a href="/pkg/net/#UnixConn.CloseRead"><code>CloseRead</code></a> and
+<a href="/pkg/net/#UnixConn.CloseWrite"><code>CloseWrite</code></a>),
+matching the existing methods of <a href="/pkg/net/#TCPConn"><code>TCPConn</code></a>.
+</li>
+
+<li>
+The <a href="/pkg/net/http/"><code>net/http</code></a> package includes several new additions.
+<a href="/pkg/net/http/#ParseTime"><code>ParseTime</code></a> parses a time string, trying
+several common HTTP time formats.
+The <a href="/pkg/net/http/#Request.PostFormValue"><code>PostFormValue</code></a> method of
+<a href="/pkg/net/http/#Request"><code>Request</code></a> is like
+<a href="/pkg/net/http/#Request.FormValue"><code>FormValue</code></a> but ignores URL parameters.
+The <a href="/pkg/net/http/#CloseNotifier"><code>CloseNotifier</code></a> interface provides a mechanism
+for a server handler to discover when a client has disconnected.
+The <code>ServeMux</code> type now has a
+<a href="/pkg/net/http/#ServeMux.Handler"><code>Handler</code></a> method to access a path's
+<code>Handler</code> without executing it.
+The <code>Transport</code> can now cancel an in-flight request with
+<a href="/pkg/net/http/#Transport.CancelRequest"><code>CancelRequest</code></a>.
+Finally, the Transport is now more aggressive at closing TCP connections when
+a <a href="/pkg/net/http/#Response"><code>Response.Body</code></a> is closed before
+being fully consumed.
+</li>
+
+<li>
+The <a href="/pkg/net/mail/"><code>net/mail</code></a> package has two new functions,
+<a href="/pkg/net/mail/#ParseAddress"><code>ParseAddress</code></a> and
+<a href="/pkg/net/mail/#ParseAddressList"><code>ParseAddressList</code></a>,
+to parse RFC 5322-formatted mail addresses into
+<a href="/pkg/net/mail/#Address"><code>Address</code></a> structures.
+</li>
+
+<li>
+The <a href="/pkg/net/smtp/"><code>net/smtp</code></a> package's
+<a href="/pkg/net/smtp/#Client"><code>Client</code></a> type has a new method,
+<a href="/pkg/net/smtp/#Client.Hello"><code>Hello</code></a>,
+which transmits a <code>HELO</code> or <code>EHLO</code> message to the server.
+</li>
+
+<li>
+The <a href="/pkg/net/textproto/"><code>net/textproto</code></a> package
+has two new functions,
+<a href="/pkg/net/textproto/#TrimBytes"><code>TrimBytes</code></a> and
+<a href="/pkg/net/textproto/#TrimString"><code>TrimString</code></a>,
+which do ASCII-only trimming of leading and trailing spaces.
+</li>
+
+<li>
+The new method <a href="/pkg/os/#FileMode.IsRegular"><code>os.FileMode.IsRegular</code></a> makes it easy to ask if a file is a plain file.
+</li>
+
+<li>
+The <a href="/pkg/os/signal/"><code>os/signal</code></a> package has a new function,
+<a href="/pkg/os/signal/#Stop"><code>Stop</code></a>, which stops the package delivering
+any further signals to the channel.
+</li>
+
+<li>
+The <a href="/pkg/regexp/"><code>regexp</code></a> package
+now supports Unix-original leftmost-longest matches through the
+<a href="/pkg/regexp/#Regexp.Longest"><code>Regexp.Longest</code></a>
+method, while
+<a href="/pkg/regexp/#Regexp.Split"><code>Regexp.Split</code></a> slices
+strings into pieces based on separators defined by the regular expression.
+</li>
+
+<li>
+The <a href="/pkg/runtime/debug/"><code>runtime/debug</code></a> package
+has three new functions regarding memory usage.
+The <a href="/pkg/runtime/debug/#FreeOSMemory"><code>FreeOSMemory</code></a>
+function triggers a run of the garbage collector and then attempts to return unused
+memory to the operating system;
+the <a href="/pkg/runtime/debug/#ReadGCStats"><code>ReadGCStats</code></a>
+function retrieves statistics about the collector; and
+<a href="/pkg/runtime/debug/#SetGCPercent"><code>SetGCPercent</code></a>
+provides a programmatic way to control how often the collector runs,
+including disabling it altogether.
+</li>
+
+<li>
+The <a href="/pkg/sort/"><code>sort</code></a> package has a new function,
+<a href="/pkg/sort/#Reverse"><code>Reverse</code></a>.
+Wrapping the argument of a call to
+<a href="/pkg/sort/#Sort"><code>sort.Sort</code></a>
+with a call to <code>Reverse</code> causes the sort order to be reversed.
+</li>
+
+<li>
+The <a href="/pkg/strings/"><code>strings</code></a> package has two new functions,
+<a href="/pkg/strings/#TrimPrefix"><code>TrimPrefix</code></a>
+and
+<a href="/pkg/strings/#TrimSuffix"><code>TrimSuffix</code></a>
+with self-evident properties, and the new method
+<a href="/pkg/strings/#Reader.WriteTo"><code>Reader.WriteTo</code></a> so the
+<a href="/pkg/strings/#Reader"><code>Reader</code></a>
+type now implements the
+<a href="/pkg/io/#WriterTo"><code>io.WriterTo</code></a> interface.
+</li>
+
+<li>
+The <a href="/pkg/syscall/"><code>syscall</code></a> package's
+<a href="/pkg/syscall/#Fchflags"><code>Fchflags</code></a> function on various BSDs
+(including Darwin) has changed signature.
+It now takes an int as the first parameter instead of a string.
+Since this API change fixes a bug, it is permitted by the Go 1 compatibility rules.
+</li>
+<li>
+The <a href="/pkg/syscall/"><code>syscall</code></a> package also has received many updates
+to make it more inclusive of constants and system calls for each supported operating system.
+</li>
+
+<li>
+The <a href="/pkg/testing/"><code>testing</code></a> package now automates the generation of allocation
+statistics in tests and benchmarks using the new
+<a href="/pkg/testing/#AllocsPerRun"><code>AllocsPerRun</code></a> function. And the
+<a href="/pkg/testing/#B.ReportAllocs"><code>ReportAllocs</code></a>
+method on <a href="/pkg/testing/#B"><code>testing.B</code></a> will enable printing of
+memory allocation statistics for the calling benchmark. It also introduces the
+<a href="/pkg/testing/#BenchmarkResult.AllocsPerOp"><code>AllocsPerOp</code></a> method of
+<a href="/pkg/testing/#BenchmarkResult"><code>BenchmarkResult</code></a>.
+There is also a new
+<a href="/pkg/testing/#Verbose"><code>Verbose</code></a> function to test the state of the <code>-v</code>
+command-line flag,
+and a new
+<a href="/pkg/testing/#B.Skip"><code>Skip</code></a> method of
+<a href="/pkg/testing/#B"><code>testing.B</code></a> and
+<a href="/pkg/testing/#T"><code>testing.T</code></a>
+to simplify skipping an inappropriate test.
+</li>
+
+<li>
+In the <a href="/pkg/text/template/"><code>text/template</code></a>
+and
+<a href="/pkg/html/template/"><code>html/template</code></a> packages,
+templates can now use parentheses to group the elements of pipelines, simplifying the construction of complex pipelines.
+Also, as part of the new parser, the
+<a href="/pkg/text/template/parse/#Node"><code>Node</code></a> interface got two new methods to provide
+better error reporting.
+Although this violates the Go 1 compatibility rules,
+no existing code should be affected because this interface is explicitly intended only to be used
+by the
+<a href="/pkg/text/template/"><code>text/template</code></a>
+and
+<a href="/pkg/html/template/"><code>html/template</code></a>
+packages and there are safeguards to guarantee that.
+</li>
+
+<li>
+The implementation of the <a href="/pkg/unicode/"><code>unicode</code></a> package has been updated to Unicode version 6.2.0.
+</li>
+
+<li>
+In the <a href="/pkg/unicode/utf8/"><code>unicode/utf8</code></a> package,
+the new function <a href="/pkg/unicode/utf8/#ValidRune"><code>ValidRune</code></a> reports whether the rune is a valid Unicode code point.
+To be valid, a rune must be in range and not be a surrogate half.
+</li>
+</ul>
diff --git a/doc/go1.2.html b/doc/go1.2.html
new file mode 100644
index 0000000..b9d36f2
--- /dev/null
+++ b/doc/go1.2.html
@@ -0,0 +1,979 @@
+<!--{
+ "Title": "Go 1.2 Release Notes",
+ "Path": "/doc/go1.2",
+ "Template": true
+}-->
+
+<h2 id="introduction">Introduction to Go 1.2</h2>
+
+<p>
+Since the release of <a href="/doc/go1.1.html">Go version 1.1</a> in April, 2013,
+the release schedule has been shortened to make the release process more efficient.
+This release, Go version 1.2 or Go 1.2 for short, arrives roughly six months after 1.1,
+while 1.1 took over a year to appear after 1.0.
+Because of the shorter time scale, 1.2 is a smaller delta than the step from 1.0 to 1.1,
+but it still has some significant developments, including
+a better scheduler and one new language feature.
+Of course, Go 1.2 keeps the <a href="/doc/go1compat.html">promise
+of compatibility</a>.
+The overwhelming majority of programs built with Go 1.1 (or 1.0 for that matter)
+will run without any changes whatsoever when moved to 1.2,
+although the introduction of one restriction
+to a corner of the language may expose already-incorrect code
+(see the discussion of the <a href="#use_of_nil">use of nil</a>).
+</p>
+
+<h2 id="language">Changes to the language</h2>
+
+<p>
+In the interest of firming up the specification, one corner case has been clarified,
+with consequences for programs.
+There is also one new language feature.
+</p>
+
+<h3 id="use_of_nil">Use of nil</h3>
+
+<p>
+The language now specifies that, for safety reasons,
+certain uses of nil pointers are guaranteed to trigger a run-time panic.
+For instance, in Go 1.0, given code like
+</p>
+
+<pre>
+type T struct {
+ X [1<<24]byte
+ Field int32
+}
+
+func main() {
+ var x *T
+ ...
+}
+</pre>
+
+<p>
+the <code>nil</code> pointer <code>x</code> could be used to access memory incorrectly:
+the expression <code>x.Field</code> could access memory at address <code>1<<24</code>.
+To prevent such unsafe behavior, in Go 1.2 the compilers now guarantee that any indirection through
+a nil pointer, such as illustrated here but also in nil pointers to arrays, nil interface values,
+nil slices, and so on, will either panic or return a correct, safe non-nil value.
+In short, any expression that explicitly or implicitly requires evaluation of a nil address is an error.
+The implementation may inject extra tests into the compiled program to enforce this behavior.
+</p>
+
+<p>
+Further details are in the
+<a href="//golang.org/s/go12nil">design document</a>.
+</p>
+
+<p>
+<em>Updating</em>:
+Most code that depended on the old behavior is erroneous and will fail when run.
+Such programs will need to be updated by hand.
+</p>
+
+<h3 id="three_index">Three-index slices</h3>
+
+<p>
+Go 1.2 adds the ability to specify the capacity as well as the length when using a slicing operation
+on an existing array or slice.
+A slicing operation creates a new slice by describing a contiguous section of an already-created array or slice:
+</p>
+
+<pre>
+var array [10]int
+slice := array[2:4]
+</pre>
+
+<p>
+The capacity of the slice is the maximum number of elements that the slice may hold, even after reslicing;
+it reflects the size of the underlying array.
+In this example, the capacity of the <code>slice</code> variable is 8.
+</p>
+
+<p>
+Go 1.2 adds new syntax to allow a slicing operation to specify the capacity as well as the length.
+A second
+colon introduces the capacity value, which must be less than or equal to the capacity of the
+source slice or array, adjusted for the origin. For instance,
+</p>
+
+<pre>
+slice = array[2:4:7]
+</pre>
+
+<p>
+sets the slice to have the same length as in the earlier example but its capacity is now only 5 elements (7-2).
+It is impossible to use this new slice value to access the last three elements of the original array.
+</p>
+
+<p>
+In this three-index notation, a missing first index (<code>[:i:j]</code>) defaults to zero but the other
+two indices must always be specified explicitly.
+It is possible that future releases of Go may introduce default values for these indices.
+</p>
+
+<p>
+Further details are in the
+<a href="//golang.org/s/go12slice">design document</a>.
+</p>
+
+<p>
+<em>Updating</em>:
+This is a backwards-compatible change that affects no existing programs.
+</p>
+
+<h2 id="impl">Changes to the implementations and tools</h2>
+
+<h3 id="preemption">Pre-emption in the scheduler</h3>
+
+<p>
+In prior releases, a goroutine that was looping forever could starve out other
+goroutines on the same thread, a serious problem when GOMAXPROCS
+provided only one user thread.
+In Go 1.2, this is partially addressed: The scheduler is invoked occasionally
+upon entry to a function.
+This means that any loop that includes a (non-inlined) function call can
+be pre-empted, allowing other goroutines to run on the same thread.
+</p>
+
+<h3 id="thread_limit">Limit on the number of threads</h3>
+
+<p>
+Go 1.2 introduces a configurable limit (default 10,000) to the total number of threads
+a single program may have in its address space, to avoid resource starvation
+issues in some environments.
+Note that goroutines are multiplexed onto threads so this limit does not directly
+limit the number of goroutines, only the number that may be simultaneously blocked
+in a system call.
+In practice, the limit is hard to reach.
+</p>
+
+<p>
+The new <a href="/pkg/runtime/debug/#SetMaxThreads"><code>SetMaxThreads</code></a> function in the
+<a href="/pkg/runtime/debug/"><code>runtime/debug</code></a> package controls the thread count limit.
+</p>
+
+<p>
+<em>Updating</em>:
+Few functions will be affected by the limit, but if a program dies because it hits the
+limit, it could be modified to call <code>SetMaxThreads</code> to set a higher count.
+Even better would be to refactor the program to need fewer threads, reducing consumption
+of kernel resources.
+</p>
+
+<h3 id="stack_size">Stack size</h3>
+
+<p>
+In Go 1.2, the minimum size of the stack when a goroutine is created has been lifted from 4KB to 8KB.
+Many programs were suffering performance problems with the old size, which had a tendency
+to introduce expensive stack-segment switching in performance-critical sections.
+The new number was determined by empirical testing.
+</p>
+
+<p>
+At the other end, the new function <a href="/pkg/runtime/debug/#SetMaxStack"><code>SetMaxStack</code></a>
+in the <a href="/pkg/runtime/debug"><code>runtime/debug</code></a> package controls
+the <em>maximum</em> size of a single goroutine's stack.
+The default is 1GB on 64-bit systems and 250MB on 32-bit systems.
+Before Go 1.2, it was too easy for a runaway recursion to consume all the memory on a machine.
+</p>
+
+<p>
+<em>Updating</em>:
+The increased minimum stack size may cause programs with many goroutines to use
+more memory. There is no workaround, but plans for future releases
+include new stack management technology that should address the problem better.
+</p>
+
+<h3 id="cgo_and_cpp">Cgo and C++</h3>
+
+<p>
+The <a href="/cmd/cgo/"><code>cgo</code></a> command will now invoke the C++
+compiler to build any pieces of the linked-to library that are written in C++;
+<a href="/cmd/cgo/">the documentation</a> has more detail.
+</p>
+
+<h3 id="go_tools_godoc">Godoc and vet moved to the go.tools subrepository</h3>
+
+<p>
+Both binaries are still included with the distribution, but the source code for the
+godoc and vet commands has moved to the
+<a href="//code.google.com/p/go.tools">go.tools</a> subrepository.
+</p>
+
+<p>
+Also, the core of the godoc program has been split into a
+<a href="https://code.google.com/p/go/source/browse/?repo=tools#hg%2Fgodoc">library</a>,
+while the command itself is in a separate
+<a href="https://code.google.com/p/go/source/browse/?repo=tools#hg%2Fcmd%2Fgodoc">directory</a>.
+The move allows the code to be updated easily and the separation into a library and command
+makes it easier to construct custom binaries for local sites and different deployment methods.
+</p>
+
+<p>
+<em>Updating</em>:
+Since godoc and vet are not part of the library,
+no client Go code depends on the their source and no updating is required.
+</p>
+
+<p>
+The binary distributions available from <a href="//golang.org">golang.org</a>
+include these binaries, so users of these distributions are unaffected.
+</p>
+
+<p>
+When building from source, users must use "go get" to install godoc and vet.
+(The binaries will continue to be installed in their usual locations, not
+<code>$GOPATH/bin</code>.)
+</p>
+
+<pre>
+$ go get code.google.com/p/go.tools/cmd/godoc
+$ go get code.google.com/p/go.tools/cmd/vet
+</pre>
+
+<h3 id="gccgo">Status of gccgo</h3>
+
+<p>
+We expect the future GCC 4.9 release to include gccgo with full
+support for Go 1.2.
+In the current (4.8.2) release of GCC, gccgo implements Go 1.1.2.
+</p>
+
+<h3 id="gc_changes">Changes to the gc compiler and linker</h3>
+
+<p>
+Go 1.2 has several semantic changes to the workings of the gc compiler suite.
+Most users will be unaffected by them.
+</p>
+
+<p>
+The <a href="/cmd/cgo/"><code>cgo</code></a> command now
+works when C++ is included in the library being linked against.
+See the <a href="/cmd/cgo/"><code>cgo</code></a> documentation
+for details.
+</p>
+
+<p>
+The gc compiler displayed a vestigial detail of its origins when
+a program had no <code>package</code> clause: it assumed
+the file was in package <code>main</code>.
+The past has been erased, and a missing <code>package</code> clause
+is now an error.
+</p>
+
+<p>
+On the ARM, the toolchain supports "external linking", which
+is a step towards being able to build shared libraries with the gc
+tool chain and to provide dynamic linking support for environments
+in which that is necessary.
+</p>
+
+<p>
+In the runtime for the ARM, with <code>5a</code>, it used to be possible to refer
+to the runtime-internal <code>m</code> (machine) and <code>g</code>
+(goroutine) variables using <code>R9</code> and <code>R10</code> directly.
+It is now necessary to refer to them by their proper names.
+</p>
+
+<p>
+Also on the ARM, the <code>5l</code> linker (sic) now defines the
+<code>MOVBS</code> and <code>MOVHS</code> instructions
+as synonyms of <code>MOVB</code> and <code>MOVH</code>,
+to make clearer the separation between signed and unsigned
+sub-word moves; the unsigned versions already existed with a
+<code>U</code> suffix.
+</p>
+
+<h3 id="cover">Test coverage</h3>
+
+<p>
+One major new feature of <a href="/pkg/go/"><code>go test</code></a> is
+that it can now compute and, with help from a new, separately installed
+"go tool cover" program, display test coverage results.
+</p>
+
+<p>
+The cover tool is part of the
+<a href="https://code.google.com/p/go/source/checkout?repo=tools"><code>go.tools</code></a>
+subrepository.
+It can be installed by running
+</p>
+
+<pre>
+$ go get code.google.com/p/go.tools/cmd/cover
+</pre>
+
+<p>
+The cover tool does two things.
+First, when "go test" is given the <code>-cover</code> flag, it is run automatically
+to rewrite the source for the package and insert instrumentation statements.
+The test is then compiled and run as usual, and basic coverage statistics are reported:
+</p>
+
+<pre>
+$ go test -cover fmt
+ok fmt 0.060s coverage: 91.4% of statements
+$
+</pre>
+
+<p>
+Second, for more detailed reports, different flags to "go test" can create a coverage profile file,
+which the cover program, invoked with "go tool cover", can then analyze.
+</p>
+
+<p>
+Details on how to generate and analyze coverage statistics can be found by running the commands
+</p>
+
+<pre>
+$ go help testflag
+$ go tool cover -help
+</pre>
+
+<h3 id="go_doc">The go doc command is deleted</h3>
+
+<p>
+The "go doc" command is deleted.
+Note that the <a href="/cmd/godoc/"><code>godoc</code></a> tool itself is not deleted,
+just the wrapping of it by the <a href="/cmd/go/"><code>go</code></a> command.
+All it did was show the documents for a package by package path,
+which godoc itself already does with more flexibility.
+It has therefore been deleted to reduce the number of documentation tools and,
+as part of the restructuring of godoc, encourage better options in future.
+</p>
+
+<p>
+<em>Updating</em>: For those who still need the precise functionality of running
+</p>
+
+<pre>
+$ go doc
+</pre>
+
+<p>
+in a directory, the behavior is identical to running
+</p>
+
+<pre>
+$ godoc .
+</pre>
+
+<h3 id="gocmd">Changes to the go command</h3>
+
+<p>
+The <a href="/cmd/go/"><code>go get</code></a> command
+now has a <code>-t</code> flag that causes it to download the dependencies
+of the tests run by the package, not just those of the package itself.
+By default, as before, dependencies of the tests are not downloaded.
+</p>
+
+<h2 id="performance">Performance</h2>
+
+<p>
+There are a number of significant performance improvements in the standard library; here are a few of them.
+</p>
+
+<ul>
+
+<li>
+The <a href="/pkg/compress/bzip2/"><code>compress/bzip2</code></a>
+decompresses about 30% faster.
+</li>
+
+<li>
+The <a href="/pkg/crypto/des/"><code>crypto/des</code></a> package
+is about five times faster.
+</li>
+
+<li>
+The <a href="/pkg/encoding/json/"><code>encoding/json</code></a> package
+encodes about 30% faster.
+</li>
+
+<li>
+Networking performance on Windows and BSD systems is about 30% faster through the use
+of an integrated network poller in the runtime, similar to what was done for Linux and OS X
+in Go 1.1.
+</li>
+
+</ul>
+
+<h2 id="library">Changes to the standard library</h2>
+
+
+<h3 id="archive_tar_zip">The archive/tar and archive/zip packages</h3>
+
+<p>
+The
+<a href="/pkg/archive/tar/"><code>archive/tar</code></a>
+and
+<a href="/pkg/archive/zip/"><code>archive/zip</code></a>
+packages have had a change to their semantics that may break existing programs.
+The issue is that they both provided an implementation of the
+<a href="/pkg/os/#FileInfo"><code>os.FileInfo</code></a>
+interface that was not compliant with the specification for that interface.
+In particular, their <code>Name</code> method returned the full
+path name of the entry, but the interface specification requires that
+the method return only the base name (final path element).
+</p>
+
+<p>
+<em>Updating</em>: Since this behavior was newly implemented and
+a bit obscure, it is possible that no code depends on the broken behavior.
+If there are programs that do depend on it, they will need to be identified
+and fixed manually.
+</p>
+
+<h3 id="encoding">The new encoding package</h3>
+
+<p>
+There is a new package, <a href="/pkg/encoding/"><code>encoding</code></a>,
+that defines a set of standard encoding interfaces that may be used to
+build custom marshalers and unmarshalers for packages such as
+<a href="/pkg/encoding/xml/"><code>encoding/xml</code></a>,
+<a href="/pkg/encoding/json/"><code>encoding/json</code></a>,
+and
+<a href="/pkg/encoding/binary/"><code>encoding/binary</code></a>.
+These new interfaces have been used to tidy up some implementations in
+the standard library.
+</p>
+
+<p>
+The new interfaces are called
+<a href="/pkg/encoding/#BinaryMarshaler"><code>BinaryMarshaler</code></a>,
+<a href="/pkg/encoding/#BinaryUnmarshaler"><code>BinaryUnmarshaler</code></a>,
+<a href="/pkg/encoding/#TextMarshaler"><code>TextMarshaler</code></a>,
+and
+<a href="/pkg/encoding/#TextUnmarshaler"><code>TextUnmarshaler</code></a>.
+Full details are in the <a href="/pkg/encoding/">documentation</a> for the package
+and a separate <a href="//golang.org/s/go12encoding">design document</a>.
+</p>
+
+<h3 id="fmt_indexed_arguments">The fmt package</h3>
+
+<p>
+The <a href="/pkg/fmt/"><code>fmt</code></a> package's formatted print
+routines such as <a href="/pkg/fmt/#Printf"><code>Printf</code></a>
+now allow the data items to be printed to be accessed in arbitrary order
+by using an indexing operation in the formatting specifications.
+Wherever an argument is to be fetched from the argument list for formatting,
+either as the value to be formatted or as a width or specification integer,
+a new optional indexing notation <code>[</code><em>n</em><code>]</code>
+fetches argument <em>n</em> instead.
+The value of <em>n</em> is 1-indexed.
+After such an indexing operating, the next argument to be fetched by normal
+processing will be <em>n</em>+1.
+</p>
+
+<p>
+For example, the normal <code>Printf</code> call
+</p>
+
+<pre>
+fmt.Sprintf("%c %c %c\n", 'a', 'b', 'c')
+</pre>
+
+<p>
+would create the string <code>"a b c"</code>, but with indexing operations like this,
+</p>
+
+<pre>
+fmt.Sprintf("%[3]c %[1]c %c\n", 'a', 'b', 'c')
+</pre>
+
+<p>
+the result is "<code>"c a b"</code>. The <code>[3]</code> index accesses the third formatting
+argument, which is <code>'c'</code>, <code>[1]</code> accesses the first, <code>'a'</code>,
+and then the next fetch accesses the argument following that one, <code>'b'</code>.
+</p>
+
+<p>
+The motivation for this feature is programmable format statements to access
+the arguments in different order for localization, but it has other uses:
+</p>
+
+<pre>
+log.Printf("trace: value %v of type %[1]T\n", expensiveFunction(a.b[c]))
+</pre>
+
+<p>
+<em>Updating</em>: The change to the syntax of format specifications
+is strictly backwards compatible, so it affects no working programs.
+</p>
+
+<h3 id="text_template">The text/template and html/template packages</h3>
+
+<p>
+The
+<a href="/pkg/text/template/"><code>text/template</code></a> package
+has a couple of changes in Go 1.2, both of which are also mirrored in the
+<a href="/pkg/html/template/"><code>html/template</code></a> package.
+</p>
+
+<p>
+First, there are new default functions for comparing basic types.
+The functions are listed in this table, which shows their names and
+the associated familiar comparison operator.
+</p>
+
+<table cellpadding="0" summary="Template comparison functions">
+<tr>
+<th width="50"></th><th width="100">Name</th> <th width="50">Operator</th>
+</tr>
+<tr>
+<td></td><td><code>eq</code></td> <td><code>==</code></td>
+</tr>
+<tr>
+<td></td><td><code>ne</code></td> <td><code>!=</code></td>
+</tr>
+<tr>
+<td></td><td><code>lt</code></td> <td><code><</code></td>
+</tr>
+<tr>
+<td></td><td><code>le</code></td> <td><code><=</code></td>
+</tr>
+<tr>
+<td></td><td><code>gt</code></td> <td><code>></code></td>
+</tr>
+<tr>
+<td></td><td><code>ge</code></td> <td><code>>=</code></td>
+</tr>
+</table>
+
+<p>
+These functions behave slightly differently from the corresponding Go operators.
+First, they operate only on basic types (<code>bool</code>, <code>int</code>,
+<code>float64</code>, <code>string</code>, etc.).
+(Go allows comparison of arrays and structs as well, under some circumstances.)
+Second, values can be compared as long as they are the same sort of value:
+any signed integer value can be compared to any other signed integer value for example. (Go
+does not permit comparing an <code>int8</code> and an <code>int16</code>).
+Finally, the <code>eq</code> function (only) allows comparison of the first
+argument with one or more following arguments. The template in this example,
+</p>
+
+<pre>
+{{"{{"}}if eq .A 1 2 3 {{"}}"}} equal {{"{{"}}else{{"}}"}} not equal {{"{{"}}end{{"}}"}}
+</pre>
+
+<p>
+reports "equal" if <code>.A</code> is equal to <em>any</em> of 1, 2, or 3.
+</p>
+
+<p>
+The second change is that a small addition to the grammar makes "if else if" chains easier to write.
+Instead of writing,
+</p>
+
+<pre>
+{{"{{"}}if eq .A 1{{"}}"}} X {{"{{"}}else{{"}}"}} {{"{{"}}if eq .A 2{{"}}"}} Y {{"{{"}}end{{"}}"}} {{"{{"}}end{{"}}"}}
+</pre>
+
+<p>
+one can fold the second "if" into the "else" and have only one "end", like this:
+</p>
+
+<pre>
+{{"{{"}}if eq .A 1{{"}}"}} X {{"{{"}}else if eq .A 2{{"}}"}} Y {{"{{"}}end{{"}}"}}
+</pre>
+
+<p>
+The two forms are identical in effect; the difference is just in the syntax.
+</p>
+
+<p>
+<em>Updating</em>: Neither the "else if" change nor the comparison functions
+affect existing programs. Those that
+already define functions called <code>eq</code> and so on through a function
+map are unaffected because the associated function map will override the new
+default function definitions.
+</p>
+
+<h3 id="new_packages">New packages</h3>
+
+<p>
+There are two new packages.
+</p>
+
+<ul>
+<li>
+The <a href="/pkg/encoding/"><code>encoding</code></a> package is
+<a href="#encoding">described above</a>.
+</li>
+<li>
+The <a href="/pkg/image/color/palette/"><code>image/color/palette</code></a> package
+provides standard color palettes.
+</li>
+</ul>
+
+<h3 id="minor_library_changes">Minor changes to the library</h3>
+
+<p>
+The following list summarizes a number of minor changes to the library, mostly additions.
+See the relevant package documentation for more information about each change.
+</p>
+
+<ul>
+
+<li>
+The <a href="/pkg/archive/zip/"><code>archive/zip</code></a> package
+adds the
+<a href="/pkg/archive/zip/#File.DataOffset"><code>DataOffset</code></a> accessor
+to return the offset of a file's (possibly compressed) data within the archive.
+</li>
+
+<li>
+The <a href="/pkg/bufio/"><code>bufio</code></a> package
+adds <a href="/pkg/bufio/#Reader.Reset"><code>Reset</code></a>
+methods to <a href="/pkg/bufio/#Reader"><code>Reader</code></a> and
+<a href="/pkg/bufio/#Writer"><code>Writer</code></a>.
+These methods allow the <a href="/pkg/io/#Reader"><code>Readers</code></a>
+and <a href="/pkg/io/#Writer"><code>Writers</code></a>
+to be re-used on new input and output readers and writers, saving
+allocation overhead.
+</li>
+
+<li>
+The <a href="/pkg/compress/bzip2/"><code>compress/bzip2</code></a>
+can now decompress concatenated archives.
+</li>
+
+<li>
+The <a href="/pkg/compress/flate/"><code>compress/flate</code></a>
+package adds a <a href="/pkg/compress/flate/#Writer.Reset"><code>Reset</code></a>
+method on the <a href="/pkg/compress/flate/#Writer"><code>Writer</code></a>,
+to make it possible to reduce allocation when, for instance, constructing an
+archive to hold multiple compressed files.
+</li>
+
+<li>
+The <a href="/pkg/compress/gzip/"><code>compress/gzip</code></a> package's
+<a href="/pkg/compress/gzip/#Writer"><code>Writer</code></a> type adds a
+<a href="/pkg/compress/gzip/#Writer.Reset"><code>Reset</code></a>
+so it may be reused.
+</li>
+
+<li>
+The <a href="/pkg/compress/zlib/"><code>compress/zlib</code></a> package's
+<a href="/pkg/compress/zlib/#Writer"><code>Writer</code></a> type adds a
+<a href="/pkg/compress/zlib/#Writer.Reset"><code>Reset</code></a>
+so it may be reused.
+</li>
+
+<li>
+The <a href="/pkg/container/heap/"><code>container/heap</code></a> package
+adds a <a href="/pkg/container/heap/#Fix"><code>Fix</code></a>
+method to provide a more efficient way to update an item's position in the heap.
+</li>
+
+<li>
+The <a href="/pkg/container/list/"><code>container/list</code></a> package
+adds the <a href="/pkg/container/list/#List.MoveBefore"><code>MoveBefore</code></a>
+and
+<a href="/pkg/container/list/#List.MoveAfter"><code>MoveAfter</code></a>
+methods, which implement the obvious rearrangement.
+</li>
+
+<li>
+The <a href="/pkg/crypto/cipher/"><code>crypto/cipher</code></a> package
+adds the a new GCM mode (Galois Counter Mode), which is almost always
+used with AES encryption.
+</li>
+
+<li>
+The
+<a href="/pkg/crypto/md5/"><code>crypto/md5</code></a> package
+adds a new <a href="/pkg/crypto/md5/#Sum"><code>Sum</code></a> function
+to simplify hashing without sacrificing performance.
+</li>
+
+<li>
+Similarly, the
+<a href="/pkg/crypto/md5/"><code>crypto/sha1</code></a> package
+adds a new <a href="/pkg/crypto/sha1/#Sum"><code>Sum</code></a> function.
+</li>
+
+<li>
+Also, the
+<a href="/pkg/crypto/sha256/"><code>crypto/sha256</code></a> package
+adds <a href="/pkg/crypto/sha256/#Sum256"><code>Sum256</code></a>
+and <a href="/pkg/crypto/sha256/#Sum224"><code>Sum224</code></a> functions.
+</li>
+
+<li>
+Finally, the <a href="/pkg/crypto/sha512/"><code>crypto/sha512</code></a> package
+adds <a href="/pkg/crypto/sha512/#Sum512"><code>Sum512</code></a> and
+<a href="/pkg/crypto/sha512/#Sum384"><code>Sum384</code></a> functions.
+</li>
+
+<li>
+The <a href="/pkg/crypto/x509/"><code>crypto/x509</code></a> package
+adds support for reading and writing arbitrary extensions.
+</li>
+
+<li>
+The <a href="/pkg/crypto/tls/"><code>crypto/tls</code></a> package adds
+support for TLS 1.1, 1.2 and AES-GCM.
+</li>
+
+<li>
+The <a href="/pkg/database/sql/"><code>database/sql</code></a> package adds a
+<a href="/pkg/database/sql/#DB.SetMaxOpenConns"><code>SetMaxOpenConns</code></a>
+method on <a href="/pkg/database/sql/#DB"><code>DB</code></a> to limit the
+number of open connections to the database.
+</li>
+
+<li>
+The <a href="/pkg/encoding/csv/"><code>encoding/csv</code></a> package
+now always allows trailing commas on fields.
+</li>
+
+<li>
+The <a href="/pkg/encoding/gob/"><code>encoding/gob</code></a> package
+now treats channel and function fields of structures as if they were unexported,
+even if they are not. That is, it ignores them completely. Previously they would
+trigger an error, which could cause unexpected compatibility problems if an
+embedded structure added such a field.
+The package also now supports the generic <code>BinaryMarshaler</code> and
+<code>BinaryUnmarshaler</code> interfaces of the
+<a href="/pkg/encoding/"><code>encoding</code></a> package
+described above.
+</li>
+
+<li>
+The <a href="/pkg/encoding/json/"><code>encoding/json</code></a> package
+now will always escape ampersands as "\u0026" when printing strings.
+It will now accept but correct invalid UTF-8 in
+<a href="/pkg/encoding/json/#Marshal"><code>Marshal</code></a>
+(such input was previously rejected).
+Finally, it now supports the generic encoding interfaces of the
+<a href="/pkg/encoding/"><code>encoding</code></a> package
+described above.
+</li>
+
+<li>
+The <a href="/pkg/encoding/xml/"><code>encoding/xml</code></a> package
+now allows attributes stored in pointers to be marshaled.
+It also supports the generic encoding interfaces of the
+<a href="/pkg/encoding/"><code>encoding</code></a> package
+described above through the new
+<a href="/pkg/encoding/xml/#Marshaler"><code>Marshaler</code></a>,
+<a href="/pkg/encoding/xml/#Unmarshaler"><code>Unmarshaler</code></a>,
+and related
+<a href="/pkg/encoding/xml/#MarshalerAttr"><code>MarshalerAttr</code></a> and
+<a href="/pkg/encoding/xml/#UnmarshalerAttr"><code>UnmarshalerAttr</code></a>
+interfaces.
+The package also adds a
+<a href="/pkg/encoding/xml/#Encoder.Flush"><code>Flush</code></a> method
+to the
+<a href="/pkg/encoding/xml/#Encoder"><code>Encoder</code></a>
+type for use by custom encoders. See the documentation for
+<a href="/pkg/encoding/xml/#Encoder.EncodeToken"><code>EncodeToken</code></a>
+to see how to use it.
+</li>
+
+<li>
+The <a href="/pkg/flag/"><code>flag</code></a> package now
+has a <a href="/pkg/flag/#Getter"><code>Getter</code></a> interface
+to allow the value of a flag to be retrieved. Due to the
+Go 1 compatibility guidelines, this method cannot be added to the existing
+<a href="/pkg/flag/#Value"><code>Value</code></a>
+interface, but all the existing standard flag types implement it.
+The package also now exports the <a href="/pkg/flag/#CommandLine"><code>CommandLine</code></a>
+flag set, which holds the flags from the command line.
+</li>
+
+<li>
+The <a href="/pkg/go/ast/"><code>go/ast</code></a> package's
+<a href="/pkg/go/ast/#SliceExpr"><code>SliceExpr</code></a> struct
+has a new boolean field, <code>Slice3</code>, which is set to true
+when representing a slice expression with three indices (two colons).
+The default is false, representing the usual two-index form.
+</li>
+
+<li>
+The <a href="/pkg/go/build/"><code>go/build</code></a> package adds
+the <code>AllTags</code> field
+to the <a href="/pkg/go/build/#Package"><code>Package</code></a> type,
+to make it easier to process build tags.
+</li>
+
+<li>
+The <a href="/pkg/image/draw/"><code>image/draw</code></a> package now
+exports an interface, <a href="/pkg/image/draw/#Drawer"><code>Drawer</code></a>,
+that wraps the standard <a href="/pkg/image/draw/#Draw"><code>Draw</code></a> method.
+The Porter-Duff operators now implement this interface, in effect binding an operation to
+the draw operator rather than providing it explicitly.
+Given a paletted image as its destination, the new
+<a href="/pkg/image/draw/#FloydSteinberg"><code>FloydSteinberg</code></a>
+implementation of the
+<a href="/pkg/image/draw/#Drawer"><code>Drawer</code></a>
+interface will use the Floyd-Steinberg error diffusion algorithm to draw the image.
+To create palettes suitable for such processing, the new
+<a href="/pkg/image/draw/#Quantizer"><code>Quantizer</code></a> interface
+represents implementations of quantization algorithms that choose a palette
+given a full-color image.
+There are no implementations of this interface in the library.
+</li>
+
+<li>
+The <a href="/pkg/image/gif/"><code>image/gif</code></a> package
+can now create GIF files using the new
+<a href="/pkg/image/gif/#Encode"><code>Encode</code></a>
+and <a href="/pkg/image/gif/#EncodeAll"><code>EncodeAll</code></a>
+functions.
+Their options argument allows specification of an image
+<a href="/pkg/image/draw/#Quantizer"><code>Quantizer</code></a> to use;
+if it is <code>nil</code>, the generated GIF will use the
+<a href="/pkg/image/color/palette/#Plan9"><code>Plan9</code></a>
+color map (palette) defined in the new
+<a href="/pkg/image/color/palette/"><code>image/color/palette</code></a> package.
+The options also specify a
+<a href="/pkg/image/draw/#Drawer"><code>Drawer</code></a>
+to use to create the output image;
+if it is <code>nil</code>, Floyd-Steinberg error diffusion is used.
+</li>
+
+<li>
+The <a href="/pkg/io/#Copy"><code>Copy</code></a> method of the
+<a href="/pkg/io/"><code>io</code></a> package now prioritizes its
+arguments differently.
+If one argument implements <a href="/pkg/io/#WriterTo"><code>WriterTo</code></a>
+and the other implements <a href="/pkg/io/#ReaderFrom"><code>ReaderFrom</code></a>,
+<a href="/pkg/io/#Copy"><code>Copy</code></a> will now invoke
+<a href="/pkg/io/#WriterTo"><code>WriterTo</code></a> to do the work,
+so that less intermediate buffering is required in general.
+</li>
+
+<li>
+The <a href="/pkg/net/"><code>net</code></a> package requires cgo by default
+because the host operating system must in general mediate network call setup.
+On some systems, though, it is possible to use the network without cgo, and useful
+to do so, for instance to avoid dynamic linking.
+The new build tag <code>netgo</code> (off by default) allows the construction of a
+<code>net</code> package in pure Go on those systems where it is possible.
+</li>
+
+<li>
+The <a href="/pkg/net/"><code>net</code></a> package adds a new field
+<code>DualStack</code> to the <a href="/pkg/net/#Dialer"><code>Dialer</code></a>
+struct for TCP connection setup using a dual IP stack as described in
+<a href="http://tools.ietf.org/html/rfc6555">RFC 6555</a>.
+</li>
+
+<li>
+The <a href="/pkg/net/http/"><code>net/http</code></a> package will no longer
+transmit cookies that are incorrect according to
+<a href="http://tools.ietf.org/html/rfc6265">RFC 6265</a>.
+It just logs an error and sends nothing.
+Also,
+the <a href="/pkg/net/http/"><code>net/http</code></a> package's
+<a href="/pkg/net/http/#ReadResponse"><code>ReadResponse</code></a>
+function now permits the <code>*Request</code> parameter to be <code>nil</code>,
+whereupon it assumes a GET request.
+Finally, an HTTP server will now serve HEAD
+requests transparently, without the need for special casing in handler code.
+While serving a HEAD request, writes to a
+<a href="/pkg/net/http/#Handler"><code>Handler</code></a>'s
+<a href="/pkg/net/http/#ResponseWriter"><code>ResponseWriter</code></a>
+are absorbed by the
+<a href="/pkg/net/http/#Server"><code>Server</code></a>
+and the client receives an empty body as required by the HTTP specification.
+</li>
+
+<li>
+The <a href="/pkg/os/exec/"><code>os/exec</code></a> package's
+<a href="/pkg/os/exec/#Cmd.StdinPipe"><code>Cmd.StdinPipe</code></a> method
+returns an <code>io.WriteCloser</code>, but has changed its concrete
+implementation from <code>*os.File</code> to an unexported type that embeds
+<code>*os.File</code>, and it is now safe to close the returned value.
+Before Go 1.2, there was an unavoidable race that this change fixes.
+Code that needs access to the methods of <code>*os.File</code> can use an
+interface type assertion, such as <code>wc.(interface{ Sync() error })</code>.
+</li>
+
+<li>
+The <a href="/pkg/runtime/"><code>runtime</code></a> package relaxes
+the constraints on finalizer functions in
+<a href="/pkg/runtime/#SetFinalizer"><code>SetFinalizer</code></a>: the
+actual argument can now be any type that is assignable to the formal type of
+the function, as is the case for any normal function call in Go.
+</li>
+
+<li>
+The <a href="/pkg/sort/"><code>sort</code></a> package has a new
+<a href="/pkg/sort/#Stable"><code>Stable</code></a> function that implements
+stable sorting. It is less efficient than the normal sort algorithm, however.
+</li>
+
+<li>
+The <a href="/pkg/strings/"><code>strings</code></a> package adds
+an <a href="/pkg/strings/#IndexByte"><code>IndexByte</code></a>
+function for consistency with the <a href="/pkg/bytes/"><code>bytes</code></a> package.
+</li>
+
+<li>
+The <a href="/pkg/sync/atomic/"><code>sync/atomic</code></a> package
+adds a new set of swap functions that atomically exchange the argument with the
+value stored in the pointer, returning the old value.
+The functions are
+<a href="/pkg/sync/atomic/#SwapInt32"><code>SwapInt32</code></a>,
+<a href="/pkg/sync/atomic/#SwapInt64"><code>SwapInt64</code></a>,
+<a href="/pkg/sync/atomic/#SwapUint32"><code>SwapUint32</code></a>,
+<a href="/pkg/sync/atomic/#SwapUint64"><code>SwapUint64</code></a>,
+<a href="/pkg/sync/atomic/#SwapUintptr"><code>SwapUintptr</code></a>,
+and
+<a href="/pkg/sync/atomic/#SwapPointer"><code>SwapPointer</code></a>,
+which swaps an <code>unsafe.Pointer</code>.
+</li>
+
+<li>
+The <a href="/pkg/syscall/"><code>syscall</code></a> package now implements
+<a href="/pkg/syscall/#Sendfile"><code>Sendfile</code></a> for Darwin.
+</li>
+
+<li>
+The <a href="/pkg/testing/"><code>testing</code></a> package
+now exports the <a href="/pkg/testing/#TB"><code>TB</code></a> interface.
+It records the methods in common with the
+<a href="/pkg/testing/#T"><code>T</code></a>
+and
+<a href="/pkg/testing/#B"><code>B</code></a> types,
+to make it easier to share code between tests and benchmarks.
+Also, the
+<a href="/pkg/testing/#AllocsPerRun"><code>AllocsPerRun</code></a>
+function now quantizes the return value to an integer (although it
+still has type <code>float64</code>), to round off any error caused by
+initialization and make the result more repeatable.
+</li>
+
+<li>
+The <a href="/pkg/text/template/"><code>text/template</code></a> package
+now automatically dereferences pointer values when evaluating the arguments
+to "escape" functions such as "html", to bring the behavior of such functions
+in agreement with that of other printing functions such as "printf".
+</li>
+
+<li>
+In the <a href="/pkg/time/"><code>time</code></a> package, the
+<a href="/pkg/time/#Parse"><code>Parse</code></a> function
+and
+<a href="/pkg/time/#Time.Format"><code>Format</code></a>
+method
+now handle time zone offsets with seconds, such as in the historical
+date "1871-01-01T05:33:02+00:34:08".
+Also, pattern matching in the formats for those routines is stricter: a non-lowercase letter
+must now follow the standard words such as "Jan" and "Mon".
+</li>
+
+<li>
+The <a href="/pkg/unicode/"><code>unicode</code></a> package
+adds <a href="/pkg/unicode/#In"><code>In</code></a>,
+a nicer-to-use but equivalent version of the original
+<a href="/pkg/unicode/#IsOneOf"><code>IsOneOf</code></a>,
+to see whether a character is a member of a Unicode category.
+</li>
+
+</ul>
diff --git a/doc/go1.3.html b/doc/go1.3.html
new file mode 100644
index 0000000..d51052b
--- /dev/null
+++ b/doc/go1.3.html
@@ -0,0 +1,608 @@
+<!--{
+ "Title": "Go 1.3 Release Notes",
+ "Path": "/doc/go1.3",
+ "Template": true
+}-->
+
+<h2 id="introduction">Introduction to Go 1.3</h2>
+
+<p>
+The latest Go release, version 1.3, arrives six months after 1.2,
+and contains no language changes.
+It focuses primarily on implementation work, providing
+precise garbage collection,
+a major refactoring of the compiler tool chain that results in
+faster builds, especially for large projects,
+significant performance improvements across the board,
+and support for DragonFly BSD, Solaris, Plan 9 and Google's Native Client architecture (NaCl).
+It also has an important refinement to the memory model regarding synchronization.
+As always, Go 1.3 keeps the <a href="/doc/go1compat.html">promise
+of compatibility</a>,
+and almost everything
+will continue to compile and run without change when moved to 1.3.
+</p>
+
+<h2 id="os">Changes to the supported operating systems and architectures</h2>
+
+<h3 id="win2000">Removal of support for Windows 2000</h3>
+
+<p>
+Microsoft stopped supporting Windows 2000 in 2010.
+Since it has <a href="https://codereview.appspot.com/74790043">implementation difficulties</a>
+regarding exception handling (signals in Unix terminology),
+as of Go 1.3 it is not supported by Go either.
+</p>
+
+<h3 id="dragonfly">Support for DragonFly BSD</h3>
+
+<p>
+Go 1.3 now includes experimental support for DragonFly BSD on the <code>amd64</code> (64-bit x86) and <code>386</code> (32-bit x86) architectures.
+It uses DragonFly BSD 3.6 or above.
+</p>
+
+<h3 id="freebsd">Support for FreeBSD</h3>
+
+<p>
+It was not announced at the time, but since the release of Go 1.2, support for Go on FreeBSD
+requires FreeBSD 8 or above.
+</p>
+
+<p>
+As of Go 1.3, support for Go on FreeBSD requires that the kernel be compiled with the
+<code>COMPAT_FREEBSD32</code> flag configured.
+</p>
+
+<p>
+In concert with the switch to EABI syscalls for ARM platforms, Go 1.3 will run only on FreeBSD 10.
+The x86 platforms, 386 and amd64, are unaffected.
+</p>
+
+<h3 id="nacl">Support for Native Client</h3>
+
+<p>
+Support for the Native Client virtual machine architecture has returned to Go with the 1.3 release.
+It runs on the 32-bit Intel architectures (<code>GOARCH=386</code>) and also on 64-bit Intel, but using
+32-bit pointers (<code>GOARCH=amd64p32</code>).
+There is not yet support for Native Client on ARM.
+Note that this is Native Client (NaCl), not Portable Native Client (PNaCl).
+Details about Native Client are <a href="https://developers.google.com/native-client/dev/">here</a>;
+how to set up the Go version is described <a href="//golang.org/wiki/NativeClient">here</a>.
+</p>
+
+<h3 id="netbsd">Support for NetBSD</h3>
+
+<p>
+As of Go 1.3, support for Go on NetBSD requires NetBSD 6.0 or above.
+</p>
+
+<h3 id="openbsd">Support for OpenBSD</h3>
+
+<p>
+As of Go 1.3, support for Go on OpenBSD requires OpenBSD 5.5 or above.
+</p>
+
+<h3 id="plan9">Support for Plan 9</h3>
+
+<p>
+Go 1.3 now includes experimental support for Plan 9 on the <code>386</code> (32-bit x86) architecture.
+It requires the <code>Tsemacquire</code> syscall, which has been in Plan 9 since June, 2012.
+</p>
+
+<h3 id="solaris">Support for Solaris</h3>
+
+<p>
+Go 1.3 now includes experimental support for Solaris on the <code>amd64</code> (64-bit x86) architecture.
+It requires illumos, Solaris 11 or above.
+</p>
+
+<h2 id="memory">Changes to the memory model</h2>
+
+<p>
+The Go 1.3 memory model <a href="https://codereview.appspot.com/75130045">adds a new rule</a>
+concerning sending and receiving on buffered channels,
+to make explicit that a buffered channel can be used as a simple
+semaphore, using a send into the
+channel to acquire and a receive from the channel to release.
+This is not a language change, just a clarification about an expected property of communication.
+</p>
+
+<h2 id="impl">Changes to the implementations and tools</h2>
+
+<h3 id="stacks">Stack</h3>
+
+<p>
+Go 1.3 has changed the implementation of goroutine stacks away from the old,
+"segmented" model to a contiguous model.
+When a goroutine needs more stack
+than is available, its stack is transferred to a larger single block of memory.
+The overhead of this transfer operation amortizes well and eliminates the old "hot spot"
+problem when a calculation repeatedly steps across a segment boundary.
+Details including performance numbers are in this
+<a href="//golang.org/s/contigstacks">design document</a>.
+</p>
+
+<h3 id="garbage_collector">Changes to the garbage collector</h3>
+
+<p>
+For a while now, the garbage collector has been <em>precise</em> when examining
+values in the heap; the Go 1.3 release adds equivalent precision to values on the stack.
+This means that a non-pointer Go value such as an integer will never be mistaken for a
+pointer and prevent unused memory from being reclaimed.
+</p>
+
+<p>
+Starting with Go 1.3, the runtime assumes that values with pointer type
+contain pointers and other values do not.
+This assumption is fundamental to the precise behavior of both stack expansion
+and garbage collection.
+Programs that use <a href="/pkg/unsafe/">package unsafe</a>
+to store integers in pointer-typed values are illegal and will crash if the runtime detects the behavior.
+Programs that use <a href="/pkg/unsafe/">package unsafe</a> to store pointers
+in integer-typed values are also illegal but more difficult to diagnose during execution.
+Because the pointers are hidden from the runtime, a stack expansion or garbage collection
+may reclaim the memory they point at, creating
+<a href="//en.wikipedia.org/wiki/Dangling_pointer">dangling pointers</a>.
+</p>
+
+<p>
+<em>Updating</em>: Code that uses <code>unsafe.Pointer</code> to convert
+an integer-typed value held in memory into a pointer is illegal and must be rewritten.
+Such code can be identified by <code>go vet</code>.
+</p>
+
+<h3 id="map">Map iteration</h3>
+
+<p>
+Iterations over small maps no longer happen in a consistent order.
+Go 1 defines that “<a href="//golang.org/ref/spec#For_statements">The iteration order over maps
+is not specified and is not guaranteed to be the same from one iteration to the next.</a>”
+To keep code from depending on map iteration order,
+Go 1.0 started each map iteration at a random index in the map.
+A new map implementation introduced in Go 1.1 neglected to randomize
+iteration for maps with eight or fewer entries, although the iteration order
+can still vary from system to system.
+This has allowed people to write Go 1.1 and Go 1.2 programs that
+depend on small map iteration order and therefore only work reliably on certain systems.
+Go 1.3 reintroduces random iteration for small maps in order to flush out these bugs.
+</p>
+
+<p>
+<em>Updating</em>: If code assumes a fixed iteration order for small maps,
+it will break and must be rewritten not to make that assumption.
+Because only small maps are affected, the problem arises most often in tests.
+</p>
+
+<h3 id="liblink">The linker</h3>
+
+<p>
+As part of the general <a href="//golang.org/s/go13linker">overhaul</a> to
+the Go linker, the compilers and linkers have been refactored.
+The linker is still a C program, but now the instruction selection phase that
+was part of the linker has been moved to the compiler through the creation of a new
+library called <code>liblink</code>.
+By doing instruction selection only once, when the package is first compiled,
+this can speed up compilation of large projects significantly.
+</p>
+
+<p>
+<em>Updating</em>: Although this is a major internal change, it should have no
+effect on programs.
+</p>
+
+<h3 id="gccgo">Status of gccgo</h3>
+
+<p>
+GCC release 4.9 will contain the Go 1.2 (not 1.3) version of gccgo.
+The release schedules for the GCC and Go projects do not coincide,
+which means that 1.3 will be available in the development branch but
+that the next GCC release, 4.10, will likely have the Go 1.4 version of gccgo.
+</p>
+
+<h3 id="gocmd">Changes to the go command</h3>
+
+<p>
+The <a href="/cmd/go/"><code>cmd/go</code></a> command has several new
+features.
+The <a href="/cmd/go/"><code>go run</code></a> and
+<a href="/cmd/go/"><code>go test</code></a> subcommands
+support a new <code>-exec</code> option to specify an alternate
+way to run the resulting binary.
+Its immediate purpose is to support NaCl.
+</p>
+
+<p>
+The test coverage support of the <a href="/cmd/go/"><code>go test</code></a>
+subcommand now automatically sets the coverage mode to <code>-atomic</code>
+when the race detector is enabled, to eliminate false reports about unsafe
+access to coverage counters.
+</p>
+
+<p>
+The <a href="/cmd/go/"><code>go test</code></a> subcommand
+now always builds the package, even if it has no test files.
+Previously, it would do nothing if no test files were present.
+</p>
+
+<p>
+The <a href="/cmd/go/"><code>go build</code></a> subcommand
+supports a new <code>-i</code> option to install dependencies
+of the specified target, but not the target itself.
+</p>
+
+<p>
+Cross compiling with <a href="/cmd/cgo/"><code>cgo</code></a> enabled
+is now supported.
+The CC_FOR_TARGET and CXX_FOR_TARGET environment
+variables are used when running all.bash to specify the cross compilers
+for C and C++ code, respectively.
+</p>
+
+<p>
+Finally, the go command now supports packages that import Objective-C
+files (suffixed <code>.m</code>) through cgo.
+</p>
+
+<h3 id="cgo">Changes to cgo</h3>
+
+<p>
+The <a href="/cmd/cgo/"><code>cmd/cgo</code></a> command,
+which processes <code>import "C"</code> declarations in Go packages,
+has corrected a serious bug that may cause some packages to stop compiling.
+Previously, all pointers to incomplete struct types translated to the Go type <code>*[0]byte</code>,
+with the effect that the Go compiler could not diagnose passing one kind of struct pointer
+to a function expecting another.
+Go 1.3 corrects this mistake by translating each different
+incomplete struct to a different named type.
+</p>
+
+<p>
+Given the C declaration <code>typedef struct S T</code> for an incomplete <code>struct S</code>,
+some Go code used this bug to refer to the types <code>C.struct_S</code> and <code>C.T</code> interchangeably.
+Cgo now explicitly allows this use, even for completed struct types.
+However, some Go code also used this bug to pass (for example) a <code>*C.FILE</code>
+from one package to another.
+This is not legal and no longer works: in general Go packages
+should avoid exposing C types and names in their APIs.
+</p>
+
+<p>
+<em>Updating</em>: Code confusing pointers to incomplete types or
+passing them across package boundaries will no longer compile
+and must be rewritten.
+If the conversion is correct and must be preserved,
+use an explicit conversion via <a href="/pkg/unsafe/#Pointer"><code>unsafe.Pointer</code></a>.
+</p>
+
+<h3 id="swig">SWIG 3.0 required for programs that use SWIG</h3>
+
+<p>
+For Go programs that use SWIG, SWIG version 3.0 is now required.
+The <a href="/cmd/go"><code>cmd/go</code></a> command will now link the
+SWIG generated object files directly into the binary, rather than
+building and linking with a shared library.
+</p>
+
+<h3 id="gc_flag">Command-line flag parsing</h3>
+
+<p>
+In the gc tool chain, the assemblers now use the
+same command-line flag parsing rules as the Go flag package, a departure
+from the traditional Unix flag parsing.
+This may affect scripts that invoke the tool directly.
+For example,
+<code>go tool 6a -SDfoo</code> must now be written
+<code>go tool 6a -S -D foo</code>.
+(The same change was made to the compilers and linkers in <a href="/doc/go1.1#gc_flag">Go 1.1</a>.)
+</p>
+
+<h3 id="godoc">Changes to godoc</h3>
+<p>
+When invoked with the <code>-analysis</code> flag,
+<a href="//godoc.org/golang.org/x/tools/cmd/godoc">godoc</a>
+now performs sophisticated <a href="/lib/godoc/analysis/help.html">static
+analysis</a> of the code it indexes.
+The results of analysis are presented in both the source view and the
+package documentation view, and include the call graph of each package
+and the relationships between
+definitions and references,
+types and their methods,
+interfaces and their implementations,
+send and receive operations on channels,
+functions and their callers, and
+call sites and their callees.
+</p>
+
+<h3 id="misc">Miscellany</h3>
+
+<p>
+The program <code>misc/benchcmp</code> that compares
+performance across benchmarking runs has been rewritten.
+Once a shell and awk script in the main repository, it is now a Go program in the <code>go.tools</code> repo.
+Documentation is <a href="//godoc.org/golang.org/x/tools/cmd/benchcmp">here</a>.
+</p>
+
+<p>
+For the few of us that build Go distributions, the tool <code>misc/dist</code> has been
+moved and renamed; it now lives in <code>misc/makerelease</code>, still in the main repository.
+</p>
+
+<h2 id="performance">Performance</h2>
+
+<p>
+The performance of Go binaries for this release has improved in many cases due to changes
+in the runtime and garbage collection, plus some changes to libraries.
+Significant instances include:
+</p>
+
+<ul>
+
+<li>
+The runtime handles defers more efficiently, reducing the memory footprint by about two kilobytes
+per goroutine that calls defer.
+</li>
+
+<li>
+The garbage collector has been sped up, using a concurrent sweep algorithm,
+better parallelization, and larger pages.
+The cumulative effect can be a 50-70% reduction in collector pause time.
+</li>
+
+<li>
+The race detector (see <a href="/doc/articles/race_detector.html">this guide</a>)
+is now about 40% faster.
+</li>
+
+<li>
+The regular expression package <a href="/pkg/regexp/"><code>regexp</code></a>
+is now significantly faster for certain simple expressions due to the implementation of
+a second, one-pass execution engine.
+The choice of which engine to use is automatic;
+the details are hidden from the user.
+</li>
+
+</ul>
+
+<p>
+Also, the runtime now includes in stack dumps how long a goroutine has been blocked,
+which can be useful information when debugging deadlocks or performance issues.
+</p>
+
+<h2 id="library">Changes to the standard library</h2>
+
+<h3 id="new_packages">New packages</h3>
+
+<p>
+A new package <a href="/pkg/debug/plan9obj/"><code>debug/plan9obj</code></a> was added to the standard library.
+It implements access to Plan 9 <a href="http://plan9.bell-labs.com/magic/man2html/6/a.out">a.out</a> object files.
+</p>
+
+<h3 id="major_library_changes">Major changes to the library</h3>
+
+<p>
+A previous bug in <a href="/pkg/crypto/tls/"><code>crypto/tls</code></a>
+made it possible to skip verification in TLS inadvertently.
+In Go 1.3, the bug is fixed: one must specify either ServerName or
+InsecureSkipVerify, and if ServerName is specified it is enforced.
+This may break existing code that incorrectly depended on insecure
+behavior.
+</p>
+
+<p>
+There is an important new type added to the standard library: <a href="/pkg/sync/#Pool"><code>sync.Pool</code></a>.
+It provides an efficient mechanism for implementing certain types of caches whose memory
+can be reclaimed automatically by the system.
+</p>
+
+<p>
+The <a href="/pkg/testing/"><code>testing</code></a> package's benchmarking helper,
+<a href="/pkg/testing/#B"><code>B</code></a>, now has a
+<a href="/pkg/testing/#B.RunParallel"><code>RunParallel</code></a> method
+to make it easier to run benchmarks that exercise multiple CPUs.
+</p>
+
+<p>
+<em>Updating</em>: The crypto/tls fix may break existing code, but such
+code was erroneous and should be updated.
+</p>
+
+<h3 id="minor_library_changes">Minor changes to the library</h3>
+
+<p>
+The following list summarizes a number of minor changes to the library, mostly additions.
+See the relevant package documentation for more information about each change.
+</p>
+
+<ul>
+
+<li> In the <a href="/pkg/crypto/tls/"><code>crypto/tls</code></a> package,
+a new <a href="/pkg/crypto/tls/#DialWithDialer"><code>DialWithDialer</code></a>
+function lets one establish a TLS connection using an existing dialer, making it easier
+to control dial options such as timeouts.
+The package also now reports the TLS version used by the connection in the
+<a href="/pkg/crypto/tls/#ConnectionState"><code>ConnectionState</code></a>
+struct.
+</li>
+
+<li> The <a href="/pkg/crypto/x509/#CreateCertificate"><code>CreateCertificate</code></a>
+function of the <a href="/pkg/crypto/tls/"><code>crypto/tls</code></a> package
+now supports parsing (and elsewhere, serialization) of PKCS #10 certificate
+signature requests.
+</li>
+
+<li>
+The formatted print functions of the <code>fmt</code> package now define <code>%F</code>
+as a synonym for <code>%f</code> when printing floating-point values.
+</li>
+
+<li>
+The <a href="/pkg/math/big/"><code>math/big</code></a> package's
+<a href="/pkg/math/big/#Int"><code>Int</code></a> and
+<a href="/pkg/math/big/#Rat"><code>Rat</code></a> types
+now implement
+<a href="/pkg/encoding/#TextMarshaler"><code>encoding.TextMarshaler</code></a> and
+<a href="/pkg/encoding/#TextUnmarshaler"><code>encoding.TextUnmarshaler</code></a>.
+</li>
+
+<li>
+The complex power function, <a href="/pkg/math/cmplx/#Pow"><code>Pow</code></a>,
+now specifies the behavior when the first argument is zero.
+It was undefined before.
+The details are in the <a href="/pkg/math/cmplx/#Pow">documentation for the function</a>.
+</li>
+
+<li>
+The <a href="/pkg/net/http/"><code>net/http</code></a> package now exposes the
+properties of a TLS connection used to make a client request in the new
+<a href="/pkg/net/http/#Response"><code>Response.TLS</code></a> field.
+</li>
+
+<li>
+The <a href="/pkg/net/http/"><code>net/http</code></a> package now
+allows setting an optional server error logger
+with <a href="/pkg/net/http/#Server"><code>Server.ErrorLog</code></a>.
+The default is still that all errors go to stderr.
+</li>
+
+<li>
+The <a href="/pkg/net/http/"><code>net/http</code></a> package now
+supports disabling HTTP keep-alive connections on the server
+with <a href="/pkg/net/http/#Server.SetKeepAlivesEnabled"><code>Server.SetKeepAlivesEnabled</code></a>.
+The default continues to be that the server does keep-alive (reuses
+connections for multiple requests) by default.
+Only resource-constrained servers or those in the process of graceful
+shutdown will want to disable them.
+</li>
+
+<li>
+The <a href="/pkg/net/http/"><code>net/http</code></a> package adds an optional
+<a href="/pkg/net/http/#Transport"><code>Transport.TLSHandshakeTimeout</code></a>
+setting to cap the amount of time HTTP client requests will wait for
+TLS handshakes to complete.
+It's now also set by default
+on <a href="/pkg/net/http#DefaultTransport"><code>DefaultTransport</code></a>.
+</li>
+
+<li>
+The <a href="/pkg/net/http/"><code>net/http</code></a> package's
+<a href="/pkg/net/http/#DefaultTransport"><code>DefaultTransport</code></a>,
+used by the HTTP client code, now
+enables <a href="http://en.wikipedia.org/wiki/Keepalive#TCP_keepalive">TCP
+keep-alives</a> by default.
+Other <a href="/pkg/net/http/#Transport"><code>Transport</code></a>
+values with a nil <code>Dial</code> field continue to function the same
+as before: no TCP keep-alives are used.
+</li>
+
+<li>
+The <a href="/pkg/net/http/"><code>net/http</code></a> package
+now enables <a href="http://en.wikipedia.org/wiki/Keepalive#TCP_keepalive">TCP
+keep-alives</a> for incoming server requests when
+<a href="/pkg/net/http/#ListenAndServe"><code>ListenAndServe</code></a>
+or
+<a href="/pkg/net/http/#ListenAndServeTLS"><code>ListenAndServeTLS</code></a>
+are used.
+When a server is started otherwise, TCP keep-alives are not enabled.
+</li>
+
+<li>
+The <a href="/pkg/net/http/"><code>net/http</code></a> package now
+provides an
+optional <a href="/pkg/net/http/#Server"><code>Server.ConnState</code></a>
+callback to hook various phases of a server connection's lifecycle
+(see <a href="/pkg/net/http/#ConnState"><code>ConnState</code></a>).
+This can be used to implement rate limiting or graceful shutdown.
+</li>
+
+<li>
+The <a href="/pkg/net/http/"><code>net/http</code></a> package's HTTP
+client now has an
+optional <a href="/pkg/net/http/#Client"><code>Client.Timeout</code></a>
+field to specify an end-to-end timeout on requests made using the
+client.
+</li>
+
+<li>
+The <a href="/pkg/net/http/"><code>net/http</code></a> package's
+<a href="/pkg/net/http/#Request.ParseMultipartForm"><code>Request.ParseMultipartForm</code></a>
+method will now return an error if the body's <code>Content-Type</code>
+is not <code>mutipart/form-data</code>.
+Prior to Go 1.3 it would silently fail and return <code>nil</code>.
+Code that relies on the previous behavior should be updated.
+</li>
+
+<li> In the <a href="/pkg/net/"><code>net</code></a> package,
+the <a href="/pkg/net/#Dialer"><code>Dialer</code></a> struct now
+has a <code>KeepAlive</code> option to specify a keep-alive period for the connection.
+</li>
+
+<li>
+The <a href="/pkg/net/http/"><code>net/http</code></a> package's
+<a href="/pkg/net/http/#Transport"><code>Transport</code></a>
+now closes <a href="/pkg/net/http/#Request"><code>Request.Body</code></a>
+consistently, even on error.
+</li>
+
+<li>
+The <a href="/pkg/os/exec/"><code>os/exec</code></a> package now implements
+what the documentation has always said with regard to relative paths for the binary.
+In particular, it only calls <a href="/pkg/os/exec/#LookPath"><code>LookPath</code></a>
+when the binary's file name contains no path separators.
+</li>
+
+<li>
+The <a href="/pkg/reflect/#Value.SetMapIndex"><code>SetMapIndex</code></a>
+function in the <a href="/pkg/reflect/"><code>reflect</code></a> package
+no longer panics when deleting from a <code>nil</code> map.
+</li>
+
+<li>
+If the main goroutine calls
+<a href="/pkg/runtime/#Goexit"><code>runtime.Goexit</code></a>
+and all other goroutines finish execution, the program now always crashes,
+reporting a detected deadlock.
+Earlier versions of Go handled this situation inconsistently: most instances
+were reported as deadlocks, but some trivial cases exited cleanly instead.
+</li>
+
+<li>
+The runtime/debug package now has a new function
+<a href="/pkg/runtime/debug/#WriteHeapDump"><code>debug.WriteHeapDump</code></a>
+that writes out a description of the heap.
+</li>
+
+<li>
+The <a href="/pkg/strconv/#CanBackquote"><code>CanBackquote</code></a>
+function in the <a href="/pkg/strconv/"><code>strconv</code></a> package
+now considers the <code>DEL</code> character, <code>U+007F</code>, to be
+non-printing.
+</li>
+
+<li>
+The <a href="/pkg/syscall/"><code>syscall</code></a> package now provides
+<a href="/pkg/syscall/#SendmsgN"><code>SendmsgN</code></a>
+as an alternate version of
+<a href="/pkg/syscall/#Sendmsg"><code>Sendmsg</code></a>
+that returns the number of bytes written.
+</li>
+
+<li>
+On Windows, the <a href="/pkg/syscall/"><code>syscall</code></a> package now
+supports the cdecl calling convention through the addition of a new function
+<a href="/pkg/syscall/#NewCallbackCDecl"><code>NewCallbackCDecl</code></a>
+alongside the existing function
+<a href="/pkg/syscall/#NewCallback"><code>NewCallback</code></a>.
+</li>
+
+<li>
+The <a href="/pkg/testing/"><code>testing</code></a> package now
+diagnoses tests that call <code>panic(nil)</code>, which are almost always erroneous.
+Also, tests now write profiles (if invoked with profiling flags) even on failure.
+</li>
+
+<li>
+The <a href="/pkg/unicode/"><code>unicode</code></a> package and associated
+support throughout the system has been upgraded from
+Unicode 6.2.0 to <a href="http://www.unicode.org/versions/Unicode6.3.0/">Unicode 6.3.0</a>.
+</li>
+
+</ul>
diff --git a/doc/go1.4.html b/doc/go1.4.html
new file mode 100644
index 0000000..b4f9619
--- /dev/null
+++ b/doc/go1.4.html
@@ -0,0 +1,896 @@
+<!--{
+ "Title": "Go 1.4 Release Notes",
+ "Path": "/doc/go1.4",
+ "Template": true
+}-->
+
+<h2 id="introduction">Introduction to Go 1.4</h2>
+
+<p>
+The latest Go release, version 1.4, arrives as scheduled six months after 1.3.
+</p>
+
+<p>
+It contains only one tiny language change,
+in the form of a backwards-compatible simple variant of <code>for</code>-<code>range</code> loop,
+and a possibly breaking change to the compiler involving methods on pointers-to-pointers.
+</p>
+
+<p>
+The release focuses primarily on implementation work, improving the garbage collector
+and preparing the ground for a fully concurrent collector to be rolled out in the
+next few releases.
+Stacks are now contiguous, reallocated when necessary rather than linking on new
+"segments";
+this release therefore eliminates the notorious "hot stack split" problem.
+There are some new tools available including support in the <code>go</code> command
+for build-time source code generation.
+The release also adds support for ARM processors on Android and Native Client (NaCl)
+and for AMD64 on Plan 9.
+</p>
+
+<p>
+As always, Go 1.4 keeps the <a href="/doc/go1compat.html">promise
+of compatibility</a>,
+and almost everything
+will continue to compile and run without change when moved to 1.4.
+</p>
+
+<h2 id="language">Changes to the language</h2>
+
+<h3 id="forrange">For-range loops</h3>
+<p>
+Up until Go 1.3, <code>for</code>-<code>range</code> loop had two forms
+</p>
+
+<pre>
+for i, v := range x {
+ ...
+}
+</pre>
+
+<p>
+and
+</p>
+
+<pre>
+for i := range x {
+ ...
+}
+</pre>
+
+<p>
+If one was not interested in the loop values, only the iteration itself, it was still
+necessary to mention a variable (probably the <a href="/ref/spec#Blank_identifier">blank identifier</a>, as in
+<code>for</code> <code>_</code> <code>=</code> <code>range</code> <code>x</code>), because
+the form
+</p>
+
+<pre>
+for range x {
+ ...
+}
+</pre>
+
+<p>
+was not syntactically permitted.
+</p>
+
+<p>
+This situation seemed awkward, so as of Go 1.4 the variable-free form is now legal.
+The pattern arises rarely but the code can be cleaner when it does.
+</p>
+
+<p>
+<em>Updating</em>: The change is strictly backwards compatible to existing Go
+programs, but tools that analyze Go parse trees may need to be modified to accept
+this new form as the
+<code>Key</code> field of <a href="/pkg/go/ast/#RangeStmt"><code>RangeStmt</code></a>
+may now be <code>nil</code>.
+</p>
+
+<h3 id="methodonpointertopointer">Method calls on **T</h3>
+
+<p>
+Given these declarations,
+</p>
+
+<pre>
+type T int
+func (T) M() {}
+var x **T
+</pre>
+
+<p>
+both <code>gc</code> and <code>gccgo</code> accepted the method call
+</p>
+
+<pre>
+x.M()
+</pre>
+
+<p>
+which is a double dereference of the pointer-to-pointer <code>x</code>.
+The Go specification allows a single dereference to be inserted automatically,
+but not two, so this call is erroneous according to the language definition.
+It has therefore been disallowed in Go 1.4, which is a breaking change,
+although very few programs will be affected.
+</p>
+
+<p>
+<em>Updating</em>: Code that depends on the old, erroneous behavior will no longer
+compile but is easy to fix by adding an explicit dereference.
+</p>
+
+<h2 id="os">Changes to the supported operating systems and architectures</h2>
+
+<h3 id="android">Android</h3>
+
+<p>
+Go 1.4 can build binaries for ARM processors running the Android operating system.
+It can also build a <code>.so</code> library that can be loaded by an Android application
+using the supporting packages in the <a href="https://golang.org/x/mobile">mobile</a> subrepository.
+A brief description of the plans for this experimental port are available
+<a href="https://golang.org/s/go14android">here</a>.
+</p>
+
+<h3 id="naclarm">NaCl on ARM</h3>
+
+<p>
+The previous release introduced Native Client (NaCl) support for the 32-bit x86
+(<code>GOARCH=386</code>)
+and 64-bit x86 using 32-bit pointers (GOARCH=amd64p32).
+The 1.4 release adds NaCl support for ARM (GOARCH=arm).
+</p>
+
+<h3 id="plan9amd64">Plan9 on AMD64</h3>
+
+<p>
+This release adds support for the Plan 9 operating system on AMD64 processors,
+provided the kernel supports the <code>nsec</code> system call and uses 4K pages.
+</p>
+
+<h2 id="compatibility">Changes to the compatibility guidelines</h2>
+
+<p>
+The <a href="/pkg/unsafe/"><code>unsafe</code></a> package allows one
+to defeat Go's type system by exploiting internal details of the implementation
+or machine representation of data.
+It was never explicitly specified what use of <code>unsafe</code> meant
+with respect to compatibility as specified in the
+<a href="go1compat.html">Go compatibility guidelines</a>.
+The answer, of course, is that we can make no promise of compatibility
+for code that does unsafe things.
+</p>
+
+<p>
+We have clarified this situation in the documentation included in the release.
+The <a href="go1compat.html">Go compatibility guidelines</a> and the
+docs for the <a href="/pkg/unsafe/"><code>unsafe</code></a> package
+are now explicit that unsafe code is not guaranteed to remain compatible.
+</p>
+
+<p>
+<em>Updating</em>: Nothing technical has changed; this is just a clarification
+of the documentation.
+</p>
+
+
+<h2 id="impl">Changes to the implementations and tools</h2>
+
+<h3 id="runtime">Changes to the runtime</h3>
+
+<p>
+Prior to Go 1.4, the runtime (garbage collector, concurrency support, interface management,
+maps, slices, strings, ...) was mostly written in C, with some assembler support.
+In 1.4, much of the code has been translated to Go so that the garbage collector can scan
+the stacks of programs in the runtime and get accurate information about what variables
+are active.
+This change was large but should have no semantic effect on programs.
+</p>
+
+<p>
+This rewrite allows the garbage collector in 1.4 to be fully precise,
+meaning that it is aware of the location of all active pointers in the program.
+This means the heap will be smaller as there will be no false positives keeping non-pointers alive.
+Other related changes also reduce the heap size, which is smaller by 10%-30% overall
+relative to the previous release.
+</p>
+
+<p>
+A consequence is that stacks are no longer segmented, eliminating the "hot split" problem.
+When a stack limit is reached, a new, larger stack is allocated, all active frames for
+the goroutine are copied there, and any pointers into the stack are updated.
+Performance can be noticeably better in some cases and is always more predictable.
+Details are available in <a href="https://golang.org/s/contigstacks">the design document</a>.
+</p>
+
+<p>
+The use of contiguous stacks means that stacks can start smaller without triggering performance issues,
+so the default starting size for a goroutine's stack in 1.4 has been reduced from 8192 bytes to 2048 bytes.
+</p>
+
+<p>
+As preparation for the concurrent garbage collector scheduled for the 1.5 release,
+writes to pointer values in the heap are now done by a function call,
+called a write barrier, rather than directly from the function updating the value.
+In this next release, this will permit the garbage collector to mediate writes to the heap while it is running.
+This change has no semantic effect on programs in 1.4, but was
+included in the release to test the compiler and the resulting performance.
+</p>
+
+<p>
+The implementation of interface values has been modified.
+In earlier releases, the interface contained a word that was either a pointer or a one-word
+scalar value, depending on the type of the concrete object stored.
+This implementation was problematical for the garbage collector,
+so as of 1.4 interface values always hold a pointer.
+In running programs, most interface values were pointers anyway,
+so the effect is minimal, but programs that store integers (for example) in
+interfaces will see more allocations.
+</p>
+
+<p>
+As of Go 1.3, the runtime crashes if it finds a memory word that should contain
+a valid pointer but instead contains an obviously invalid pointer (for example, the value 3).
+Programs that store integers in pointer values may run afoul of this check and crash.
+In Go 1.4, setting the <a href="/pkg/runtime/"><code>GODEBUG</code></a> variable
+<code>invalidptr=0</code> disables
+the crash as a workaround, but we cannot guarantee that future releases will be
+able to avoid the crash; the correct fix is to rewrite code not to alias integers and pointers.
+</p>
+
+<h3 id="asm">Assembly</h3>
+
+<p>
+The language accepted by the assemblers <code>cmd/5a</code>, <code>cmd/6a</code>
+and <code>cmd/8a</code> has had several changes,
+mostly to make it easier to deliver type information to the runtime.
+</p>
+
+<p>
+First, the <code>textflag.h</code> file that defines flags for <code>TEXT</code> directives
+has been copied from the linker source directory to a standard location so it can be
+included with the simple directive
+</p>
+
+<pre>
+#include "textflag.h"
+</pre>
+
+<p>
+The more important changes are in how assembler source can define the necessary
+type information.
+For most programs it will suffice to move data
+definitions (<code>DATA</code> and <code>GLOBL</code> directives)
+out of assembly into Go files
+and to write a Go declaration for each assembly function.
+The <a href="/doc/asm#runtime">assembly document</a> describes what to do.
+</p>
+
+<p>
+<em>Updating</em>:
+Assembly files that include <code>textflag.h</code> from its old
+location will still work, but should be updated.
+For the type information, most assembly routines will need no change,
+but all should be examined.
+Assembly source files that define data,
+functions with non-empty stack frames, or functions that return pointers
+need particular attention.
+A description of the necessary (but simple) changes
+is in the <a href="/doc/asm#runtime">assembly document</a>.
+</p>
+
+<p>
+More information about these changes is in the <a href="/doc/asm">assembly document</a>.
+</p>
+
+<h3 id="gccgo">Status of gccgo</h3>
+
+<p>
+The release schedules for the GCC and Go projects do not coincide.
+GCC release 4.9 contains the Go 1.2 version of gccgo.
+The next release, GCC 5, will likely have the Go 1.4 version of gccgo.
+</p>
+
+<h3 id="internalpackages">Internal packages</h3>
+
+<p>
+Go's package system makes it easy to structure programs into components with clean boundaries,
+but there are only two forms of access: local (unexported) and global (exported).
+Sometimes one wishes to have components that are not exported,
+for instance to avoid acquiring clients of interfaces to code that is part of a public repository
+but not intended for use outside the program to which it belongs.
+</p>
+
+<p>
+The Go language does not have the power to enforce this distinction, but as of Go 1.4 the
+<a href="/cmd/go/"><code>go</code></a> command introduces
+a mechanism to define "internal" packages that may not be imported by packages outside
+the source subtree in which they reside.
+</p>
+
+<p>
+To create such a package, place it in a directory named <code>internal</code> or in a subdirectory of a directory
+named internal.
+When the <code>go</code> command sees an import of a package with <code>internal</code> in its path,
+it verifies that the package doing the import
+is within the tree rooted at the parent of the <code>internal</code> directory.
+For example, a package <code>.../a/b/c/internal/d/e/f</code>
+can be imported only by code in the directory tree rooted at <code>.../a/b/c</code>.
+It cannot be imported by code in <code>.../a/b/g</code> or in any other repository.
+</p>
+
+<p>
+For Go 1.4, the internal package mechanism is enforced for the main Go repository;
+from 1.5 and onward it will be enforced for any repository.
+</p>
+
+<p>
+Full details of the mechanism are in
+<a href="https://golang.org/s/go14internal">the design document</a>.
+</p>
+
+<h3 id="canonicalimports">Canonical import paths</h3>
+
+<p>
+Code often lives in repositories hosted by public services such as <code>github.com</code>,
+meaning that the import paths for packages begin with the name of the hosting service,
+<code>github.com/rsc/pdf</code> for example.
+One can use
+<a href="/cmd/go/#hdr-Remote_import_paths">an existing mechanism</a>
+to provide a "custom" or "vanity" import path such as
+<code>rsc.io/pdf</code>, but
+that creates two valid import paths for the package.
+That is a problem: one may inadvertently import the package through the two
+distinct paths in a single program, which is wasteful;
+miss an update to a package because the path being used is not recognized to be
+out of date;
+or break clients using the old path by moving the package to a different hosting service.
+</p>
+
+<p>
+Go 1.4 introduces an annotation for package clauses in Go source that identify a canonical
+import path for the package.
+If an import is attempted using a path that is not canonical,
+the <a href="/cmd/go/"><code>go</code></a> command
+will refuse to compile the importing package.
+</p>
+
+<p>
+The syntax is simple: put an identifying comment on the package line.
+For our example, the package clause would read:
+</p>
+
+<pre>
+package pdf // import "rsc.io/pdf"
+</pre>
+
+<p>
+With this in place,
+the <code>go</code> command will
+refuse to compile a package that imports <code>github.com/rsc/pdf</code>,
+ensuring that the code can be moved without breaking users.
+</p>
+
+<p>
+The check is at build time, not download time, so if <code>go</code> <code>get</code>
+fails because of this check, the mis-imported package has been copied to the local machine
+and should be removed manually.
+</p>
+
+<p>
+To complement this new feature, a check has been added at update time to verify
+that the local package's remote repository matches that of its custom import.
+The <code>go</code> <code>get</code> <code>-u</code> command will fail to
+update a package if its remote repository has changed since it was first
+downloaded.
+The new <code>-f</code> flag overrides this check.
+</p>
+
+<p>
+Further information is in
+<a href="https://golang.org/s/go14customimport">the design document</a>.
+</p>
+
+<h3 id="subrepo">Import paths for the subrepositories</h3>
+
+<p>
+The Go project subrepositories (<code>code.google.com/p/go.tools</code> and so on)
+are now available under custom import paths replacing <code>code.google.com/p/go.</code> with <code>golang.org/x/</code>,
+as in <code>golang.org/x/tools</code>.
+We will add canonical import comments to the code around June 1, 2015,
+at which point Go 1.4 and later will stop accepting the old <code>code.google.com</code> paths.
+</p>
+
+<p>
+<em>Updating</em>: All code that imports from subrepositories should change
+to use the new <code>golang.org</code> paths.
+Go 1.0 and later can resolve and import the new paths, so updating will not break
+compatibility with older releases.
+Code that has not updated will stop compiling with Go 1.4 around June 1, 2015.
+</p>
+
+<h3 id="gogenerate">The go generate subcommand</h3>
+
+<p>
+The <a href="/cmd/go/"><code>go</code></a> command has a new subcommand,
+<a href="/cmd/go/#hdr-Generate_Go_files_by_processing_source"><code>go generate</code></a>,
+to automate the running of tools to generate source code before compilation.
+For example, it can be used to run the <a href="/cmd/yacc"><code>yacc</code></a>
+compiler-compiler on a <code>.y</code> file to produce the Go source file implementing the grammar,
+or to automate the generation of <code>String</code> methods for typed constants using the new
+<a href="http://godoc.org/golang.org/x/tools/cmd/stringer">stringer</a>
+tool in the <code>golang.org/x/tools</code> subrepository.
+</p>
+
+<p>
+For more information, see the
+<a href="https://golang.org/s/go1.4-generate">design document</a>.
+</p>
+
+<h3 id="filenames">Change to file name handling</h3>
+
+<p>
+Build constraints, also known as build tags, control compilation by including or excluding files
+(see the documentation <a href="/pkg/go/build/"><code>/go/build</code></a>).
+Compilation can also be controlled by the name of the file itself by "tagging" the file with
+a suffix (before the <code>.go</code> or <code>.s</code> extension) with an underscore
+and the name of the architecture or operating system.
+For instance, the file <code>gopher_arm.go</code> will only be compiled if the target
+processor is an ARM.
+</p>
+
+<p>
+Before Go 1.4, a file called just <code>arm.go</code> was similarly tagged, but this behavior
+can break sources when new architectures are added, causing files to suddenly become tagged.
+In 1.4, therefore, a file will be tagged in this manner only if the tag (architecture or operating
+system name) is preceded by an underscore.
+</p>
+
+<p>
+<em>Updating</em>: Packages that depend on the old behavior will no longer compile correctly.
+Files with names like <code>windows.go</code> or <code>amd64.go</code> should either
+have explicit build tags added to the source or be renamed to something like
+<code>os_windows.go</code> or <code>support_amd64.go</code>.
+</p>
+
+<h3 id="gocmd">Other changes to the go command</h3>
+
+<p>
+There were a number of minor changes to the
+<a href="/cmd/go/"><code>cmd/go</code></a>
+command worth noting.
+</p>
+
+<ul>
+
+<li>
+Unless <a href="/cmd/cgo/"><code>cgo</code></a> is being used to build the package,
+the <code>go</code> command now refuses to compile C source files,
+since the relevant C compilers
+(<a href="/cmd/6c/"><code>6c</code></a> etc.)
+are intended to be removed from the installation in some future release.
+(They are used today only to build part of the runtime.)
+It is difficult to use them correctly in any case, so any extant uses are likely incorrect,
+so we have disabled them.
+</li>
+
+<li>
+The <a href="/cmd/go/#hdr-Test_packages"><code>go</code> <code>test</code></a>
+subcommand has a new flag, <code>-o</code>, to set the name of the resulting binary,
+corresponding to the same flag in other subcommands.
+The non-functional <code>-file</code> flag has been removed.
+</li>
+
+<li>
+The <a href="/cmd/go/#hdr-Test_packages"><code>go</code> <code>test</code></a>
+subcommand will compile and link all <code>*_test.go</code> files in the package,
+even when there are no <code>Test</code> functions in them.
+It previously ignored such files.
+</li>
+
+<li>
+The behavior of the
+<a href="/cmd/go/#hdr-Test_packages"><code>go</code> <code>build</code></a>
+subcommand's
+<code>-a</code> flag has been changed for non-development installations.
+For installations running a released distribution, the <code>-a</code> flag will no longer
+rebuild the standard library and commands, to avoid overwriting the installation's files.
+</li>
+
+</ul>
+
+<h3 id="pkg">Changes to package source layout</h3>
+
+<p>
+In the main Go source repository, the source code for the packages was kept in
+the directory <code>src/pkg</code>, which made sense but differed from
+other repositories, including the Go subrepositories.
+In Go 1.4, the<code> pkg</code> level of the source tree is now gone, so for example
+the <a href="/pkg/fmt/"><code>fmt</code></a> package's source, once kept in
+directory <code>src/pkg/fmt</code>, now lives one level higher in <code>src/fmt</code>.
+</p>
+
+<p>
+<em>Updating</em>: Tools like <code>godoc</code> that discover source code
+need to know about the new location. All tools and services maintained by the Go team
+have been updated.
+</p>
+
+
+<h3 id="swig">SWIG</h3>
+
+<p>
+Due to runtime changes in this release, Go 1.4 requires SWIG 3.0.3.
+</p>
+
+<h3 id="misc">Miscellany</h3>
+
+<p>
+The standard repository's top-level <code>misc</code> directory used to contain
+Go support for editors and IDEs: plugins, initialization scripts and so on.
+Maintaining these was becoming time-consuming
+and needed external help because many of the editors listed were not used by
+members of the core team.
+It also required us to make decisions about which plugin was best for a given
+editor, even for editors we do not use.
+</p>
+
+<p>
+The Go community at large is much better suited to managing this information.
+In Go 1.4, therefore, this support has been removed from the repository.
+Instead, there is a curated, informative list of what's available on
+a <a href="//golang.org/wiki/IDEsAndTextEditorPlugins">wiki page</a>.
+</p>
+
+<h2 id="performance">Performance</h2>
+
+<p>
+Most programs will run about the same speed or slightly faster in 1.4 than in 1.3;
+some will be slightly slower.
+There are many changes, making it hard to be precise about what to expect.
+</p>
+
+<p>
+As mentioned above, much of the runtime was translated to Go from C,
+which led to some reduction in heap sizes.
+It also improved performance slightly because the Go compiler is better
+at optimization, due to things like inlining, than the C compiler used to build
+the runtime.
+</p>
+
+<p>
+The garbage collector was sped up, leading to measurable improvements for
+garbage-heavy programs.
+On the other hand, the new write barriers slow things down again, typically
+by about the same amount but, depending on their behavior, some programs
+may be somewhat slower or faster.
+</p>
+
+<p>
+Library changes that affect performance are documented below.
+</p>
+
+<h2 id="library">Changes to the standard library</h2>
+
+<h3 id="new_packages">New packages</h3>
+
+<p>
+There are no new packages in this release.
+</p>
+
+<h3 id="major_library_changes">Major changes to the library</h3>
+
+<h4 id="scanner">bufio.Scanner</h4>
+
+<p>
+The <a href="/pkg/bufio/#Scanner"><code>Scanner</code></a> type in the
+<a href="/pkg/bufio/"><code>bufio</code></a> package
+has had a bug fixed that may require changes to custom
+<a href="/pkg/bufio/#SplitFunc"><code>split functions</code></a>.
+The bug made it impossible to generate an empty token at EOF; the fix
+changes the end conditions seen by the split function.
+Previously, scanning stopped at EOF if there was no more data.
+As of 1.4, the split function will be called once at EOF after input is exhausted,
+so the split function can generate a final empty token
+as the documentation already promised.
+</p>
+
+<p>
+<em>Updating</em>: Custom split functions may need to be modified to
+handle empty tokens at EOF as desired.
+</p>
+
+<h4 id="syscall">syscall</h4>
+
+<p>
+The <a href="/pkg/syscall/"><code>syscall</code></a> package is now frozen except
+for changes needed to maintain the core repository.
+In particular, it will no longer be extended to support new or different system calls
+that are not used by the core.
+The reasons are described at length in <a href="https://golang.org/s/go1.4-syscall">a
+separate document</a>.
+</p>
+
+<p>
+A new subrepository, <a href="https://golang.org/x/sys">golang.org/x/sys</a>,
+has been created to serve as the location for new developments to support system
+calls on all kernels.
+It has a nicer structure, with three packages that each hold the implementation of
+system calls for one of
+<a href="http://godoc.org/golang.org/x/sys/unix">Unix</a>,
+<a href="http://godoc.org/golang.org/x/sys/windows">Windows</a> and
+<a href="http://godoc.org/golang.org/x/sys/plan9">Plan 9</a>.
+These packages will be curated more generously, accepting all reasonable changes
+that reflect kernel interfaces in those operating systems.
+See the documentation and the article mentioned above for more information.
+</p>
+
+<p>
+<em>Updating</em>: Existing programs are not affected as the <code>syscall</code>
+package is largely unchanged from the 1.3 release.
+Future development that requires system calls not in the <code>syscall</code> package
+should build on <code>golang.org/x/sys</code> instead.
+</p>
+
+<h3 id="minor_library_changes">Minor changes to the library</h3>
+
+<p>
+The following list summarizes a number of minor changes to the library, mostly additions.
+See the relevant package documentation for more information about each change.
+</p>
+
+<ul>
+
+<li>
+The <a href="/pkg/archive/zip/"><code>archive/zip</code></a> package's
+<a href="/pkg/archive/zip/#Writer"><code>Writer</code></a> now supports a
+<a href="/pkg/archive/zip/#Writer.Flush"><code>Flush</code></a> method.
+</li>
+
+<li>
+The <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>
+packages now support a <code>Reset</code> method
+for the decompressors, allowing them to reuse buffers and improve performance.
+The <a href="/pkg/compress/gzip/"><code>compress/gzip</code></a> package also has a
+<a href="/pkg/compress/gzip/#Reader.Multistream"><code>Multistream</code></a> method to control support
+for multistream files.
+</li>
+
+<li>
+The <a href="/pkg/crypto/"><code>crypto</code></a> package now has a
+<a href="/pkg/crypto/#Signer"><code>Signer</code></a> interface, implemented by the
+<code>PrivateKey</code> types in
+<a href="/pkg/crypto/ecdsa"><code>crypto/ecdsa</code></a> and
+<a href="/pkg/crypto/rsa"><code>crypto/rsa</code></a>.
+</li>
+
+<li>
+The <a href="/pkg/crypto/tls/"><code>crypto/tls</code></a> package
+now supports ALPN as defined in <a href="http://tools.ietf.org/html/rfc7301">RFC 7301</a>.
+</li>
+
+<li>
+The <a href="/pkg/crypto/tls/"><code>crypto/tls</code></a> package
+now supports programmatic selection of server certificates
+through the new <a href="/pkg/crypto/tls/#Config.CertificateForName"><code>CertificateForName</code></a> function
+of the <a href="/pkg/crypo/tls/#Config"><code>Config</code></a> struct.
+</li>
+
+<li>
+Also in the crypto/tls package, the server now supports
+<a href="https://tools.ietf.org/html/draft-ietf-tls-downgrade-scsv-00">TLS_FALLBACK_SCSV</a>
+to help clients detect fallback attacks.
+(The Go client does not support fallback at all, so it is not vulnerable to
+those attacks.)
+</li>
+
+<li>
+The <a href="/pkg/database/sql/"><code>database/sql</code></a> package can now list all registered
+<a href="/pkg/database/sql/#Drivers"><code>Drivers</code></a>.
+</li>
+
+<li>
+The <a href="/pkg/debug/dwarf/"><code>debug/dwarf</code></a> package now supports
+<a href="/pkg/debug/dwarf/#UnspecifiedType"><code>UnspecifiedType</code></a>s.
+</li>
+
+<li>
+In the <a href="/pkg/encoding/asn1/"><code>encoding/asn1</code></a> package,
+optional elements with a default value will now only be omitted if they have that value.
+</li>
+
+<li>
+The <a href="/pkg/encoding/csv/"><code>encoding/csv</code></a> package no longer
+quotes empty strings but does quote the end-of-data marker <code>\.</code> (backslash dot).
+This is permitted by the definition of CSV and allows it to work better with Postgres.
+</li>
+
+<li>
+The <a href="/pkg/encoding/gob/"><code>encoding/gob</code></a> package has been rewritten to eliminate
+the use of unsafe operations, allowing it to be used in environments that do not permit use of the
+<a href="/pkg/unsafe/"><code>unsafe</code></a> package.
+For typical uses it will be 10-30% slower, but the delta is dependent on the type of the data and
+in some cases, especially involving arrays, it can be faster.
+There is no functional change.
+</li>
+
+<li>
+The <a href="/pkg/encoding/xml/"><code>encoding/xml</code></a> package's
+<a href="/pkg/encoding/xml/#Decoder"><code>Decoder</code></a> can now report its input offset.
+</li>
+
+<li>
+In the <a href="/pkg/fmt/"><code>fmt</code></a> package,
+formatting of pointers to maps has changed to be consistent with that of pointers
+to structs, arrays, and so on.
+For instance, <code>&map[string]int{"one":</code> <code>1}</code> now prints by default as
+<code>&map[one:</code> <code>1]</code> rather than as a hexadecimal pointer value.
+</li>
+
+<li>
+The <a href="/pkg/image/"><code>image</code></a> package's
+<a href="/pkg/image/#Image"><code>Image</code></a>
+implementations like
+<a href="/pkg/image/#RGBA"><code>RGBA</code></a> and
+<a href="/pkg/image/#Gray"><code>Gray</code></a> have specialized
+<a href="/pkg/image/#RGBA.RGBAAt"><code>RGBAAt</code></a> and
+<a href="/pkg/image/#Gray.GrayAt"><code>GrayAt</code></a> methods alongside the general
+<a href="/pkg/image/#Image.At"><code>At</code></a> method.
+</li>
+
+<li>
+The <a href="/pkg/image/png/"><code>image/png</code></a> package now has an
+<a href="/pkg/image/png/#Encoder"><code>Encoder</code></a>
+type to control the compression level used for encoding.
+</li>
+
+<li>
+The <a href="/pkg/math/"><code>math</code></a> package now has a
+<a href="/pkg/math/#Nextafter32"><code>Nextafter32</code><a/> function.
+</li>
+
+<li>
+The <a href="/pkg/net/http/"><code>net/http</code></a> package's
+<a href="/pkg/net/http/#Request"><code>Request</code></a> type
+has a new <a href="/pkg/net/http/#Request.BasicAuth"><code>BasicAuth</code></a> method
+that returns the username and password from authenticated requests using the
+HTTP Basic Authentication
+Scheme.
+</li>
+
+<li>The <a href="/pkg/net/http/"><code>net/http</code></a> package's
+<a href="/pkg/net/http/#Request"><code>Transport</code></a> type
+has a new <a href="/pkg/net/http/#Transport.DialTLS"><code>DialTLS</code></a> hook
+that allows customizing the behavior of outbound TLS connections.
+</li>
+
+<li>
+The <a href="/pkg/net/http/httputil/"><code>net/http/httputil</code></a> package's
+<a href="/pkg/net/http/httputil/#ReverseProxy"><code>ReverseProxy</code></a> type
+has a new field,
+<a href="/pkg/net/http/#ReverseProxy.ErrorLog"><code>ErrorLog</code></a>, that
+provides user control of logging.
+</li>
+
+<li>
+The <a href="/pkg/os/"><code>os</code></a> package
+now implements symbolic links on the Windows operating system
+through the <a href="/pkg/os/#Symlink"><code>Symlink</code></a> function.
+Other operating systems already have this functionality.
+There is also a new <a href="/pkg/os/#Unsetenv"><code>Unsetenv</code></a> function.
+</li>
+
+<li>
+The <a href="/pkg/reflect/"><code>reflect</code></a> package's
+<a href="/pkg/reflect/#Type"><code>Type</code></a> interface
+has a new method, <a href="/pkg/reflect/#type.Comparable"><code>Comparable</code></a>,
+that reports whether the type implements general comparisons.
+</li>
+
+<li>
+Also in the <a href="/pkg/reflect/"><code>reflect</code></a> package, the
+<a href="/pkg/reflect/#Value"><code>Value</code></a> interface is now three instead of four words
+because of changes to the implementation of interfaces in the runtime.
+This saves memory but has no semantic effect.
+</li>
+
+<li>
+The <a href="/pkg/runtime/"><code>runtime</code></a> package
+now implements monotonic clocks on Windows,
+as it already did for the other systems.
+</li>
+
+<li>
+The <a href="/pkg/runtime/"><code>runtime</code></a> package's
+<a href="/pkg/runtime/#MemStats.Mallocs"><code>Mallocs</code></a> counter
+now counts very small allocations that were missed in Go 1.3.
+This may break tests using <a href="/pkg/runtime/#ReadMemStats"><code>ReadMemStats</code></a>
+or <a href="/pkg/testing/#AllocsPerRun"><code>AllocsPerRun</code></a>
+due to the more accurate answer.
+</li>
+
+<li>
+In the <a href="/pkg/runtime/"><code>runtime</code></a> package,
+an array <a href="/pkg/runtime/#MemStats.PauseEnd"><code>PauseEnd</code></a>
+has been added to the
+<a href="/pkg/runtime/#MemStats"><code>MemStats</code></a>
+and <a href="/pkg/runtime/#GCStats"><code>GCStats</code></a> structs.
+This array is a circular buffer of times when garbage collection pauses ended.
+The corresponding pause durations are already recorded in
+<a href="/pkg/runtime/#MemStats.PauseNs"><code>PauseNs</code></a>
+</li>
+
+<li>
+The <a href="/pkg/runtime/race/"><code>runtime/race</code></a> package
+now supports FreeBSD, which means the
+<a href="/pkg/cmd/go/"><code>go</code></a> command's <code>-race</code>
+flag now works on FreeBSD.
+</li>
+
+<li>
+The <a href="/pkg/sync/atomic/"><code>sync/atomic</code></a> package
+has a new type, <a href="/pkg/sync/atomic/#Value"><code>Value</code></a>.
+<code>Value</code> provides an efficient mechanism for atomic loads and
+stores of values of arbitrary type.
+</li>
+
+<li>
+In the <a href="/pkg/syscall/"><code>syscall</code></a> package's
+implementation on Linux, the
+<a href="/pkg/syscall/#Setuid"><code>Setuid</code></a>
+and <a href="/pkg/syscall/#Setgid"><code>Setgid</code></a> have been disabled
+because those system calls operate on the calling thread, not the whole process, which is
+different from other platforms and not the expected result.
+</li>
+
+<li>
+The <a href="/pkg/testing/"><code>testing</code></a> package
+has a new facility to provide more control over running a set of tests.
+If the test code contains a function
+<pre>
+func TestMain(m *<a href="/pkg/testing/#M"><code>testing.M</code></a>)
+</pre>
+
+that function will be called instead of running the tests directly.
+The <code>M</code> struct contains methods to access and run the tests.
+</li>
+
+<li>
+Also in the <a href="/pkg/testing/"><code>testing</code></a> package,
+a new <a href="/pkg/testing/#Coverage"><code>Coverage</code></a>
+function reports the current test coverage fraction,
+enabling individual tests to report how much they are contributing to the
+overall coverage.
+</li>
+
+<li>
+The <a href="/pkg/text/scanner/"><code>text/scanner</code></a> package's
+<a href="/pkg/text/scanner/#Scanner"><code>Scanner</code></a> type
+has a new function,
+<a href="/pkg/text/scanner/#Scanner.IsIdentRune"><code>IsIdentRune</code></a>,
+allowing one to control the definition of an identifier when scanning.
+</li>
+
+<li>
+The <a href="/pkg/text/template/"><code>text/template</code></a> package's boolean
+functions <code>eq</code>, <code>lt</code>, and so on have been generalized to allow comparison
+of signed and unsigned integers, simplifying their use in practice.
+(Previously one could only compare values of the same signedness.)
+All negative values compare less than all unsigned values.
+</li>
+
+<li>
+The <code>time</code> package now uses the standard symbol for the micro prefix,
+the micro symbol (U+00B5 'µ'), to print microsecond durations.
+<a href="/pkg/time/#ParseDuration"><code>ParseDuration</code></a> still accepts <code>us</code>
+but the package no longer prints microseconds as <code>us</code>.
+<br>
+<em>Updating</em>: Code that depends on the output format of durations
+but does not use ParseDuration will need to be updated.
+</li>
+
+</ul>
diff --git a/doc/go1.html b/doc/go1.html
new file mode 100644
index 0000000..1665d74
--- /dev/null
+++ b/doc/go1.html
@@ -0,0 +1,2038 @@
+<!--{
+ "Title": "Go 1 Release Notes",
+ "Path": "/doc/go1",
+ "Template": true
+}-->
+
+<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 "/doc/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 "/doc/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<- int = c
+ var crecv <-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 "/doc/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 "/doc/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 "/doc/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 "/doc/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 "/doc/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 "/doc/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 < 5; i++ {
+ for j := 0; j < 5; j++ { // Redeclares j.
+ k += i*j
+ if k > 100 {
+ return // Rejected: j is shadowed here.
+ }
+ }
+ }
+ return // OK: j is not shadowed here.
+ }
+</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 "/doc/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><</code> <code><=</code>
+<code>></code> <code>>=</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="//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="//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>†</sup></li>
+<li><code>go/types</code></li>
+</ul>
+
+<p>
+(<sup>†</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>
+</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>old/regexp</code></li>
+<li><code>old/template</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="//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="//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 get</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 "/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.
+</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 "/doc/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 "/doc/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>
+function and
+<a href="/pkg/crypto/x509/#Certificate.CreateCRL"><code>CreateCRL</code></a>
+method 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 "/doc/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/#CommentGroup.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/http/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>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/#ErrNotExist"><code>ErrNotExist</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 "/doc/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/#pkg-variables"><code>filepath.SkipDir</code></a>
+</p>
+
+{{code "/doc/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="//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>Atoui64(x)</td> <td>ParseUint(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/#pkg-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 "/doc/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="//golang.org/change/2646dc956207">encoding/gob</a> and the <a href="//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>
+
+<p>
+One of the most significant changes associated with Go 1 is the availability
+of prepackaged, downloadable distributions.
+They are available for many combinations of architecture and operating system
+(including Windows) and the list will grow.
+Installation details are described on the
+<a href="/doc/install">Getting Started</a> page, while
+the distributions themselves are listed on the
+<a href="https://golang.org/dl/">downloads page</a>.
diff --git a/doc/go1compat.html b/doc/go1compat.html
new file mode 100644
index 0000000..d800dec
--- /dev/null
+++ b/doc/go1compat.html
@@ -0,0 +1,190 @@
+<!--{
+ "Title": "Go 1 and the Future of Go Programs",
+ "Path": "/doc/go1compat"
+}-->
+
+<h2 id="introduction">Introduction</h2>
+<p>
+The release of Go version 1, Go 1 for short, is a major milestone
+in the development of the language. Go 1 is a stable platform for
+the growth of programs and projects written in Go.
+</p>
+
+<p>
+Go 1 defines two things: first, the specification of the language;
+and second, the specification of a set of core APIs, the "standard
+packages" of the Go library. The Go 1 release includes their
+implementation in the form of two compiler suites (gc and gccgo),
+and the core libraries themselves.
+</p>
+
+<p>
+It is intended that programs written to the Go 1 specification will
+continue to compile and run correctly, unchanged, over the lifetime
+of that specification. At some indefinite point, a Go 2 specification
+may arise, but until that time, Go programs that work today should
+continue to work even as future "point" releases of Go 1 arise (Go
+1.1, Go 1.2, etc.).
+</p>
+
+<p>
+Compatibility is at the source level. Binary compatibility for
+compiled packages is not guaranteed between releases. After a point
+release, Go source will need to be recompiled to link against the
+new release.
+</p>
+
+<p>
+The APIs may grow, acquiring new packages and features, but not in
+a way that breaks existing Go 1 code.
+</p>
+
+<h2 id="expectations">Expectations</h2>
+
+<p>
+Although we expect that the vast majority of programs will maintain
+this compatibility over time, it is impossible to guarantee that
+no future change will break any program. This document is an attempt
+to set expectations for the compatibility of Go 1 software in the
+future. There are a number of ways in which a program that compiles
+and runs today may fail to do so after a future point release. They
+are all unlikely but worth recording.
+</p>
+
+<ul>
+<li>
+Security. A security issue in the specification or implementation
+may come to light whose resolution requires breaking compatibility.
+We reserve the right to address such security issues.
+</li>
+
+<li>
+Unspecified behavior. The Go specification tries to be explicit
+about most properties of the language, but there are some aspects
+that are undefined. Programs that depend on such unspecified behavior
+may break in future releases.
+</li>
+
+<li>
+Specification errors. If it becomes necessary to address an
+inconsistency or incompleteness in the specification, resolving the
+issue could affect the meaning or legality of existing programs.
+We reserve the right to address such issues, including updating the
+implementations. Except for security issues, no incompatible changes
+to the specification would be made.
+</li>
+
+<li>
+Bugs. If a compiler or library has a bug that violates the
+specification, a program that depends on the buggy behavior may
+break if the bug is fixed. We reserve the right to fix such bugs.
+</li>
+
+<li>
+Struct literals. For the addition of features in later point
+releases, it may be necessary to add fields to exported structs in
+the API. Code that uses unkeyed struct literals (such as pkg.T{3,
+"x"}) to create values of these types would fail to compile after
+such a change. However, code that uses keyed literals (pkg.T{A:
+3, B: "x"}) will continue to compile after such a change. We will
+update such data structures in a way that allows keyed struct
+literals to remain compatible, although unkeyed literals may fail
+to compile. (There are also more intricate cases involving nested
+data structures or interfaces, but they have the same resolution.)
+We therefore recommend that composite literals whose type is defined
+in a separate package should use the keyed notation.
+</li>
+
+<li>
+Dot imports. If a program imports a standard package
+using <code>import . "path"</code>, additional names defined in the
+imported package in future releases may conflict with other names
+defined in the program. We do not recommend the use of <code>import .</code>
+outside of tests, and using it may cause a program to fail
+to compile in future releases.
+</li>
+
+<li>
+Use of package <code>unsafe</code>. Packages that import
+<a href="/pkg/unsafe/"><code>unsafe</code></a>
+may depend on internal properties of the Go implementation.
+We reserve the right to make changes to the implementation
+that may break such programs.
+</li>
+
+</ul>
+
+<p>
+Of course, for all of these possibilities, should they arise, we
+would endeavor whenever feasible to update the specification,
+compilers, or libraries without affecting existing code.
+</p>
+
+<p>
+These same considerations apply to successive point releases. For
+instance, code that runs under Go 1.2 should be compatible with Go
+1.2.1, Go 1.3, Go 1.4, etc., although not necessarily with Go 1.1
+since it may use features added only in Go 1.2
+</p>
+
+<p>
+Features added between releases, available in the source repository
+but not part of the numbered binary releases, are under active
+development. No promise of compatibility is made for software using
+such features until they have been released.
+</p>
+
+<p>
+Finally, although it is not a correctness issue, it is possible
+that the performance of a program may be affected by
+changes in the implementation of the compilers or libraries upon
+which it depends.
+No guarantee can be made about the performance of a
+given program between releases.
+</p>
+
+<p>
+Although these expectations apply to Go 1 itself, we hope similar
+considerations would be made for the development of externally
+developed software based on Go 1.
+</p>
+
+<h2 id="subrepos">Sub-repositories</h2>
+
+<p>
+Code in sub-repositories of the main go tree, such as
+<a href="//golang.org/x/net">golang.org/x/net</a>,
+may be developed under
+looser compatibility requirements. However, the sub-repositories
+will be tagged as appropriate to identify versions that are compatible
+with the Go 1 point releases.
+</p>
+
+<h2 id="operating_systems">Operating systems</h2>
+
+<p>
+It is impossible to guarantee long-term compatibility with operating
+system interfaces, which are changed by outside parties.
+The <a href="/pkg/syscall/"><code>syscall</code></a> package
+is therefore outside the purview of the guarantees made here.
+As of Go version 1.4, the <code>syscall</code> package is frozen.
+Any evolution of the system call interface must be supported elsewhere,
+such as in the
+<a href="//golang.org/x/sys">go.sys</a> subrepository.
+For details and background, see
+<a href="//golang.org/s/go1.4-syscall">this document</a>.
+</p>
+
+<h2 id="tools">Tools</h2>
+
+<p>
+Finally, the Go tool chain (compilers, linkers, build tools, and so
+on) are under active development and may change behavior. This
+means, for instance, that scripts that depend on the location and
+properties of the tools may be broken by a point release.
+</p>
+
+<p>
+These caveats aside, we believe that Go 1 will be a firm foundation
+for the development of Go and its ecosystem.
+</p>
diff --git a/doc/go_faq.html b/doc/go_faq.html
new file mode 100644
index 0000000..6b77f1c
--- /dev/null
+++ b/doc/go_faq.html
@@ -0,0 +1,1901 @@
+<!--{
+ "Title": "Frequently Asked Questions (FAQ)",
+ "Path": "/doc/faq"
+}-->
+
+<h2 id="Origins">Origins</h2>
+
+<h3 id="What_is_the_purpose_of_the_project">
+What is the purpose of the project?</h3>
+
+<p>
+No major systems language has emerged in over a decade, but over that time
+the computing landscape has changed tremendously. There are several trends:
+</p>
+
+<ul>
+<li>
+Computers are enormously quicker but software development is not faster.
+<li>
+Dependency management is a big part of software development today but the
+“header files” of languages in the C tradition are antithetical to clean
+dependency analysis—and fast compilation.
+<li>
+There is a growing rebellion against cumbersome type systems like those of
+Java and C++, pushing people towards dynamically typed languages such as
+Python and JavaScript.
+<li>
+Some fundamental concepts such as garbage collection and parallel computation
+are not well supported by popular systems languages.
+<li>
+The emergence of multicore computers has generated worry and confusion.
+</ul>
+
+<p>
+We believe it's worth trying again with a new language, a concurrent,
+garbage-collected language with fast compilation. Regarding the points above:
+</p>
+
+<ul>
+<li>
+It is possible to compile a large Go program in a few seconds on a single computer.
+<li>
+Go provides a model for software construction that makes dependency
+analysis easy and avoids much of the overhead of C-style include files and
+libraries.
+<li>
+Go's type system has no hierarchy, so no time is spent defining the
+relationships between types. Also, although Go has static types the language
+attempts to make types feel lighter weight than in typical OO languages.
+<li>
+Go is fully garbage-collected and provides fundamental support for
+concurrent execution and communication.
+<li>
+By its design, Go proposes an approach for the construction of system
+software on multicore machines.
+</ul>
+
+<p>
+A much more expansive answer to this question is available in the article,
+<a href="//talks.golang.org/2012/splash.article">Go at Google:
+Language Design in the Service of Software Engineering</a>.
+
+<h3 id="What_is_the_status_of_the_project">
+What is the status of the project?</h3>
+
+<p>
+Go became a public open source project on November 10, 2009.
+After a couple of years of very active design and development, stability was called for and
+Go 1 was <a href="//blog.golang.org/2012/03/go-version-1-is-released.html">released</a>
+on March 28, 2012.
+Go 1, which includes a <a href="/ref/spec">language specification</a>,
+<a href="/pkg/">standard libraries</a>,
+and <a href="/cmd/go/">custom tools</a>,
+provides a stable foundation for creating reliable products, projects, and publications.
+</p>
+
+<p>
+With that stability established, we are using Go to develop programs, products, and tools rather than
+actively changing the language and libraries.
+In fact, the purpose of Go 1 is to provide <a href="/doc/go1compat.html">long-term stability</a>.
+Backwards-incompatible changes will not be made to any Go 1 point release.
+We want to use what we have to learn how a future version of Go might look, rather than to play with
+the language underfoot.
+</p>
+
+<p>
+Of course, development will continue on Go itself, but the focus will be on performance, reliability,
+portability and the addition of new functionality such as improved support for internationalization.
+</p>
+
+<p>
+There may well be a Go 2 one day, but not for a few years and it will be influenced by what we learn using Go 1 as it is today.
+</p>
+
+<h3 id="What_is_the_origin_of_the_name">
+What is the origin of the name?</h3>
+
+<p>
+“Ogle” would be a good name for a Go debugger.
+</p>
+
+<h3 id="Whats_the_origin_of_the_mascot">
+What's the origin of the mascot?</h3>
+
+<p>
+The mascot and logo were designed by
+<a href="http://reneefrench.blogspot.com">Renée French</a>, who also designed
+<a href="http://plan9.bell-labs.com/plan9/glenda.html">Glenda</a>,
+the Plan 9 bunny.
+The gopher is derived from one she used for an <a href="http://wfmu.org/">WFMU</a>
+T-shirt design some years ago.
+The logo and mascot are covered by the
+<a href="http://creativecommons.org/licenses/by/3.0/">Creative Commons Attribution 3.0</a>
+license.
+</p>
+
+<h3 id="history">
+What is the history of the project?</h3>
+<p>
+Robert Griesemer, Rob Pike and Ken Thompson started sketching the
+goals for a new language on the white board on September 21, 2007.
+Within a few days the goals had settled into a plan to do something
+and a fair idea of what it would be. Design continued part-time in
+parallel with unrelated work. By January 2008, Ken had started work
+on a compiler with which to explore ideas; it generated C code as its
+output. By mid-year the language had become a full-time project and
+had settled enough to attempt a production compiler. In May 2008,
+Ian Taylor independently started on a GCC front end for Go using the
+draft specification. Russ Cox joined in late 2008 and helped move the language
+and libraries from prototype to reality.
+</p>
+
+<p>
+Go became a public open source project on November 10, 2009.
+Many people from the community have contributed ideas, discussions, and code.
+</p>
+
+<h3 id="creating_a_new_language">
+Why are you creating a new language?</h3>
+<p>
+Go was born out of frustration with existing languages and
+environments for systems programming. Programming had become too
+difficult and the choice of languages was partly to blame. One had to
+choose either efficient compilation, efficient execution, or ease of
+programming; all three were not available in the same mainstream
+language. Programmers who could were choosing ease over
+safety and efficiency by moving to dynamically typed languages such as
+Python and JavaScript rather than C++ or, to a lesser extent, Java.
+</p>
+
+<p>
+Go is an attempt to combine the ease of programming of an interpreted,
+dynamically typed
+language with the efficiency and safety of a statically typed, compiled language.
+It also aims to be modern, with support for networked and multicore
+computing. Finally, it is intended to be <i>fast</i>: it should take
+at most a few seconds to build a large executable on a single computer.
+To meet these goals required addressing a number of
+linguistic issues: an expressive but lightweight type system;
+concurrency and garbage collection; rigid dependency specification;
+and so on. These cannot be addressed well by libraries or tools; a new
+language was called for.
+</p>
+
+<p>
+The article <a href="//talks.golang.org/2012/splash.article">Go at Google</a>
+discusses the background and motivation behind the design of the Go language,
+as well as providing more detail about many of the answers presented in this FAQ.
+</p>
+
+<h3 id="ancestors">
+What are Go's ancestors?</h3>
+<p>
+Go is mostly in the C family (basic syntax),
+with significant input from the Pascal/Modula/Oberon
+family (declarations, packages),
+plus some ideas from languages
+inspired by Tony Hoare's CSP,
+such as Newsqueak and Limbo (concurrency).
+However, it is a new language across the board.
+In every respect the language was designed by thinking
+about what programmers do and how to make programming, at least the
+kind of programming we do, more effective, which means more fun.
+</p>
+
+<h3 id="principles">
+What are the guiding principles in the design?</h3>
+<p>
+Programming today involves too much bookkeeping, repetition, and
+clerical work. As Dick Gabriel says, “Old programs read
+like quiet conversations between a well-spoken research worker and a
+well-studied mechanical colleague, not as a debate with a compiler.
+Who'd have guessed sophistication bought such noise?”
+The sophistication is worthwhile—no one wants to go back to
+the old languages—but can it be more quietly achieved?
+</p>
+<p>
+Go attempts to reduce the amount of typing in both senses of the word.
+Throughout its design, we have tried to reduce clutter and
+complexity. There are no forward declarations and no header files;
+everything is declared exactly once. Initialization is expressive,
+automatic, and easy to use. Syntax is clean and light on keywords.
+Stuttering (<code>foo.Foo* myFoo = new(foo.Foo)</code>) is reduced by
+simple type derivation using the <code>:=</code>
+declare-and-initialize construct. And perhaps most radically, there
+is no type hierarchy: types just <i>are</i>, they don't have to
+announce their relationships. These simplifications allow Go to be
+expressive yet comprehensible without sacrificing, well, sophistication.
+</p>
+<p>
+Another important principle is to keep the concepts orthogonal.
+Methods can be implemented for any type; structures represent data while
+interfaces represent abstraction; and so on. Orthogonality makes it
+easier to understand what happens when things combine.
+</p>
+
+<h2 id="Usage">Usage</h2>
+
+<h3 id="Is_Google_using_go_internally"> Is Google using Go internally?</h3>
+
+<p>
+Yes. There are now several Go programs deployed in
+production inside Google. A public example is the server behind
+<a href="//golang.org">golang.org</a>.
+It's just the <a href="/cmd/godoc"><code>godoc</code></a>
+document server running in a production configuration on
+<a href="https://developers.google.com/appengine/">Google App Engine</a>.
+</p>
+
+<p>
+Other examples include the <a href="//code.google.com/p/vitess/">Vitess</a>
+system for large-scale SQL installations and Google's download server, <code>dl.google.com</code>,
+which delivers Chrome binaries and other large installables such as <code>apt-get</code>
+packages.
+</p>
+
+<h3 id="Do_Go_programs_link_with_Cpp_programs">
+Do Go programs link with C/C++ programs?</h3>
+
+<p>
+There are two Go compiler implementations, <code>gc</code>
+(the <code>6g</code> program and friends) and <code>gccgo</code>.
+<code>Gc</code> uses a different calling convention and linker and can
+therefore only be linked with C programs using the same convention.
+There is such a C compiler but no C++ compiler.
+<code>Gccgo</code> is a GCC front-end that can, with care, be linked with
+GCC-compiled C or C++ programs.
+</p>
+
+<p>
+The <a href="/cmd/cgo/">cgo</a> program provides the mechanism for a
+“foreign function interface” to allow safe calling of
+C libraries from Go code. SWIG extends this capability to C++ libraries.
+</p>
+
+
+<h3 id="Does_Go_support_Google_protocol_buffers">
+Does Go support Google's protocol buffers?</h3>
+
+<p>
+A separate open source project provides the necessary compiler plugin and library.
+It is available at
+<a href="//code.google.com/p/goprotobuf/">code.google.com/p/goprotobuf/</a>
+</p>
+
+
+<h3 id="Can_I_translate_the_Go_home_page">
+Can I translate the Go home page into another language?</h3>
+
+<p>
+Absolutely. We encourage developers to make Go Language sites in their own languages.
+However, if you choose to add the Google logo or branding to your site
+(it does not appear on <a href="//golang.org/">golang.org</a>),
+you will need to abide by the guidelines at
+<a href="//www.google.com/permissions/guidelines.html">www.google.com/permissions/guidelines.html</a>
+</p>
+
+<h2 id="Design">Design</h2>
+
+<h3 id="unicode_identifiers">
+What's up with Unicode identifiers?</h3>
+
+<p>
+It was important to us to extend the space of identifiers from the
+confines of ASCII. Go's rule—identifier characters must be
+letters or digits as defined by Unicode—is simple to understand
+and to implement but has restrictions. Combining characters are
+excluded by design, for instance.
+Until there
+is an agreed external definition of what an identifier might be,
+plus a definition of canonicalization of identifiers that guarantees
+no ambiguity, it seemed better to keep combining characters out of
+the mix. Thus we have a simple rule that can be expanded later
+without breaking programs, one that avoids bugs that would surely arise
+from a rule that admits ambiguous identifiers.
+</p>
+
+<p>
+On a related note, since an exported identifier must begin with an
+upper-case letter, identifiers created from “letters”
+in some languages can, by definition, not be exported. For now the
+only solution is to use something like <code>X日本語</code>, which
+is clearly unsatisfactory; we are considering other options. The
+case-for-visibility rule is unlikely to change however; it's one
+of our favorite features of Go.
+</p>
+
+<h3 id="Why_doesnt_Go_have_feature_X">Why does Go not have feature X?</h3>
+
+<p>
+Every language contains novel features and omits someone's favorite
+feature. Go was designed with an eye on felicity of programming, speed of
+compilation, orthogonality of concepts, and the need to support features
+such as concurrency and garbage collection. Your favorite feature may be
+missing because it doesn't fit, because it affects compilation speed or
+clarity of design, or because it would make the fundamental system model
+too difficult.
+</p>
+
+<p>
+If it bothers you that Go is missing feature <var>X</var>,
+please forgive us and investigate the features that Go does have. You might find that
+they compensate in interesting ways for the lack of <var>X</var>.
+</p>
+
+<h3 id="generics">
+Why does Go not have generic types?</h3>
+<p>
+Generics may well be added at some point. We don't feel an urgency for
+them, although we understand some programmers do.
+</p>
+
+<p>
+Generics are convenient but they come at a cost in
+complexity in the type system and run-time. We haven't yet found a
+design that gives value proportionate to the complexity, although we
+continue to think about it. Meanwhile, Go's built-in maps and slices,
+plus the ability to use the empty interface to construct containers
+(with explicit unboxing) mean in many cases it is possible to write
+code that does what generics would enable, if less smoothly.
+</p>
+
+<p>
+This remains an open issue.
+</p>
+
+<h3 id="exceptions">
+Why does Go not have exceptions?</h3>
+<p>
+We believe that coupling exceptions to a control
+structure, as in the <code>try-catch-finally</code> idiom, results in
+convoluted code. It also tends to encourage programmers to label
+too many ordinary errors, such as failing to open a file, as
+exceptional.
+</p>
+
+<p>
+Go takes a different approach. For plain error handling, Go's multi-value
+returns make it easy to report an error without overloading the return value.
+<a href="/doc/articles/error_handling.html">A canonical error type, coupled
+with Go's other features</a>, makes error handling pleasant but quite different
+from that in other languages.
+</p>
+
+<p>
+Go also has a couple
+of built-in functions to signal and recover from truly exceptional
+conditions. The recovery mechanism is executed only as part of a
+function's state being torn down after an error, which is sufficient
+to handle catastrophe but requires no extra control structures and,
+when used well, can result in clean error-handling code.
+</p>
+
+<p>
+See the <a href="/doc/articles/defer_panic_recover.html">Defer, Panic, and Recover</a> article for details.
+</p>
+
+<h3 id="assertions">
+Why does Go not have assertions?</h3>
+
+<p>
+Go doesn't provide assertions. They are undeniably convenient, but our
+experience has been that programmers use them as a crutch to avoid thinking
+about proper error handling and reporting. Proper error handling means that
+servers continue operation after non-fatal errors instead of crashing.
+Proper error reporting means that errors are direct and to the point,
+saving the programmer from interpreting a large crash trace. Precise
+errors are particularly important when the programmer seeing the errors is
+not familiar with the code.
+</p>
+
+<p>
+We understand that this is a point of contention. There are many things in
+the Go language and libraries that differ from modern practices, simply
+because we feel it's sometimes worth trying a different approach.
+</p>
+
+<h3 id="csp">
+Why build concurrency on the ideas of CSP?</h3>
+<p>
+Concurrency and multi-threaded programming have a reputation
+for difficulty. We believe this is due partly to complex
+designs such as pthreads and partly to overemphasis on low-level details
+such as mutexes, condition variables, and memory barriers.
+Higher-level interfaces enable much simpler code, even if there are still
+mutexes and such under the covers.
+</p>
+
+<p>
+One of the most successful models for providing high-level linguistic support
+for concurrency comes from Hoare's Communicating Sequential Processes, or CSP.
+Occam and Erlang are two well known languages that stem from CSP.
+Go's concurrency primitives derive from a different part of the family tree
+whose main contribution is the powerful notion of channels as first class objects.
+Experience with several earlier languages has shown that the CSP model
+fits well into a procedural language framework.
+</p>
+
+<h3 id="goroutines">
+Why goroutines instead of threads?</h3>
+<p>
+Goroutines are part of making concurrency easy to use. The idea, which has
+been around for a while, is to multiplex independently executing
+functions—coroutines—onto a set of threads.
+When a coroutine blocks, such as by calling a blocking system call,
+the run-time automatically moves other coroutines on the same operating
+system thread to a different, runnable thread so they won't be blocked.
+The programmer sees none of this, which is the point.
+The result, which we call goroutines, can be very cheap: they have little
+overhead beyond the memory for the stack, which is just a few kilobytes.
+</p>
+
+<p>
+To make the stacks small, Go's run-time uses resizable, bounded stacks. A newly
+minted goroutine is given a few kilobytes, which is almost always enough.
+When it isn't, the run-time grows (and shrinks) the memory for storing
+the stack automatically, allowing many goroutines to live in a modest
+amount of memory.
+The CPU overhead averages about three cheap instructions per function call.
+It is practical to create hundreds of thousands of goroutines in the same
+address space.
+If goroutines were just threads, system resources would
+run out at a much smaller number.
+</p>
+
+<h3 id="atomic_maps">
+Why are map operations not defined to be atomic?</h3>
+
+<p>
+After long discussion it was decided that the typical use of maps did not require
+safe access from multiple goroutines, and in those cases where it did, the map was
+probably part of some larger data structure or computation that was already
+synchronized. Therefore requiring that all map operations grab a mutex would slow
+down most programs and add safety to few. This was not an easy decision,
+however, since it means uncontrolled map access can crash the program.
+</p>
+
+<p>
+The language does not preclude atomic map updates. When required, such
+as when hosting an untrusted program, the implementation could interlock
+map access.
+</p>
+
+<h3 id="language_changes">
+Will you accept my language change?</h3>
+
+<p>
+People often suggest improvements to the language—the
+<a href="//groups.google.com/group/golang-nuts">mailing list</a>
+contains a rich history of such discussions—but very few of these changes have
+been accepted.
+</p>
+
+<p>
+Although Go is an open source project, the language and libraries are protected
+by a <a href="/doc/go1compat.html">compatibility promise</a> that prevents
+changes that break existing programs.
+If your proposal violates the Go 1 specification we cannot even entertain the
+idea, regardless of its merit.
+A future major release of Go may be incompatible with Go 1, but we're not ready
+to start talking about what that might be.
+</p>
+
+<p>
+Even if your proposal is compatible with the Go 1 spec, it might
+not be in the spirit of Go's design goals.
+The article <i><a href="//talks.golang.org/2012/splash.article">Go
+at Google: Language Design in the Service of Software Engineering</a></i>
+explains Go's origins and the motivation behind its design.
+</p>
+
+<h2 id="types">Types</h2>
+
+<h3 id="Is_Go_an_object-oriented_language">
+Is Go an object-oriented language?</h3>
+
+<p>
+Yes and no. Although Go has types and methods and allows an
+object-oriented style of programming, there is no type hierarchy.
+The concept of “interface” in Go provides a different approach that
+we believe is easy to use and in some ways more general. There are
+also ways to embed types in other types to provide something
+analogous—but not identical—to subclassing.
+Moreover, methods in Go are more general than in C++ or Java:
+they can be defined for any sort of data, even built-in types such
+as plain, “unboxed” integers.
+They are not restricted to structs (classes).
+</p>
+
+<p>
+Also, the lack of type hierarchy makes “objects” in Go feel much more
+lightweight than in languages such as C++ or Java.
+</p>
+
+<h3 id="How_do_I_get_dynamic_dispatch_of_methods">
+How do I get dynamic dispatch of methods?</h3>
+
+<p>
+The only way to have dynamically dispatched methods is through an
+interface. Methods on a struct or any other concrete type are always resolved statically.
+</p>
+
+<h3 id="inheritance">
+Why is there no type inheritance?</h3>
+<p>
+Object-oriented programming, at least in the best-known languages,
+involves too much discussion of the relationships between types,
+relationships that often could be derived automatically. Go takes a
+different approach.
+</p>
+
+<p>
+Rather than requiring the programmer to declare ahead of time that two
+types are related, in Go a type automatically satisfies any interface
+that specifies a subset of its methods. Besides reducing the
+bookkeeping, this approach has real advantages. Types can satisfy
+many interfaces at once, without the complexities of traditional
+multiple inheritance.
+Interfaces can be very lightweight—an interface with
+one or even zero methods can express a useful concept.
+Interfaces can be added after the fact if a new idea comes along
+or for testing—without annotating the original types.
+Because there are no explicit relationships between types
+and interfaces, there is no type hierarchy to manage or discuss.
+</p>
+
+<p>
+It's possible to use these ideas to construct something analogous to
+type-safe Unix pipes. For instance, see how <code>fmt.Fprintf</code>
+enables formatted printing to any output, not just a file, or how the
+<code>bufio</code> package can be completely separate from file I/O,
+or how the <code>image</code> packages generate compressed
+image files. All these ideas stem from a single interface
+(<code>io.Writer</code>) representing a single method
+(<code>Write</code>). And that's only scratching the surface.
+Go's interfaces have a profound influence on how programs are structured.
+</p>
+
+<p>
+It takes some getting used to but this implicit style of type
+dependency is one of the most productive things about Go.
+</p>
+
+<h3 id="methods_on_basics">
+Why is <code>len</code> a function and not a method?</h3>
+<p>
+We debated this issue but decided
+implementing <code>len</code> and friends as functions was fine in practice and
+didn't complicate questions about the interface (in the Go type sense)
+of basic types.
+</p>
+
+<h3 id="overloading">
+Why does Go not support overloading of methods and operators?</h3>
+<p>
+Method dispatch is simplified if it doesn't need to do type matching as well.
+Experience with other languages told us that having a variety of
+methods with the same name but different signatures was occasionally useful
+but that it could also be confusing and fragile in practice. Matching only by name
+and requiring consistency in the types was a major simplifying decision
+in Go's type system.
+</p>
+
+<p>
+Regarding operator overloading, it seems more a convenience than an absolute
+requirement. Again, things are simpler without it.
+</p>
+
+<h3 id="implements_interface">
+Why doesn't Go have "implements" declarations?</h3>
+
+<p>
+A Go type satisfies an interface by implementing the methods of that interface,
+nothing more. This property allows interfaces to be defined and used without
+having to modify existing code. It enables a kind of structural typing that
+promotes separation of concerns and improves code re-use, and makes it easier
+to build on patterns that emerge as the code develops.
+The semantics of interfaces is one of the main reasons for Go's nimble,
+lightweight feel.
+</p>
+
+<p>
+See the <a href="#inheritance">question on type inheritance</a> for more detail.
+</p>
+
+<h3 id="guarantee_satisfies_interface">
+How can I guarantee my type satisfies an interface?</h3>
+
+<p>
+You can ask the compiler to check that the type <code>T</code> implements the
+interface <code>I</code> by attempting an assignment:
+</p>
+
+<pre>
+type T struct{}
+var _ I = T{} // Verify that T implements I.
+</pre>
+
+<p>
+If <code>T</code> doesn't implement <code>I</code>, the mistake will be caught
+at compile time.
+</p>
+
+<p>
+If you wish the users of an interface to explicitly declare that they implement
+it, you can add a method with a descriptive name to the interface's method set.
+For example:
+</p>
+
+<pre>
+type Fooer interface {
+ Foo()
+ ImplementsFooer()
+}
+</pre>
+
+<p>
+A type must then implement the <code>ImplementsFooer</code> method to be a
+<code>Fooer</code>, clearly documenting the fact and announcing it in
+<a href="/cmd/godoc/">godoc</a>'s output.
+</p>
+
+<pre>
+type Bar struct{}
+func (b Bar) ImplementsFooer() {}
+func (b Bar) Foo() {}
+</pre>
+
+<p>
+Most code doesn't make use of such constraints, since they limit the utility of
+the interface idea. Sometimes, though, they're necessary to resolve ambiguities
+among similar interfaces.
+</p>
+
+<h3 id="t_and_equal_interface">
+Why doesn't type T satisfy the Equal interface?</h3>
+
+<p>
+Consider this simple interface to represent an object that can compare
+itself with another value:
+</p>
+
+<pre>
+type Equaler interface {
+ Equal(Equaler) bool
+}
+</pre>
+
+<p>
+and this type, <code>T</code>:
+</p>
+
+<pre>
+type T int
+func (t T) Equal(u T) bool { return t == u } // does not satisfy Equaler
+</pre>
+
+<p>
+Unlike the analogous situation in some polymorphic type systems,
+<code>T</code> does not implement <code>Equaler</code>.
+The argument type of <code>T.Equal</code> is <code>T</code>,
+not literally the required type <code>Equaler</code>.
+</p>
+
+<p>
+In Go, the type system does not promote the argument of
+<code>Equal</code>; that is the programmer's responsibility, as
+illustrated by the type <code>T2</code>, which does implement
+<code>Equaler</code>:
+</p>
+
+<pre>
+type T2 int
+func (t T2) Equal(u Equaler) bool { return t == u.(T2) } // satisfies Equaler
+</pre>
+
+<p>
+Even this isn't like other type systems, though, because in Go <em>any</em>
+type that satisfies <code>Equaler</code> could be passed as the
+argument to <code>T2.Equal</code>, and at run time we must
+check that the argument is of type <code>T2</code>.
+Some languages arrange to make that guarantee at compile time.
+</p>
+
+<p>
+A related example goes the other way:
+</p>
+
+<pre>
+type Opener interface {
+ Open() Reader
+}
+
+func (t T3) Open() *os.File
+</pre>
+
+<p>
+In Go, <code>T3</code> does not satisfy <code>Opener</code>,
+although it might in another language.
+</p>
+
+<p>
+While it is true that Go's type system does less for the programmer
+in such cases, the lack of subtyping makes the rules about
+interface satisfaction very easy to state: are the function's names
+and signatures exactly those of the interface?
+Go's rule is also easy to implement efficiently.
+We feel these benefits offset the lack of
+automatic type promotion. Should Go one day adopt some form of generic
+typing, we expect there would be a way to express the idea of these
+examples and also have them be statically checked.
+</p>
+
+<h3 id="convert_slice_of_interface">
+Can I convert a []T to an []interface{}?</h3>
+
+<p>
+Not directly, because they do not have the same representation in memory.
+It is necessary to copy the elements individually to the destination
+slice. This example converts a slice of <code>int</code> to a slice of
+<code>interface{}</code>:
+</p>
+
+<pre>
+t := []int{1, 2, 3, 4}
+s := make([]interface{}, len(t))
+for i, v := range t {
+ s[i] = v
+}
+</pre>
+
+<h3 id="nil_error">
+Why is my nil error value not equal to nil?
+</h3>
+
+<p>
+Under the covers, interfaces are implemented as two elements, a type and a value.
+The value, called the interface's dynamic value,
+is an arbitrary concrete value and the type is that of the value.
+For the <code>int</code> value 3, an interface value contains,
+schematically, (<code>int</code>, <code>3</code>).
+</p>
+
+<p>
+An interface value is <code>nil</code> only if the inner value and type are both unset,
+(<code>nil</code>, <code>nil</code>).
+In particular, a <code>nil</code> interface will always hold a <code>nil</code> type.
+If we store a pointer of type <code>*int</code> inside
+an interface value, the inner type will be <code>*int</code> regardless of the value of the pointer:
+(<code>*int</code>, <code>nil</code>).
+Such an interface value will therefore be non-<code>nil</code>
+<em>even when the pointer inside is</em> <code>nil</code>.
+</p>
+
+<p>
+This situation can be confusing, and often arises when a <code>nil</code> value is
+stored inside an interface value such as an <code>error</code> return:
+</p>
+
+<pre>
+func returnsError() error {
+ var p *MyError = nil
+ if bad() {
+ p = ErrBad
+ }
+ return p // Will always return a non-nil error.
+}
+</pre>
+
+<p>
+If all goes well, the function returns a <code>nil</code> <code>p</code>,
+so the return value is an <code>error</code> interface
+value holding (<code>*MyError</code>, <code>nil</code>).
+This means that if the caller compares the returned error to <code>nil</code>,
+it will always look as if there was an error even if nothing bad happened.
+To return a proper <code>nil</code> <code>error</code> to the caller,
+the function must return an explicit <code>nil</code>:
+</p>
+
+
+<pre>
+func returnsError() error {
+ if bad() {
+ return ErrBad
+ }
+ return nil
+}
+</pre>
+
+<p>
+It's a good idea for functions
+that return errors always to use the <code>error</code> type in
+their signature (as we did above) rather than a concrete type such
+as <code>*MyError</code>, to help guarantee the error is
+created correctly. As an example,
+<a href="/pkg/os/#Open"><code>os.Open</code></a>
+returns an <code>error</code> even though, if not <code>nil</code>,
+it's always of concrete type
+<a href="/pkg/os/#PathError"><code>*os.PathError</code></a>.
+</p>
+
+<p>
+Similar situations to those described here can arise whenever interfaces are used.
+Just keep in mind that if any concrete value
+has been stored in the interface, the interface will not be <code>nil</code>.
+For more information, see
+<a href="/doc/articles/laws_of_reflection.html">The Laws of Reflection</a>.
+</p>
+
+
+<h3 id="unions">
+Why are there no untagged unions, as in C?</h3>
+
+<p>
+Untagged unions would violate Go's memory safety
+guarantees.
+</p>
+
+<h3 id="variant_types">
+Why does Go not have variant types?</h3>
+
+<p>
+Variant types, also known as algebraic types, provide a way to specify
+that a value might take one of a set of other types, but only those
+types. A common example in systems programming would specify that an
+error is, say, a network error, a security error or an application
+error and allow the caller to discriminate the source of the problem
+by examining the type of the error. Another example is a syntax tree
+in which each node can be a different type: declaration, statement,
+assignment and so on.
+</p>
+
+<p>
+We considered adding variant types to Go, but after discussion
+decided to leave them out because they overlap in confusing ways
+with interfaces. What would happen if the elements of a variant type
+were themselves interfaces?
+</p>
+
+<p>
+Also, some of what variant types address is already covered by the
+language. The error example is easy to express using an interface
+value to hold the error and a type switch to discriminate cases. The
+syntax tree example is also doable, although not as elegantly.
+</p>
+
+<h2 id="values">Values</h2>
+
+<h3 id="conversions">
+Why does Go not provide implicit numeric conversions?</h3>
+<p>
+The convenience of automatic conversion between numeric types in C is
+outweighed by the confusion it causes. When is an expression unsigned?
+How big is the value? Does it overflow? Is the result portable, independent
+of the machine on which it executes?
+It also complicates the compiler; “the usual arithmetic conversions”
+are not easy to implement and inconsistent across architectures.
+For reasons of portability, we decided to make things clear and straightforward
+at the cost of some explicit conversions in the code.
+The definition of constants in Go—arbitrary precision values free
+of signedness and size annotations—ameliorates matters considerably,
+though.
+</p>
+
+<p>
+A related detail is that, unlike in C, <code>int</code> and <code>int64</code>
+are distinct types even if <code>int</code> is a 64-bit type. The <code>int</code>
+type is generic; if you care about how many bits an integer holds, Go
+encourages you to be explicit.
+</p>
+
+<p>
+A blog post, title <a href="http://blog.golang.org/constants">Constants</a>,
+explores this topic in more detail.
+</p>
+
+<h3 id="builtin_maps">
+Why are maps built in?</h3>
+<p>
+The same reason strings are: they are such a powerful and important data
+structure that providing one excellent implementation with syntactic support
+makes programming more pleasant. We believe that Go's implementation of maps
+is strong enough that it will serve for the vast majority of uses.
+If a specific application can benefit from a custom implementation, it's possible
+to write one but it will not be as convenient syntactically; this seems a reasonable tradeoff.
+</p>
+
+<h3 id="map_keys">
+Why don't maps allow slices as keys?</h3>
+<p>
+Map lookup requires an equality operator, which slices do not implement.
+They don't implement equality because equality is not well defined on such types;
+there are multiple considerations involving shallow vs. deep comparison, pointer vs.
+value comparison, how to deal with recursive types, and so on.
+We may revisit this issue—and implementing equality for slices
+will not invalidate any existing programs—but without a clear idea of what
+equality of slices should mean, it was simpler to leave it out for now.
+</p>
+
+<p>
+In Go 1, unlike prior releases, equality is defined for structs and arrays, so such
+types can be used as map keys. Slices still do not have a definition of equality, though.
+</p>
+
+<h3 id="references">
+Why are maps, slices, and channels references while arrays are values?</h3>
+<p>
+There's a lot of history on that topic. Early on, maps and channels
+were syntactically pointers and it was impossible to declare or use a
+non-pointer instance. Also, we struggled with how arrays should work.
+Eventually we decided that the strict separation of pointers and
+values made the language harder to use. Changing these
+types to act as references to the associated, shared data structures resolved
+these issues. This change added some regrettable complexity to the
+language but had a large effect on usability: Go became a more
+productive, comfortable language when it was introduced.
+</p>
+
+<h2 id="Writing_Code">Writing Code</h2>
+
+<h3 id="How_are_libraries_documented">
+How are libraries documented?</h3>
+
+<p>
+There is a program, <code>godoc</code>, written in Go, that extracts
+package documentation from the source code. It can be used on the
+command line or on the web. An instance is running at
+<a href="/pkg/">golang.org/pkg/</a>.
+In fact, <code>godoc</code> implements the full site at
+<a href="/">golang.org/</a>.
+</p>
+
+<h3 id="Is_there_a_Go_programming_style_guide">
+Is there a Go programming style guide?</h3>
+
+<p>
+Eventually, there may be a small number of rules to guide things
+like naming, layout, and file organization.
+The document <a href="effective_go.html">Effective Go</a>
+contains some style advice.
+More directly, the program <code>gofmt</code> is a pretty-printer
+whose purpose is to enforce layout rules; it replaces the usual
+compendium of do's and don'ts that allows interpretation.
+All the Go code in the repository has been run through <code>gofmt</code>.
+</p>
+
+<p>
+The document titled
+<a href="//golang.org/s/comments">Go Code Review Comments</a>
+is a collection of very short essays about details of Go idiom that are often
+missed by programmers.
+It is a handy reference for people doing code reviews for Go projects.
+</p>
+
+<h3 id="How_do_I_submit_patches_to_the_Go_libraries">
+How do I submit patches to the Go libraries?</h3>
+
+<p>
+The library sources are in the <code>src</code> directory of the repository.
+If you want to make a significant change, please discuss on the mailing list before embarking.
+</p>
+
+<p>
+See the document
+<a href="contribute.html">Contributing to the Go project</a>
+for more information about how to proceed.
+</p>
+
+<h3 id="git_https">
+Why does "go get" use HTTPS when cloning a repository?</h3>
+
+<p>
+Companies often permit outgoing traffic only on the standard TCP ports 80 (HTTP)
+and 443 (HTTPS), blocking outgoing traffic on other ports, including TCP port 9418
+(git) and TCP port 22 (SSH).
+When using HTTPS instead of HTTP, <code>git</code> enforces certificate validation by
+default, providing protection against man-in-the-middle, eavesdropping and tampering attacks.
+The <code>go get</code> command therefore uses HTTPS for safety.
+</p>
+
+<p>
+If you use <code>git</code> and prefer to push changes through SSH using your existing key
+it's easy to work around this. For GitHub, try one of these solutions:
+</p>
+<ul>
+<li>Manually clone the repository in the expected package directory:
+<pre>
+$ cd $GOPATH/src/github.com/username
+$ git clone git@github.com:username/package.git
+</pre>
+</li>
+<li>Force <code>git push</code> to use the <code>SSH</code> protocol by appending
+these two lines to <code>~/.gitconfig</code>:
+<pre>
+[url "git@github.com:"]
+ pushInsteadOf = https://github.com/
+</pre>
+</li>
+</ul>
+
+<h3 id="get_version">
+How should I manage package versions using "go get"?</h3>
+
+<p>
+"Go get" does not have any explicit concept of package versions.
+Versioning is a source of significant complexity, especially in large code bases,
+and we are unaware of any approach that works well at scale in a large enough
+variety of situations to be appropriate to force on all Go users.
+What "go get" and the larger Go toolchain do provide is isolation of
+packages with different import paths.
+For example, the standard library's <code>html/template</code> and <code>text/template</code>
+coexist even though both are "package template".
+This observation leads to some advice for package authors and package users.
+</p>
+
+<p>
+Packages intended for public use should try to maintain backwards compatibility as they evolve.
+The <a href="/doc/go1compat.html">Go 1 compatibility guidelines</a> are a good reference here:
+don't remove exported names, encourage tagged composite literals, and so on.
+If different functionality is required, add a new name instead of changing an old one.
+If a complete break is required, create a new package with a new import path.</p>
+
+<p>
+If you're using an externally supplied package and worry that it might change in
+unexpected ways, the simplest solution is to copy it to your local repository.
+(This is the approach Google takes internally.)
+Store the copy under a new import path that identifies it as a local copy.
+For example, you might copy "original.com/pkg" to "you.com/external/original.com/pkg".
+Keith Rarick's <a href="https://github.com/kr/goven">goven</a> is one tool to help automate this process.
+</p>
+
+<h2 id="Pointers">Pointers and Allocation</h2>
+
+<h3 id="pass_by_value">
+When are function parameters passed by value?</h3>
+
+<p>
+As in all languages in the C family, everything in Go is passed by value.
+That is, a function always gets a copy of the
+thing being passed, as if there were an assignment statement assigning the
+value to the parameter. For instance, passing an <code>int</code> value
+to a function makes a copy of the <code>int</code>, and passing a pointer
+value makes a copy of the pointer, but not the data it points to.
+(See the next section for a discussion of how this affects method receivers.)
+</p>
+
+<p>
+Map and slice values behave like pointers: they are descriptors that
+contain pointers to the underlying map or slice data. Copying a map or
+slice value doesn't copy the data it points to. Copying an interface value
+makes a copy of the thing stored in the interface value. If the interface
+value holds a struct, copying the interface value makes a copy of the
+struct. If the interface value holds a pointer, copying the interface value
+makes a copy of the pointer, but again not the data it points to.
+</p>
+
+<h3 id="pointer_to_interface">
+When should I use a pointer to an interface?</h3>
+
+<p>
+Almost never. Pointers to interface values arise only in rare, tricky situations involving
+disguising an interface value's type for delayed evaluation.
+</p>
+
+<p>
+It is however a common mistake to pass a pointer to an interface value
+to a function expecting an interface. The compiler will complain about this
+error but the situation can still be confusing, because sometimes a
+<a href="#different_method_sets">pointer
+is necessary to satisfy an interface</a>.
+The insight is that although a pointer to a concrete type can satisfy
+an interface, with one exception <em>a pointer to an interface can never satisfy an interface</em>.
+</p>
+
+<p>
+Consider the variable declaration,
+</p>
+
+<pre>
+var w io.Writer
+</pre>
+
+<p>
+The printing function <code>fmt.Fprintf</code> takes as its first argument
+a value that satisfies <code>io.Writer</code>—something that implements
+the canonical <code>Write</code> method. Thus we can write
+</p>
+
+<pre>
+fmt.Fprintf(w, "hello, world\n")
+</pre>
+
+<p>
+If however we pass the address of <code>w</code>, the program will not compile.
+</p>
+
+<pre>
+fmt.Fprintf(&w, "hello, world\n") // Compile-time error.
+</pre>
+
+<p>
+The one exception is that any value, even a pointer to an interface, can be assigned to
+a variable of empty interface type (<code>interface{}</code>).
+Even so, it's almost certainly a mistake if the value is a pointer to an interface;
+the result can be confusing.
+</p>
+
+<h3 id="methods_on_values_or_pointers">
+Should I define methods on values or pointers?</h3>
+
+<pre>
+func (s *MyStruct) pointerMethod() { } // method on pointer
+func (s MyStruct) valueMethod() { } // method on value
+</pre>
+
+<p>
+For programmers unaccustomed to pointers, the distinction between these
+two examples can be confusing, but the situation is actually very simple.
+When defining a method on a type, the receiver (<code>s</code> in the above
+examples) behaves exactly as if it were an argument to the method.
+Whether to define the receiver as a value or as a pointer is the same
+question, then, as whether a function argument should be a value or
+a pointer.
+There are several considerations.
+</p>
+
+<p>
+First, and most important, does the method need to modify the
+receiver?
+If it does, the receiver <em>must</em> be a pointer.
+(Slices and maps act as references, so their story is a little
+more subtle, but for instance to change the length of a slice
+in a method the receiver must still be a pointer.)
+In the examples above, if <code>pointerMethod</code> modifies
+the fields of <code>s</code>,
+the caller will see those changes, but <code>valueMethod</code>
+is called with a copy of the caller's argument (that's the definition
+of passing a value), so changes it makes will be invisible to the caller.
+</p>
+
+<p>
+By the way, pointer receivers are identical to the situation in Java,
+although in Java the pointers are hidden under the covers; it's Go's
+value receivers that are unusual.
+</p>
+
+<p>
+Second is the consideration of efficiency. If the receiver is large,
+a big <code>struct</code> for instance, it will be much cheaper to
+use a pointer receiver.
+</p>
+
+<p>
+Next is consistency. If some of the methods of the type must have
+pointer receivers, the rest should too, so the method set is
+consistent regardless of how the type is used.
+See the section on <a href="#different_method_sets">method sets</a>
+for details.
+</p>
+
+<p>
+For types such as basic types, slices, and small <code>structs</code>,
+a value receiver is very cheap so unless the semantics of the method
+requires a pointer, a value receiver is efficient and clear.
+</p>
+
+
+<h3 id="new_and_make">
+What's the difference between new and make?</h3>
+
+<p>
+In short: <code>new</code> allocates memory, <code>make</code> initializes
+the slice, map, and channel types.
+</p>
+
+<p>
+See the <a href="/doc/effective_go.html#allocation_new">relevant section
+of Effective Go</a> for more details.
+</p>
+
+<h3 id="q_int_sizes">
+What is the size of an <code>int</code> on a 64 bit machine?</h3>
+
+<p>
+The sizes of <code>int</code> and <code>uint</code> are implementation-specific
+but the same as each other on a given platform.
+For portability, code that relies on a particular
+size of value should use an explicitly sized type, like <code>int64</code>.
+Prior to Go 1.1, the 64-bit Go compilers (both gc and gccgo) used
+a 32-bit representation for <code>int</code>. As of Go 1.1 they use
+a 64-bit representation.
+On the other hand, floating-point scalars and complex
+numbers are always sized: <code>float32</code>, <code>complex64</code>,
+etc., because programmers should be aware of precision when using
+floating-point numbers.
+The default size of a floating-point constant is <code>float64</code>.
+</p>
+
+<h3 id="stack_or_heap">
+How do I know whether a variable is allocated on the heap or the stack?</h3>
+
+<p>
+From a correctness standpoint, you don't need to know.
+Each variable in Go exists as long as there are references to it.
+The storage location chosen by the implementation is irrelevant to the
+semantics of the language.
+</p>
+
+<p>
+The storage location does have an effect on writing efficient programs.
+When possible, the Go compilers will allocate variables that are
+local to a function in that function's stack frame. However, if the
+compiler cannot prove that the variable is not referenced after the
+function returns, then the compiler must allocate the variable on the
+garbage-collected heap to avoid dangling pointer errors.
+Also, if a local variable is very large, it might make more sense
+to store it on the heap rather than the stack.
+</p>
+
+<p>
+In the current compilers, if a variable has its address taken, that variable
+is a candidate for allocation on the heap. However, a basic <em>escape
+analysis</em> recognizes some cases when such variables will not
+live past the return from the function and can reside on the stack.
+</p>
+
+<h3 id="Why_does_my_Go_process_use_so_much_virtual_memory">
+Why does my Go process use so much virtual memory?</h3>
+
+<p>
+The Go memory allocator reserves a large region of virtual memory as an arena
+for allocations. This virtual memory is local to the specific Go process; the
+reservation does not deprive other processes of memory.
+</p>
+
+<p>
+To find the amount of actual memory allocated to a Go process, use the Unix
+<code>top</code> command and consult the <code>RES</code> (Linux) or
+<code>RSIZE</code> (Mac OS X) columns.
+<!-- TODO(adg): find out how this works on Windows -->
+</p>
+
+<h2 id="Concurrency">Concurrency</h2>
+
+<h3 id="What_operations_are_atomic_What_about_mutexes">
+What operations are atomic? What about mutexes?</h3>
+
+<p>
+We haven't fully defined it all yet, but some details about atomicity are
+available in the <a href="/ref/mem">Go Memory Model specification</a>.
+</p>
+
+<p>
+Regarding mutexes, the <a href="/pkg/sync">sync</a>
+package implements them, but we hope Go programming style will
+encourage people to try higher-level techniques. In particular, consider
+structuring your program so that only one goroutine at a time is ever
+responsible for a particular piece of data.
+</p>
+
+<p>
+Do not communicate by sharing memory. Instead, share memory by communicating.
+</p>
+
+<p>
+See the <a href="/doc/codewalk/sharemem/">Share Memory By Communicating</a> code walk and its <a href="//blog.golang.org/2010/07/share-memory-by-communicating.html">associated article</a> for a detailed discussion of this concept.
+</p>
+
+<h3 id="Why_no_multi_CPU">
+Why doesn't my multi-goroutine program use multiple CPUs?</h3>
+
+<p>
+You must set the <code>GOMAXPROCS</code> shell environment variable
+or use the similarly-named <a href="/pkg/runtime/#GOMAXPROCS"><code>function</code></a>
+of the runtime package to allow the
+run-time support to utilize more than one OS thread.
+</p>
+
+<p>
+Programs that perform parallel computation should benefit from an increase in
+<code>GOMAXPROCS</code>.
+However, be aware that
+<a href="//blog.golang.org/2013/01/concurrency-is-not-parallelism.html">concurrency
+is not parallelism</a>.
+</p>
+
+<h3 id="Why_GOMAXPROCS">
+Why does using <code>GOMAXPROCS</code> > 1 sometimes make my program
+slower?</h3>
+
+<p>
+It depends on the nature of your program.
+Problems that are intrinsically sequential cannot be sped up by adding
+more goroutines.
+Concurrency only becomes parallelism when the problem is
+intrinsically parallel.
+</p>
+
+<p>
+In practical terms, programs that spend more time
+communicating on channels than doing computation
+will experience performance degradation when using
+multiple OS threads.
+This is because sending data between threads involves switching
+contexts, which has significant cost.
+For instance, the <a href="/ref/spec#An_example_package">prime sieve example</a>
+from the Go specification has no significant parallelism although it launches many
+goroutines; increasing <code>GOMAXPROCS</code> is more likely to slow it down than
+to speed it up.
+</p>
+
+<p>
+Go's goroutine scheduler is not as good as it needs to be. In the future, it
+should recognize such cases and optimize its use of OS threads. For now,
+<code>GOMAXPROCS</code> should be set on a per-application basis.
+</p>
+
+<p>
+For more detail on this topic see the talk entitled,
+<a href="//blog.golang.org/2013/01/concurrency-is-not-parallelism.html">Concurrency
+is not Parallelism</a>.
+
+<h2 id="Functions_methods">Functions and Methods</h2>
+
+<h3 id="different_method_sets">
+Why do T and *T have different method sets?</h3>
+
+<p>
+From the <a href="/ref/spec#Types">Go Spec</a>:
+</p>
+
+<blockquote>
+The method set of any other named type <code>T</code> consists of all methods
+with receiver type <code>T</code>. The method set of the corresponding pointer
+type <code>*T</code> is the set of all methods with receiver <code>*T</code> or
+<code>T</code> (that is, it also contains the method set of <code>T</code>).
+</blockquote>
+
+<p>
+If an interface value contains a pointer <code>*T</code>,
+a method call can obtain a value by dereferencing the pointer,
+but if an interface value contains a value <code>T</code>,
+there is no useful way for a method call to obtain a pointer.
+</p>
+
+<p>
+Even in cases where the compiler could take the address of a value
+to pass to the method, if the method modifies the value the changes
+will be lost in the caller.
+As a common example, this code:
+</p>
+
+<pre>
+var buf bytes.Buffer
+io.Copy(buf, os.Stdin)
+</pre>
+
+<p>
+would copy standard input into a <i>copy</i> of <code>buf</code>,
+not into <code>buf</code> itself.
+This is almost never the desired behavior.
+</p>
+
+<h3 id="closures_and_goroutines">
+What happens with closures running as goroutines?</h3>
+
+<p>
+Some confusion may arise when using closures with concurrency.
+Consider the following program:
+</p>
+
+<pre>
+func main() {
+ done := make(chan bool)
+
+ values := []string{"a", "b", "c"}
+ for _, v := range values {
+ go func() {
+ fmt.Println(v)
+ done <- true
+ }()
+ }
+
+ // wait for all goroutines to complete before exiting
+ for _ = range values {
+ <-done
+ }
+}
+</pre>
+
+<p>
+One might mistakenly expect to see <code>a, b, c</code> as the output.
+What you'll probably see instead is <code>c, c, c</code>. This is because
+each iteration of the loop uses the same instance of the variable <code>v</code>, so
+each closure shares that single variable. When the closure runs, it prints the
+value of <code>v</code> at the time <code>fmt.Println</code> is executed,
+but <code>v</code> may have been modified since the goroutine was launched.
+To help detect this and other problems before they happen, run
+<a href="/cmd/go/#hdr-Run_go_tool_vet_on_packages"><code>go vet</code></a>.
+</p>
+
+<p>
+To bind the current value of <code>v</code> to each closure as it is launched, one
+must modify the inner loop to create a new variable each iteration.
+One way is to pass the variable as an argument to the closure:
+</p>
+
+<pre>
+ for _, v := range values {
+ go func(<b>u</b> string) {
+ fmt.Println(<b>u</b>)
+ done <- true
+ }(<b>v</b>)
+ }
+</pre>
+
+<p>
+In this example, the value of <code>v</code> is passed as an argument to the
+anonymous function. That value is then accessible inside the function as
+the variable <code>u</code>.
+</p>
+
+<p>
+Even easier is just to create a new variable, using a declaration style that may
+seem odd but works fine in Go:
+</p>
+
+<pre>
+ for _, v := range values {
+ <b>v := v</b> // create a new 'v'.
+ go func() {
+ fmt.Println(<b>v</b>)
+ done <- true
+ }()
+ }
+</pre>
+
+<h2 id="Control_flow">Control flow</h2>
+
+<h3 id="Does_Go_have_a_ternary_form">
+Does Go have the <code>?:</code> operator?</h3>
+
+<p>
+There is no ternary form in Go. You may use the following to achieve the same
+result:
+</p>
+
+<pre>
+if expr {
+ n = trueVal
+} else {
+ n = falseVal
+}
+</pre>
+
+<h2 id="Packages_Testing">Packages and Testing</h2>
+
+<h3 id="How_do_I_create_a_multifile_package">
+How do I create a multifile package?</h3>
+
+<p>
+Put all the source files for the package in a directory by themselves.
+Source files can refer to items from different files at will; there is
+no need for forward declarations or a header file.
+</p>
+
+<p>
+Other than being split into multiple files, the package will compile and test
+just like a single-file package.
+</p>
+
+<h3 id="How_do_I_write_a_unit_test">
+How do I write a unit test?</h3>
+
+<p>
+Create a new file ending in <code>_test.go</code> in the same directory
+as your package sources. Inside that file, <code>import "testing"</code>
+and write functions of the form
+</p>
+
+<pre>
+func TestFoo(t *testing.T) {
+ ...
+}
+</pre>
+
+<p>
+Run <code>go test</code> in that directory.
+That script finds the <code>Test</code> functions,
+builds a test binary, and runs it.
+</p>
+
+<p>See the <a href="/doc/code.html">How to Write Go Code</a> document,
+the <a href="/pkg/testing/"><code>testing</code></a> package
+and the <a href="/cmd/go/#hdr-Test_packages"><code>go test</code></a> subcommand for more details.
+</p>
+
+<h3 id="testing_framework">
+Where is my favorite helper function for testing?</h3>
+
+<p>
+Go's standard <a href="/pkg/testing/"><code>testing</code></a> package makes it easy to write unit tests, but it lacks
+features provided in other language's testing frameworks such as assertion functions.
+An <a href="#assertions">earlier section</a> of this document explained why Go
+doesn't have assertions, and
+the same arguments apply to the use of <code>assert</code> in tests.
+Proper error handling means letting other tests run after one has failed, so
+that the person debugging the failure gets a complete picture of what is
+wrong. It is more useful for a test to report that
+<code>isPrime</code> gives the wrong answer for 2, 3, 5, and 7 (or for
+2, 4, 8, and 16) than to report that <code>isPrime</code> gives the wrong
+answer for 2 and therefore no more tests were run. The programmer who
+triggers the test failure may not be familiar with the code that fails.
+Time invested writing a good error message now pays off later when the
+test breaks.
+</p>
+
+<p>
+A related point is that testing frameworks tend to develop into mini-languages
+of their own, with conditionals and controls and printing mechanisms,
+but Go already has all those capabilities; why recreate them?
+We'd rather write tests in Go; it's one fewer language to learn and the
+approach keeps the tests straightforward and easy to understand.
+</p>
+
+<p>
+If the amount of extra code required to write
+good errors seems repetitive and overwhelming, the test might work better if
+table-driven, iterating over a list of inputs and outputs defined
+in a data structure (Go has excellent support for data structure literals).
+The work to write a good test and good error messages will then be amortized over many
+test cases. The standard Go library is full of illustrative examples, such as in
+<a href="/src/fmt/fmt_test.go">the formatting tests for the <code>fmt</code> package</a>.
+</p>
+
+
+<h2 id="Implementation">Implementation</h2>
+
+<h3 id="What_compiler_technology_is_used_to_build_the_compilers">
+What compiler technology is used to build the compilers?</h3>
+
+<p>
+<code>Gccgo</code> has a front end written in C++, with a recursive descent parser coupled to the
+standard GCC back end. <code>Gc</code> is written in C using
+<code>yacc</code>/<code>bison</code> for the parser.
+Although it's a new program, it fits in the Plan 9 C compiler suite
+(<a href="http://plan9.bell-labs.com/sys/doc/compiler.html">http://plan9.bell-labs.com/sys/doc/compiler.html</a>)
+and uses a variant of the Plan 9 loader to generate ELF/Mach-O/PE binaries.
+</p>
+
+<p>
+We considered using LLVM for <code>gc</code> but we felt it was too large and
+slow to meet our performance goals.
+</p>
+
+<p>
+We also considered writing <code>gc</code>, the original Go compiler, in Go itself but
+elected not to do so because of the difficulties of bootstrapping and
+especially of open source distribution—you'd need a Go compiler to
+set up a Go environment. <code>Gccgo</code>, which came later, makes it possible to
+consider writing a compiler in Go.
+A plan to do that by machine translation of the existing compiler is under development.
+<a href="http://golang.org/s/go13compiler">A separate document</a>
+explains the reason for this approach.
+</p>
+
+<p>
+That plan aside,
+Go is a
+fine language in which to implement a self-hosting compiler: a native lexer and
+parser are already available in the <a href="/pkg/go/"><code>go</code></a> package
+and a separate type checking
+<a href="http://godoc.org/golang.org/x/tools/go/types">package</a>
+has also been written.
+</p>
+
+<h3 id="How_is_the_run_time_support_implemented">
+How is the run-time support implemented?</h3>
+
+<p>
+Again due to bootstrapping issues, the run-time code was originally written mostly in C (with a
+tiny bit of assembler) although much of it has been translated to Go since then
+and one day all of it might be (except for the assembler bits).
+<code>Gccgo</code>'s run-time support uses <code>glibc</code>.
+<code>Gc</code> uses a custom C library to keep the footprint under
+control; it is
+compiled with a version of the Plan 9 C compiler that supports
+resizable stacks for goroutines.
+The <code>gccgo</code> compiler implements these on Linux only,
+using a technique called segmented stacks,
+supported by recent modifications to the gold linker.
+</p>
+
+<h3 id="Why_is_my_trivial_program_such_a_large_binary">
+Why is my trivial program such a large binary?</h3>
+
+<p>
+The linkers in the gc tool chain (<code>5l</code>, <code>6l</code>, and <code>8l</code>)
+do static linking. All Go binaries therefore include the Go
+run-time, along with the run-time type information necessary to support dynamic
+type checks, reflection, and even panic-time stack traces.
+</p>
+
+<p>
+A simple C "hello, world" program compiled and linked statically using gcc
+on Linux is around 750 kB,
+including an implementation of <code>printf</code>.
+An equivalent Go program using <code>fmt.Printf</code>
+is around 1.9 MB, but
+that includes more powerful run-time support and type information.
+</p>
+
+<h3 id="unused_variables_and_imports">
+Can I stop these complaints about my unused variable/import?</h3>
+
+<p>
+The presence of an unused variable may indicate a bug, while
+unused imports just slow down compilation,
+an effect that can become substantial as a program accumulates
+code and programmers over time.
+For these reasons, Go refuses to compile programs with unused
+variables or imports,
+trading short-term convenience for long-term build speed and
+program clarity.
+</p>
+
+<p>
+Still, when developing code, it's common to create these situations
+temporarily and it can be annoying to have to edit them out before the
+program will compile.
+</p>
+
+<p>
+Some have asked for a compiler option to turn those checks off
+or at least reduce them to warnings.
+Such an option has not been added, though,
+because compiler options should not affect the semantics of the
+language and because the Go compiler does not report warnings, only
+errors that prevent compilation.
+</p>
+
+<p>
+There are two reasons for having no warnings. First, if it's worth
+complaining about, it's worth fixing in the code. (And if it's not
+worth fixing, it's not worth mentioning.) Second, having the compiler
+generate warnings encourages the implementation to warn about weak
+cases that can make compilation noisy, masking real errors that
+<em>should</em> be fixed.
+</p>
+
+<p>
+It's easy to address the situation, though. Use the blank identifier
+to let unused things persist while you're developing.
+</p>
+
+<pre>
+import "unused"
+
+// This declaration marks the import as used by referencing an
+// item from the package.
+var _ = unused.Item // TODO: Delete before committing!
+
+func main() {
+ debugData := debug.Profile()
+ _ = debugData // Used only during debugging.
+ ....
+}
+</pre>
+
+<p>
+Nowadays, most Go programmers use a tool,
+<a href="http://godoc.org/golang.org/x/tools/cmd/goimports">goimports</a>,
+which automatically rewrites a Go source file to have the correct imports,
+eliminating the unused imports issue in practice.
+This program is easily connected to most editors to run automatically when a Go source file is written.
+</p>
+
+<h2 id="Performance">Performance</h2>
+
+<h3 id="Why_does_Go_perform_badly_on_benchmark_x">
+Why does Go perform badly on benchmark X?</h3>
+
+<p>
+One of Go's design goals is to approach the performance of C for comparable
+programs, yet on some benchmarks it does quite poorly, including several
+in <a href="/test/bench/shootout/">test/bench/shootout</a>. The slowest depend on libraries
+for which versions of comparable performance are not available in Go.
+For instance, <a href="/test/bench/shootout/pidigits.go">pidigits.go</a>
+depends on a multi-precision math package, and the C
+versions, unlike Go's, use <a href="http://gmplib.org/">GMP</a> (which is
+written in optimized assembler).
+Benchmarks that depend on regular expressions
+(<a href="/test/bench/shootout/regex-dna.go">regex-dna.go</a>, for instance) are
+essentially comparing Go's native <a href="/pkg/regexp">regexp package</a> to
+mature, highly optimized regular expression libraries like PCRE.
+</p>
+
+<p>
+Benchmark games are won by extensive tuning and the Go versions of most
+of the benchmarks need attention. If you measure comparable C
+and Go programs
+(<a href="/test/bench/shootout/reverse-complement.go">reverse-complement.go</a> is one example), you'll see the two
+languages are much closer in raw performance than this suite would
+indicate.
+</p>
+
+<p>
+Still, there is room for improvement. The compilers are good but could be
+better, many libraries need major performance work, and the garbage collector
+isn't fast enough yet. (Even if it were, taking care not to generate unnecessary
+garbage can have a huge effect.)
+</p>
+
+<p>
+In any case, Go can often be very competitive.
+There has been significant improvement in the performance of many programs
+as the language and tools have developed.
+See the blog post about
+<a href="//blog.golang.org/2011/06/profiling-go-programs.html">profiling
+Go programs</a> for an informative example.
+
+<h2 id="change_from_c">Changes from C</h2>
+
+<h3 id="different_syntax">
+Why is the syntax so different from C?</h3>
+<p>
+Other than declaration syntax, the differences are not major and stem
+from two desires. First, the syntax should feel light, without too
+many mandatory keywords, repetition, or arcana. Second, the language
+has been designed to be easy to analyze
+and can be parsed without a symbol table. This makes it much easier
+to build tools such as debuggers, dependency analyzers, automated
+documentation extractors, IDE plug-ins, and so on. C and its
+descendants are notoriously difficult in this regard.
+</p>
+
+<h3 id="declarations_backwards">
+Why are declarations backwards?</h3>
+<p>
+They're only backwards if you're used to C. In C, the notion is that a
+variable is declared like an expression denoting its type, which is a
+nice idea, but the type and expression grammars don't mix very well and
+the results can be confusing; consider function pointers. Go mostly
+separates expression and type syntax and that simplifies things (using
+prefix <code>*</code> for pointers is an exception that proves the rule). In C,
+the declaration
+</p>
+<pre>
+ int* a, b;
+</pre>
+<p>
+declares <code>a</code> to be a pointer but not <code>b</code>; in Go
+</p>
+<pre>
+ var a, b *int
+</pre>
+<p>
+declares both to be pointers. This is clearer and more regular.
+Also, the <code>:=</code> short declaration form argues that a full variable
+declaration should present the same order as <code>:=</code> so
+</p>
+<pre>
+ var a uint64 = 1
+</pre>
+<p>
+has the same effect as
+</p>
+<pre>
+ a := uint64(1)
+</pre>
+<p>
+Parsing is also simplified by having a distinct grammar for types that
+is not just the expression grammar; keywords such as <code>func</code>
+and <code>chan</code> keep things clear.
+</p>
+
+<p>
+See the article about
+<a href="/doc/articles/gos_declaration_syntax.html">Go's Declaration Syntax</a>
+for more details.
+</p>
+
+<h3 id="no_pointer_arithmetic">
+Why is there no pointer arithmetic?</h3>
+<p>
+Safety. Without pointer arithmetic it's possible to create a
+language that can never derive an illegal address that succeeds
+incorrectly. Compiler and hardware technology have advanced to the
+point where a loop using array indices can be as efficient as a loop
+using pointer arithmetic. Also, the lack of pointer arithmetic can
+simplify the implementation of the garbage collector.
+</p>
+
+<h3 id="inc_dec">
+Why are <code>++</code> and <code>--</code> statements and not expressions? And why postfix, not prefix?</h3>
+<p>
+Without pointer arithmetic, the convenience value of pre- and postfix
+increment operators drops. By removing them from the expression
+hierarchy altogether, expression syntax is simplified and the messy
+issues around order of evaluation of <code>++</code> and <code>--</code>
+(consider <code>f(i++)</code> and <code>p[i] = q[++i]</code>)
+are eliminated as well. The simplification is
+significant. As for postfix vs. prefix, either would work fine but
+the postfix version is more traditional; insistence on prefix arose
+with the STL, a library for a language whose name contains, ironically, a
+postfix increment.
+</p>
+
+<h3 id="semicolons">
+Why are there braces but no semicolons? And why can't I put the opening
+brace on the next line?</h3>
+<p>
+Go uses brace brackets for statement grouping, a syntax familiar to
+programmers who have worked with any language in the C family.
+Semicolons, however, are for parsers, not for people, and we wanted to
+eliminate them as much as possible. To achieve this goal, Go borrows
+a trick from BCPL: the semicolons that separate statements are in the
+formal grammar but are injected automatically, without lookahead, by
+the lexer at the end of any line that could be the end of a statement.
+This works very well in practice but has the effect that it forces a
+brace style. For instance, the opening brace of a function cannot
+appear on a line by itself.
+</p>
+
+<p>
+Some have argued that the lexer should do lookahead to permit the
+brace to live on the next line. We disagree. Since Go code is meant
+to be formatted automatically by
+<a href="/cmd/gofmt/"><code>gofmt</code></a>,
+<i>some</i> style must be chosen. That style may differ from what
+you've used in C or Java, but Go is a new language and
+<code>gofmt</code>'s style is as good as any other. More
+important—much more important—the advantages of a single,
+programmatically mandated format for all Go programs greatly outweigh
+any perceived disadvantages of the particular style.
+Note too that Go's style means that an interactive implementation of
+Go can use the standard syntax one line at a time without special rules.
+</p>
+
+<h3 id="garbage_collection">
+Why do garbage collection? Won't it be too expensive?</h3>
+<p>
+One of the biggest sources of bookkeeping in systems programs is
+memory management. We feel it's critical to eliminate that
+programmer overhead, and advances in garbage collection
+technology in the last few years give us confidence that we can
+implement it with low enough overhead and no significant
+latency.
+</p>
+
+<p>
+Another point is that a large part of the difficulty of concurrent
+and multi-threaded programming is memory management;
+as objects get passed among threads it becomes cumbersome
+to guarantee they become freed safely.
+Automatic garbage collection makes concurrent code far easier to write.
+Of course, implementing garbage collection in a concurrent environment is
+itself a challenge, but meeting it once rather than in every
+program helps everyone.
+</p>
+
+<p>
+Finally, concurrency aside, garbage collection makes interfaces
+simpler because they don't need to specify how memory is managed across them.
+</p>
+
+<p>
+The current implementation is a parallel mark-and-sweep
+collector but a future version might take a different approach.
+</p>
+
+<p>
+On the topic of performance, keep in mind that Go gives the programmer
+considerable control over memory layout and allocation, much more than
+is typical in garbage-collected languages. A careful programmer can reduce
+the garbage collection overhead dramatically by using the language well;
+see the article about
+<a href="//blog.golang.org/2011/06/profiling-go-programs.html">profiling
+Go programs</a> for a worked example, including a demonstration of Go's
+profiling tools.
+</p>
diff --git a/doc/go_mem.html b/doc/go_mem.html
new file mode 100644
index 0000000..5dd48ff
--- /dev/null
+++ b/doc/go_mem.html
@@ -0,0 +1,566 @@
+<!--{
+ "Title": "The Go Memory Model",
+ "Subtitle": "Version of May 31, 2014",
+ "Path": "/ref/mem"
+}-->
+
+<style>
+p.rule {
+ font-style: italic;
+}
+span.event {
+ font-style: italic;
+}
+</style>
+
+<h2>Introduction</h2>
+
+<p>
+The Go memory model specifies the conditions under which
+reads of a variable in one goroutine can be guaranteed to
+observe values produced by writes to the same variable in a different goroutine.
+</p>
+
+
+<h2>Advice</h2>
+
+<p>
+Programs that modify data being simultaneously accessed by multiple goroutines
+must serialize such access.
+</p>
+
+<p>
+To serialize access, protect the data with channel operations or other synchronization primitives
+such as those in the <a href="/pkg/sync/"><code>sync</code></a>
+and <a href="/pkg/sync/atomic/"><code>sync/atomic</code></a> packages.
+</p>
+
+<p>
+If you must read the rest of this document to understand the behavior of your program,
+you are being too clever.
+</p>
+
+<p>
+Don't be clever.
+</p>
+
+<h2>Happens Before</h2>
+
+<p>
+Within a single goroutine, reads and writes must behave
+as if they executed in the order specified by the program.
+That is, compilers and processors may reorder the reads and writes
+executed within a single goroutine only when the reordering
+does not change the behavior within that goroutine
+as defined by the language specification.
+Because of this reordering, the execution order observed
+by one goroutine may differ from the order perceived
+by another. For example, if one goroutine
+executes <code>a = 1; b = 2;</code>, another might observe
+the updated value of <code>b</code> before the updated value of <code>a</code>.
+</p>
+
+<p>
+To specify the requirements of reads and writes, we define
+<i>happens before</i>, a partial order on the execution
+of memory operations in a Go program. If event <span class="event">e<sub>1</sub></span> happens
+before event <span class="event">e<sub>2</sub></span>, then we say that <span class="event">e<sub>2</sub></span> happens after <span class="event">e<sub>1</sub></span>.
+Also, if <span class="event">e<sub>1</sub></span> does not happen before <span class="event">e<sub>2</sub></span> and does not happen
+after <span class="event">e<sub>2</sub></span>, then we say that <span class="event">e<sub>1</sub></span> and <span class="event">e<sub>2</sub></span> happen concurrently.
+</p>
+
+<p class="rule">
+Within a single goroutine, the happens-before order is the
+order expressed by the program.
+</p>
+
+<p>
+A read <span class="event">r</span> of a variable <code>v</code> is <i>allowed</i> to observe a write <span class="event">w</span> to <code>v</code>
+if both of the following hold:
+</p>
+
+<ol>
+<li><span class="event">r</span> does not happen before <span class="event">w</span>.</li>
+<li>There is no other write <span class="event">w'</span> to <code>v</code> that happens
+ after <span class="event">w</span> but before <span class="event">r</span>.</li>
+</ol>
+
+<p>
+To guarantee that a read <span class="event">r</span> of a variable <code>v</code> observes a
+particular write <span class="event">w</span> to <code>v</code>, ensure that <span class="event">w</span> is the only
+write <span class="event">r</span> is allowed to observe.
+That is, <span class="event">r</span> is <i>guaranteed</i> to observe <span class="event">w</span> if both of the following hold:
+</p>
+
+<ol>
+<li><span class="event">w</span> happens before <span class="event">r</span>.</li>
+<li>Any other write to the shared variable <code>v</code>
+either happens before <span class="event">w</span> or after <span class="event">r</span>.</li>
+</ol>
+
+<p>
+This pair of conditions is stronger than the first pair;
+it requires that there are no other writes happening
+concurrently with <span class="event">w</span> or <span class="event">r</span>.
+</p>
+
+<p>
+Within a single goroutine,
+there is no concurrency, so the two definitions are equivalent:
+a read <span class="event">r</span> observes the value written by the most recent write <span class="event">w</span> to <code>v</code>.
+When multiple goroutines access a shared variable <code>v</code>,
+they must use synchronization events to establish
+happens-before conditions that ensure reads observe the
+desired writes.
+</p>
+
+<p>
+The initialization of variable <code>v</code> with the zero value
+for <code>v</code>'s type behaves as a write in the memory model.
+</p>
+
+<p>
+Reads and writes of values larger than a single machine word
+behave as multiple machine-word-sized operations in an
+unspecified order.
+</p>
+
+<h2>Synchronization</h2>
+
+<h3>Initialization</h3>
+
+<p>
+Program initialization runs in a single goroutine,
+but that goroutine may create other goroutines,
+which run concurrently.
+</p>
+
+<p class="rule">
+If a package <code>p</code> imports package <code>q</code>, the completion of
+<code>q</code>'s <code>init</code> functions happens before the start of any of <code>p</code>'s.
+</p>
+
+<p class="rule">
+The start of the function <code>main.main</code> happens after
+all <code>init</code> functions have finished.
+</p>
+
+<h3>Goroutine creation</h3>
+
+<p class="rule">
+The <code>go</code> statement that starts a new goroutine
+happens before the goroutine's execution begins.
+</p>
+
+<p>
+For example, in this program:
+</p>
+
+<pre>
+var a string
+
+func f() {
+ print(a)
+}
+
+func hello() {
+ a = "hello, world"
+ go f()
+}
+</pre>
+
+<p>
+calling <code>hello</code> will print <code>"hello, world"</code>
+at some point in the future (perhaps after <code>hello</code> has returned).
+</p>
+
+<h3>Goroutine destruction</h3>
+
+<p>
+The exit of a goroutine is not guaranteed to happen before
+any event in the program. For example, in this program:
+</p>
+
+<pre>
+var a string
+
+func hello() {
+ go func() { a = "hello" }()
+ print(a)
+}
+</pre>
+
+<p>
+the assignment to <code>a</code> is not followed by
+any synchronization event, so it is not guaranteed to be
+observed by any other goroutine.
+In fact, an aggressive compiler might delete the entire <code>go</code> statement.
+</p>
+
+<p>
+If the effects of a goroutine must be observed by another goroutine,
+use a synchronization mechanism such as a lock or channel
+communication to establish a relative ordering.
+</p>
+
+<h3>Channel communication</h3>
+
+<p>
+Channel communication is the main method of synchronization
+between goroutines. Each send on a particular channel
+is matched to a corresponding receive from that channel,
+usually in a different goroutine.
+</p>
+
+<p class="rule">
+A send on a channel happens before the corresponding
+receive from that channel completes.
+</p>
+
+<p>
+This program:
+</p>
+
+<pre>
+var c = make(chan int, 10)
+var a string
+
+func f() {
+ a = "hello, world"
+ c <- 0
+}
+
+func main() {
+ go f()
+ <-c
+ print(a)
+}
+</pre>
+
+<p>
+is guaranteed to print <code>"hello, world"</code>. The write to <code>a</code>
+happens before the send on <code>c</code>, which happens before
+the corresponding receive on <code>c</code> completes, which happens before
+the <code>print</code>.
+</p>
+
+<p class="rule">
+The closing of a channel happens before a receive that returns a zero value
+because the channel is closed.
+</p>
+
+<p>
+In the previous example, replacing
+<code>c <- 0</code> with <code>close(c)</code>
+yields a program with the same guaranteed behavior.
+</p>
+
+<p class="rule">
+A receive from an unbuffered channel happens before
+the send on that channel completes.
+</p>
+
+<p>
+This program (as above, but with the send and receive statements swapped and
+using an unbuffered channel):
+</p>
+
+<pre>
+var c = make(chan int)
+var a string
+
+func f() {
+ a = "hello, world"
+ <-c
+}
+</pre>
+
+<pre>
+func main() {
+ go f()
+ c <- 0
+ print(a)
+}
+</pre>
+
+<p>
+is also guaranteed to print <code>"hello, world"</code>. The write to <code>a</code>
+happens before the receive on <code>c</code>, which happens before
+the corresponding send on <code>c</code> completes, which happens
+before the <code>print</code>.
+</p>
+
+<p>
+If the channel were buffered (e.g., <code>c = make(chan int, 1)</code>)
+then the program would not be guaranteed to print
+<code>"hello, world"</code>. (It might print the empty string,
+crash, or do something else.)
+</p>
+
+<p class="rule">
+The <i>k</i>th receive on a channel with capacity <i>C</i> happens before the <i>k</i>+<i>C</i>th send from that channel completes.
+</p>
+
+<p>
+This rule generalizes the previous rule to buffered channels.
+It allows a counting semaphore to be modeled by a buffered channel:
+the number of items in the channel corresponds to the number of active uses,
+the capacity of the channel corresponds to the maximum number of simultaneous uses,
+sending an item acquires the semaphore, and receiving an item releases
+the semaphore.
+This is a common idiom for limiting concurrency.
+</p>
+
+<p>
+This program starts a goroutine for every entry in the work list, but the
+goroutines coordinate using the <code>limit</code> channel to ensure
+that at most three are running work functions at a time.
+</p>
+
+<pre>
+var limit = make(chan int, 3)
+
+func main() {
+ for _, w := range work {
+ go func() {
+ limit <- 1
+ w()
+ <-limit
+ }()
+ }
+ select{}
+}
+</pre>
+
+<h3>Locks</h3>
+
+<p>
+The <code>sync</code> package implements two lock data types,
+<code>sync.Mutex</code> and <code>sync.RWMutex</code>.
+</p>
+
+<p class="rule">
+For any <code>sync.Mutex</code> or <code>sync.RWMutex</code> variable <code>l</code> and <i>n</i> < <i>m</i>,
+call <i>n</i> of <code>l.Unlock()</code> happens before call <i>m</i> of <code>l.Lock()</code> returns.
+</p>
+
+<p>
+This program:
+</p>
+
+<pre>
+var l sync.Mutex
+var a string
+
+func f() {
+ a = "hello, world"
+ l.Unlock()
+}
+
+func main() {
+ l.Lock()
+ go f()
+ l.Lock()
+ print(a)
+}
+</pre>
+
+<p>
+is guaranteed to print <code>"hello, world"</code>.
+The first call to <code>l.Unlock()</code> (in <code>f</code>) happens
+before the second call to <code>l.Lock()</code> (in <code>main</code>) returns,
+which happens before the <code>print</code>.
+</p>
+
+<p class="rule">
+For any call to <code>l.RLock</code> on a <code>sync.RWMutex</code> variable <code>l</code>,
+there is an <i>n</i> such that the <code>l.RLock</code> happens (returns) after call <i>n</i> to
+<code>l.Unlock</code> and the matching <code>l.RUnlock</code> happens
+before call <i>n</i>+1 to <code>l.Lock</code>.
+</p>
+
+<h3>Once</h3>
+
+<p>
+The <code>sync</code> package provides a safe mechanism for
+initialization in the presence of multiple goroutines
+through the use of the <code>Once</code> type.
+Multiple threads can execute <code>once.Do(f)</code> for a particular <code>f</code>,
+but only one will run <code>f()</code>, and the other calls block
+until <code>f()</code> has returned.
+</p>
+
+<p class="rule">
+A single call of <code>f()</code> from <code>once.Do(f)</code> happens (returns) before any call of <code>once.Do(f)</code> returns.
+</p>
+
+<p>
+In this program:
+</p>
+
+<pre>
+var a string
+var once sync.Once
+
+func setup() {
+ a = "hello, world"
+}
+
+func doprint() {
+ once.Do(setup)
+ print(a)
+}
+
+func twoprint() {
+ go doprint()
+ go doprint()
+}
+</pre>
+
+<p>
+calling <code>twoprint</code> causes <code>"hello, world"</code> to be printed twice.
+The first call to <code>doprint</code> runs <code>setup</code> once.
+</p>
+
+<h2>Incorrect synchronization</h2>
+
+<p>
+Note that a read <span class="event">r</span> may observe the value written by a write <span class="event">w</span>
+that happens concurrently with <span class="event">r</span>.
+Even if this occurs, it does not imply that reads happening after <span class="event">r</span>
+will observe writes that happened before <span class="event">w</span>.
+</p>
+
+<p>
+In this program:
+</p>
+
+<pre>
+var a, b int
+
+func f() {
+ a = 1
+ b = 2
+}
+
+func g() {
+ print(b)
+ print(a)
+}
+
+func main() {
+ go f()
+ g()
+}
+</pre>
+
+<p>
+it can happen that <code>g</code> prints <code>2</code> and then <code>0</code>.
+</p>
+
+<p>
+This fact invalidates a few common idioms.
+</p>
+
+<p>
+Double-checked locking is an attempt to avoid the overhead of synchronization.
+For example, the <code>twoprint</code> program might be
+incorrectly written as:
+</p>
+
+<pre>
+var a string
+var done bool
+
+func setup() {
+ a = "hello, world"
+ done = true
+}
+
+func doprint() {
+ if !done {
+ once.Do(setup)
+ }
+ print(a)
+}
+
+func twoprint() {
+ go doprint()
+ go doprint()
+}
+</pre>
+
+<p>
+but there is no guarantee that, in <code>doprint</code>, observing the write to <code>done</code>
+implies observing the write to <code>a</code>. This
+version can (incorrectly) print an empty string
+instead of <code>"hello, world"</code>.
+</p>
+
+<p>
+Another incorrect idiom is busy waiting for a value, as in:
+</p>
+
+<pre>
+var a string
+var done bool
+
+func setup() {
+ a = "hello, world"
+ done = true
+}
+
+func main() {
+ go setup()
+ for !done {
+ }
+ print(a)
+}
+</pre>
+
+<p>
+As before, there is no guarantee that, in <code>main</code>,
+observing the write to <code>done</code>
+implies observing the write to <code>a</code>, so this program could
+print an empty string too.
+Worse, there is no guarantee that the write to <code>done</code> will ever
+be observed by <code>main</code>, since there are no synchronization
+events between the two threads. The loop in <code>main</code> is not
+guaranteed to finish.
+</p>
+
+<p>
+There are subtler variants on this theme, such as this program.
+</p>
+
+<pre>
+type T struct {
+ msg string
+}
+
+var g *T
+
+func setup() {
+ t := new(T)
+ t.msg = "hello, world"
+ g = t
+}
+
+func main() {
+ go setup()
+ for g == nil {
+ }
+ print(g.msg)
+}
+</pre>
+
+<p>
+Even if <code>main</code> observes <code>g != nil</code> and exits its loop,
+there is no guarantee that it will observe the initialized
+value for <code>g.msg</code>.
+</p>
+
+<p>
+In all these examples, the solution is the same:
+use explicit synchronization.
+</p>
diff --git a/doc/go_spec.html b/doc/go_spec.html
new file mode 100644
index 0000000..ca0deb5
--- /dev/null
+++ b/doc/go_spec.html
@@ -0,0 +1,6322 @@
+<!--{
+ "Title": "The Go Programming Language Specification",
+ "Subtitle": "Version of November 11, 2014",
+ "Path": "/ref/spec"
+}-->
+
+<!--
+TODO
+[ ] need language about function/method calls and parameter passing rules
+[ ] last paragraph of #Assignments (constant promotion) should be elsewhere
+ and mention assignment to empty interface.
+[ ] need to say something about "scope" of selectors?
+[ ] clarify what a field name is in struct declarations
+ (struct{T} vs struct {T T} vs struct {t T})
+[ ] need explicit language about the result type of operations
+[ ] should probably write something about evaluation order of statements even
+ though obvious
+[ ] in Selectors section, clarify what receiver value is passed in method invocations
+-->
+
+
+<h2 id="Introduction">Introduction</h2>
+
+<p>
+This is a reference manual for the Go programming language. For
+more information and other documents, see <a href="/">golang.org</a>.
+</p>
+
+<p>
+Go is a general-purpose language designed with systems programming
+in mind. It is strongly typed and garbage-collected and has explicit
+support for concurrent programming. Programs are constructed from
+<i>packages</i>, whose properties allow efficient management of
+dependencies. The existing implementations use a traditional
+compile/link model to generate executable binaries.
+</p>
+
+<p>
+The grammar is compact and regular, allowing for easy analysis by
+automatic tools such as integrated development environments.
+</p>
+
+<h2 id="Notation">Notation</h2>
+<p>
+The syntax is specified using Extended Backus-Naur Form (EBNF):
+</p>
+
+<pre class="grammar">
+Production = production_name "=" [ Expression ] "." .
+Expression = Alternative { "|" Alternative } .
+Alternative = Term { Term } .
+Term = production_name | token [ "…" token ] | Group | Option | Repetition .
+Group = "(" Expression ")" .
+Option = "[" Expression "]" .
+Repetition = "{" Expression "}" .
+</pre>
+
+<p>
+Productions are expressions constructed from terms and the following
+operators, in increasing precedence:
+</p>
+<pre class="grammar">
+| alternation
+() grouping
+[] option (0 or 1 times)
+{} repetition (0 to n times)
+</pre>
+
+<p>
+Lower-case production names are used to identify lexical tokens.
+Non-terminals are in CamelCase. Lexical tokens are enclosed in
+double quotes <code>""</code> or back quotes <code>``</code>.
+</p>
+
+<p>
+The form <code>a … b</code> represents the set of characters from
+<code>a</code> through <code>b</code> as alternatives. The horizontal
+ellipsis <code>…</code> is also used elsewhere in the spec to informally denote various
+enumerations or code snippets that are not further specified. The character <code>…</code>
+(as opposed to the three characters <code>...</code>) is not a token of the Go
+language.
+</p>
+
+<h2 id="Source_code_representation">Source code representation</h2>
+
+<p>
+Source code is Unicode text encoded in
+<a href="http://en.wikipedia.org/wiki/UTF-8">UTF-8</a>. The text is not
+canonicalized, so a single accented code point is distinct from the
+same character constructed from combining an accent and a letter;
+those are treated as two code points. For simplicity, this document
+will use the unqualified term <i>character</i> to refer to a Unicode code point
+in the source text.
+</p>
+<p>
+Each code point is distinct; for instance, upper and lower case letters
+are different characters.
+</p>
+<p>
+Implementation restriction: For compatibility with other tools, a
+compiler may disallow the NUL character (U+0000) in the source text.
+</p>
+<p>
+Implementation restriction: For compatibility with other tools, a
+compiler may ignore a UTF-8-encoded byte order mark
+(U+FEFF) if it is the first Unicode code point in the source text.
+A byte order mark may be disallowed anywhere else in the source.
+</p>
+
+<h3 id="Characters">Characters</h3>
+
+<p>
+The following terms are used to denote specific Unicode character classes:
+</p>
+<pre class="ebnf">
+newline = /* the Unicode code point U+000A */ .
+unicode_char = /* an arbitrary Unicode code point except newline */ .
+unicode_letter = /* a Unicode code point classified as "Letter" */ .
+unicode_digit = /* a Unicode code point classified as "Decimal Digit" */ .
+</pre>
+
+<p>
+In <a href="http://www.unicode.org/versions/Unicode6.3.0/">The Unicode Standard 6.3</a>,
+Section 4.5 "General Category"
+defines a set of character categories. Go treats
+those characters in category Lu, Ll, Lt, Lm, or Lo as Unicode letters,
+and those in category Nd as Unicode digits.
+</p>
+
+<h3 id="Letters_and_digits">Letters and digits</h3>
+
+<p>
+The underscore character <code>_</code> (U+005F) is considered a letter.
+</p>
+<pre class="ebnf">
+letter = unicode_letter | "_" .
+decimal_digit = "0" … "9" .
+octal_digit = "0" … "7" .
+hex_digit = "0" … "9" | "A" … "F" | "a" … "f" .
+</pre>
+
+<h2 id="Lexical_elements">Lexical elements</h2>
+
+<h3 id="Comments">Comments</h3>
+
+<p>
+There are two forms of comments:
+</p>
+
+<ol>
+<li>
+<i>Line comments</i> start with the character sequence <code>//</code>
+and stop at the end of the line. A line comment acts like a newline.
+</li>
+<li>
+<i>General comments</i> start with the character sequence <code>/*</code>
+and continue through the character sequence <code>*/</code>. A general
+comment containing one or more newlines acts like a newline, otherwise it acts
+like a space.
+</li>
+</ol>
+
+<p>
+Comments do not nest.
+</p>
+
+
+<h3 id="Tokens">Tokens</h3>
+
+<p>
+Tokens form the vocabulary of the Go language.
+There are four classes: <i>identifiers</i>, <i>keywords</i>, <i>operators
+and delimiters</i>, and <i>literals</i>. <i>White space</i>, formed from
+spaces (U+0020), horizontal tabs (U+0009),
+carriage returns (U+000D), and newlines (U+000A),
+is ignored except as it separates tokens
+that would otherwise combine into a single token. Also, a newline or end of file
+may trigger the insertion of a <a href="#Semicolons">semicolon</a>.
+While breaking the input into tokens,
+the next token is the longest sequence of characters that form a
+valid token.
+</p>
+
+<h3 id="Semicolons">Semicolons</h3>
+
+<p>
+The formal grammar uses semicolons <code>";"</code> as terminators in
+a number of productions. Go programs may omit most of these semicolons
+using the following two rules:
+</p>
+
+<ol>
+<li>
+<p>
+When the input is broken into tokens, a semicolon is automatically inserted
+into the token stream at the end of a non-blank line if the line's final
+token is
+</p>
+<ul>
+ <li>an
+ <a href="#Identifiers">identifier</a>
+ </li>
+
+ <li>an
+ <a href="#Integer_literals">integer</a>,
+ <a href="#Floating-point_literals">floating-point</a>,
+ <a href="#Imaginary_literals">imaginary</a>,
+ <a href="#Rune_literals">rune</a>, or
+ <a href="#String_literals">string</a> literal
+ </li>
+
+ <li>one of the <a href="#Keywords">keywords</a>
+ <code>break</code>,
+ <code>continue</code>,
+ <code>fallthrough</code>, or
+ <code>return</code>
+ </li>
+
+ <li>one of the <a href="#Operators_and_Delimiters">operators and delimiters</a>
+ <code>++</code>,
+ <code>--</code>,
+ <code>)</code>,
+ <code>]</code>, or
+ <code>}</code>
+ </li>
+</ul>
+</li>
+
+<li>
+To allow complex statements to occupy a single line, a semicolon
+may be omitted before a closing <code>")"</code> or <code>"}"</code>.
+</li>
+</ol>
+
+<p>
+To reflect idiomatic use, code examples in this document elide semicolons
+using these rules.
+</p>
+
+
+<h3 id="Identifiers">Identifiers</h3>
+
+<p>
+Identifiers name program entities such as variables and types.
+An identifier is a sequence of one or more letters and digits.
+The first character in an identifier must be a letter.
+</p>
+<pre class="ebnf">
+identifier = letter { letter | unicode_digit } .
+</pre>
+<pre>
+a
+_x9
+ThisVariableIsExported
+αβ
+</pre>
+
+<p>
+Some identifiers are <a href="#Predeclared_identifiers">predeclared</a>.
+</p>
+
+
+<h3 id="Keywords">Keywords</h3>
+
+<p>
+The following keywords are reserved and may not be used as identifiers.
+</p>
+<pre class="grammar">
+break default func interface select
+case defer go map struct
+chan else goto package switch
+const fallthrough if range type
+continue for import return var
+</pre>
+
+<h3 id="Operators_and_Delimiters">Operators and Delimiters</h3>
+
+<p>
+The following character sequences represent <a href="#Operators">operators</a>, delimiters, and other special tokens:
+</p>
+<pre class="grammar">
++ & += &= && == != ( )
+- | -= |= || < <= [ ]
+* ^ *= ^= <- > >= { }
+/ << /= <<= ++ = := , ;
+% >> %= >>= -- ! ... . :
+ &^ &^=
+</pre>
+
+<h3 id="Integer_literals">Integer literals</h3>
+
+<p>
+An integer literal is a sequence of digits representing an
+<a href="#Constants">integer constant</a>.
+An optional prefix sets a non-decimal base: <code>0</code> for octal, <code>0x</code> or
+<code>0X</code> for hexadecimal. In hexadecimal literals, letters
+<code>a-f</code> and <code>A-F</code> represent values 10 through 15.
+</p>
+<pre class="ebnf">
+int_lit = decimal_lit | octal_lit | hex_lit .
+decimal_lit = ( "1" … "9" ) { decimal_digit } .
+octal_lit = "0" { octal_digit } .
+hex_lit = "0" ( "x" | "X" ) hex_digit { hex_digit } .
+</pre>
+
+<pre>
+42
+0600
+0xBadFace
+170141183460469231731687303715884105727
+</pre>
+
+<h3 id="Floating-point_literals">Floating-point literals</h3>
+<p>
+A floating-point literal is a decimal representation of a
+<a href="#Constants">floating-point constant</a>.
+It has an integer part, a decimal point, a fractional part,
+and an exponent part. The integer and fractional part comprise
+decimal digits; the exponent part is an <code>e</code> or <code>E</code>
+followed by an optionally signed decimal exponent. One of the
+integer part or the fractional part may be elided; one of the decimal
+point or the exponent may be elided.
+</p>
+<pre class="ebnf">
+float_lit = decimals "." [ decimals ] [ exponent ] |
+ decimals exponent |
+ "." decimals [ exponent ] .
+decimals = decimal_digit { decimal_digit } .
+exponent = ( "e" | "E" ) [ "+" | "-" ] decimals .
+</pre>
+
+<pre>
+0.
+72.40
+072.40 // == 72.40
+2.71828
+1.e+0
+6.67428e-11
+1E6
+.25
+.12345E+5
+</pre>
+
+<h3 id="Imaginary_literals">Imaginary literals</h3>
+<p>
+An imaginary literal is a decimal representation of the imaginary part of a
+<a href="#Constants">complex constant</a>.
+It consists of a
+<a href="#Floating-point_literals">floating-point literal</a>
+or decimal integer followed
+by the lower-case letter <code>i</code>.
+</p>
+<pre class="ebnf">
+imaginary_lit = (decimals | float_lit) "i" .
+</pre>
+
+<pre>
+0i
+011i // == 11i
+0.i
+2.71828i
+1.e+0i
+6.67428e-11i
+1E6i
+.25i
+.12345E+5i
+</pre>
+
+
+<h3 id="Rune_literals">Rune literals</h3>
+
+<p>
+A rune literal represents a <a href="#Constants">rune constant</a>,
+an integer value identifying a Unicode code point.
+A rune literal is expressed as one or more characters enclosed in single quotes.
+Within the quotes, any character may appear except single
+quote and newline. A single quoted character represents the Unicode value
+of the character itself,
+while multi-character sequences beginning with a backslash encode
+values in various formats.
+</p>
+<p>
+The simplest form represents the single character within the quotes;
+since Go source text is Unicode characters encoded in UTF-8, multiple
+UTF-8-encoded bytes may represent a single integer value. For
+instance, the literal <code>'a'</code> holds a single byte representing
+a literal <code>a</code>, Unicode U+0061, value <code>0x61</code>, while
+<code>'ä'</code> holds two bytes (<code>0xc3</code> <code>0xa4</code>) representing
+a literal <code>a</code>-dieresis, U+00E4, value <code>0xe4</code>.
+</p>
+<p>
+Several backslash escapes allow arbitrary values to be encoded as
+ASCII text. There are four ways to represent the integer value
+as a numeric constant: <code>\x</code> followed by exactly two hexadecimal
+digits; <code>\u</code> followed by exactly four hexadecimal digits;
+<code>\U</code> followed by exactly eight hexadecimal digits, and a
+plain backslash <code>\</code> followed by exactly three octal digits.
+In each case the value of the literal is the value represented by
+the digits in the corresponding base.
+</p>
+<p>
+Although these representations all result in an integer, they have
+different valid ranges. Octal escapes must represent a value between
+0 and 255 inclusive. Hexadecimal escapes satisfy this condition
+by construction. The escapes <code>\u</code> and <code>\U</code>
+represent Unicode code points so within them some values are illegal,
+in particular those above <code>0x10FFFF</code> and surrogate halves.
+</p>
+<p>
+After a backslash, certain single-character escapes represent special values:
+</p>
+<pre class="grammar">
+\a U+0007 alert or bell
+\b U+0008 backspace
+\f U+000C form feed
+\n U+000A line feed or newline
+\r U+000D carriage return
+\t U+0009 horizontal tab
+\v U+000b vertical tab
+\\ U+005c backslash
+\' U+0027 single quote (valid escape only within rune literals)
+\" U+0022 double quote (valid escape only within string literals)
+</pre>
+<p>
+All other sequences starting with a backslash are illegal inside rune literals.
+</p>
+<pre class="ebnf">
+rune_lit = "'" ( unicode_value | byte_value ) "'" .
+unicode_value = unicode_char | little_u_value | big_u_value | escaped_char .
+byte_value = octal_byte_value | hex_byte_value .
+octal_byte_value = `\` octal_digit octal_digit octal_digit .
+hex_byte_value = `\` "x" hex_digit hex_digit .
+little_u_value = `\` "u" hex_digit hex_digit hex_digit hex_digit .
+big_u_value = `\` "U" hex_digit hex_digit hex_digit hex_digit
+ hex_digit hex_digit hex_digit hex_digit .
+escaped_char = `\` ( "a" | "b" | "f" | "n" | "r" | "t" | "v" | `\` | "'" | `"` ) .
+</pre>
+
+<pre>
+'a'
+'ä'
+'本'
+'\t'
+'\000'
+'\007'
+'\377'
+'\x07'
+'\xff'
+'\u12e4'
+'\U00101234'
+'aa' // illegal: too many characters
+'\xa' // illegal: too few hexadecimal digits
+'\0' // illegal: too few octal digits
+'\uDFFF' // illegal: surrogate half
+'\U00110000' // illegal: invalid Unicode code point
+</pre>
+
+
+<h3 id="String_literals">String literals</h3>
+
+<p>
+A string literal represents a <a href="#Constants">string constant</a>
+obtained from concatenating a sequence of characters. There are two forms:
+raw string literals and interpreted string literals.
+</p>
+<p>
+Raw string literals are character sequences between back quotes
+<code>``</code>. Within the quotes, any character is legal except
+back quote. The value of a raw string literal is the
+string composed of the uninterpreted (implicitly UTF-8-encoded) characters
+between the quotes;
+in particular, backslashes have no special meaning and the string may
+contain newlines.
+Carriage return characters ('\r') inside raw string literals
+are discarded from the raw string value.
+</p>
+<p>
+Interpreted string literals are character sequences between double
+quotes <code>""</code>. The text between the quotes,
+which may not contain newlines, forms the
+value of the literal, with backslash escapes interpreted as they
+are in <a href="#Rune_literals">rune literals</a> (except that <code>\'</code> is illegal and
+<code>\"</code> is legal), with the same restrictions.
+The three-digit octal (<code>\</code><i>nnn</i>)
+and two-digit hexadecimal (<code>\x</code><i>nn</i>) escapes represent individual
+<i>bytes</i> of the resulting string; all other escapes represent
+the (possibly multi-byte) UTF-8 encoding of individual <i>characters</i>.
+Thus inside a string literal <code>\377</code> and <code>\xFF</code> represent
+a single byte of value <code>0xFF</code>=255, while <code>ÿ</code>,
+<code>\u00FF</code>, <code>\U000000FF</code> and <code>\xc3\xbf</code> represent
+the two bytes <code>0xc3</code> <code>0xbf</code> of the UTF-8 encoding of character
+U+00FF.
+</p>
+
+<pre class="ebnf">
+string_lit = raw_string_lit | interpreted_string_lit .
+raw_string_lit = "`" { unicode_char | newline } "`" .
+interpreted_string_lit = `"` { unicode_value | byte_value } `"` .
+</pre>
+
+<pre>
+`abc` // same as "abc"
+`\n
+\n` // same as "\\n\n\\n"
+"\n"
+""
+"Hello, world!\n"
+"日本語"
+"\u65e5本\U00008a9e"
+"\xff\u00FF"
+"\uD800" // illegal: surrogate half
+"\U00110000" // illegal: invalid Unicode code point
+</pre>
+
+<p>
+These examples all represent the same string:
+</p>
+
+<pre>
+"日本語" // UTF-8 input text
+`日本語` // UTF-8 input text as a raw literal
+"\u65e5\u672c\u8a9e" // the explicit Unicode code points
+"\U000065e5\U0000672c\U00008a9e" // the explicit Unicode code points
+"\xe6\x97\xa5\xe6\x9c\xac\xe8\xaa\x9e" // the explicit UTF-8 bytes
+</pre>
+
+<p>
+If the source code represents a character as two code points, such as
+a combining form involving an accent and a letter, the result will be
+an error if placed in a rune literal (it is not a single code
+point), and will appear as two code points if placed in a string
+literal.
+</p>
+
+
+<h2 id="Constants">Constants</h2>
+
+<p>There are <i>boolean constants</i>,
+<i>rune constants</i>,
+<i>integer constants</i>,
+<i>floating-point constants</i>, <i>complex constants</i>,
+and <i>string constants</i>. Rune, integer, floating-point,
+and complex constants are
+collectively called <i>numeric constants</i>.
+</p>
+
+<p>
+A constant value is represented by a
+<a href="#Rune_literals">rune</a>,
+<a href="#Integer_literals">integer</a>,
+<a href="#Floating-point_literals">floating-point</a>,
+<a href="#Imaginary_literals">imaginary</a>,
+or
+<a href="#String_literals">string</a> literal,
+an identifier denoting a constant,
+a <a href="#Constant_expressions">constant expression</a>,
+a <a href="#Conversions">conversion</a> with a result that is a constant, or
+the result value of some built-in functions such as
+<code>unsafe.Sizeof</code> applied to any value,
+<code>cap</code> or <code>len</code> applied to
+<a href="#Length_and_capacity">some expressions</a>,
+<code>real</code> and <code>imag</code> applied to a complex constant
+and <code>complex</code> applied to numeric constants.
+The boolean truth values are represented by the predeclared constants
+<code>true</code> and <code>false</code>. The predeclared identifier
+<a href="#Iota">iota</a> denotes an integer constant.
+</p>
+
+<p>
+In general, complex constants are a form of
+<a href="#Constant_expressions">constant expression</a>
+and are discussed in that section.
+</p>
+
+<p>
+Numeric constants represent values of arbitrary precision and do not overflow.
+</p>
+
+<p>
+Constants may be <a href="#Types">typed</a> or <i>untyped</i>.
+Literal constants, <code>true</code>, <code>false</code>, <code>iota</code>,
+and certain <a href="#Constant_expressions">constant expressions</a>
+containing only untyped constant operands are untyped.
+</p>
+
+<p>
+A constant may be given a type explicitly by a <a href="#Constant_declarations">constant declaration</a>
+or <a href="#Conversions">conversion</a>, or implicitly when used in a
+<a href="#Variable_declarations">variable declaration</a> or an
+<a href="#Assignments">assignment</a> or as an
+operand in an <a href="#Expressions">expression</a>.
+It is an error if the constant value
+cannot be represented as a value of the respective type.
+For instance, <code>3.0</code> can be given any integer or any
+floating-point type, while <code>2147483648.0</code> (equal to <code>1<<31</code>)
+can be given the types <code>float32</code>, <code>float64</code>, or <code>uint32</code> but
+not <code>int32</code> or <code>string</code>.
+</p>
+
+<p>
+An untyped constant has a <i>default type</i> which is the type to which the
+constant is implicitly converted in contexts where a typed value is required,
+for instance, in a <a href="#Short_variable_declarations">short variable declaration</a>
+such as <code>i := 0</code> where there is no explicit type.
+The default type of an untyped constant is <code>bool</code>, <code>rune</code>,
+<code>int</code>, <code>float64</code>, <code>complex128</code> or <code>string</code>
+respectively, depending on whether it is a boolean, rune, integer, floating-point,
+complex, or string constant.
+</p>
+
+<p>
+There are no constants denoting the IEEE-754 infinity and not-a-number values,
+but the <a href="/pkg/math/"><code>math</code> package</a>'s
+<a href="/pkg/math/#Inf">Inf</a>,
+<a href="/pkg/math/#NaN">NaN</a>,
+<a href="/pkg/math/#IsInf">IsInf</a>, and
+<a href="/pkg/math/#IsNaN">IsNaN</a>
+functions return and test for those values at run time.
+</p>
+
+<p>
+Implementation restriction: Although numeric constants have arbitrary
+precision in the language, a compiler may implement them using an
+internal representation with limited precision. That said, every
+implementation must:
+</p>
+<ul>
+ <li>Represent integer constants with at least 256 bits.</li>
+
+ <li>Represent floating-point constants, including the parts of
+ a complex constant, with a mantissa of at least 256 bits
+ and a signed exponent of at least 32 bits.</li>
+
+ <li>Give an error if unable to represent an integer constant
+ precisely.</li>
+
+ <li>Give an error if unable to represent a floating-point or
+ complex constant due to overflow.</li>
+
+ <li>Round to the nearest representable constant if unable to
+ represent a floating-point or complex constant due to limits
+ on precision.</li>
+</ul>
+<p>
+These requirements apply both to literal constants and to the result
+of evaluating <a href="#Constant_expressions">constant
+expressions</a>.
+</p>
+
+<h2 id="Variables">Variables</h2>
+
+<p>
+A variable is a storage location for holding a <i>value</i>.
+The set of permissible values is determined by the
+variable's <i><a href="#Types">type</a></i>.
+</p>
+
+<p>
+A <a href="#Variable_declarations">variable declaration</a>
+or, for function parameters and results, the signature
+of a <a href="#Function_declarations">function declaration</a>
+or <a href="#Function_literals">function literal</a> reserves
+storage for a named variable.
+
+Calling the built-in function <a href="#Allocation"><code>new</code></a>
+or taking the address of a <a href="#Composite_literals">composite literal</a>
+allocates storage for a variable at run time.
+Such an anonymous variable is referred to via a (possibly implicit)
+<a href="#Address_operators">pointer indirection</a>.
+</p>
+
+<p>
+<i>Structured</i> variables of <a href="#Array_types">array</a>, <a href="#Slice_types">slice</a>,
+and <a href="#Struct_types">struct</a> types have elements and fields that may
+be <a href="#Address_operators">addressed</a> individually. Each such element
+acts like a variable.
+</p>
+
+<p>
+The <i>static type</i> (or just <i>type</i>) of a variable is the
+type given in its declaration, the type provided in the
+<code>new</code> call or composite literal, or the type of
+an element of a structured variable.
+Variables of interface type also have a distinct <i>dynamic type</i>,
+which is the concrete type of the value assigned to the variable at run time
+(unless the value is the predeclared identifier <code>nil</code>,
+which has no type).
+The dynamic type may vary during execution but values stored in interface
+variables are always <a href="#Assignability">assignable</a>
+to the static type of the variable.
+</p>
+
+<pre>
+var x interface{} // x is nil and has static type interface{}
+var v *T // v has value nil, static type *T
+x = 42 // x has value 42 and dynamic type int
+x = v // x has value (*T)(nil) and dynamic type *T
+</pre>
+
+<p>
+A variable's value is retrieved by referring to the variable in an
+<a href="#Expressions">expression</a>; it is the most recent value
+<a href="#Assignments">assigned</a> to the variable.
+If a variable has not yet been assigned a value, its value is the
+<a href="#The_zero_value">zero value</a> for its type.
+</p>
+
+
+<h2 id="Types">Types</h2>
+
+<p>
+A type determines the set of values and operations specific to values of that
+type. Types may be <i>named</i> or <i>unnamed</i>. Named types are specified
+by a (possibly <a href="#Qualified_identifiers">qualified</a>)
+<a href="#Type_declarations"><i>type name</i></a>; unnamed types are specified
+using a <i>type literal</i>, which composes a new type from existing types.
+</p>
+
+<pre class="ebnf">
+Type = TypeName | TypeLit | "(" Type ")" .
+TypeName = identifier | QualifiedIdent .
+TypeLit = ArrayType | StructType | PointerType | FunctionType | InterfaceType |
+ SliceType | MapType | ChannelType .
+</pre>
+
+<p>
+Named instances of the boolean, numeric, and string types are
+<a href="#Predeclared_identifiers">predeclared</a>.
+<i>Composite types</i>—array, struct, pointer, function,
+interface, slice, map, and channel types—may be constructed using
+type literals.
+</p>
+
+<p>
+Each type <code>T</code> has an <i>underlying type</i>: If <code>T</code>
+is one of the predeclared boolean, numeric, or string types, or a type literal,
+the corresponding underlying
+type is <code>T</code> itself. Otherwise, <code>T</code>'s underlying type
+is the underlying type of the type to which <code>T</code> refers in its
+<a href="#Type_declarations">type declaration</a>.
+</p>
+
+<pre>
+ type T1 string
+ type T2 T1
+ type T3 []T1
+ type T4 T3
+</pre>
+
+<p>
+The underlying type of <code>string</code>, <code>T1</code>, and <code>T2</code>
+is <code>string</code>. The underlying type of <code>[]T1</code>, <code>T3</code>,
+and <code>T4</code> is <code>[]T1</code>.
+</p>
+
+<h3 id="Method_sets">Method sets</h3>
+<p>
+A type may have a <i>method set</i> associated with it.
+The method set of an <a href="#Interface_types">interface type</a> is its interface.
+The method set of any other type <code>T</code> consists of all
+<a href="#Method_declarations">methods</a> declared with receiver type <code>T</code>.
+The method set of the corresponding <a href="#Pointer_types">pointer type</a> <code>*T</code>
+is the set of all methods declared with receiver <code>*T</code> or <code>T</code>
+(that is, it also contains the method set of <code>T</code>).
+Further rules apply to structs containing anonymous fields, as described
+in the section on <a href="#Struct_types">struct types</a>.
+Any other type has an empty method set.
+In a method set, each method must have a
+<a href="#Uniqueness_of_identifiers">unique</a>
+non-<a href="#Blank_identifier">blank</a> <a href="#MethodName">method name</a>.
+</p>
+
+<p>
+The method set of a type determines the interfaces that the
+type <a href="#Interface_types">implements</a>
+and the methods that can be <a href="#Calls">called</a>
+using a receiver of that type.
+</p>
+
+<h3 id="Boolean_types">Boolean types</h3>
+
+<p>
+A <i>boolean type</i> represents the set of Boolean truth values
+denoted by the predeclared constants <code>true</code>
+and <code>false</code>. The predeclared boolean type is <code>bool</code>.
+</p>
+
+<h3 id="Numeric_types">Numeric types</h3>
+
+<p>
+A <i>numeric type</i> represents sets of integer or floating-point values.
+The predeclared architecture-independent numeric types are:
+</p>
+
+<pre class="grammar">
+uint8 the set of all unsigned 8-bit integers (0 to 255)
+uint16 the set of all unsigned 16-bit integers (0 to 65535)
+uint32 the set of all unsigned 32-bit integers (0 to 4294967295)
+uint64 the set of all unsigned 64-bit integers (0 to 18446744073709551615)
+
+int8 the set of all signed 8-bit integers (-128 to 127)
+int16 the set of all signed 16-bit integers (-32768 to 32767)
+int32 the set of all signed 32-bit integers (-2147483648 to 2147483647)
+int64 the set of all signed 64-bit integers (-9223372036854775808 to 9223372036854775807)
+
+float32 the set of all IEEE-754 32-bit floating-point numbers
+float64 the set of all IEEE-754 64-bit floating-point numbers
+
+complex64 the set of all complex numbers with float32 real and imaginary parts
+complex128 the set of all complex numbers with float64 real and imaginary parts
+
+byte alias for uint8
+rune alias for int32
+</pre>
+
+<p>
+The value of an <i>n</i>-bit integer is <i>n</i> bits wide and represented using
+<a href="http://en.wikipedia.org/wiki/Two's_complement">two's complement arithmetic</a>.
+</p>
+
+<p>
+There is also a set of predeclared numeric types with implementation-specific sizes:
+</p>
+
+<pre class="grammar">
+uint either 32 or 64 bits
+int same size as uint
+uintptr an unsigned integer large enough to store the uninterpreted bits of a pointer value
+</pre>
+
+<p>
+To avoid portability issues all numeric types are distinct except
+<code>byte</code>, which is an alias for <code>uint8</code>, and
+<code>rune</code>, which is an alias for <code>int32</code>.
+Conversions
+are required when different numeric types are mixed in an expression
+or assignment. For instance, <code>int32</code> and <code>int</code>
+are not the same type even though they may have the same size on a
+particular architecture.
+
+
+<h3 id="String_types">String types</h3>
+
+<p>
+A <i>string type</i> represents the set of string values.
+A string value is a (possibly empty) sequence of bytes.
+Strings are immutable: once created,
+it is impossible to change the contents of a string.
+The predeclared string type is <code>string</code>.
+</p>
+
+<p>
+The length of a string <code>s</code> (its size in bytes) can be discovered using
+the built-in function <a href="#Length_and_capacity"><code>len</code></a>.
+The length is a compile-time constant if the string is a constant.
+A string's bytes can be accessed by integer <a href="#Index_expressions">indices</a>
+0 through <code>len(s)-1</code>.
+It is illegal to take the address of such an element; if
+<code>s[i]</code> is the <code>i</code>'th byte of a
+string, <code>&s[i]</code> is invalid.
+</p>
+
+
+<h3 id="Array_types">Array types</h3>
+
+<p>
+An array is a numbered sequence of elements of a single
+type, called the element type.
+The number of elements is called the length and is never
+negative.
+</p>
+
+<pre class="ebnf">
+ArrayType = "[" ArrayLength "]" ElementType .
+ArrayLength = Expression .
+ElementType = Type .
+</pre>
+
+<p>
+The length is part of the array's type; it must evaluate to a
+non-negative <a href="#Constants">constant</a> representable by a value
+of type <code>int</code>.
+The length of array <code>a</code> can be discovered
+using the built-in function <a href="#Length_and_capacity"><code>len</code></a>.
+The elements can be addressed by integer <a href="#Index_expressions">indices</a>
+0 through <code>len(a)-1</code>.
+Array types are always one-dimensional but may be composed to form
+multi-dimensional types.
+</p>
+
+<pre>
+[32]byte
+[2*N] struct { x, y int32 }
+[1000]*float64
+[3][5]int
+[2][2][2]float64 // same as [2]([2]([2]float64))
+</pre>
+
+<h3 id="Slice_types">Slice types</h3>
+
+<p>
+A slice is a descriptor for a contiguous segment of an <i>underlying array</i> and
+provides access to a numbered sequence of elements from that array.
+A slice type denotes the set of all slices of arrays of its element type.
+The value of an uninitialized slice is <code>nil</code>.
+</p>
+
+<pre class="ebnf">
+SliceType = "[" "]" ElementType .
+</pre>
+
+<p>
+Like arrays, slices are indexable and have a length. The length of a
+slice <code>s</code> can be discovered by the built-in function
+<a href="#Length_and_capacity"><code>len</code></a>; unlike with arrays it may change during
+execution. The elements can be addressed by integer <a href="#Index_expressions">indices</a>
+0 through <code>len(s)-1</code>. The slice index of a
+given element may be less than the index of the same element in the
+underlying array.
+</p>
+<p>
+A slice, once initialized, is always associated with an underlying
+array that holds its elements. A slice therefore shares storage
+with its array and with other slices of the same array; by contrast,
+distinct arrays always represent distinct storage.
+</p>
+<p>
+The array underlying a slice may extend past the end of the slice.
+The <i>capacity</i> is a measure of that extent: it is the sum of
+the length of the slice and the length of the array beyond the slice;
+a slice of length up to that capacity can be created by
+<a href="#Slice_expressions"><i>slicing</i></a> a new one from the original slice.
+The capacity of a slice <code>a</code> can be discovered using the
+built-in function <a href="#Length_and_capacity"><code>cap(a)</code></a>.
+</p>
+
+<p>
+A new, initialized slice value for a given element type <code>T</code> is
+made using the built-in function
+<a href="#Making_slices_maps_and_channels"><code>make</code></a>,
+which takes a slice type
+and parameters specifying the length and optionally the capacity.
+A slice created with <code>make</code> always allocates a new, hidden array
+to which the returned slice value refers. That is, executing
+</p>
+
+<pre>
+make([]T, length, capacity)
+</pre>
+
+<p>
+produces the same slice as allocating an array and <a href="#Slice_expressions">slicing</a>
+it, so these two expressions are equivalent:
+</p>
+
+<pre>
+make([]int, 50, 100)
+new([100]int)[0:50]
+</pre>
+
+<p>
+Like arrays, slices are always one-dimensional but may be composed to construct
+higher-dimensional objects.
+With arrays of arrays, the inner arrays are, by construction, always the same length;
+however with slices of slices (or arrays of slices), the inner lengths may vary dynamically.
+Moreover, the inner slices must be initialized individually.
+</p>
+
+<h3 id="Struct_types">Struct types</h3>
+
+<p>
+A struct is a sequence of named elements, called fields, each of which has a
+name and a type. Field names may be specified explicitly (IdentifierList) or
+implicitly (AnonymousField).
+Within a struct, non-<a href="#Blank_identifier">blank</a> field names must
+be <a href="#Uniqueness_of_identifiers">unique</a>.
+</p>
+
+<pre class="ebnf">
+StructType = "struct" "{" { FieldDecl ";" } "}" .
+FieldDecl = (IdentifierList Type | AnonymousField) [ Tag ] .
+AnonymousField = [ "*" ] TypeName .
+Tag = string_lit .
+</pre>
+
+<pre>
+// An empty struct.
+struct {}
+
+// A struct with 6 fields.
+struct {
+ x, y int
+ u float32
+ _ float32 // padding
+ A *[]int
+ F func()
+}
+</pre>
+
+<p>
+A field declared with a type but no explicit field name is an <i>anonymous field</i>,
+also called an <i>embedded</i> field or an embedding of the type in the struct.
+An embedded type must be specified as
+a type name <code>T</code> or as a pointer to a non-interface type name <code>*T</code>,
+and <code>T</code> itself may not be
+a pointer type. The unqualified type name acts as the field name.
+</p>
+
+<pre>
+// A struct with four anonymous fields of type T1, *T2, P.T3 and *P.T4
+struct {
+ T1 // field name is T1
+ *T2 // field name is T2
+ P.T3 // field name is T3
+ *P.T4 // field name is T4
+ x, y int // field names are x and y
+}
+</pre>
+
+<p>
+The following declaration is illegal because field names must be unique
+in a struct type:
+</p>
+
+<pre>
+struct {
+ T // conflicts with anonymous field *T and *P.T
+ *T // conflicts with anonymous field T and *P.T
+ *P.T // conflicts with anonymous field T and *T
+}
+</pre>
+
+<p>
+A field or <a href="#Method_declarations">method</a> <code>f</code> of an
+anonymous field in a struct <code>x</code> is called <i>promoted</i> if
+<code>x.f</code> is a legal <a href="#Selectors">selector</a> that denotes
+that field or method <code>f</code>.
+</p>
+
+<p>
+Promoted fields act like ordinary fields
+of a struct except that they cannot be used as field names in
+<a href="#Composite_literals">composite literals</a> of the struct.
+</p>
+
+<p>
+Given a struct type <code>S</code> and a type named <code>T</code>,
+promoted methods are included in the method set of the struct as follows:
+</p>
+<ul>
+ <li>
+ If <code>S</code> contains an anonymous field <code>T</code>,
+ the <a href="#Method_sets">method sets</a> of <code>S</code>
+ and <code>*S</code> both include promoted methods with receiver
+ <code>T</code>. The method set of <code>*S</code> also
+ includes promoted methods with receiver <code>*T</code>.
+ </li>
+
+ <li>
+ If <code>S</code> contains an anonymous field <code>*T</code>,
+ the method sets of <code>S</code> and <code>*S</code> both
+ include promoted methods with receiver <code>T</code> or
+ <code>*T</code>.
+ </li>
+</ul>
+
+<p>
+A field declaration may be followed by an optional string literal <i>tag</i>,
+which becomes an attribute for all the fields in the corresponding
+field declaration. The tags are made
+visible through a <a href="/pkg/reflect/#StructTag">reflection interface</a>
+and take part in <a href="#Type_identity">type identity</a> for structs
+but are otherwise ignored.
+</p>
+
+<pre>
+// A struct corresponding to the TimeStamp protocol buffer.
+// The tag strings define the protocol buffer field numbers.
+struct {
+ microsec uint64 "field 1"
+ serverIP6 uint64 "field 2"
+ process string "field 3"
+}
+</pre>
+
+<h3 id="Pointer_types">Pointer types</h3>
+
+<p>
+A pointer type denotes the set of all pointers to <a href="#Variables">variables</a> of a given
+type, called the <i>base type</i> of the pointer.
+The value of an uninitialized pointer is <code>nil</code>.
+</p>
+
+<pre class="ebnf">
+PointerType = "*" BaseType .
+BaseType = Type .
+</pre>
+
+<pre>
+*Point
+*[4]int
+</pre>
+
+<h3 id="Function_types">Function types</h3>
+
+<p>
+A function type denotes the set of all functions with the same parameter
+and result types. The value of an uninitialized variable of function type
+is <code>nil</code>.
+</p>
+
+<pre class="ebnf">
+FunctionType = "func" Signature .
+Signature = Parameters [ Result ] .
+Result = Parameters | Type .
+Parameters = "(" [ ParameterList [ "," ] ] ")" .
+ParameterList = ParameterDecl { "," ParameterDecl } .
+ParameterDecl = [ IdentifierList ] [ "..." ] Type .
+</pre>
+
+<p>
+Within a list of parameters or results, the names (IdentifierList)
+must either all be present or all be absent. If present, each name
+stands for one item (parameter or result) of the specified type and
+all non-<a href="#Blank_identifier">blank</a> names in the signature
+must be <a href="#Uniqueness_of_identifiers">unique</a>.
+If absent, each type stands for one item of that type.
+Parameter and result
+lists are always parenthesized except that if there is exactly
+one unnamed result it may be written as an unparenthesized type.
+</p>
+
+<p>
+The final parameter in a function signature may have
+a type prefixed with <code>...</code>.
+A function with such a parameter is called <i>variadic</i> and
+may be invoked with zero or more arguments for that parameter.
+</p>
+
+<pre>
+func()
+func(x int) int
+func(a, _ int, z float32) bool
+func(a, b int, z float32) (bool)
+func(prefix string, values ...int)
+func(a, b int, z float64, opt ...interface{}) (success bool)
+func(int, int, float64) (float64, *[]int)
+func(n int) func(p *T)
+</pre>
+
+
+<h3 id="Interface_types">Interface types</h3>
+
+<p>
+An interface type specifies a <a href="#Method_sets">method set</a> called its <i>interface</i>.
+A variable of interface type can store a value of any type with a method set
+that is any superset of the interface. Such a type is said to
+<i>implement the interface</i>.
+The value of an uninitialized variable of interface type is <code>nil</code>.
+</p>
+
+<pre class="ebnf">
+InterfaceType = "interface" "{" { MethodSpec ";" } "}" .
+MethodSpec = MethodName Signature | InterfaceTypeName .
+MethodName = identifier .
+InterfaceTypeName = TypeName .
+</pre>
+
+<p>
+As with all method sets, in an interface type, each method must have a
+<a href="#Uniqueness_of_identifiers">unique</a>
+non-<a href="#Blank_identifier">blank</a> name.
+</p>
+
+<pre>
+// A simple File interface
+interface {
+ Read(b Buffer) bool
+ Write(b Buffer) bool
+ Close()
+}
+</pre>
+
+<p>
+More than one type may implement an interface.
+For instance, if two types <code>S1</code> and <code>S2</code>
+have the method set
+</p>
+
+<pre>
+func (p T) Read(b Buffer) bool { return … }
+func (p T) Write(b Buffer) bool { return … }
+func (p T) Close() { … }
+</pre>
+
+<p>
+(where <code>T</code> stands for either <code>S1</code> or <code>S2</code>)
+then the <code>File</code> interface is implemented by both <code>S1</code> and
+<code>S2</code>, regardless of what other methods
+<code>S1</code> and <code>S2</code> may have or share.
+</p>
+
+<p>
+A type implements any interface comprising any subset of its methods
+and may therefore implement several distinct interfaces. For
+instance, all types implement the <i>empty interface</i>:
+</p>
+
+<pre>
+interface{}
+</pre>
+
+<p>
+Similarly, consider this interface specification,
+which appears within a <a href="#Type_declarations">type declaration</a>
+to define an interface called <code>Locker</code>:
+</p>
+
+<pre>
+type Locker interface {
+ Lock()
+ Unlock()
+}
+</pre>
+
+<p>
+If <code>S1</code> and <code>S2</code> also implement
+</p>
+
+<pre>
+func (p T) Lock() { … }
+func (p T) Unlock() { … }
+</pre>
+
+<p>
+they implement the <code>Locker</code> interface as well
+as the <code>File</code> interface.
+</p>
+
+<p>
+An interface <code>T</code> may use a (possibly qualified) interface type
+name <code>E</code> in place of a method specification. This is called
+<i>embedding</i> interface <code>E</code> in <code>T</code>; it adds
+all (exported and non-exported) methods of <code>E</code> to the interface
+<code>T</code>.
+</p>
+
+<pre>
+type ReadWriter interface {
+ Read(b Buffer) bool
+ Write(b Buffer) bool
+}
+
+type File interface {
+ ReadWriter // same as adding the methods of ReadWriter
+ Locker // same as adding the methods of Locker
+ Close()
+}
+
+type LockedFile interface {
+ Locker
+ File // illegal: Lock, Unlock not unique
+ Lock() // illegal: Lock not unique
+}
+</pre>
+
+<p>
+An interface type <code>T</code> may not embed itself
+or any interface type that embeds <code>T</code>, recursively.
+</p>
+
+<pre>
+// illegal: Bad cannot embed itself
+type Bad interface {
+ Bad
+}
+
+// illegal: Bad1 cannot embed itself using Bad2
+type Bad1 interface {
+ Bad2
+}
+type Bad2 interface {
+ Bad1
+}
+</pre>
+
+<h3 id="Map_types">Map types</h3>
+
+<p>
+A map is an unordered group of elements of one type, called the
+element type, indexed by a set of unique <i>keys</i> of another type,
+called the key type.
+The value of an uninitialized map is <code>nil</code>.
+</p>
+
+<pre class="ebnf">
+MapType = "map" "[" KeyType "]" ElementType .
+KeyType = Type .
+</pre>
+
+<p>
+The <a href="#Comparison_operators">comparison operators</a>
+<code>==</code> and <code>!=</code> must be fully defined
+for operands of the key type; thus the key type must not be a function, map, or
+slice.
+If the key type is an interface type, these
+comparison operators must be defined for the dynamic key values;
+failure will cause a <a href="#Run_time_panics">run-time panic</a>.
+
+</p>
+
+<pre>
+map[string]int
+map[*T]struct{ x, y float64 }
+map[string]interface{}
+</pre>
+
+<p>
+The number of map elements is called its length.
+For a map <code>m</code>, it can be discovered using the
+built-in function <a href="#Length_and_capacity"><code>len</code></a>
+and may change during execution. Elements may be added during execution
+using <a href="#Assignments">assignments</a> and retrieved with
+<a href="#Index_expressions">index expressions</a>; they may be removed with the
+<a href="#Deletion_of_map_elements"><code>delete</code></a> built-in function.
+</p>
+<p>
+A new, empty map value is made using the built-in
+function <a href="#Making_slices_maps_and_channels"><code>make</code></a>,
+which takes the map type and an optional capacity hint as arguments:
+</p>
+
+<pre>
+make(map[string]int)
+make(map[string]int, 100)
+</pre>
+
+<p>
+The initial capacity does not bound its size:
+maps grow to accommodate the number of items
+stored in them, with the exception of <code>nil</code> maps.
+A <code>nil</code> map is equivalent to an empty map except that no elements
+may be added.
+
+<h3 id="Channel_types">Channel types</h3>
+
+<p>
+A channel provides a mechanism for
+<a href="#Go_statements">concurrently executing functions</a>
+to communicate by
+<a href="#Send_statements">sending</a> and
+<a href="#Receive_operator">receiving</a>
+values of a specified element type.
+The value of an uninitialized channel is <code>nil</code>.
+</p>
+
+<pre class="ebnf">
+ChannelType = ( "chan" | "chan" "<-" | "<-" "chan" ) ElementType .
+</pre>
+
+<p>
+The optional <code><-</code> operator specifies the channel <i>direction</i>,
+<i>send</i> or <i>receive</i>. If no direction is given, the channel is
+<i>bidirectional</i>.
+A channel may be constrained only to send or only to receive by
+<a href="#Conversions">conversion</a> or <a href="#Assignments">assignment</a>.
+</p>
+
+<pre>
+chan T // can be used to send and receive values of type T
+chan<- float64 // can only be used to send float64s
+<-chan int // can only be used to receive ints
+</pre>
+
+<p>
+The <code><-</code> operator associates with the leftmost <code>chan</code>
+possible:
+</p>
+
+<pre>
+chan<- chan int // same as chan<- (chan int)
+chan<- <-chan int // same as chan<- (<-chan int)
+<-chan <-chan int // same as <-chan (<-chan int)
+chan (<-chan int)
+</pre>
+
+<p>
+A new, initialized channel
+value can be made using the built-in function
+<a href="#Making_slices_maps_and_channels"><code>make</code></a>,
+which takes the channel type and an optional <i>capacity</i> as arguments:
+</p>
+
+<pre>
+make(chan int, 100)
+</pre>
+
+<p>
+The capacity, in number of elements, sets the size of the buffer in the channel.
+If the capacity is zero or absent, the channel is unbuffered and communication
+succeeds only when both a sender and receiver are ready. Otherwise, the channel
+is buffered and communication succeeds without blocking if the buffer
+is not full (sends) or not empty (receives).
+A <code>nil</code> channel is never ready for communication.
+</p>
+
+<p>
+A channel may be closed with the built-in function
+<a href="#Close"><code>close</code></a>.
+The multi-valued assignment form of the
+<a href="#Receive_operator">receive operator</a>
+reports whether a received value was sent before
+the channel was closed.
+</p>
+
+<p>
+A single channel may be used in
+<a href="#Send_statements">send statements</a>,
+<a href="#Receive_operator">receive operations</a>,
+and calls to the built-in functions
+<a href="#Length_and_capacity"><code>cap</code></a> and
+<a href="#Length_and_capacity"><code>len</code></a>
+by any number of goroutines without further synchronization.
+Channels act as first-in-first-out queues.
+For example, if one goroutine sends values on a channel
+and a second goroutine receives them, the values are
+received in the order sent.
+</p>
+
+<h2 id="Properties_of_types_and_values">Properties of types and values</h2>
+
+<h3 id="Type_identity">Type identity</h3>
+
+<p>
+Two types are either <i>identical</i> or <i>different</i>.
+</p>
+
+<p>
+Two <a href="#Types">named types</a> are identical if their type names originate in the same
+<a href="#Type_declarations">TypeSpec</a>.
+A named and an <a href="#Types">unnamed type</a> are always different. Two unnamed types are identical
+if the corresponding type literals are identical, that is, if they have the same
+literal structure and corresponding components have identical types. In detail:
+</p>
+
+<ul>
+ <li>Two array types are identical if they have identical element types and
+ the same array length.</li>
+
+ <li>Two slice types are identical if they have identical element types.</li>
+
+ <li>Two struct types are identical if they have the same sequence of fields,
+ and if corresponding fields have the same names, and identical types,
+ and identical tags.
+ Two anonymous fields are considered to have the same name. Lower-case field
+ names from different packages are always different.</li>
+
+ <li>Two pointer types are identical if they have identical base types.</li>
+
+ <li>Two function types are identical if they have the same number of parameters
+ and result values, corresponding parameter and result types are
+ identical, and either both functions are variadic or neither is.
+ Parameter and result names are not required to match.</li>
+
+ <li>Two interface types are identical if they have the same set of methods
+ with the same names and identical function types. Lower-case method names from
+ different packages are always different. The order of the methods is irrelevant.</li>
+
+ <li>Two map types are identical if they have identical key and value types.</li>
+
+ <li>Two channel types are identical if they have identical value types and
+ the same direction.</li>
+</ul>
+
+<p>
+Given the declarations
+</p>
+
+<pre>
+type (
+ T0 []string
+ T1 []string
+ T2 struct{ a, b int }
+ T3 struct{ a, c int }
+ T4 func(int, float64) *T0
+ T5 func(x int, y float64) *[]string
+)
+</pre>
+
+<p>
+these types are identical:
+</p>
+
+<pre>
+T0 and T0
+[]int and []int
+struct{ a, b *T5 } and struct{ a, b *T5 }
+func(x int, y float64) *[]string and func(int, float64) (result *[]string)
+</pre>
+
+<p>
+<code>T0</code> and <code>T1</code> are different because they are named types
+with distinct declarations; <code>func(int, float64) *T0</code> and
+<code>func(x int, y float64) *[]string</code> are different because <code>T0</code>
+is different from <code>[]string</code>.
+</p>
+
+
+<h3 id="Assignability">Assignability</h3>
+
+<p>
+A value <code>x</code> is <i>assignable</i> to a <a href="#Variables">variable</a> of type <code>T</code>
+("<code>x</code> is assignable to <code>T</code>") in any of these cases:
+</p>
+
+<ul>
+<li>
+<code>x</code>'s type is identical to <code>T</code>.
+</li>
+<li>
+<code>x</code>'s type <code>V</code> and <code>T</code> have identical
+<a href="#Types">underlying types</a> and at least one of <code>V</code>
+or <code>T</code> is not a <a href="#Types">named type</a>.
+</li>
+<li>
+<code>T</code> is an interface type and
+<code>x</code> <a href="#Interface_types">implements</a> <code>T</code>.
+</li>
+<li>
+<code>x</code> is a bidirectional channel value, <code>T</code> is a channel type,
+<code>x</code>'s type <code>V</code> and <code>T</code> have identical element types,
+and at least one of <code>V</code> or <code>T</code> is not a named type.
+</li>
+<li>
+<code>x</code> is the predeclared identifier <code>nil</code> and <code>T</code>
+is a pointer, function, slice, map, channel, or interface type.
+</li>
+<li>
+<code>x</code> is an untyped <a href="#Constants">constant</a> representable
+by a value of type <code>T</code>.
+</li>
+</ul>
+
+
+<h2 id="Blocks">Blocks</h2>
+
+<p>
+A <i>block</i> is a possibly empty sequence of declarations and statements
+within matching brace brackets.
+</p>
+
+<pre class="ebnf">
+Block = "{" StatementList "}" .
+StatementList = { Statement ";" } .
+</pre>
+
+<p>
+In addition to explicit blocks in the source code, there are implicit blocks:
+</p>
+
+<ol>
+ <li>The <i>universe block</i> encompasses all Go source text.</li>
+
+ <li>Each <a href="#Packages">package</a> has a <i>package block</i> containing all
+ Go source text for that package.</li>
+
+ <li>Each file has a <i>file block</i> containing all Go source text
+ in that file.</li>
+
+ <li>Each <a href="#If_statements">"if"</a>,
+ <a href="#For_statements">"for"</a>, and
+ <a href="#Switch_statements">"switch"</a>
+ statement is considered to be in its own implicit block.</li>
+
+ <li>Each clause in a <a href="#Switch_statements">"switch"</a>
+ or <a href="#Select_statements">"select"</a> statement
+ acts as an implicit block.</li>
+</ol>
+
+<p>
+Blocks nest and influence <a href="#Declarations_and_scope">scoping</a>.
+</p>
+
+
+<h2 id="Declarations_and_scope">Declarations and scope</h2>
+
+<p>
+A <i>declaration</i> binds a non-<a href="#Blank_identifier">blank</a> identifier to a
+<a href="#Constant_declarations">constant</a>,
+<a href="#Type_declarations">type</a>,
+<a href="#Variable_declarations">variable</a>,
+<a href="#Function_declarations">function</a>,
+<a href="#Labeled_statements">label</a>, or
+<a href="#Import_declarations">package</a>.
+Every identifier in a program must be declared.
+No identifier may be declared twice in the same block, and
+no identifier may be declared in both the file and package block.
+</p>
+
+<p>
+The <a href="#Blank_identifier">blank identifier</a> may be used like any other identifier
+in a declaration, but it does not introduce a binding and thus is not declared.
+In the package block, the identifier <code>init</code> may only be used for
+<a href="#Package_initialization"><code>init</code> function</a> declarations,
+and like the blank identifier it does not introduce a new binding.
+</p>
+
+<pre class="ebnf">
+Declaration = ConstDecl | TypeDecl | VarDecl .
+TopLevelDecl = Declaration | FunctionDecl | MethodDecl .
+</pre>
+
+<p>
+The <i>scope</i> of a declared identifier is the extent of source text in which
+the identifier denotes the specified constant, type, variable, function, label, or package.
+</p>
+
+<p>
+Go is lexically scoped using <a href="#Blocks">blocks</a>:
+</p>
+
+<ol>
+ <li>The scope of a <a href="#Predeclared_identifiers">predeclared identifier</a> is the universe block.</li>
+
+ <li>The scope of an identifier denoting a constant, type, variable,
+ or function (but not method) declared at top level (outside any
+ function) is the package block.</li>
+
+ <li>The scope of the package name of an imported package is the file block
+ of the file containing the import declaration.</li>
+
+ <li>The scope of an identifier denoting a method receiver, function parameter,
+ or result variable is the function body.</li>
+
+ <li>The scope of a constant or variable identifier declared
+ inside a function begins at the end of the ConstSpec or VarSpec
+ (ShortVarDecl for short variable declarations)
+ and ends at the end of the innermost containing block.</li>
+
+ <li>The scope of a type identifier declared inside a function
+ begins at the identifier in the TypeSpec
+ and ends at the end of the innermost containing block.</li>
+</ol>
+
+<p>
+An identifier declared in a block may be redeclared in an inner block.
+While the identifier of the inner declaration is in scope, it denotes
+the entity declared by the inner declaration.
+</p>
+
+<p>
+The <a href="#Package_clause">package clause</a> is not a declaration; the package name
+does not appear in any scope. Its purpose is to identify the files belonging
+to the same <a href="#Packages">package</a> and to specify the default package name for import
+declarations.
+</p>
+
+
+<h3 id="Label_scopes">Label scopes</h3>
+
+<p>
+Labels are declared by <a href="#Labeled_statements">labeled statements</a> and are
+used in the <a href="#Break_statements">"break"</a>,
+<a href="#Continue_statements">"continue"</a>, and
+<a href="#Goto_statements">"goto"</a> statements.
+It is illegal to define a label that is never used.
+In contrast to other identifiers, labels are not block scoped and do
+not conflict with identifiers that are not labels. The scope of a label
+is the body of the function in which it is declared and excludes
+the body of any nested function.
+</p>
+
+
+<h3 id="Blank_identifier">Blank identifier</h3>
+
+<p>
+The <i>blank identifier</i> is represented by the underscore character <code>_</code>.
+It serves as an anonymous placeholder instead of a regular (non-blank)
+identifier and has special meaning in <a href="#Declarations_and_scope">declarations</a>,
+as an <a href="#Operands">operand</a>, and in <a href="#Assignments">assignments</a>.
+</p>
+
+
+<h3 id="Predeclared_identifiers">Predeclared identifiers</h3>
+
+<p>
+The following identifiers are implicitly declared in the
+<a href="#Blocks">universe block</a>:
+</p>
+<pre class="grammar">
+Types:
+ bool byte complex64 complex128 error float32 float64
+ int int8 int16 int32 int64 rune string
+ uint uint8 uint16 uint32 uint64 uintptr
+
+Constants:
+ true false iota
+
+Zero value:
+ nil
+
+Functions:
+ append cap close complex copy delete imag len
+ make new panic print println real recover
+</pre>
+
+
+<h3 id="Exported_identifiers">Exported identifiers</h3>
+
+<p>
+An identifier may be <i>exported</i> to permit access to it from another package.
+An identifier is exported if both:
+</p>
+<ol>
+ <li>the first character of the identifier's name is a Unicode upper case
+ letter (Unicode class "Lu"); and</li>
+ <li>the identifier is declared in the <a href="#Blocks">package block</a>
+ or it is a <a href="#Struct_types">field name</a> or
+ <a href="#MethodName">method name</a>.</li>
+</ol>
+<p>
+All other identifiers are not exported.
+</p>
+
+
+<h3 id="Uniqueness_of_identifiers">Uniqueness of identifiers</h3>
+
+<p>
+Given a set of identifiers, an identifier is called <i>unique</i> if it is
+<i>different</i> from every other in the set.
+Two identifiers are different if they are spelled differently, or if they
+appear in different <a href="#Packages">packages</a> and are not
+<a href="#Exported_identifiers">exported</a>. Otherwise, they are the same.
+</p>
+
+<h3 id="Constant_declarations">Constant declarations</h3>
+
+<p>
+A constant declaration binds a list of identifiers (the names of
+the constants) to the values of a list of <a href="#Constant_expressions">constant expressions</a>.
+The number of identifiers must be equal
+to the number of expressions, and the <i>n</i>th identifier on
+the left is bound to the value of the <i>n</i>th expression on the
+right.
+</p>
+
+<pre class="ebnf">
+ConstDecl = "const" ( ConstSpec | "(" { ConstSpec ";" } ")" ) .
+ConstSpec = IdentifierList [ [ Type ] "=" ExpressionList ] .
+
+IdentifierList = identifier { "," identifier } .
+ExpressionList = Expression { "," Expression } .
+</pre>
+
+<p>
+If the type is present, all constants take the type specified, and
+the expressions must be <a href="#Assignability">assignable</a> to that type.
+If the type is omitted, the constants take the
+individual types of the corresponding expressions.
+If the expression values are untyped <a href="#Constants">constants</a>,
+the declared constants remain untyped and the constant identifiers
+denote the constant values. For instance, if the expression is a
+floating-point literal, the constant identifier denotes a floating-point
+constant, even if the literal's fractional part is zero.
+</p>
+
+<pre>
+const Pi float64 = 3.14159265358979323846
+const zero = 0.0 // untyped floating-point constant
+const (
+ size int64 = 1024
+ eof = -1 // untyped integer constant
+)
+const a, b, c = 3, 4, "foo" // a = 3, b = 4, c = "foo", untyped integer and string constants
+const u, v float32 = 0, 3 // u = 0.0, v = 3.0
+</pre>
+
+<p>
+Within a parenthesized <code>const</code> declaration list the
+expression list may be omitted from any but the first declaration.
+Such an empty list is equivalent to the textual substitution of the
+first preceding non-empty expression list and its type if any.
+Omitting the list of expressions is therefore equivalent to
+repeating the previous list. The number of identifiers must be equal
+to the number of expressions in the previous list.
+Together with the <a href="#Iota"><code>iota</code> constant generator</a>
+this mechanism permits light-weight declaration of sequential values:
+</p>
+
+<pre>
+const (
+ Sunday = iota
+ Monday
+ Tuesday
+ Wednesday
+ Thursday
+ Friday
+ Partyday
+ numberOfDays // this constant is not exported
+)
+</pre>
+
+
+<h3 id="Iota">Iota</h3>
+
+<p>
+Within a <a href="#Constant_declarations">constant declaration</a>, the predeclared identifier
+<code>iota</code> represents successive untyped integer <a href="#Constants">
+constants</a>. It is reset to 0 whenever the reserved word <code>const</code>
+appears in the source and increments after each <a href="#ConstSpec">ConstSpec</a>.
+It can be used to construct a set of related constants:
+</p>
+
+<pre>
+const ( // iota is reset to 0
+ c0 = iota // c0 == 0
+ c1 = iota // c1 == 1
+ c2 = iota // c2 == 2
+)
+
+const (
+ a = 1 << iota // a == 1 (iota has been reset)
+ b = 1 << iota // b == 2
+ c = 1 << iota // c == 4
+)
+
+const (
+ u = iota * 42 // u == 0 (untyped integer constant)
+ v float64 = iota * 42 // v == 42.0 (float64 constant)
+ w = iota * 42 // w == 84 (untyped integer constant)
+)
+
+const x = iota // x == 0 (iota has been reset)
+const y = iota // y == 0 (iota has been reset)
+</pre>
+
+<p>
+Within an ExpressionList, the value of each <code>iota</code> is the same because
+it is only incremented after each ConstSpec:
+</p>
+
+<pre>
+const (
+ bit0, mask0 = 1 << iota, 1<<iota - 1 // bit0 == 1, mask0 == 0
+ bit1, mask1 // bit1 == 2, mask1 == 1
+ _, _ // skips iota == 2
+ bit3, mask3 // bit3 == 8, mask3 == 7
+)
+</pre>
+
+<p>
+This last example exploits the implicit repetition of the
+last non-empty expression list.
+</p>
+
+
+<h3 id="Type_declarations">Type declarations</h3>
+
+<p>
+A type declaration binds an identifier, the <i>type name</i>, to a new type
+that has the same <a href="#Types">underlying type</a> as an existing type,
+and operations defined for the existing type are also defined for the new type.
+The new type is <a href="#Type_identity">different</a> from the existing type.
+</p>
+
+<pre class="ebnf">
+TypeDecl = "type" ( TypeSpec | "(" { TypeSpec ";" } ")" ) .
+TypeSpec = identifier Type .
+</pre>
+
+<pre>
+type IntArray [16]int
+
+type (
+ Point struct{ x, y float64 }
+ Polar Point
+)
+
+type TreeNode struct {
+ left, right *TreeNode
+ value *Comparable
+}
+
+type Block interface {
+ BlockSize() int
+ Encrypt(src, dst []byte)
+ Decrypt(src, dst []byte)
+}
+</pre>
+
+<p>
+The declared type does not inherit any <a href="#Method_declarations">methods</a>
+bound to the existing type, but the <a href="#Method_sets">method set</a>
+of an interface type or of elements of a composite type remains unchanged:
+</p>
+
+<pre>
+// A Mutex is a data type with two methods, Lock and Unlock.
+type Mutex struct { /* Mutex fields */ }
+func (m *Mutex) Lock() { /* Lock implementation */ }
+func (m *Mutex) Unlock() { /* Unlock implementation */ }
+
+// NewMutex has the same composition as Mutex but its method set is empty.
+type NewMutex Mutex
+
+// The method set of the <a href="#Pointer_types">base type</a> of PtrMutex remains unchanged,
+// but the method set of PtrMutex is empty.
+type PtrMutex *Mutex
+
+// The method set of *PrintableMutex contains the methods
+// Lock and Unlock bound to its anonymous field Mutex.
+type PrintableMutex struct {
+ Mutex
+}
+
+// MyBlock is an interface type that has the same method set as Block.
+type MyBlock Block
+</pre>
+
+<p>
+A type declaration may be used to define a different boolean, numeric, or string
+type and attach methods to it:
+</p>
+
+<pre>
+type TimeZone int
+
+const (
+ EST TimeZone = -(5 + iota)
+ CST
+ MST
+ PST
+)
+
+func (tz TimeZone) String() string {
+ return fmt.Sprintf("GMT+%dh", tz)
+}
+</pre>
+
+
+<h3 id="Variable_declarations">Variable declarations</h3>
+
+<p>
+A variable declaration creates one or more variables, binds corresponding
+identifiers to them, and gives each a type and an initial value.
+</p>
+
+<pre class="ebnf">
+VarDecl = "var" ( VarSpec | "(" { VarSpec ";" } ")" ) .
+VarSpec = IdentifierList ( Type [ "=" ExpressionList ] | "=" ExpressionList ) .
+</pre>
+
+<pre>
+var i int
+var U, V, W float64
+var k = 0
+var x, y float32 = -1, -2
+var (
+ i int
+ u, v, s = 2.0, 3.0, "bar"
+)
+var re, im = complexSqrt(-1)
+var _, found = entries[name] // map lookup; only interested in "found"
+</pre>
+
+<p>
+If a list of expressions is given, the variables are initialized
+with the expressions following the rules for <a href="#Assignments">assignments</a>.
+Otherwise, each variable is initialized to its <a href="#The_zero_value">zero value</a>.
+</p>
+
+<p>
+If a type is present, each variable is given that type.
+Otherwise, each variable is given the type of the corresponding
+initialization value in the assignment.
+If that value is an untyped constant, it is first
+<a href="#Conversions">converted</a> to its <a href="#Constants">default type</a>;
+if it is an untyped boolean value, it is first converted to type <code>bool</code>.
+The predeclared value <code>nil</code> cannot be used to initialize a variable
+with no explicit type.
+</p>
+
+<pre>
+var d = math.Sin(0.5) // d is int64
+var i = 42 // i is int
+var t, ok = x.(T) // t is T, ok is bool
+var n = nil // illegal
+</pre>
+
+<p>
+Implementation restriction: A compiler may make it illegal to declare a variable
+inside a <a href="#Function_declarations">function body</a> if the variable is
+never used.
+</p>
+
+<h3 id="Short_variable_declarations">Short variable declarations</h3>
+
+<p>
+A <i>short variable declaration</i> uses the syntax:
+</p>
+
+<pre class="ebnf">
+ShortVarDecl = IdentifierList ":=" ExpressionList .
+</pre>
+
+<p>
+It is shorthand for a regular <a href="#Variable_declarations">variable declaration</a>
+with initializer expressions but no types:
+</p>
+
+<pre class="grammar">
+"var" IdentifierList = ExpressionList .
+</pre>
+
+<pre>
+i, j := 0, 10
+f := func() int { return 7 }
+ch := make(chan int)
+r, w := os.Pipe(fd) // os.Pipe() returns two values
+_, y, _ := coord(p) // coord() returns three values; only interested in y coordinate
+</pre>
+
+<p>
+Unlike regular variable declarations, a short variable declaration may redeclare variables provided they
+were originally declared earlier in the same block with the same type, and at
+least one of the non-<a href="#Blank_identifier">blank</a> variables is new. As a consequence, redeclaration
+can only appear in a multi-variable short declaration.
+Redeclaration does not introduce a new
+variable; it just assigns a new value to the original.
+</p>
+
+<pre>
+field1, offset := nextField(str, 0)
+field2, offset := nextField(str, offset) // redeclares offset
+a, a := 1, 2 // illegal: double declaration of a or no new variable if a was declared elsewhere
+</pre>
+
+<p>
+Short variable declarations may appear only inside functions.
+In some contexts such as the initializers for
+<a href="#If_statements">"if"</a>,
+<a href="#For_statements">"for"</a>, or
+<a href="#Switch_statements">"switch"</a> statements,
+they can be used to declare local temporary variables.
+</p>
+
+<h3 id="Function_declarations">Function declarations</h3>
+
+<p>
+A function declaration binds an identifier, the <i>function name</i>,
+to a function.
+</p>
+
+<pre class="ebnf">
+FunctionDecl = "func" FunctionName ( Function | Signature ) .
+FunctionName = identifier .
+Function = Signature FunctionBody .
+FunctionBody = Block .
+</pre>
+
+<p>
+If the function's <a href="#Function_types">signature</a> declares
+result parameters, the function body's statement list must end in
+a <a href="#Terminating_statements">terminating statement</a>.
+</p>
+
+<pre>
+func findMarker(c <-chan int) int {
+ for i := range c {
+ if x := <-c; isMarker(x) {
+ return x
+ }
+ }
+ // invalid: missing return statement.
+}
+</pre>
+
+<p>
+A function declaration may omit the body. Such a declaration provides the
+signature for a function implemented outside Go, such as an assembly routine.
+</p>
+
+<pre>
+func min(x int, y int) int {
+ if x < y {
+ return x
+ }
+ return y
+}
+
+func flushICache(begin, end uintptr) // implemented externally
+</pre>
+
+<h3 id="Method_declarations">Method declarations</h3>
+
+<p>
+A method is a <a href="#Function_declarations">function</a> with a <i>receiver</i>.
+A method declaration binds an identifier, the <i>method name</i>, to a method,
+and associates the method with the receiver's <i>base type</i>.
+</p>
+
+<pre class="ebnf">
+MethodDecl = "func" Receiver MethodName ( Function | Signature ) .
+Receiver = Parameters .
+</pre>
+
+<p>
+The receiver is specified via an extra parameter section preceeding the method
+name. That parameter section must declare a single parameter, the receiver.
+Its type must be of the form <code>T</code> or <code>*T</code> (possibly using
+parentheses) where <code>T</code> is a type name. The type denoted by <code>T</code> is called
+the receiver <i>base type</i>; it must not be a pointer or interface type and
+it must be declared in the same package as the method.
+The method is said to be <i>bound</i> to the base type and the method name
+is visible only within selectors for that type.
+</p>
+
+<p>
+A non-<a href="#Blank_identifier">blank</a> receiver identifier must be
+<a href="#Uniqueness_of_identifiers">unique</a> in the method signature.
+If the receiver's value is not referenced inside the body of the method,
+its identifier may be omitted in the declaration. The same applies in
+general to parameters of functions and methods.
+</p>
+
+<p>
+For a base type, the non-blank names of methods bound to it must be unique.
+If the base type is a <a href="#Struct_types">struct type</a>,
+the non-blank method and field names must be distinct.
+</p>
+
+<p>
+Given type <code>Point</code>, the declarations
+</p>
+
+<pre>
+func (p *Point) Length() float64 {
+ return math.Sqrt(p.x * p.x + p.y * p.y)
+}
+
+func (p *Point) Scale(factor float64) {
+ p.x *= factor
+ p.y *= factor
+}
+</pre>
+
+<p>
+bind the methods <code>Length</code> and <code>Scale</code>,
+with receiver type <code>*Point</code>,
+to the base type <code>Point</code>.
+</p>
+
+<p>
+The type of a method is the type of a function with the receiver as first
+argument. For instance, the method <code>Scale</code> has type
+</p>
+
+<pre>
+func(p *Point, factor float64)
+</pre>
+
+<p>
+However, a function declared this way is not a method.
+</p>
+
+
+<h2 id="Expressions">Expressions</h2>
+
+<p>
+An expression specifies the computation of a value by applying
+operators and functions to operands.
+</p>
+
+<h3 id="Operands">Operands</h3>
+
+<p>
+Operands denote the elementary values in an expression. An operand may be a
+literal, a (possibly <a href="#Qualified_identifiers">qualified</a>)
+non-<a href="#Blank_identifier">blank</a> identifier denoting a
+<a href="#Constant_declarations">constant</a>,
+<a href="#Variable_declarations">variable</a>, or
+<a href="#Function_declarations">function</a>,
+a <a href="#Method_expressions">method expression</a> yielding a function,
+or a parenthesized expression.
+</p>
+
+<p>
+The <a href="#Blank_identifier">blank identifier</a> may appear as an
+operand only on the left-hand side of an <a href="#Assignments">assignment</a>.
+</p>
+
+<pre class="ebnf">
+Operand = Literal | OperandName | MethodExpr | "(" Expression ")" .
+Literal = BasicLit | CompositeLit | FunctionLit .
+BasicLit = int_lit | float_lit | imaginary_lit | rune_lit | string_lit .
+OperandName = identifier | QualifiedIdent.
+</pre>
+
+<h3 id="Qualified_identifiers">Qualified identifiers</h3>
+
+<p>
+A qualified identifier is an identifier qualified with a package name prefix.
+Both the package name and the identifier must not be
+<a href="#Blank_identifier">blank</a>.
+</p>
+
+<pre class="ebnf">
+QualifiedIdent = PackageName "." identifier .
+</pre>
+
+<p>
+A qualified identifier accesses an identifier in a different package, which
+must be <a href="#Import_declarations">imported</a>.
+The identifier must be <a href="#Exported_identifiers">exported</a> and
+declared in the <a href="#Blocks">package block</a> of that package.
+</p>
+
+<pre>
+math.Sin // denotes the Sin function in package math
+</pre>
+
+<h3 id="Composite_literals">Composite literals</h3>
+
+<p>
+Composite literals construct values for structs, arrays, slices, and maps
+and create a new value each time they are evaluated.
+They consist of the type of the value
+followed by a brace-bound list of composite elements. An element may be
+a single expression or a key-value pair.
+</p>
+
+<pre class="ebnf">
+CompositeLit = LiteralType LiteralValue .
+LiteralType = StructType | ArrayType | "[" "..." "]" ElementType |
+ SliceType | MapType | TypeName .
+LiteralValue = "{" [ ElementList [ "," ] ] "}" .
+ElementList = Element { "," Element } .
+Element = [ Key ":" ] Value .
+Key = FieldName | ElementIndex .
+FieldName = identifier .
+ElementIndex = Expression .
+Value = Expression | LiteralValue .
+</pre>
+
+<p>
+The LiteralType must be a struct, array, slice, or map type
+(the grammar enforces this constraint except when the type is given
+as a TypeName).
+The types of the expressions must be <a href="#Assignability">assignable</a>
+to the respective field, element, and key types of the LiteralType;
+there is no additional conversion.
+The key is interpreted as a field name for struct literals,
+an index for array and slice literals, and a key for map literals.
+For map literals, all elements must have a key. It is an error
+to specify multiple elements with the same field name or
+constant key value.
+</p>
+
+<p>
+For struct literals the following rules apply:
+</p>
+<ul>
+ <li>A key must be a field name declared in the LiteralType.
+ </li>
+ <li>An element list that does not contain any keys must
+ list an element for each struct field in the
+ order in which the fields are declared.
+ </li>
+ <li>If any element has a key, every element must have a key.
+ </li>
+ <li>An element list that contains keys does not need to
+ have an element for each struct field. Omitted fields
+ get the zero value for that field.
+ </li>
+ <li>A literal may omit the element list; such a literal evaluates
+ to the zero value for its type.
+ </li>
+ <li>It is an error to specify an element for a non-exported
+ field of a struct belonging to a different package.
+ </li>
+</ul>
+
+<p>
+Given the declarations
+</p>
+<pre>
+type Point3D struct { x, y, z float64 }
+type Line struct { p, q Point3D }
+</pre>
+
+<p>
+one may write
+</p>
+
+<pre>
+origin := Point3D{} // zero value for Point3D
+line := Line{origin, Point3D{y: -4, z: 12.3}} // zero value for line.q.x
+</pre>
+
+<p>
+For array and slice literals the following rules apply:
+</p>
+<ul>
+ <li>Each element has an associated integer index marking
+ its position in the array.
+ </li>
+ <li>An element with a key uses the key as its index; the
+ key must be a constant integer expression.
+ </li>
+ <li>An element without a key uses the previous element's index plus one.
+ If the first element has no key, its index is zero.
+ </li>
+</ul>
+
+<p>
+<a href="#Address_operators">Taking the address</a> of a composite literal
+generates a pointer to a unique <a href="#Variables">variable</a> initialized
+with the literal's value.
+</p>
+<pre>
+var pointer *Point3D = &Point3D{y: 1000}
+</pre>
+
+<p>
+The length of an array literal is the length specified in the LiteralType.
+If fewer elements than the length are provided in the literal, the missing
+elements are set to the zero value for the array element type.
+It is an error to provide elements with index values outside the index range
+of the array. The notation <code>...</code> specifies an array length equal
+to the maximum element index plus one.
+</p>
+
+<pre>
+buffer := [10]string{} // len(buffer) == 10
+intSet := [6]int{1, 2, 3, 5} // len(intSet) == 6
+days := [...]string{"Sat", "Sun"} // len(days) == 2
+</pre>
+
+<p>
+A slice literal describes the entire underlying array literal.
+Thus, the length and capacity of a slice literal are the maximum
+element index plus one. A slice literal has the form
+</p>
+
+<pre>
+[]T{x1, x2, … xn}
+</pre>
+
+<p>
+and is shorthand for a slice operation applied to an array:
+</p>
+
+<pre>
+tmp := [n]T{x1, x2, … xn}
+tmp[0 : n]
+</pre>
+
+<p>
+Within a composite literal of array, slice, or map type <code>T</code>,
+elements that are themselves composite literals may elide the respective
+literal type if it is identical to the element type of <code>T</code>.
+Similarly, elements that are addresses of composite literals may elide
+the <code>&T</code> when the element type is <code>*T</code>.
+</p>
+
+<pre>
+[...]Point{{1.5, -3.5}, {0, 0}} // same as [...]Point{Point{1.5, -3.5}, Point{0, 0}}
+[][]int{{1, 2, 3}, {4, 5}} // same as [][]int{[]int{1, 2, 3}, []int{4, 5}}
+
+[...]*Point{{1.5, -3.5}, {0, 0}} // same as [...]*Point{&Point{1.5, -3.5}, &Point{0, 0}}
+</pre>
+
+<p>
+A parsing ambiguity arises when a composite literal using the
+TypeName form of the LiteralType appears as an operand between the
+<a href="#Keywords">keyword</a> and the opening brace of the block
+of an "if", "for", or "switch" statement, and the composite literal
+is not enclosed in parentheses, square brackets, or curly braces.
+In this rare case, the opening brace of the literal is erroneously parsed
+as the one introducing the block of statements. To resolve the ambiguity,
+the composite literal must appear within parentheses.
+</p>
+
+<pre>
+if x == (T{a,b,c}[i]) { … }
+if (x == T{a,b,c}[i]) { … }
+</pre>
+
+<p>
+Examples of valid array, slice, and map literals:
+</p>
+
+<pre>
+// list of prime numbers
+primes := []int{2, 3, 5, 7, 9, 2147483647}
+
+// vowels[ch] is true if ch is a vowel
+vowels := [128]bool{'a': true, 'e': true, 'i': true, 'o': true, 'u': true, 'y': true}
+
+// the array [10]float32{-1, 0, 0, 0, -0.1, -0.1, 0, 0, 0, -1}
+filter := [10]float32{-1, 4: -0.1, -0.1, 9: -1}
+
+// frequencies in Hz for equal-tempered scale (A4 = 440Hz)
+noteFrequency := map[string]float32{
+ "C0": 16.35, "D0": 18.35, "E0": 20.60, "F0": 21.83,
+ "G0": 24.50, "A0": 27.50, "B0": 30.87,
+}
+</pre>
+
+
+<h3 id="Function_literals">Function literals</h3>
+
+<p>
+A function literal represents an anonymous <a href="#Function_declarations">function</a>.
+</p>
+
+<pre class="ebnf">
+FunctionLit = "func" Function .
+</pre>
+
+<pre>
+func(a, b int, z float64) bool { return a*b < int(z) }
+</pre>
+
+<p>
+A function literal can be assigned to a variable or invoked directly.
+</p>
+
+<pre>
+f := func(x, y int) int { return x + y }
+func(ch chan int) { ch <- ACK }(replyChan)
+</pre>
+
+<p>
+Function literals are <i>closures</i>: they may refer to variables
+defined in a surrounding function. Those variables are then shared between
+the surrounding function and the function literal, and they survive as long
+as they are accessible.
+</p>
+
+
+<h3 id="Primary_expressions">Primary expressions</h3>
+
+<p>
+Primary expressions are the operands for unary and binary expressions.
+</p>
+
+<pre class="ebnf">
+PrimaryExpr =
+ Operand |
+ Conversion |
+ PrimaryExpr Selector |
+ PrimaryExpr Index |
+ PrimaryExpr Slice |
+ PrimaryExpr TypeAssertion |
+ PrimaryExpr Arguments .
+
+Selector = "." identifier .
+Index = "[" Expression "]" .
+Slice = "[" ( [ Expression ] ":" [ Expression ] ) |
+ ( [ Expression ] ":" Expression ":" Expression )
+ "]" .
+TypeAssertion = "." "(" Type ")" .
+Arguments = "(" [ ( ExpressionList | Type [ "," ExpressionList ] ) [ "..." ] [ "," ] ] ")" .
+</pre>
+
+
+<pre>
+x
+2
+(s + ".txt")
+f(3.1415, true)
+Point{1, 2}
+m["foo"]
+s[i : j + 1]
+obj.color
+f.p[i].x()
+</pre>
+
+
+<h3 id="Selectors">Selectors</h3>
+
+<p>
+For a <a href="#Primary_expressions">primary expression</a> <code>x</code>
+that is not a <a href="#Package_clause">package name</a>, the
+<i>selector expression</i>
+</p>
+
+<pre>
+x.f
+</pre>
+
+<p>
+denotes the field or method <code>f</code> of the value <code>x</code>
+(or sometimes <code>*x</code>; see below).
+The identifier <code>f</code> is called the (field or method) <i>selector</i>;
+it must not be the <a href="#Blank_identifier">blank identifier</a>.
+The type of the selector expression is the type of <code>f</code>.
+If <code>x</code> is a package name, see the section on
+<a href="#Qualified_identifiers">qualified identifiers</a>.
+</p>
+
+<p>
+A selector <code>f</code> may denote a field or method <code>f</code> of
+a type <code>T</code>, or it may refer
+to a field or method <code>f</code> of a nested
+<a href="#Struct_types">anonymous field</a> of <code>T</code>.
+The number of anonymous fields traversed
+to reach <code>f</code> is called its <i>depth</i> in <code>T</code>.
+The depth of a field or method <code>f</code>
+declared in <code>T</code> is zero.
+The depth of a field or method <code>f</code> declared in
+an anonymous field <code>A</code> in <code>T</code> is the
+depth of <code>f</code> in <code>A</code> plus one.
+</p>
+
+<p>
+The following rules apply to selectors:
+</p>
+
+<ol>
+<li>
+For a value <code>x</code> of type <code>T</code> or <code>*T</code>
+where <code>T</code> is not a pointer or interface type,
+<code>x.f</code> denotes the field or method at the shallowest depth
+in <code>T</code> where there
+is such an <code>f</code>.
+If there is not exactly <a href="#Uniqueness_of_identifiers">one <code>f</code></a>
+with shallowest depth, the selector expression is illegal.
+</li>
+
+<li>
+For a value <code>x</code> of type <code>I</code> where <code>I</code>
+is an interface type, <code>x.f</code> denotes the actual method with name
+<code>f</code> of the dynamic value of <code>x</code>.
+If there is no method with name <code>f</code> in the
+<a href="#Method_sets">method set</a> of <code>I</code>, the selector
+expression is illegal.
+</li>
+
+<li>
+As an exception, if the type of <code>x</code> is a named pointer type
+and <code>(*x).f</code> is a valid selector expression denoting a field
+(but not a method), <code>x.f</code> is shorthand for <code>(*x).f</code>.
+</li>
+
+<li>
+In all other cases, <code>x.f</code> is illegal.
+</li>
+
+<li>
+If <code>x</code> is of pointer type and has the value
+<code>nil</code> and <code>x.f</code> denotes a struct field,
+assigning to or evaluating <code>x.f</code>
+causes a <a href="#Run_time_panics">run-time panic</a>.
+</li>
+
+<li>
+If <code>x</code> is of interface type and has the value
+<code>nil</code>, <a href="#Calls">calling</a> or
+<a href="#Method_values">evaluating</a> the method <code>x.f</code>
+causes a <a href="#Run_time_panics">run-time panic</a>.
+</li>
+</ol>
+
+<p>
+For example, given the declarations:
+</p>
+
+<pre>
+type T0 struct {
+ x int
+}
+
+func (*T0) M0()
+
+type T1 struct {
+ y int
+}
+
+func (T1) M1()
+
+type T2 struct {
+ z int
+ T1
+ *T0
+}
+
+func (*T2) M2()
+
+type Q *T2
+
+var t T2 // with t.T0 != nil
+var p *T2 // with p != nil and (*p).T0 != nil
+var q Q = p
+</pre>
+
+<p>
+one may write:
+</p>
+
+<pre>
+t.z // t.z
+t.y // t.T1.y
+t.x // (*t.TO).x
+
+p.z // (*p).z
+p.y // (*p).T1.y
+p.x // (*(*p).T0).x
+
+q.x // (*(*q).T0).x (*q).x is a valid field selector
+
+p.M2() // p.M2() M2 expects *T2 receiver
+p.M1() // ((*p).T1).M1() M1 expects T1 receiver
+p.M0() // ((&(*p).T0)).M0() M0 expects *T0 receiver, see section on Calls
+</pre>
+
+<p>
+but the following is invalid:
+</p>
+
+<pre>
+q.M0() // (*q).M0 is valid but not a field selector
+</pre>
+
+
+<h3 id="Method_expressions">Method expressions</h3>
+
+<p>
+If <code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>,
+<code>T.M</code> is a function that is callable as a regular function
+with the same arguments as <code>M</code> prefixed by an additional
+argument that is the receiver of the method.
+</p>
+
+<pre class="ebnf">
+MethodExpr = ReceiverType "." MethodName .
+ReceiverType = TypeName | "(" "*" TypeName ")" | "(" ReceiverType ")" .
+</pre>
+
+<p>
+Consider a struct type <code>T</code> with two methods,
+<code>Mv</code>, whose receiver is of type <code>T</code>, and
+<code>Mp</code>, whose receiver is of type <code>*T</code>.
+</p>
+
+<pre>
+type T struct {
+ a int
+}
+func (tv T) Mv(a int) int { return 0 } // value receiver
+func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver
+
+var t T
+</pre>
+
+<p>
+The expression
+</p>
+
+<pre>
+T.Mv
+</pre>
+
+<p>
+yields a function equivalent to <code>Mv</code> but
+with an explicit receiver as its first argument; it has signature
+</p>
+
+<pre>
+func(tv T, a int) int
+</pre>
+
+<p>
+That function may be called normally with an explicit receiver, so
+these five invocations are equivalent:
+</p>
+
+<pre>
+t.Mv(7)
+T.Mv(t, 7)
+(T).Mv(t, 7)
+f1 := T.Mv; f1(t, 7)
+f2 := (T).Mv; f2(t, 7)
+</pre>
+
+<p>
+Similarly, the expression
+</p>
+
+<pre>
+(*T).Mp
+</pre>
+
+<p>
+yields a function value representing <code>Mp</code> with signature
+</p>
+
+<pre>
+func(tp *T, f float32) float32
+</pre>
+
+<p>
+For a method with a value receiver, one can derive a function
+with an explicit pointer receiver, so
+</p>
+
+<pre>
+(*T).Mv
+</pre>
+
+<p>
+yields a function value representing <code>Mv</code> with signature
+</p>
+
+<pre>
+func(tv *T, a int) int
+</pre>
+
+<p>
+Such a function indirects through the receiver to create a value
+to pass as the receiver to the underlying method;
+the method does not overwrite the value whose address is passed in
+the function call.
+</p>
+
+<p>
+The final case, a value-receiver function for a pointer-receiver method,
+is illegal because pointer-receiver methods are not in the method set
+of the value type.
+</p>
+
+<p>
+Function values derived from methods are called with function call syntax;
+the receiver is provided as the first argument to the call.
+That is, given <code>f := T.Mv</code>, <code>f</code> is invoked
+as <code>f(t, 7)</code> not <code>t.f(7)</code>.
+To construct a function that binds the receiver, use a
+<a href="#Function_literals">function literal</a> or
+<a href="#Method_values">method value</a>.
+</p>
+
+<p>
+It is legal to derive a function value from a method of an interface type.
+The resulting function takes an explicit receiver of that interface type.
+</p>
+
+<h3 id="Method_values">Method values</h3>
+
+<p>
+If the expression <code>x</code> has static type <code>T</code> and
+<code>M</code> is in the <a href="#Method_sets">method set</a> of type <code>T</code>,
+<code>x.M</code> is called a <i>method value</i>.
+The method value <code>x.M</code> is a function value that is callable
+with the same arguments as a method call of <code>x.M</code>.
+The expression <code>x</code> is evaluated and saved during the evaluation of the
+method value; the saved copy is then used as the receiver in any calls,
+which may be executed later.
+</p>
+
+<p>
+The type <code>T</code> may be an interface or non-interface type.
+</p>
+
+<p>
+As in the discussion of <a href="#Method_expressions">method expressions</a> above,
+consider a struct type <code>T</code> with two methods,
+<code>Mv</code>, whose receiver is of type <code>T</code>, and
+<code>Mp</code>, whose receiver is of type <code>*T</code>.
+</p>
+
+<pre>
+type T struct {
+ a int
+}
+func (tv T) Mv(a int) int { return 0 } // value receiver
+func (tp *T) Mp(f float32) float32 { return 1 } // pointer receiver
+
+var t T
+var pt *T
+func makeT() T
+</pre>
+
+<p>
+The expression
+</p>
+
+<pre>
+t.Mv
+</pre>
+
+<p>
+yields a function value of type
+</p>
+
+<pre>
+func(int) int
+</pre>
+
+<p>
+These two invocations are equivalent:
+</p>
+
+<pre>
+t.Mv(7)
+f := t.Mv; f(7)
+</pre>
+
+<p>
+Similarly, the expression
+</p>
+
+<pre>
+pt.Mp
+</pre>
+
+<p>
+yields a function value of type
+</p>
+
+<pre>
+func(float32) float32
+</pre>
+
+<p>
+As with <a href="#Selectors">selectors</a>, a reference to a non-interface method with a value receiver
+using a pointer will automatically dereference that pointer: <code>pt.Mv</code> is equivalent to <code>(*pt).Mv</code>.
+</p>
+
+<p>
+As with <a href="#Calls">method calls</a>, a reference to a non-interface method with a pointer receiver
+using an addressable value will automatically take the address of that value: <code>t.Mp</code> is equivalent to <code>(&t).Mp</code>.
+</p>
+
+<pre>
+f := t.Mv; f(7) // like t.Mv(7)
+f := pt.Mp; f(7) // like pt.Mp(7)
+f := pt.Mv; f(7) // like (*pt).Mv(7)
+f := t.Mp; f(7) // like (&t).Mp(7)
+f := makeT().Mp // invalid: result of makeT() is not addressable
+</pre>
+
+<p>
+Although the examples above use non-interface types, it is also legal to create a method value
+from a value of interface type.
+</p>
+
+<pre>
+var i interface { M(int) } = myVal
+f := i.M; f(7) // like i.M(7)
+</pre>
+
+
+<h3 id="Index_expressions">Index expressions</h3>
+
+<p>
+A primary expression of the form
+</p>
+
+<pre>
+a[x]
+</pre>
+
+<p>
+denotes the element of the array, pointer to array, slice, string or map <code>a</code> indexed by <code>x</code>.
+The value <code>x</code> is called the <i>index</i> or <i>map key</i>, respectively.
+The following rules apply:
+</p>
+
+<p>
+If <code>a</code> is not a map:
+</p>
+<ul>
+ <li>the index <code>x</code> must be of integer type or untyped;
+ it is <i>in range</i> if <code>0 <= x < len(a)</code>,
+ otherwise it is <i>out of range</i></li>
+ <li>a <a href="#Constants">constant</a> index must be non-negative
+ and representable by a value of type <code>int</code>
+</ul>
+
+<p>
+For <code>a</code> of <a href="#Array_types">array type</a> <code>A</code>:
+</p>
+<ul>
+ <li>a <a href="#Constants">constant</a> index must be in range</li>
+ <li>if <code>x</code> is out of range at run time,
+ a <a href="#Run_time_panics">run-time panic</a> occurs</li>
+ <li><code>a[x]</code> is the array element at index <code>x</code> and the type of
+ <code>a[x]</code> is the element type of <code>A</code></li>
+</ul>
+
+<p>
+For <code>a</code> of <a href="#Pointer_types">pointer</a> to array type:
+</p>
+<ul>
+ <li><code>a[x]</code> is shorthand for <code>(*a)[x]</code></li>
+</ul>
+
+<p>
+For <code>a</code> of <a href="#Slice_types">slice type</a> <code>S</code>:
+</p>
+<ul>
+ <li>if <code>x</code> is out of range at run time,
+ a <a href="#Run_time_panics">run-time panic</a> occurs</li>
+ <li><code>a[x]</code> is the slice element at index <code>x</code> and the type of
+ <code>a[x]</code> is the element type of <code>S</code></li>
+</ul>
+
+<p>
+For <code>a</code> of <a href="#String_types">string type</a>:
+</p>
+<ul>
+ <li>a <a href="#Constants">constant</a> index must be in range
+ if the string <code>a</code> is also constant</li>
+ <li>if <code>x</code> is out of range at run time,
+ a <a href="#Run_time_panics">run-time panic</a> occurs</li>
+ <li><code>a[x]</code> is the non-constant byte value at index <code>x</code> and the type of
+ <code>a[x]</code> is <code>byte</code></li>
+ <li><code>a[x]</code> may not be assigned to</li>
+</ul>
+
+<p>
+For <code>a</code> of <a href="#Map_types">map type</a> <code>M</code>:
+</p>
+<ul>
+ <li><code>x</code>'s type must be
+ <a href="#Assignability">assignable</a>
+ to the key type of <code>M</code></li>
+ <li>if the map contains an entry with key <code>x</code>,
+ <code>a[x]</code> is the map value with key <code>x</code>
+ and the type of <code>a[x]</code> is the value type of <code>M</code></li>
+ <li>if the map is <code>nil</code> or does not contain such an entry,
+ <code>a[x]</code> is the <a href="#The_zero_value">zero value</a>
+ for the value type of <code>M</code></li>
+</ul>
+
+<p>
+Otherwise <code>a[x]</code> is illegal.
+</p>
+
+<p>
+An index expression on a map <code>a</code> of type <code>map[K]V</code>
+used in an <a href="#Assignments">assignment</a> or initialization of the special form
+</p>
+
+<pre>
+v, ok = a[x]
+v, ok := a[x]
+var v, ok = a[x]
+</pre>
+
+<p>
+yields an additional untyped boolean value. The value of <code>ok</code> is
+<code>true</code> if the key <code>x</code> is present in the map, and
+<code>false</code> otherwise.
+</p>
+
+<p>
+Assigning to an element of a <code>nil</code> map causes a
+<a href="#Run_time_panics">run-time panic</a>.
+</p>
+
+
+<h3 id="Slice_expressions">Slice expressions</h3>
+
+<p>
+Slice expressions construct a substring or slice from a string, array, pointer
+to array, or slice. There are two variants: a simple form that specifies a low
+and high bound, and a full form that also specifies a bound on the capacity.
+</p>
+
+<h4>Simple slice expressions</h4>
+
+<p>
+For a string, array, pointer to array, or slice <code>a</code>, the primary expression
+</p>
+
+<pre>
+a[low : high]
+</pre>
+
+<p>
+constructs a substring or slice. The <i>indices</i> <code>low</code> and
+<code>high</code> select which elements of operand <code>a</code> appear
+in the result. The result has indices starting at 0 and length equal to
+<code>high</code> - <code>low</code>.
+After slicing the array <code>a</code>
+</p>
+
+<pre>
+a := [5]int{1, 2, 3, 4, 5}
+s := a[1:4]
+</pre>
+
+<p>
+the slice <code>s</code> has type <code>[]int</code>, length 3, capacity 4, and elements
+</p>
+
+<pre>
+s[0] == 2
+s[1] == 3
+s[2] == 4
+</pre>
+
+<p>
+For convenience, any of the indices may be omitted. A missing <code>low</code>
+index defaults to zero; a missing <code>high</code> index defaults to the length of the
+sliced operand:
+</p>
+
+<pre>
+a[2:] // same as a[2 : len(a)]
+a[:3] // same as a[0 : 3]
+a[:] // same as a[0 : len(a)]
+</pre>
+
+<p>
+If <code>a</code> is a pointer to an array, <code>a[low : high]</code> is shorthand for
+<code>(*a)[low : high]</code>.
+</p>
+
+<p>
+For arrays or strings, the indices are <i>in range</i> if
+<code>0</code> <= <code>low</code> <= <code>high</code> <= <code>len(a)</code>,
+otherwise they are <i>out of range</i>.
+For slices, the upper index bound is the slice capacity <code>cap(a)</code> rather than the length.
+A <a href="#Constants">constant</a> index must be non-negative and representable by a value of type
+<code>int</code>; for arrays or constant strings, constant indices must also be in range.
+If both indices are constant, they must satisfy <code>low <= high</code>.
+If the indices are out of range at run time, a <a href="#Run_time_panics">run-time panic</a> occurs.
+</p>
+
+<p>
+Except for <a href="#Constants">untyped strings</a>, if the sliced operand is a string or slice,
+the result of the slice operation is a non-constant value of the same type as the operand.
+For untyped string operands the result is a non-constant value of type <code>string</code>.
+If the sliced operand is an array, it must be <a href="#Address_operators">addressable</a>
+and the result of the slice operation is a slice with the same element type as the array.
+</p>
+
+<p>
+If the sliced operand of a valid slice expression is a <code>nil</code> slice, the result
+is a <code>nil</code> slice. Otherwise, the result shares its underlying array with the
+operand.
+</p>
+
+<h4>Full slice expressions</h4>
+
+<p>
+For an array, pointer to array, or slice <code>a</code> (but not a string), the primary expression
+</p>
+
+<pre>
+a[low : high : max]
+</pre>
+
+<p>
+constructs a slice of the same type, and with the same length and elements as the simple slice
+expression <code>a[low : high]</code>. Additionally, it controls the resulting slice's capacity
+by setting it to <code>max - low</code>. Only the first index may be omitted; it defaults to 0.
+After slicing the array <code>a</code>
+</p>
+
+<pre>
+a := [5]int{1, 2, 3, 4, 5}
+t := a[1:3:5]
+</pre>
+
+<p>
+the slice <code>t</code> has type <code>[]int</code>, length 2, capacity 4, and elements
+</p>
+
+<pre>
+t[0] == 2
+t[1] == 3
+</pre>
+
+<p>
+As for simple slice expressions, if <code>a</code> is a pointer to an array,
+<code>a[low : high : max]</code> is shorthand for <code>(*a)[low : high : max]</code>.
+If the sliced operand is an array, it must be <a href="#Address_operators">addressable</a>.
+</p>
+
+<p>
+The indices are <i>in range</i> if <code>0 <= low <= high <= max <= cap(a)</code>,
+otherwise they are <i>out of range</i>.
+A <a href="#Constants">constant</a> index must be non-negative and representable by a value of type
+<code>int</code>; for arrays, constant indices must also be in range.
+If multiple indices are constant, the constants that are present must be in range relative to each
+other.
+If the indices are out of range at run time, a <a href="#Run_time_panics">run-time panic</a> occurs.
+</p>
+
+<h3 id="Type_assertions">Type assertions</h3>
+
+<p>
+For an expression <code>x</code> of <a href="#Interface_types">interface type</a>
+and a type <code>T</code>, the primary expression
+</p>
+
+<pre>
+x.(T)
+</pre>
+
+<p>
+asserts that <code>x</code> is not <code>nil</code>
+and that the value stored in <code>x</code> is of type <code>T</code>.
+The notation <code>x.(T)</code> is called a <i>type assertion</i>.
+</p>
+<p>
+More precisely, if <code>T</code> is not an interface type, <code>x.(T)</code> asserts
+that the dynamic type of <code>x</code> is <a href="#Type_identity">identical</a>
+to the type <code>T</code>.
+In this case, <code>T</code> must <a href="#Method_sets">implement</a> the (interface) type of <code>x</code>;
+otherwise the type assertion is invalid since it is not possible for <code>x</code>
+to store a value of type <code>T</code>.
+If <code>T</code> is an interface type, <code>x.(T)</code> asserts that the dynamic type
+of <code>x</code> implements the interface <code>T</code>.
+</p>
+<p>
+If the type assertion holds, the value of the expression is the value
+stored in <code>x</code> and its type is <code>T</code>. If the type assertion is false,
+a <a href="#Run_time_panics">run-time panic</a> occurs.
+In other words, even though the dynamic type of <code>x</code>
+is known only at run time, the type of <code>x.(T)</code> is
+known to be <code>T</code> in a correct program.
+</p>
+
+<pre>
+var x interface{} = 7 // x has dynamic type int and value 7
+i := x.(int) // i has type int and value 7
+
+type I interface { m() }
+var y I
+s := y.(string) // illegal: string does not implement I (missing method m)
+r := y.(io.Reader) // r has type io.Reader and y must implement both I and io.Reader
+</pre>
+
+<p>
+A type assertion used in an <a href="#Assignments">assignment</a> or initialization of the special form
+</p>
+
+<pre>
+v, ok = x.(T)
+v, ok := x.(T)
+var v, ok = x.(T)
+</pre>
+
+<p>
+yields an additional untyped boolean value. The value of <code>ok</code> is <code>true</code>
+if the assertion holds. Otherwise it is <code>false</code> and the value of <code>v</code> is
+the <a href="#The_zero_value">zero value</a> for type <code>T</code>.
+No run-time panic occurs in this case.
+</p>
+
+
+<h3 id="Calls">Calls</h3>
+
+<p>
+Given an expression <code>f</code> of function type
+<code>F</code>,
+</p>
+
+<pre>
+f(a1, a2, … an)
+</pre>
+
+<p>
+calls <code>f</code> with arguments <code>a1, a2, … an</code>.
+Except for one special case, arguments must be single-valued expressions
+<a href="#Assignability">assignable</a> to the parameter types of
+<code>F</code> and are evaluated before the function is called.
+The type of the expression is the result type
+of <code>F</code>.
+A method invocation is similar but the method itself
+is specified as a selector upon a value of the receiver type for
+the method.
+</p>
+
+<pre>
+math.Atan2(x, y) // function call
+var pt *Point
+pt.Scale(3.5) // method call with receiver pt
+</pre>
+
+<p>
+In a function call, the function value and arguments are evaluated in
+<a href="#Order_of_evaluation">the usual order</a>.
+After they are evaluated, the parameters of the call are passed by value to the function
+and the called function begins execution.
+The return parameters of the function are passed by value
+back to the calling function when the function returns.
+</p>
+
+<p>
+Calling a <code>nil</code> function value
+causes a <a href="#Run_time_panics">run-time panic</a>.
+</p>
+
+<p>
+As a special case, if the return values of a function or method
+<code>g</code> are equal in number and individually
+assignable to the parameters of another function or method
+<code>f</code>, then the call <code>f(g(<i>parameters_of_g</i>))</code>
+will invoke <code>f</code> after binding the return values of
+<code>g</code> to the parameters of <code>f</code> in order. The call
+of <code>f</code> must contain no parameters other than the call of <code>g</code>,
+and <code>g</code> must have at least one return value.
+If <code>f</code> has a final <code>...</code> parameter, it is
+assigned the return values of <code>g</code> that remain after
+assignment of regular parameters.
+</p>
+
+<pre>
+func Split(s string, pos int) (string, string) {
+ return s[0:pos], s[pos:]
+}
+
+func Join(s, t string) string {
+ return s + t
+}
+
+if Join(Split(value, len(value)/2)) != value {
+ log.Panic("test fails")
+}
+</pre>
+
+<p>
+A method call <code>x.m()</code> is valid if the <a href="#Method_sets">method set</a>
+of (the type of) <code>x</code> contains <code>m</code> and the
+argument list can be assigned to the parameter list of <code>m</code>.
+If <code>x</code> is <a href="#Address_operators">addressable</a> and <code>&x</code>'s method
+set contains <code>m</code>, <code>x.m()</code> is shorthand
+for <code>(&x).m()</code>:
+</p>
+
+<pre>
+var p Point
+p.Scale(3.5)
+</pre>
+
+<p>
+There is no distinct method type and there are no method literals.
+</p>
+
+<h3 id="Passing_arguments_to_..._parameters">Passing arguments to <code>...</code> parameters</h3>
+
+<p>
+If <code>f</code> is <a href="#Function_types">variadic</a> with a final
+parameter <code>p</code> of type <code>...T</code>, then within <code>f</code>
+the type of <code>p</code> is equivalent to type <code>[]T</code>.
+If <code>f</code> is invoked with no actual arguments for <code>p</code>,
+the value passed to <code>p</code> is <code>nil</code>.
+Otherwise, the value passed is a new slice
+of type <code>[]T</code> with a new underlying array whose successive elements
+are the actual arguments, which all must be <a href="#Assignability">assignable</a>
+to <code>T</code>. The length and capacity of the slice is therefore
+the number of arguments bound to <code>p</code> and may differ for each
+call site.
+</p>
+
+<p>
+Given the function and calls
+</p>
+<pre>
+func Greeting(prefix string, who ...string)
+Greeting("nobody")
+Greeting("hello:", "Joe", "Anna", "Eileen")
+</pre>
+
+<p>
+within <code>Greeting</code>, <code>who</code> will have the value
+<code>nil</code> in the first call, and
+<code>[]string{"Joe", "Anna", "Eileen"}</code> in the second.
+</p>
+
+<p>
+If the final argument is assignable to a slice type <code>[]T</code>, it may be
+passed unchanged as the value for a <code>...T</code> parameter if the argument
+is followed by <code>...</code>. In this case no new slice is created.
+</p>
+
+<p>
+Given the slice <code>s</code> and call
+</p>
+
+<pre>
+s := []string{"James", "Jasmine"}
+Greeting("goodbye:", s...)
+</pre>
+
+<p>
+within <code>Greeting</code>, <code>who</code> will have the same value as <code>s</code>
+with the same underlying array.
+</p>
+
+
+<h3 id="Operators">Operators</h3>
+
+<p>
+Operators combine operands into expressions.
+</p>
+
+<pre class="ebnf">
+Expression = UnaryExpr | Expression binary_op UnaryExpr .
+UnaryExpr = PrimaryExpr | unary_op UnaryExpr .
+
+binary_op = "||" | "&&" | rel_op | add_op | mul_op .
+rel_op = "==" | "!=" | "<" | "<=" | ">" | ">=" .
+add_op = "+" | "-" | "|" | "^" .
+mul_op = "*" | "/" | "%" | "<<" | ">>" | "&" | "&^" .
+
+unary_op = "+" | "-" | "!" | "^" | "*" | "&" | "<-" .
+</pre>
+
+<p>
+Comparisons are discussed <a href="#Comparison_operators">elsewhere</a>.
+For other binary operators, the operand types must be <a href="#Type_identity">identical</a>
+unless the operation involves shifts or untyped <a href="#Constants">constants</a>.
+For operations involving constants only, see the section on
+<a href="#Constant_expressions">constant expressions</a>.
+</p>
+
+<p>
+Except for shift operations, if one operand is an untyped <a href="#Constants">constant</a>
+and the other operand is not, the constant is <a href="#Conversions">converted</a>
+to the type of the other operand.
+</p>
+
+<p>
+The right operand in a shift expression must have unsigned integer type
+or be an untyped constant that can be converted to unsigned integer type.
+If the left operand of a non-constant shift expression is an untyped constant,
+the type of the constant is what it would be if the shift expression were
+replaced by its left operand alone.
+</p>
+
+<pre>
+var s uint = 33
+var i = 1<<s // 1 has type int
+var j int32 = 1<<s // 1 has type int32; j == 0
+var k = uint64(1<<s) // 1 has type uint64; k == 1<<33
+var m int = 1.0<<s // 1.0 has type int
+var n = 1.0<<s != i // 1.0 has type int; n == false if ints are 32bits in size
+var o = 1<<s == 2<<s // 1 and 2 have type int; o == true if ints are 32bits in size
+var p = 1<<s == 1<<33 // illegal if ints are 32bits in size: 1 has type int, but 1<<33 overflows int
+var u = 1.0<<s // illegal: 1.0 has type float64, cannot shift
+var u1 = 1.0<<s != 0 // illegal: 1.0 has type float64, cannot shift
+var u2 = 1<<s != 1.0 // illegal: 1 has type float64, cannot shift
+var v float32 = 1<<s // illegal: 1 has type float32, cannot shift
+var w int64 = 1.0<<33 // 1.0<<33 is a constant shift expression
+</pre>
+
+<h3 id="Operator_precedence">Operator precedence</h3>
+<p>
+Unary operators have the highest precedence.
+As the <code>++</code> and <code>--</code> operators form
+statements, not expressions, they fall
+outside the operator hierarchy.
+As a consequence, statement <code>*p++</code> is the same as <code>(*p)++</code>.
+<p>
+There are five precedence levels for binary operators.
+Multiplication operators bind strongest, followed by addition
+operators, comparison operators, <code>&&</code> (logical AND),
+and finally <code>||</code> (logical OR):
+</p>
+
+<pre class="grammar">
+Precedence Operator
+ 5 * / % << >> & &^
+ 4 + - | ^
+ 3 == != < <= > >=
+ 2 &&
+ 1 ||
+</pre>
+
+<p>
+Binary operators of the same precedence associate from left to right.
+For instance, <code>x / y * z</code> is the same as <code>(x / y) * z</code>.
+</p>
+
+<pre>
++x
+23 + 3*x[i]
+x <= f()
+^a >> b
+f() || g()
+x == y+1 && <-chanPtr > 0
+</pre>
+
+
+<h3 id="Arithmetic_operators">Arithmetic operators</h3>
+<p>
+Arithmetic operators apply to numeric values and yield a result of the same
+type as the first operand. The four standard arithmetic operators (<code>+</code>,
+<code>-</code>, <code>*</code>, <code>/</code>) apply to integer,
+floating-point, and complex types; <code>+</code> also applies
+to strings. All other arithmetic operators apply to integers only.
+</p>
+
+<pre class="grammar">
++ sum integers, floats, complex values, strings
+- difference integers, floats, complex values
+* product integers, floats, complex values
+/ quotient integers, floats, complex values
+% remainder integers
+
+& bitwise AND integers
+| bitwise OR integers
+^ bitwise XOR integers
+&^ bit clear (AND NOT) integers
+
+<< left shift integer << unsigned integer
+>> right shift integer >> unsigned integer
+</pre>
+
+<p>
+Strings can be concatenated using the <code>+</code> operator
+or the <code>+=</code> assignment operator:
+</p>
+
+<pre>
+s := "hi" + string(c)
+s += " and good bye"
+</pre>
+
+<p>
+String addition creates a new string by concatenating the operands.
+</p>
+<p>
+For two integer values <code>x</code> and <code>y</code>, the integer quotient
+<code>q = x / y</code> and remainder <code>r = x % y</code> satisfy the following
+relationships:
+</p>
+
+<pre>
+x = q*y + r and |r| < |y|
+</pre>
+
+<p>
+with <code>x / y</code> truncated towards zero
+(<a href="http://en.wikipedia.org/wiki/Modulo_operation">"truncated division"</a>).
+</p>
+
+<pre>
+ x y x / y x % y
+ 5 3 1 2
+-5 3 -1 -2
+ 5 -3 -1 2
+-5 -3 1 -2
+</pre>
+
+<p>
+As an exception to this rule, if the dividend <code>x</code> is the most
+negative value for the int type of <code>x</code>, the quotient
+<code>q = x / -1</code> is equal to <code>x</code> (and <code>r = 0</code>).
+</p>
+
+<pre>
+ x, q
+int8 -128
+int16 -32768
+int32 -2147483648
+int64 -9223372036854775808
+</pre>
+
+<p>
+If the divisor is a <a href="#Constants">constant</a>, it must not be zero.
+If the divisor is zero at run time, a <a href="#Run_time_panics">run-time panic</a> occurs.
+If the dividend is non-negative and the divisor is a constant power of 2,
+the division may be replaced by a right shift, and computing the remainder may
+be replaced by a bitwise AND operation:
+</p>
+
+<pre>
+ x x / 4 x % 4 x >> 2 x & 3
+ 11 2 3 2 3
+-11 -2 -3 -3 1
+</pre>
+
+<p>
+The shift operators shift the left operand by the shift count specified by the
+right operand. They implement arithmetic shifts if the left operand is a signed
+integer and logical shifts if it is an unsigned integer.
+There is no upper limit on the shift count. Shifts behave
+as if the left operand is shifted <code>n</code> times by 1 for a shift
+count of <code>n</code>.
+As a result, <code>x << 1</code> is the same as <code>x*2</code>
+and <code>x >> 1</code> is the same as
+<code>x/2</code> but truncated towards negative infinity.
+</p>
+
+<p>
+For integer operands, the unary operators
+<code>+</code>, <code>-</code>, and <code>^</code> are defined as
+follows:
+</p>
+
+<pre class="grammar">
++x is 0 + x
+-x negation is 0 - x
+^x bitwise complement is m ^ x with m = "all bits set to 1" for unsigned x
+ and m = -1 for signed x
+</pre>
+
+<p>
+For floating-point and complex numbers,
+<code>+x</code> is the same as <code>x</code>,
+while <code>-x</code> is the negation of <code>x</code>.
+The result of a floating-point or complex division by zero is not specified beyond the
+IEEE-754 standard; whether a <a href="#Run_time_panics">run-time panic</a>
+occurs is implementation-specific.
+</p>
+
+<h3 id="Integer_overflow">Integer overflow</h3>
+
+<p>
+For unsigned integer values, the operations <code>+</code>,
+<code>-</code>, <code>*</code>, and <code><<</code> are
+computed modulo 2<sup><i>n</i></sup>, where <i>n</i> is the bit width of
+the <a href="#Numeric_types">unsigned integer</a>'s type.
+Loosely speaking, these unsigned integer operations
+discard high bits upon overflow, and programs may rely on ``wrap around''.
+</p>
+<p>
+For signed integers, the operations <code>+</code>,
+<code>-</code>, <code>*</code>, and <code><<</code> may legally
+overflow and the resulting value exists and is deterministically defined
+by the signed integer representation, the operation, and its operands.
+No exception is raised as a result of overflow. A
+compiler may not optimize code under the assumption that overflow does
+not occur. For instance, it may not assume that <code>x < x + 1</code> is always true.
+</p>
+
+
+<h3 id="Comparison_operators">Comparison operators</h3>
+
+<p>
+Comparison operators compare two operands and yield an untyped boolean value.
+</p>
+
+<pre class="grammar">
+== equal
+!= not equal
+< less
+<= less or equal
+> greater
+>= greater or equal
+</pre>
+
+<p>
+In any comparison, the first operand
+must be <a href="#Assignability">assignable</a>
+to the type of the second operand, or vice versa.
+</p>
+<p>
+The equality operators <code>==</code> and <code>!=</code> apply
+to operands that are <i>comparable</i>.
+The ordering operators <code><</code>, <code><=</code>, <code>></code>, and <code>>=</code>
+apply to operands that are <i>ordered</i>.
+These terms and the result of the comparisons are defined as follows:
+</p>
+
+<ul>
+ <li>
+ Boolean values are comparable.
+ Two boolean values are equal if they are either both
+ <code>true</code> or both <code>false</code>.
+ </li>
+
+ <li>
+ Integer values are comparable and ordered, in the usual way.
+ </li>
+
+ <li>
+ Floating point values are comparable and ordered,
+ as defined by the IEEE-754 standard.
+ </li>
+
+ <li>
+ Complex values are comparable.
+ Two complex values <code>u</code> and <code>v</code> are
+ equal if both <code>real(u) == real(v)</code> and
+ <code>imag(u) == imag(v)</code>.
+ </li>
+
+ <li>
+ String values are comparable and ordered, lexically byte-wise.
+ </li>
+
+ <li>
+ Pointer values are comparable.
+ Two pointer values are equal if they point to the same variable or if both have value <code>nil</code>.
+ Pointers to distinct <a href="#Size_and_alignment_guarantees">zero-size</a> variables may or may not be equal.
+ </li>
+
+ <li>
+ Channel values are comparable.
+ Two channel values are equal if they were created by the same call to
+ <a href="#Making_slices_maps_and_channels"><code>make</code></a>
+ or if both have value <code>nil</code>.
+ </li>
+
+ <li>
+ Interface values are comparable.
+ Two interface values are equal if they have <a href="#Type_identity">identical</a> dynamic types
+ and equal dynamic values or if both have value <code>nil</code>.
+ </li>
+
+ <li>
+ A value <code>x</code> of non-interface type <code>X</code> and
+ a value <code>t</code> of interface type <code>T</code> are comparable when values
+ of type <code>X</code> are comparable and
+ <code>X</code> implements <code>T</code>.
+ They are equal if <code>t</code>'s dynamic type is identical to <code>X</code>
+ and <code>t</code>'s dynamic value is equal to <code>x</code>.
+ </li>
+
+ <li>
+ Struct values are comparable if all their fields are comparable.
+ Two struct values are equal if their corresponding
+ non-<a href="#Blank_identifier">blank</a> fields are equal.
+ </li>
+
+ <li>
+ Array values are comparable if values of the array element type are comparable.
+ Two array values are equal if their corresponding elements are equal.
+ </li>
+</ul>
+
+<p>
+A comparison of two interface values with identical dynamic types
+causes a <a href="#Run_time_panics">run-time panic</a> if values
+of that type are not comparable. This behavior applies not only to direct interface
+value comparisons but also when comparing arrays of interface values
+or structs with interface-valued fields.
+</p>
+
+<p>
+Slice, map, and function values are not comparable.
+However, as a special case, a slice, map, or function value may
+be compared to the predeclared identifier <code>nil</code>.
+Comparison of pointer, channel, and interface values to <code>nil</code>
+is also allowed and follows from the general rules above.
+</p>
+
+<pre>
+const c = 3 < 4 // c is the untyped bool constant true
+
+type MyBool bool
+var x, y int
+var (
+ // The result of a comparison is an untyped bool.
+ // The usual assignment rules apply.
+ b3 = x == y // b3 has type bool
+ b4 bool = x == y // b4 has type bool
+ b5 MyBool = x == y // b5 has type MyBool
+)
+</pre>
+
+<h3 id="Logical_operators">Logical operators</h3>
+
+<p>
+Logical operators apply to <a href="#Boolean_types">boolean</a> values
+and yield a result of the same type as the operands.
+The right operand is evaluated conditionally.
+</p>
+
+<pre class="grammar">
+&& conditional AND p && q is "if p then q else false"
+|| conditional OR p || q is "if p then true else q"
+! NOT !p is "not p"
+</pre>
+
+
+<h3 id="Address_operators">Address operators</h3>
+
+<p>
+For an operand <code>x</code> of type <code>T</code>, the address operation
+<code>&x</code> generates a pointer of type <code>*T</code> to <code>x</code>.
+The operand must be <i>addressable</i>,
+that is, either a variable, pointer indirection, or slice indexing
+operation; or a field selector of an addressable struct operand;
+or an array indexing operation of an addressable array.
+As an exception to the addressability requirement, <code>x</code> may also be a
+(possibly parenthesized)
+<a href="#Composite_literals">composite literal</a>.
+If the evaluation of <code>x</code> would cause a <a href="#Run_time_panics">run-time panic</a>,
+then the evaluation of <code>&x</code> does too.
+</p>
+
+<p>
+For an operand <code>x</code> of pointer type <code>*T</code>, the pointer
+indirection <code>*x</code> denotes the <a href="#Variables">variable</a> of type <code>T</code> pointed
+to by <code>x</code>.
+If <code>x</code> is <code>nil</code>, an attempt to evaluate <code>*x</code>
+will cause a <a href="#Run_time_panics">run-time panic</a>.
+</p>
+
+<pre>
+&x
+&a[f(2)]
+&Point{2, 3}
+*p
+*pf(x)
+
+var x *int = nil
+*x // causes a run-time panic
+&*x // causes a run-time panic
+</pre>
+
+
+<h3 id="Receive_operator">Receive operator</h3>
+
+<p>
+For an operand <code>ch</code> of <a href="#Channel_types">channel type</a>,
+the value of the receive operation <code><-ch</code> is the value received
+from the channel <code>ch</code>. The channel direction must permit receive operations,
+and the type of the receive operation is the element type of the channel.
+The expression blocks until a value is available.
+Receiving from a <code>nil</code> channel blocks forever.
+A receive operation on a <a href="#Close">closed</a> channel can always proceed
+immediately, yielding the element type's <a href="#The_zero_value">zero value</a>
+after any previously sent values have been received.
+</p>
+
+<pre>
+v1 := <-ch
+v2 = <-ch
+f(<-ch)
+<-strobe // wait until clock pulse and discard received value
+</pre>
+
+<p>
+A receive expression used in an <a href="#Assignments">assignment</a> or initialization of the special form
+</p>
+
+<pre>
+x, ok = <-ch
+x, ok := <-ch
+var x, ok = <-ch
+</pre>
+
+<p>
+yields an additional untyped boolean result reporting whether the
+communication succeeded. The value of <code>ok</code> is <code>true</code>
+if the value received was delivered by a successful send operation to the
+channel, or <code>false</code> if it is a zero value generated because the
+channel is closed and empty.
+</p>
+
+
+<h3 id="Conversions">Conversions</h3>
+
+<p>
+Conversions are expressions of the form <code>T(x)</code>
+where <code>T</code> is a type and <code>x</code> is an expression
+that can be converted to type <code>T</code>.
+</p>
+
+<pre class="ebnf">
+Conversion = Type "(" Expression [ "," ] ")" .
+</pre>
+
+<p>
+If the type starts with the operator <code>*</code> or <code><-</code>,
+or if the type starts with the keyword <code>func</code>
+and has no result list, it must be parenthesized when
+necessary to avoid ambiguity:
+</p>
+
+<pre>
+*Point(p) // same as *(Point(p))
+(*Point)(p) // p is converted to *Point
+<-chan int(c) // same as <-(chan int(c))
+(<-chan int)(c) // c is converted to <-chan int
+func()(x) // function signature func() x
+(func())(x) // x is converted to func()
+(func() int)(x) // x is converted to func() int
+func() int(x) // x is converted to func() int (unambiguous)
+</pre>
+
+<p>
+A <a href="#Constants">constant</a> value <code>x</code> can be converted to
+type <code>T</code> in any of these cases:
+</p>
+
+<ul>
+ <li>
+ <code>x</code> is representable by a value of type <code>T</code>.
+ </li>
+ <li>
+ <code>x</code> is a floating-point constant,
+ <code>T</code> is a floating-point type,
+ and <code>x</code> is representable by a value
+ of type <code>T</code> after rounding using
+ IEEE 754 round-to-even rules.
+ The constant <code>T(x)</code> is the rounded value.
+ </li>
+ <li>
+ <code>x</code> is an integer constant and <code>T</code> is a
+ <a href="#String_types">string type</a>.
+ The <a href="#Conversions_to_and_from_a_string_type">same rule</a>
+ as for non-constant <code>x</code> applies in this case.
+ </li>
+</ul>
+
+<p>
+Converting a constant yields a typed constant as result.
+</p>
+
+<pre>
+uint(iota) // iota value of type uint
+float32(2.718281828) // 2.718281828 of type float32
+complex128(1) // 1.0 + 0.0i of type complex128
+float32(0.49999999) // 0.5 of type float32
+string('x') // "x" of type string
+string(0x266c) // "♬" of type string
+MyString("foo" + "bar") // "foobar" of type MyString
+string([]byte{'a'}) // not a constant: []byte{'a'} is not a constant
+(*int)(nil) // not a constant: nil is not a constant, *int is not a boolean, numeric, or string type
+int(1.2) // illegal: 1.2 cannot be represented as an int
+string(65.0) // illegal: 65.0 is not an integer constant
+</pre>
+
+<p>
+A non-constant value <code>x</code> can be converted to type <code>T</code>
+in any of these cases:
+</p>
+
+<ul>
+ <li>
+ <code>x</code> is <a href="#Assignability">assignable</a>
+ to <code>T</code>.
+ </li>
+ <li>
+ <code>x</code>'s type and <code>T</code> have identical
+ <a href="#Types">underlying types</a>.
+ </li>
+ <li>
+ <code>x</code>'s type and <code>T</code> are unnamed pointer types
+ and their pointer base types have identical underlying types.
+ </li>
+ <li>
+ <code>x</code>'s type and <code>T</code> are both integer or floating
+ point types.
+ </li>
+ <li>
+ <code>x</code>'s type and <code>T</code> are both complex types.
+ </li>
+ <li>
+ <code>x</code> is an integer or a slice of bytes or runes
+ and <code>T</code> is a string type.
+ </li>
+ <li>
+ <code>x</code> is a string and <code>T</code> is a slice of bytes or runes.
+ </li>
+</ul>
+
+<p>
+Specific rules apply to (non-constant) conversions between numeric types or
+to and from a string type.
+These conversions may change the representation of <code>x</code>
+and incur a run-time cost.
+All other conversions only change the type but not the representation
+of <code>x</code>.
+</p>
+
+<p>
+There is no linguistic mechanism to convert between pointers and integers.
+The package <a href="#Package_unsafe"><code>unsafe</code></a>
+implements this functionality under
+restricted circumstances.
+</p>
+
+<h4>Conversions between numeric types</h4>
+
+<p>
+For the conversion of non-constant numeric values, the following rules apply:
+</p>
+
+<ol>
+<li>
+When converting between integer types, if the value is a signed integer, it is
+sign extended to implicit infinite precision; otherwise it is zero extended.
+It is then truncated to fit in the result type's size.
+For example, if <code>v := uint16(0x10F0)</code>, then <code>uint32(int8(v)) == 0xFFFFFFF0</code>.
+The conversion always yields a valid value; there is no indication of overflow.
+</li>
+<li>
+When converting a floating-point number to an integer, the fraction is discarded
+(truncation towards zero).
+</li>
+<li>
+When converting an integer or floating-point number to a floating-point type,
+or a complex number to another complex type, the result value is rounded
+to the precision specified by the destination type.
+For instance, the value of a variable <code>x</code> of type <code>float32</code>
+may be stored using additional precision beyond that of an IEEE-754 32-bit number,
+but float32(x) represents the result of rounding <code>x</code>'s value to
+32-bit precision. Similarly, <code>x + 0.1</code> may use more than 32 bits
+of precision, but <code>float32(x + 0.1)</code> does not.
+</li>
+</ol>
+
+<p>
+In all non-constant conversions involving floating-point or complex values,
+if the result type cannot represent the value the conversion
+succeeds but the result value is implementation-dependent.
+</p>
+
+<h4 id="Conversions_to_and_from_a_string_type">Conversions to and from a string type</h4>
+
+<ol>
+<li>
+Converting a signed or unsigned integer value to a string type yields a
+string containing the UTF-8 representation of the integer. Values outside
+the range of valid Unicode code points are converted to <code>"\uFFFD"</code>.
+
+<pre>
+string('a') // "a"
+string(-1) // "\ufffd" == "\xef\xbf\xbd"
+string(0xf8) // "\u00f8" == "ø" == "\xc3\xb8"
+type MyString string
+MyString(0x65e5) // "\u65e5" == "日" == "\xe6\x97\xa5"
+</pre>
+</li>
+
+<li>
+Converting a slice of bytes to a string type yields
+a string whose successive bytes are the elements of the slice.
+
+<pre>
+string([]byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'}) // "hellø"
+string([]byte{}) // ""
+string([]byte(nil)) // ""
+
+type MyBytes []byte
+string(MyBytes{'h', 'e', 'l', 'l', '\xc3', '\xb8'}) // "hellø"
+</pre>
+</li>
+
+<li>
+Converting a slice of runes to a string type yields
+a string that is the concatenation of the individual rune values
+converted to strings.
+
+<pre>
+string([]rune{0x767d, 0x9d6c, 0x7fd4}) // "\u767d\u9d6c\u7fd4" == "白鵬翔"
+string([]rune{}) // ""
+string([]rune(nil)) // ""
+
+type MyRunes []rune
+string(MyRunes{0x767d, 0x9d6c, 0x7fd4}) // "\u767d\u9d6c\u7fd4" == "白鵬翔"
+</pre>
+</li>
+
+<li>
+Converting a value of a string type to a slice of bytes type
+yields a slice whose successive elements are the bytes of the string.
+
+<pre>
+[]byte("hellø") // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'}
+[]byte("") // []byte{}
+
+MyBytes("hellø") // []byte{'h', 'e', 'l', 'l', '\xc3', '\xb8'}
+</pre>
+</li>
+
+<li>
+Converting a value of a string type to a slice of runes type
+yields a slice containing the individual Unicode code points of the string.
+
+<pre>
+[]rune(MyString("白鵬翔")) // []rune{0x767d, 0x9d6c, 0x7fd4}
+[]rune("") // []rune{}
+
+MyRunes("白鵬翔") // []rune{0x767d, 0x9d6c, 0x7fd4}
+</pre>
+</li>
+</ol>
+
+
+<h3 id="Constant_expressions">Constant expressions</h3>
+
+<p>
+Constant expressions may contain only <a href="#Constants">constant</a>
+operands and are evaluated at compile time.
+</p>
+
+<p>
+Untyped boolean, numeric, and string constants may be used as operands
+wherever it is legal to use an operand of boolean, numeric, or string type,
+respectively.
+Except for shift operations, if the operands of a binary operation are
+different kinds of untyped constants, the operation and, for non-boolean operations, the result use
+the kind that appears later in this list: integer, rune, floating-point, complex.
+For example, an untyped integer constant divided by an
+untyped complex constant yields an untyped complex constant.
+</p>
+
+<p>
+A constant <a href="#Comparison_operators">comparison</a> always yields
+an untyped boolean constant. If the left operand of a constant
+<a href="#Operators">shift expression</a> is an untyped constant, the
+result is an integer constant; otherwise it is a constant of the same
+type as the left operand, which must be of
+<a href="#Numeric_types">integer type</a>.
+Applying all other operators to untyped constants results in an untyped
+constant of the same kind (that is, a boolean, integer, floating-point,
+complex, or string constant).
+</p>
+
+<pre>
+const a = 2 + 3.0 // a == 5.0 (untyped floating-point constant)
+const b = 15 / 4 // b == 3 (untyped integer constant)
+const c = 15 / 4.0 // c == 3.75 (untyped floating-point constant)
+const Θ float64 = 3/2 // Θ == 1.0 (type float64, 3/2 is integer division)
+const Π float64 = 3/2. // Π == 1.5 (type float64, 3/2. is float division)
+const d = 1 << 3.0 // d == 8 (untyped integer constant)
+const e = 1.0 << 3 // e == 8 (untyped integer constant)
+const f = int32(1) << 33 // illegal (constant 8589934592 overflows int32)
+const g = float64(2) >> 1 // illegal (float64(2) is a typed floating-point constant)
+const h = "foo" > "bar" // h == true (untyped boolean constant)
+const j = true // j == true (untyped boolean constant)
+const k = 'w' + 1 // k == 'x' (untyped rune constant)
+const l = "hi" // l == "hi" (untyped string constant)
+const m = string(k) // m == "x" (type string)
+const Σ = 1 - 0.707i // (untyped complex constant)
+const Δ = Σ + 2.0e-4 // (untyped complex constant)
+const Φ = iota*1i - 1/1i // (untyped complex constant)
+</pre>
+
+<p>
+Applying the built-in function <code>complex</code> to untyped
+integer, rune, or floating-point constants yields
+an untyped complex constant.
+</p>
+
+<pre>
+const ic = complex(0, c) // ic == 3.75i (untyped complex constant)
+const iΘ = complex(0, Θ) // iΘ == 1i (type complex128)
+</pre>
+
+<p>
+Constant expressions are always evaluated exactly; intermediate values and the
+constants themselves may require precision significantly larger than supported
+by any predeclared type in the language. The following are legal declarations:
+</p>
+
+<pre>
+const Huge = 1 << 100 // Huge == 1267650600228229401496703205376 (untyped integer constant)
+const Four int8 = Huge >> 98 // Four == 4 (type int8)
+</pre>
+
+<p>
+The divisor of a constant division or remainder operation must not be zero:
+</p>
+
+<pre>
+3.14 / 0.0 // illegal: division by zero
+</pre>
+
+<p>
+The values of <i>typed</i> constants must always be accurately representable as values
+of the constant type. The following constant expressions are illegal:
+</p>
+
+<pre>
+uint(-1) // -1 cannot be represented as a uint
+int(3.14) // 3.14 cannot be represented as an int
+int64(Huge) // 1267650600228229401496703205376 cannot be represented as an int64
+Four * 300 // operand 300 cannot be represented as an int8 (type of Four)
+Four * 100 // product 400 cannot be represented as an int8 (type of Four)
+</pre>
+
+<p>
+The mask used by the unary bitwise complement operator <code>^</code> matches
+the rule for non-constants: the mask is all 1s for unsigned constants
+and -1 for signed and untyped constants.
+</p>
+
+<pre>
+^1 // untyped integer constant, equal to -2
+uint8(^1) // illegal: same as uint8(-2), -2 cannot be represented as a uint8
+^uint8(1) // typed uint8 constant, same as 0xFF ^ uint8(1) = uint8(0xFE)
+int8(^1) // same as int8(-2)
+^int8(1) // same as -1 ^ int8(1) = -2
+</pre>
+
+<p>
+Implementation restriction: A compiler may use rounding while
+computing untyped floating-point or complex constant expressions; see
+the implementation restriction in the section
+on <a href="#Constants">constants</a>. This rounding may cause a
+floating-point constant expression to be invalid in an integer
+context, even if it would be integral when calculated using infinite
+precision.
+</p>
+
+
+<h3 id="Order_of_evaluation">Order of evaluation</h3>
+
+<p>
+At package level, <a href="#Package_initialization">initialization dependencies</a>
+determine the evaluation order of individual initialization expressions in
+<a href="#Variable_declarations">variable declarations</a>.
+Otherwise, when evaluating the <a href="#Operands">operands</a> of an
+expression, assignment, or
+<a href="#Return_statements">return statement</a>,
+all function calls, method calls, and
+communication operations are evaluated in lexical left-to-right
+order.
+</p>
+
+<p>
+For example, in the (function-local) assignment
+</p>
+<pre>
+y[f()], ok = g(h(), i()+x[j()], <-c), k()
+</pre>
+<p>
+the function calls and communication happen in the order
+<code>f()</code>, <code>h()</code>, <code>i()</code>, <code>j()</code>,
+<code><-c</code>, <code>g()</code>, and <code>k()</code>.
+However, the order of those events compared to the evaluation
+and indexing of <code>x</code> and the evaluation
+of <code>y</code> is not specified.
+</p>
+
+<pre>
+a := 1
+f := func() int { a++; return a }
+x := []int{a, f()} // x may be [1, 2] or [2, 2]: evaluation order between a and f() is not specified
+m := map[int]int{a: 1, a: 2} // m may be {2: 1} or {2: 2}: evaluation order between the two map assignments is not specified
+n := map[int]int{a: f()} // n may be {2: 3} or {3: 3}: evaluation order between the key and the value is not specified
+</pre>
+
+<p>
+At package level, initialization dependencies override the left-to-right rule
+for individual initialization expressions, but not for operands within each
+expression:
+</p>
+
+<pre>
+var a, b, c = f() + v(), g(), sqr(u()) + v()
+
+func f() int { return c }
+func g() int { return a }
+func sqr(x int) int { return x*x }
+
+// functions u and v are independent of all other variables and functions
+</pre>
+
+<p>
+The function calls happen in the order
+<code>u()</code>, <code>sqr()</code>, <code>v()</code>,
+<code>f()</code>, <code>v()</code>, and <code>g()</code>.
+</p>
+
+<p>
+Floating-point operations within a single expression are evaluated according to
+the associativity of the operators. Explicit parentheses affect the evaluation
+by overriding the default associativity.
+In the expression <code>x + (y + z)</code> the addition <code>y + z</code>
+is performed before adding <code>x</code>.
+</p>
+
+<h2 id="Statements">Statements</h2>
+
+<p>
+Statements control execution.
+</p>
+
+<pre class="ebnf">
+Statement =
+ Declaration | LabeledStmt | SimpleStmt |
+ GoStmt | ReturnStmt | BreakStmt | ContinueStmt | GotoStmt |
+ FallthroughStmt | Block | IfStmt | SwitchStmt | SelectStmt | ForStmt |
+ DeferStmt .
+
+SimpleStmt = EmptyStmt | ExpressionStmt | SendStmt | IncDecStmt | Assignment | ShortVarDecl .
+</pre>
+
+<h3 id="Terminating_statements">Terminating statements</h3>
+
+<p>
+A terminating statement is one of the following:
+</p>
+
+<ol>
+<li>
+ A <a href="#Return_statements">"return"</a> or
+ <a href="#Goto_statements">"goto"</a> statement.
+ <!-- ul below only for regular layout -->
+ <ul> </ul>
+</li>
+
+<li>
+ A call to the built-in function
+ <a href="#Handling_panics"><code>panic</code></a>.
+ <!-- ul below only for regular layout -->
+ <ul> </ul>
+</li>
+
+<li>
+ A <a href="#Blocks">block</a> in which the statement list ends in a terminating statement.
+ <!-- ul below only for regular layout -->
+ <ul> </ul>
+</li>
+
+<li>
+ An <a href="#If_statements">"if" statement</a> in which:
+ <ul>
+ <li>the "else" branch is present, and</li>
+ <li>both branches are terminating statements.</li>
+ </ul>
+</li>
+
+<li>
+ A <a href="#For_statements">"for" statement</a> in which:
+ <ul>
+ <li>there are no "break" statements referring to the "for" statement, and</li>
+ <li>the loop condition is absent.</li>
+ </ul>
+</li>
+
+<li>
+ A <a href="#Switch_statements">"switch" statement</a> in which:
+ <ul>
+ <li>there are no "break" statements referring to the "switch" statement,</li>
+ <li>there is a default case, and</li>
+ <li>the statement lists in each case, including the default, end in a terminating
+ statement, or a possibly labeled <a href="#Fallthrough_statements">"fallthrough"
+ statement</a>.</li>
+ </ul>
+</li>
+
+<li>
+ A <a href="#Select_statements">"select" statement</a> in which:
+ <ul>
+ <li>there are no "break" statements referring to the "select" statement, and</li>
+ <li>the statement lists in each case, including the default if present,
+ end in a terminating statement.</li>
+ </ul>
+</li>
+
+<li>
+ A <a href="#Labeled_statements">labeled statement</a> labeling
+ a terminating statement.
+</li>
+</ol>
+
+<p>
+All other statements are not terminating.
+</p>
+
+<p>
+A <a href="#Blocks">statement list</a> ends in a terminating statement if the list
+is not empty and its final statement is terminating.
+</p>
+
+
+<h3 id="Empty_statements">Empty statements</h3>
+
+<p>
+The empty statement does nothing.
+</p>
+
+<pre class="ebnf">
+EmptyStmt = .
+</pre>
+
+
+<h3 id="Labeled_statements">Labeled statements</h3>
+
+<p>
+A labeled statement may be the target of a <code>goto</code>,
+<code>break</code> or <code>continue</code> statement.
+</p>
+
+<pre class="ebnf">
+LabeledStmt = Label ":" Statement .
+Label = identifier .
+</pre>
+
+<pre>
+Error: log.Panic("error encountered")
+</pre>
+
+
+<h3 id="Expression_statements">Expression statements</h3>
+
+<p>
+With the exception of specific built-in functions,
+function and method <a href="#Calls">calls</a> and
+<a href="#Receive_operator">receive operations</a>
+can appear in statement context. Such statements may be parenthesized.
+</p>
+
+<pre class="ebnf">
+ExpressionStmt = Expression .
+</pre>
+
+<p>
+The following built-in functions are not permitted in statement context:
+</p>
+
+<pre>
+append cap complex imag len make new real
+unsafe.Alignof unsafe.Offsetof unsafe.Sizeof
+</pre>
+
+<pre>
+h(x+y)
+f.Close()
+<-ch
+(<-ch)
+len("foo") // illegal if len is the built-in function
+</pre>
+
+
+<h3 id="Send_statements">Send statements</h3>
+
+<p>
+A send statement sends a value on a channel.
+The channel expression must be of <a href="#Channel_types">channel type</a>,
+the channel direction must permit send operations,
+and the type of the value to be sent must be <a href="#Assignability">assignable</a>
+to the channel's element type.
+</p>
+
+<pre class="ebnf">
+SendStmt = Channel "<-" Expression .
+Channel = Expression .
+</pre>
+
+<p>
+Both the channel and the value expression are evaluated before communication
+begins. Communication blocks until the send can proceed.
+A send on an unbuffered channel can proceed if a receiver is ready.
+A send on a buffered channel can proceed if there is room in the buffer.
+A send on a closed channel proceeds by causing a <a href="#Run_time_panics">run-time panic</a>.
+A send on a <code>nil</code> channel blocks forever.
+</p>
+
+<pre>
+ch <- 3 // send value 3 to channel ch
+</pre>
+
+
+<h3 id="IncDec_statements">IncDec statements</h3>
+
+<p>
+The "++" and "--" statements increment or decrement their operands
+by the untyped <a href="#Constants">constant</a> <code>1</code>.
+As with an assignment, the operand must be <a href="#Address_operators">addressable</a>
+or a map index expression.
+</p>
+
+<pre class="ebnf">
+IncDecStmt = Expression ( "++" | "--" ) .
+</pre>
+
+<p>
+The following <a href="#Assignments">assignment statements</a> are semantically
+equivalent:
+</p>
+
+<pre class="grammar">
+IncDec statement Assignment
+x++ x += 1
+x-- x -= 1
+</pre>
+
+
+<h3 id="Assignments">Assignments</h3>
+
+<pre class="ebnf">
+Assignment = ExpressionList assign_op ExpressionList .
+
+assign_op = [ add_op | mul_op ] "=" .
+</pre>
+
+<p>
+Each left-hand side operand must be <a href="#Address_operators">addressable</a>,
+a map index expression, or (for <code>=</code> assignments only) the
+<a href="#Blank_identifier">blank identifier</a>.
+Operands may be parenthesized.
+</p>
+
+<pre>
+x = 1
+*p = f()
+a[i] = 23
+(k) = <-ch // same as: k = <-ch
+</pre>
+
+<p>
+An <i>assignment operation</i> <code>x</code> <i>op</i><code>=</code>
+<code>y</code> where <i>op</i> is a binary arithmetic operation is equivalent
+to <code>x</code> <code>=</code> <code>x</code> <i>op</i>
+<code>y</code> but evaluates <code>x</code>
+only once. The <i>op</i><code>=</code> construct is a single token.
+In assignment operations, both the left- and right-hand expression lists
+must contain exactly one single-valued expression, and the left-hand
+expression must not be the blank identifier.
+</p>
+
+<pre>
+a[i] <<= 2
+i &^= 1<<n
+</pre>
+
+<p>
+A tuple assignment assigns the individual elements of a multi-valued
+operation to a list of variables. There are two forms. In the
+first, the right hand operand is a single multi-valued expression
+such as a function call, a <a href="#Channel_types">channel</a> or
+<a href="#Map_types">map</a> operation, or a <a href="#Type_assertions">type assertion</a>.
+The number of operands on the left
+hand side must match the number of values. For instance, if
+<code>f</code> is a function returning two values,
+</p>
+
+<pre>
+x, y = f()
+</pre>
+
+<p>
+assigns the first value to <code>x</code> and the second to <code>y</code>.
+In the second form, the number of operands on the left must equal the number
+of expressions on the right, each of which must be single-valued, and the
+<i>n</i>th expression on the right is assigned to the <i>n</i>th
+operand on the left:
+</p>
+
+<pre>
+one, two, three = '一', '二', '三'
+</pre>
+
+<p>
+The <a href="#Blank_identifier">blank identifier</a> provides a way to
+ignore right-hand side values in an assignment:
+</p>
+
+<pre>
+_ = x // evaluate x but ignore it
+x, _ = f() // evaluate f() but ignore second result value
+</pre>
+
+<p>
+The assignment proceeds in two phases.
+First, the operands of <a href="#Index_expressions">index expressions</a>
+and <a href="#Address_operators">pointer indirections</a>
+(including implicit pointer indirections in <a href="#Selectors">selectors</a>)
+on the left and the expressions on the right are all
+<a href="#Order_of_evaluation">evaluated in the usual order</a>.
+Second, the assignments are carried out in left-to-right order.
+</p>
+
+<pre>
+a, b = b, a // exchange a and b
+
+x := []int{1, 2, 3}
+i := 0
+i, x[i] = 1, 2 // set i = 1, x[0] = 2
+
+i = 0
+x[i], i = 2, 1 // set x[0] = 2, i = 1
+
+x[0], x[0] = 1, 2 // set x[0] = 1, then x[0] = 2 (so x[0] == 2 at end)
+
+x[1], x[3] = 4, 5 // set x[1] = 4, then panic setting x[3] = 5.
+
+type Point struct { x, y int }
+var p *Point
+x[2], p.x = 6, 7 // set x[2] = 6, then panic setting p.x = 7
+
+i = 2
+x = []int{3, 5, 7}
+for i, x[i] = range x { // set i, x[2] = 0, x[0]
+ break
+}
+// after this loop, i == 0 and x == []int{3, 5, 3}
+</pre>
+
+<p>
+In assignments, each value must be <a href="#Assignability">assignable</a>
+to the type of the operand to which it is assigned, with the following special cases:
+</p>
+
+<ol>
+<li>
+ Any typed value may be assigned to the blank identifier.
+</li>
+
+<li>
+ If an untyped constant
+ is assigned to a variable of interface type or the blank identifier,
+ the constant is first <a href="#Conversions">converted</a> to its
+ <a href="#Constants">default type</a>.
+</li>
+
+<li>
+ If an untyped boolean value is assigned to a variable of interface type or
+ the blank identifier, it is first converted to type <code>bool</code>.
+</li>
+</ol>
+
+<h3 id="If_statements">If statements</h3>
+
+<p>
+"If" statements specify the conditional execution of two branches
+according to the value of a boolean expression. If the expression
+evaluates to true, the "if" branch is executed, otherwise, if
+present, the "else" branch is executed.
+</p>
+
+<pre class="ebnf">
+IfStmt = "if" [ SimpleStmt ";" ] Expression Block [ "else" ( IfStmt | Block ) ] .
+</pre>
+
+<pre>
+if x > max {
+ x = max
+}
+</pre>
+
+<p>
+The expression may be preceded by a simple statement, which
+executes before the expression is evaluated.
+</p>
+
+<pre>
+if x := f(); x < y {
+ return x
+} else if x > z {
+ return z
+} else {
+ return y
+}
+</pre>
+
+
+<h3 id="Switch_statements">Switch statements</h3>
+
+<p>
+"Switch" statements provide multi-way execution.
+An expression or type specifier is compared to the "cases"
+inside the "switch" to determine which branch
+to execute.
+</p>
+
+<pre class="ebnf">
+SwitchStmt = ExprSwitchStmt | TypeSwitchStmt .
+</pre>
+
+<p>
+There are two forms: expression switches and type switches.
+In an expression switch, the cases contain expressions that are compared
+against the value of the switch expression.
+In a type switch, the cases contain types that are compared against the
+type of a specially annotated switch expression.
+</p>
+
+<h4 id="Expression_switches">Expression switches</h4>
+
+<p>
+In an expression switch,
+the switch expression is evaluated and
+the case expressions, which need not be constants,
+are evaluated left-to-right and top-to-bottom; the first one that equals the
+switch expression
+triggers execution of the statements of the associated case;
+the other cases are skipped.
+If no case matches and there is a "default" case,
+its statements are executed.
+There can be at most one default case and it may appear anywhere in the
+"switch" statement.
+A missing switch expression is equivalent to the boolean value
+<code>true</code>.
+</p>
+
+<pre class="ebnf">
+ExprSwitchStmt = "switch" [ SimpleStmt ";" ] [ Expression ] "{" { ExprCaseClause } "}" .
+ExprCaseClause = ExprSwitchCase ":" StatementList .
+ExprSwitchCase = "case" ExpressionList | "default" .
+</pre>
+
+<p>
+In a case or default clause, the last non-empty statement
+may be a (possibly <a href="#Labeled_statements">labeled</a>)
+<a href="#Fallthrough_statements">"fallthrough" statement</a> to
+indicate that control should flow from the end of this clause to
+the first statement of the next clause.
+Otherwise control flows to the end of the "switch" statement.
+A "fallthrough" statement may appear as the last statement of all
+but the last clause of an expression switch.
+</p>
+
+<p>
+The expression may be preceded by a simple statement, which
+executes before the expression is evaluated.
+</p>
+
+<pre>
+switch tag {
+default: s3()
+case 0, 1, 2, 3: s1()
+case 4, 5, 6, 7: s2()
+}
+
+switch x := f(); { // missing switch expression means "true"
+case x < 0: return -x
+default: return x
+}
+
+switch {
+case x < y: f1()
+case x < z: f2()
+case x == 4: f3()
+}
+</pre>
+
+<h4 id="Type_switches">Type switches</h4>
+
+<p>
+A type switch compares types rather than values. It is otherwise similar
+to an expression switch. It is marked by a special switch expression that
+has the form of a <a href="#Type_assertions">type assertion</a>
+using the reserved word <code>type</code> rather than an actual type:
+</p>
+
+<pre>
+switch x.(type) {
+// cases
+}
+</pre>
+
+<p>
+Cases then match actual types <code>T</code> against the dynamic type of the
+expression <code>x</code>. As with type assertions, <code>x</code> must be of
+<a href="#Interface_types">interface type</a>, and each non-interface type
+<code>T</code> listed in a case must implement the type of <code>x</code>.
+</p>
+
+<pre class="ebnf">
+TypeSwitchStmt = "switch" [ SimpleStmt ";" ] TypeSwitchGuard "{" { TypeCaseClause } "}" .
+TypeSwitchGuard = [ identifier ":=" ] PrimaryExpr "." "(" "type" ")" .
+TypeCaseClause = TypeSwitchCase ":" StatementList .
+TypeSwitchCase = "case" TypeList | "default" .
+TypeList = Type { "," Type } .
+</pre>
+
+<p>
+The TypeSwitchGuard may include a
+<a href="#Short_variable_declarations">short variable declaration</a>.
+When that form is used, the variable is declared at the beginning of
+the <a href="#Blocks">implicit block</a> in each clause.
+In clauses with a case listing exactly one type, the variable
+has that type; otherwise, the variable has the type of the expression
+in the TypeSwitchGuard.
+</p>
+
+<p>
+The type in a case may be <a href="#Predeclared_identifiers"><code>nil</code></a>;
+that case is used when the expression in the TypeSwitchGuard
+is a <code>nil</code> interface value.
+</p>
+
+<p>
+Given an expression <code>x</code> of type <code>interface{}</code>,
+the following type switch:
+</p>
+
+<pre>
+switch i := x.(type) {
+case nil:
+ printString("x is nil") // type of i is type of x (interface{})
+case int:
+ printInt(i) // type of i is int
+case float64:
+ printFloat64(i) // type of i is float64
+case func(int) float64:
+ printFunction(i) // type of i is func(int) float64
+case bool, string:
+ printString("type is bool or string") // type of i is type of x (interface{})
+default:
+ printString("don't know the type") // type of i is type of x (interface{})
+}
+</pre>
+
+<p>
+could be rewritten:
+</p>
+
+<pre>
+v := x // x is evaluated exactly once
+if v == nil {
+ i := v // type of i is type of x (interface{})
+ printString("x is nil")
+} else if i, isInt := v.(int); isInt {
+ printInt(i) // type of i is int
+} else if i, isFloat64 := v.(float64); isFloat64 {
+ printFloat64(i) // type of i is float64
+} else if i, isFunc := v.(func(int) float64); isFunc {
+ printFunction(i) // type of i is func(int) float64
+} else {
+ _, isBool := v.(bool)
+ _, isString := v.(string)
+ if isBool || isString {
+ i := v // type of i is type of x (interface{})
+ printString("type is bool or string")
+ } else {
+ i := v // type of i is type of x (interface{})
+ printString("don't know the type")
+ }
+}
+</pre>
+
+<p>
+The type switch guard may be preceded by a simple statement, which
+executes before the guard is evaluated.
+</p>
+
+<p>
+The "fallthrough" statement is not permitted in a type switch.
+</p>
+
+<h3 id="For_statements">For statements</h3>
+
+<p>
+A "for" statement specifies repeated execution of a block. The iteration is
+controlled by a condition, a "for" clause, or a "range" clause.
+</p>
+
+<pre class="ebnf">
+ForStmt = "for" [ Condition | ForClause | RangeClause ] Block .
+Condition = Expression .
+</pre>
+
+<p>
+In its simplest form, a "for" statement specifies the repeated execution of
+a block as long as a boolean condition evaluates to true.
+The condition is evaluated before each iteration.
+If the condition is absent, it is equivalent to the boolean value
+<code>true</code>.
+</p>
+
+<pre>
+for a < b {
+ a *= 2
+}
+</pre>
+
+<p>
+A "for" statement with a ForClause is also controlled by its condition, but
+additionally it may specify an <i>init</i>
+and a <i>post</i> statement, such as an assignment,
+an increment or decrement statement. The init statement may be a
+<a href="#Short_variable_declarations">short variable declaration</a>, but the post statement must not.
+Variables declared by the init statement are re-used in each iteration.
+</p>
+
+<pre class="ebnf">
+ForClause = [ InitStmt ] ";" [ Condition ] ";" [ PostStmt ] .
+InitStmt = SimpleStmt .
+PostStmt = SimpleStmt .
+</pre>
+
+<pre>
+for i := 0; i < 10; i++ {
+ f(i)
+}
+</pre>
+
+<p>
+If non-empty, the init statement is executed once before evaluating the
+condition for the first iteration;
+the post statement is executed after each execution of the block (and
+only if the block was executed).
+Any element of the ForClause may be empty but the
+<a href="#Semicolons">semicolons</a> are
+required unless there is only a condition.
+If the condition is absent, it is equivalent to the boolean value
+<code>true</code>.
+</p>
+
+<pre>
+for cond { S() } is the same as for ; cond ; { S() }
+for { S() } is the same as for true { S() }
+</pre>
+
+<p>
+A "for" statement with a "range" clause
+iterates through all entries of an array, slice, string or map,
+or values received on a channel. For each entry it assigns <i>iteration values</i>
+to corresponding <i>iteration variables</i> if present and then executes the block.
+</p>
+
+<pre class="ebnf">
+RangeClause = [ ExpressionList "=" | IdentifierList ":=" ] "range" Expression .
+</pre>
+
+<p>
+The expression on the right in the "range" clause is called the <i>range expression</i>,
+which may be an array, pointer to an array, slice, string, map, or channel permitting
+<a href="#Receive_operator">receive operations</a>.
+As with an assignment, if present the operands on the left must be
+<a href="#Address_operators">addressable</a> or map index expressions; they
+denote the iteration variables. If the range expression is a channel, at most
+one iteration variable is permitted, otherwise there may be up to two.
+If the last iteration variable is the <a href="#Blank_identifier">blank identifier</a>,
+the range clause is equivalent to the same clause without that identifier.
+</p>
+
+<p>
+The range expression is evaluated once before beginning the loop,
+with one exception: if the range expression is an array or a pointer to an array
+and at most one iteration variable is present, only the range expression's
+length is evaluated; if that length is constant,
+<a href="#Length_and_capacity">by definition</a>
+the range expression itself will not be evaluated.
+</p>
+
+<p>
+Function calls on the left are evaluated once per iteration.
+For each iteration, iteration values are produced as follows
+if the respective iteration variables are present:
+</p>
+
+<pre class="grammar">
+Range expression 1st value 2nd value
+
+array or slice a [n]E, *[n]E, or []E index i int a[i] E
+string s string type index i int see below rune
+map m map[K]V key k K m[k] V
+channel c chan E, <-chan E element e E
+</pre>
+
+<ol>
+<li>
+For an array, pointer to array, or slice value <code>a</code>, the index iteration
+values are produced in increasing order, starting at element index 0.
+If at most one iteration variable is present, the range loop produces
+iteration values from 0 up to <code>len(a)-1</code> and does not index into the array
+or slice itself. For a <code>nil</code> slice, the number of iterations is 0.
+</li>
+
+<li>
+For a string value, the "range" clause iterates over the Unicode code points
+in the string starting at byte index 0. On successive iterations, the index value will be the
+index of the first byte of successive UTF-8-encoded code points in the string,
+and the second value, of type <code>rune</code>, will be the value of
+the corresponding code point. If the iteration encounters an invalid
+UTF-8 sequence, the second value will be <code>0xFFFD</code>,
+the Unicode replacement character, and the next iteration will advance
+a single byte in the string.
+</li>
+
+<li>
+The iteration order over maps is not specified
+and is not guaranteed to be the same from one iteration to the next.
+If map entries that have not yet been reached are removed during iteration,
+the corresponding iteration values will not be produced. If map entries are
+created during iteration, that entry may be produced during the iteration or
+may be skipped. The choice may vary for each entry created and from one
+iteration to the next.
+If the map is <code>nil</code>, the number of iterations is 0.
+</li>
+
+<li>
+For channels, the iteration values produced are the successive values sent on
+the channel until the channel is <a href="#Close">closed</a>. If the channel
+is <code>nil</code>, the range expression blocks forever.
+</li>
+</ol>
+
+<p>
+The iteration values are assigned to the respective
+iteration variables as in an <a href="#Assignments">assignment statement</a>.
+</p>
+
+<p>
+The iteration variables may be declared by the "range" clause using a form of
+<a href="#Short_variable_declarations">short variable declaration</a>
+(<code>:=</code>).
+In this case their types are set to the types of the respective iteration values
+and their <a href="#Declarations_and_scope">scope</a> is the block of the "for"
+statement; they are re-used in each iteration.
+If the iteration variables are declared outside the "for" statement,
+after execution their values will be those of the last iteration.
+</p>
+
+<pre>
+var testdata *struct {
+ a *[7]int
+}
+for i, _ := range testdata.a {
+ // testdata.a is never evaluated; len(testdata.a) is constant
+ // i ranges from 0 to 6
+ f(i)
+}
+
+var a [10]string
+for i, s := range a {
+ // type of i is int
+ // type of s is string
+ // s == a[i]
+ g(i, s)
+}
+
+var key string
+var val interface {} // value type of m is assignable to val
+m := map[string]int{"mon":0, "tue":1, "wed":2, "thu":3, "fri":4, "sat":5, "sun":6}
+for key, val = range m {
+ h(key, val)
+}
+// key == last map key encountered in iteration
+// val == map[key]
+
+var ch chan Work = producer()
+for w := range ch {
+ doWork(w)
+}
+
+// empty a channel
+for range ch {}
+</pre>
+
+
+<h3 id="Go_statements">Go statements</h3>
+
+<p>
+A "go" statement starts the execution of a function call
+as an independent concurrent thread of control, or <i>goroutine</i>,
+within the same address space.
+</p>
+
+<pre class="ebnf">
+GoStmt = "go" Expression .
+</pre>
+
+<p>
+The expression must be a function or method call; it cannot be parenthesized.
+Calls of built-in functions are restricted as for
+<a href="#Expression_statements">expression statements</a>.
+</p>
+
+<p>
+The function value and parameters are
+<a href="#Calls">evaluated as usual</a>
+in the calling goroutine, but
+unlike with a regular call, program execution does not wait
+for the invoked function to complete.
+Instead, the function begins executing independently
+in a new goroutine.
+When the function terminates, its goroutine also terminates.
+If the function has any return values, they are discarded when the
+function completes.
+</p>
+
+<pre>
+go Server()
+go func(ch chan<- bool) { for { sleep(10); ch <- true; }} (c)
+</pre>
+
+
+<h3 id="Select_statements">Select statements</h3>
+
+<p>
+A "select" statement chooses which of a set of possible
+<a href="#Send_statements">send</a> or
+<a href="#Receive_operator">receive</a>
+operations will proceed.
+It looks similar to a
+<a href="#Switch_statements">"switch"</a> statement but with the
+cases all referring to communication operations.
+</p>
+
+<pre class="ebnf">
+SelectStmt = "select" "{" { CommClause } "}" .
+CommClause = CommCase ":" StatementList .
+CommCase = "case" ( SendStmt | RecvStmt ) | "default" .
+RecvStmt = [ ExpressionList "=" | IdentifierList ":=" ] RecvExpr .
+RecvExpr = Expression .
+</pre>
+
+<p>
+A case with a RecvStmt may assign the result of a RecvExpr to one or
+two variables, which may be declared using a
+<a href="#Short_variable_declarations">short variable declaration</a>.
+The RecvExpr must be a (possibly parenthesized) receive operation.
+There can be at most one default case and it may appear anywhere
+in the list of cases.
+</p>
+
+<p>
+Execution of a "select" statement proceeds in several steps:
+</p>
+
+<ol>
+<li>
+For all the cases in the statement, the channel operands of receive operations
+and the channel and right-hand-side expressions of send statements are
+evaluated exactly once, in source order, upon entering the "select" statement.
+The result is a set of channels to receive from or send to,
+and the corresponding values to send.
+Any side effects in that evaluation will occur irrespective of which (if any)
+communication operation is selected to proceed.
+Expressions on the left-hand side of a RecvStmt with a short variable declaration
+or assignment are not yet evaluated.
+</li>
+
+<li>
+If one or more of the communications can proceed,
+a single one that can proceed is chosen via a uniform pseudo-random selection.
+Otherwise, if there is a default case, that case is chosen.
+If there is no default case, the "select" statement blocks until
+at least one of the communications can proceed.
+</li>
+
+<li>
+Unless the selected case is the default case, the respective communication
+operation is executed.
+</li>
+
+<li>
+If the selected case is a RecvStmt with a short variable declaration or
+an assignment, the left-hand side expressions are evaluated and the
+received value (or values) are assigned.
+</li>
+
+<li>
+The statement list of the selected case is executed.
+</li>
+</ol>
+
+<p>
+Since communication on <code>nil</code> channels can never proceed,
+a select with only <code>nil</code> channels and no default case blocks forever.
+</p>
+
+<pre>
+var a []int
+var c, c1, c2, c3, c4 chan int
+var i1, i2 int
+select {
+case i1 = <-c1:
+ print("received ", i1, " from c1\n")
+case c2 <- i2:
+ print("sent ", i2, " to c2\n")
+case i3, ok := (<-c3): // same as: i3, ok := <-c3
+ if ok {
+ print("received ", i3, " from c3\n")
+ } else {
+ print("c3 is closed\n")
+ }
+case a[f()] = <-c4:
+ // same as:
+ // case t := <-c4
+ // a[f()] = t
+default:
+ print("no communication\n")
+}
+
+for { // send random sequence of bits to c
+ select {
+ case c <- 0: // note: no statement, no fallthrough, no folding of cases
+ case c <- 1:
+ }
+}
+
+select {} // block forever
+</pre>
+
+
+<h3 id="Return_statements">Return statements</h3>
+
+<p>
+A "return" statement in a function <code>F</code> terminates the execution
+of <code>F</code>, and optionally provides one or more result values.
+Any functions <a href="#Defer_statements">deferred</a> by <code>F</code>
+are executed before <code>F</code> returns to its caller.
+</p>
+
+<pre class="ebnf">
+ReturnStmt = "return" [ ExpressionList ] .
+</pre>
+
+<p>
+In a function without a result type, a "return" statement must not
+specify any result values.
+</p>
+<pre>
+func noResult() {
+ return
+}
+</pre>
+
+<p>
+There are three ways to return values from a function with a result
+type:
+</p>
+
+<ol>
+ <li>The return value or values may be explicitly listed
+ in the "return" statement. Each expression must be single-valued
+ and <a href="#Assignability">assignable</a>
+ to the corresponding element of the function's result type.
+<pre>
+func simpleF() int {
+ return 2
+}
+
+func complexF1() (re float64, im float64) {
+ return -7.0, -4.0
+}
+</pre>
+ </li>
+ <li>The expression list in the "return" statement may be a single
+ call to a multi-valued function. The effect is as if each value
+ returned from that function were assigned to a temporary
+ variable with the type of the respective value, followed by a
+ "return" statement listing these variables, at which point the
+ rules of the previous case apply.
+<pre>
+func complexF2() (re float64, im float64) {
+ return complexF1()
+}
+</pre>
+ </li>
+ <li>The expression list may be empty if the function's result
+ type specifies names for its <a href="#Function_types">result parameters</a>.
+ The result parameters act as ordinary local variables
+ and the function may assign values to them as necessary.
+ The "return" statement returns the values of these variables.
+<pre>
+func complexF3() (re float64, im float64) {
+ re = 7.0
+ im = 4.0
+ return
+}
+
+func (devnull) Write(p []byte) (n int, _ error) {
+ n = len(p)
+ return
+}
+</pre>
+ </li>
+</ol>
+
+<p>
+Regardless of how they are declared, all the result values are initialized to
+the <a href="#The_zero_value">zero values</a> for their type upon entry to the
+function. A "return" statement that specifies results sets the result parameters before
+any deferred functions are executed.
+</p>
+
+<p>
+Implementation restriction: A compiler may disallow an empty expression list
+in a "return" statement if a different entity (constant, type, or variable)
+with the same name as a result parameter is in
+<a href="#Declarations_and_scope">scope</a> at the place of the return.
+</p>
+
+<pre>
+func f(n int) (res int, err error) {
+ if _, err := f(n-1); err != nil {
+ return // invalid return statement: err is shadowed
+ }
+ return
+}
+</pre>
+
+<h3 id="Break_statements">Break statements</h3>
+
+<p>
+A "break" statement terminates execution of the innermost
+<a href="#For_statements">"for"</a>,
+<a href="#Switch_statements">"switch"</a>, or
+<a href="#Select_statements">"select"</a> statement
+within the same function.
+</p>
+
+<pre class="ebnf">
+BreakStmt = "break" [ Label ] .
+</pre>
+
+<p>
+If there is a label, it must be that of an enclosing
+"for", "switch", or "select" statement,
+and that is the one whose execution terminates.
+</p>
+
+<pre>
+OuterLoop:
+ for i = 0; i < n; i++ {
+ for j = 0; j < m; j++ {
+ switch a[i][j] {
+ case nil:
+ state = Error
+ break OuterLoop
+ case item:
+ state = Found
+ break OuterLoop
+ }
+ }
+ }
+</pre>
+
+<h3 id="Continue_statements">Continue statements</h3>
+
+<p>
+A "continue" statement begins the next iteration of the
+innermost <a href="#For_statements">"for" loop</a> at its post statement.
+The "for" loop must be within the same function.
+</p>
+
+<pre class="ebnf">
+ContinueStmt = "continue" [ Label ] .
+</pre>
+
+<p>
+If there is a label, it must be that of an enclosing
+"for" statement, and that is the one whose execution
+advances.
+</p>
+
+<pre>
+RowLoop:
+ for y, row := range rows {
+ for x, data := range row {
+ if data == endOfRow {
+ continue RowLoop
+ }
+ row[x] = data + bias(x, y)
+ }
+ }
+</pre>
+
+<h3 id="Goto_statements">Goto statements</h3>
+
+<p>
+A "goto" statement transfers control to the statement with the corresponding label
+within the same function.
+</p>
+
+<pre class="ebnf">
+GotoStmt = "goto" Label .
+</pre>
+
+<pre>
+goto Error
+</pre>
+
+<p>
+Executing the "goto" statement must not cause any variables to come into
+<a href="#Declarations_and_scope">scope</a> that were not already in scope at the point of the goto.
+For instance, this example:
+</p>
+
+<pre>
+ goto L // BAD
+ v := 3
+L:
+</pre>
+
+<p>
+is erroneous because the jump to label <code>L</code> skips
+the creation of <code>v</code>.
+</p>
+
+<p>
+A "goto" statement outside a <a href="#Blocks">block</a> cannot jump to a label inside that block.
+For instance, this example:
+</p>
+
+<pre>
+if n%2 == 1 {
+ goto L1
+}
+for n > 0 {
+ f()
+ n--
+L1:
+ f()
+ n--
+}
+</pre>
+
+<p>
+is erroneous because the label <code>L1</code> is inside
+the "for" statement's block but the <code>goto</code> is not.
+</p>
+
+<h3 id="Fallthrough_statements">Fallthrough statements</h3>
+
+<p>
+A "fallthrough" statement transfers control to the first statement of the
+next case clause in a <a href="#Expression_switches">expression "switch" statement</a>.
+It may be used only as the final non-empty statement in such a clause.
+</p>
+
+<pre class="ebnf">
+FallthroughStmt = "fallthrough" .
+</pre>
+
+
+<h3 id="Defer_statements">Defer statements</h3>
+
+<p>
+A "defer" statement invokes a function whose execution is deferred
+to the moment the surrounding function returns, either because the
+surrounding function executed a <a href="#Return_statements">return statement</a>,
+reached the end of its <a href="#Function_declarations">function body</a>,
+or because the corresponding goroutine is <a href="#Handling_panics">panicking</a>.
+</p>
+
+<pre class="ebnf">
+DeferStmt = "defer" Expression .
+</pre>
+
+<p>
+The expression must be a function or method call; it cannot be parenthesized.
+Calls of built-in functions are restricted as for
+<a href="#Expression_statements">expression statements</a>.
+</p>
+
+<p>
+Each time a "defer" statement
+executes, the function value and parameters to the call are
+<a href="#Calls">evaluated as usual</a>
+and saved anew but the actual function is not invoked.
+Instead, deferred functions are invoked immediately before
+the surrounding function returns, in the reverse order
+they were deferred.
+If a deferred function value evaluates
+to <code>nil</code>, execution <a href="#Handling_panics">panics</a>
+when the function is invoked, not when the "defer" statement is executed.
+</p>
+
+<p>
+For instance, if the deferred function is
+a <a href="#Function_literals">function literal</a> and the surrounding
+function has <a href="#Function_types">named result parameters</a> that
+are in scope within the literal, the deferred function may access and modify
+the result parameters before they are returned.
+If the deferred function has any return values, they are discarded when
+the function completes.
+(See also the section on <a href="#Handling_panics">handling panics</a>.)
+</p>
+
+<pre>
+lock(l)
+defer unlock(l) // unlocking happens before surrounding function returns
+
+// prints 3 2 1 0 before surrounding function returns
+for i := 0; i <= 3; i++ {
+ defer fmt.Print(i)
+}
+
+// f returns 1
+func f() (result int) {
+ defer func() {
+ result++
+ }()
+ return 0
+}
+</pre>
+
+<h2 id="Built-in_functions">Built-in functions</h2>
+
+<p>
+Built-in functions are
+<a href="#Predeclared_identifiers">predeclared</a>.
+They are called like any other function but some of them
+accept a type instead of an expression as the first argument.
+</p>
+
+<p>
+The built-in functions do not have standard Go types,
+so they can only appear in <a href="#Calls">call expressions</a>;
+they cannot be used as function values.
+</p>
+
+<h3 id="Close">Close</h3>
+
+<p>
+For a channel <code>c</code>, the built-in function <code>close(c)</code>
+records that no more values will be sent on the channel.
+It is an error if <code>c</code> is a receive-only channel.
+Sending to or closing a closed channel causes a <a href="#Run_time_panics">run-time panic</a>.
+Closing the nil channel also causes a <a href="#Run_time_panics">run-time panic</a>.
+After calling <code>close</code>, and after any previously
+sent values have been received, receive operations will return
+the zero value for the channel's type without blocking.
+The multi-valued <a href="#Receive_operator">receive operation</a>
+returns a received value along with an indication of whether the channel is closed.
+</p>
+
+
+<h3 id="Length_and_capacity">Length and capacity</h3>
+
+<p>
+The built-in functions <code>len</code> and <code>cap</code> take arguments
+of various types and return a result of type <code>int</code>.
+The implementation guarantees that the result always fits into an <code>int</code>.
+</p>
+
+<pre class="grammar">
+Call Argument type Result
+
+len(s) string type string length in bytes
+ [n]T, *[n]T array length (== n)
+ []T slice length
+ map[K]T map length (number of defined keys)
+ chan T number of elements queued in channel buffer
+
+cap(s) [n]T, *[n]T array length (== n)
+ []T slice capacity
+ chan T channel buffer capacity
+</pre>
+
+<p>
+The capacity of a slice is the number of elements for which there is
+space allocated in the underlying array.
+At any time the following relationship holds:
+</p>
+
+<pre>
+0 <= len(s) <= cap(s)
+</pre>
+
+<p>
+The length of a <code>nil</code> slice, map or channel is 0.
+The capacity of a <code>nil</code> slice or channel is 0.
+</p>
+
+<p>
+The expression <code>len(s)</code> is <a href="#Constants">constant</a> if
+<code>s</code> is a string constant. The expressions <code>len(s)</code> and
+<code>cap(s)</code> are constants if the type of <code>s</code> is an array
+or pointer to an array and the expression <code>s</code> does not contain
+<a href="#Receive_operator">channel receives</a> or (non-constant)
+<a href="#Calls">function calls</a>; in this case <code>s</code> is not evaluated.
+Otherwise, invocations of <code>len</code> and <code>cap</code> are not
+constant and <code>s</code> is evaluated.
+</p>
+
+<pre>
+const (
+ c1 = imag(2i) // imag(2i) = 2.0 is a constant
+ c2 = len([10]float64{2}) // [10]float64{2} contains no function calls
+ c3 = len([10]float64{c1}) // [10]float64{c1} contains no function calls
+ c4 = len([10]float64{imag(2i)}) // imag(2i) is a constant and no function call is issued
+ c5 = len([10]float64{imag(z)}) // invalid: imag(x) is a (non-constant) function call
+)
+var z complex128
+</pre>
+
+<h3 id="Allocation">Allocation</h3>
+
+<p>
+The built-in function <code>new</code> takes a type <code>T</code>,
+allocates storage for a <a href="#Variables">variable</a> of that type
+at run time, and returns a value of type <code>*T</code>
+<a href="#Pointer_types">pointing</a> to it.
+The variable is initialized as described in the section on
+<a href="#The_zero_value">initial values</a>.
+</p>
+
+<pre class="grammar">
+new(T)
+</pre>
+
+<p>
+For instance
+</p>
+
+<pre>
+type S struct { a int; b float64 }
+new(S)
+</pre>
+
+<p>
+allocates storage for a variable of type <code>S</code>,
+initializes it (<code>a=0</code>, <code>b=0.0</code>),
+and returns a value of type <code>*S</code> containing the address
+of the location.
+</p>
+
+<h3 id="Making_slices_maps_and_channels">Making slices, maps and channels</h3>
+
+<p>
+The built-in function <code>make</code> takes a type <code>T</code>,
+which must be a slice, map or channel type,
+optionally followed by a type-specific list of expressions.
+It returns a value of type <code>T</code> (not <code>*T</code>).
+The memory is initialized as described in the section on
+<a href="#The_zero_value">initial values</a>.
+</p>
+
+<pre class="grammar">
+Call Type T Result
+
+make(T, n) slice slice of type T with length n and capacity n
+make(T, n, m) slice slice of type T with length n and capacity m
+
+make(T) map map of type T
+make(T, n) map map of type T with initial space for n elements
+
+make(T) channel unbuffered channel of type T
+make(T, n) channel buffered channel of type T, buffer size n
+</pre>
+
+
+<p>
+The size arguments <code>n</code> and <code>m</code> must be of integer type or untyped.
+A <a href="#Constants">constant</a> size argument must be non-negative and
+representable by a value of type <code>int</code>.
+If both <code>n</code> and <code>m</code> are provided and are constant, then
+<code>n</code> must be no larger than <code>m</code>.
+If <code>n</code> is negative or larger than <code>m</code> at run time,
+a <a href="#Run_time_panics">run-time panic</a> occurs.
+</p>
+
+<pre>
+s := make([]int, 10, 100) // slice with len(s) == 10, cap(s) == 100
+s := make([]int, 1e3) // slice with len(s) == cap(s) == 1000
+s := make([]int, 1<<63) // illegal: len(s) is not representable by a value of type int
+s := make([]int, 10, 0) // illegal: len(s) > cap(s)
+c := make(chan int, 10) // channel with a buffer size of 10
+m := make(map[string]int, 100) // map with initial space for 100 elements
+</pre>
+
+
+<h3 id="Appending_and_copying_slices">Appending to and copying slices</h3>
+
+<p>
+The built-in functions <code>append</code> and <code>copy</code> assist in
+common slice operations.
+For both functions, the result is independent of whether the memory referenced
+by the arguments overlaps.
+</p>
+
+<p>
+The <a href="#Function_types">variadic</a> function <code>append</code>
+appends zero or more values <code>x</code>
+to <code>s</code> of type <code>S</code>, which must be a slice type, and
+returns the resulting slice, also of type <code>S</code>.
+The values <code>x</code> are passed to a parameter of type <code>...T</code>
+where <code>T</code> is the <a href="#Slice_types">element type</a> of
+<code>S</code> and the respective
+<a href="#Passing_arguments_to_..._parameters">parameter passing rules</a> apply.
+As a special case, <code>append</code> also accepts a first argument
+assignable to type <code>[]byte</code> with a second argument of
+string type followed by <code>...</code>. This form appends the
+bytes of the string.
+</p>
+
+<pre class="grammar">
+append(s S, x ...T) S // T is the element type of S
+</pre>
+
+<p>
+If the capacity of <code>s</code> is not large enough to fit the additional
+values, <code>append</code> allocates a new, sufficiently large underlying
+array that fits both the existing slice elements and the additional values.
+Otherwise, <code>append</code> re-uses the underlying array.
+</p>
+
+<pre>
+s0 := []int{0, 0}
+s1 := append(s0, 2) // append a single element s1 == []int{0, 0, 2}
+s2 := append(s1, 3, 5, 7) // append multiple elements s2 == []int{0, 0, 2, 3, 5, 7}
+s3 := append(s2, s0...) // append a slice s3 == []int{0, 0, 2, 3, 5, 7, 0, 0}
+s4 := append(s3[3:6], s3[2:]...) // append overlapping slice s4 == []int{3, 5, 7, 2, 3, 5, 7, 0, 0}
+
+var t []interface{}
+t = append(t, 42, 3.1415, "foo") t == []interface{}{42, 3.1415, "foo"}
+
+var b []byte
+b = append(b, "bar"...) // append string contents b == []byte{'b', 'a', 'r' }
+</pre>
+
+<p>
+The function <code>copy</code> copies slice elements from
+a source <code>src</code> to a destination <code>dst</code> and returns the
+number of elements copied.
+Both arguments must have <a href="#Type_identity">identical</a> element type <code>T</code> and must be
+<a href="#Assignability">assignable</a> to a slice of type <code>[]T</code>.
+The number of elements copied is the minimum of
+<code>len(src)</code> and <code>len(dst)</code>.
+As a special case, <code>copy</code> also accepts a destination argument assignable
+to type <code>[]byte</code> with a source argument of a string type.
+This form copies the bytes from the string into the byte slice.
+</p>
+
+<pre class="grammar">
+copy(dst, src []T) int
+copy(dst []byte, src string) int
+</pre>
+
+<p>
+Examples:
+</p>
+
+<pre>
+var a = [...]int{0, 1, 2, 3, 4, 5, 6, 7}
+var s = make([]int, 6)
+var b = make([]byte, 5)
+n1 := copy(s, a[0:]) // n1 == 6, s == []int{0, 1, 2, 3, 4, 5}
+n2 := copy(s, s[2:]) // n2 == 4, s == []int{2, 3, 4, 5, 4, 5}
+n3 := copy(b, "Hello, World!") // n3 == 5, b == []byte("Hello")
+</pre>
+
+
+<h3 id="Deletion_of_map_elements">Deletion of map elements</h3>
+
+<p>
+The built-in function <code>delete</code> removes the element with key
+<code>k</code> from a <a href="#Map_types">map</a> <code>m</code>. The
+type of <code>k</code> must be <a href="#Assignability">assignable</a>
+to the key type of <code>m</code>.
+</p>
+
+<pre class="grammar">
+delete(m, k) // remove element m[k] from map m
+</pre>
+
+<p>
+If the map <code>m</code> is <code>nil</code> or the element <code>m[k]</code>
+does not exist, <code>delete</code> is a no-op.
+</p>
+
+
+<h3 id="Complex_numbers">Manipulating complex numbers</h3>
+
+<p>
+Three functions assemble and disassemble complex numbers.
+The built-in function <code>complex</code> constructs a complex
+value from a floating-point real and imaginary part, while
+<code>real</code> and <code>imag</code>
+extract the real and imaginary parts of a complex value.
+</p>
+
+<pre class="grammar">
+complex(realPart, imaginaryPart floatT) complexT
+real(complexT) floatT
+imag(complexT) floatT
+</pre>
+
+<p>
+The type of the arguments and return value correspond.
+For <code>complex</code>, the two arguments must be of the same
+floating-point type and the return type is the complex type
+with the corresponding floating-point constituents:
+<code>complex64</code> for <code>float32</code>,
+<code>complex128</code> for <code>float64</code>.
+The <code>real</code> and <code>imag</code> functions
+together form the inverse, so for a complex value <code>z</code>,
+<code>z</code> <code>==</code> <code>complex(real(z),</code> <code>imag(z))</code>.
+</p>
+
+<p>
+If the operands of these functions are all constants, the return
+value is a constant.
+</p>
+
+<pre>
+var a = complex(2, -2) // complex128
+var b = complex(1.0, -1.4) // complex128
+x := float32(math.Cos(math.Pi/2)) // float32
+var c64 = complex(5, -x) // complex64
+var im = imag(b) // float64
+var rl = real(c64) // float32
+</pre>
+
+<h3 id="Handling_panics">Handling panics</h3>
+
+<p> Two built-in functions, <code>panic</code> and <code>recover</code>,
+assist in reporting and handling <a href="#Run_time_panics">run-time panics</a>
+and program-defined error conditions.
+</p>
+
+<pre class="grammar">
+func panic(interface{})
+func recover() interface{}
+</pre>
+
+<p>
+While executing a function <code>F</code>,
+an explicit call to <code>panic</code> or a <a href="#Run_time_panics">run-time panic</a>
+terminates the execution of <code>F</code>.
+Any functions <a href="#Defer_statements">deferred</a> by <code>F</code>
+are then executed as usual.
+Next, any deferred functions run by <code>F's</code> caller are run,
+and so on up to any deferred by the top-level function in the executing goroutine.
+At that point, the program is terminated and the error
+condition is reported, including the value of the argument to <code>panic</code>.
+This termination sequence is called <i>panicking</i>.
+</p>
+
+<pre>
+panic(42)
+panic("unreachable")
+panic(Error("cannot parse"))
+</pre>
+
+<p>
+The <code>recover</code> function allows a program to manage behavior
+of a panicking goroutine.
+Suppose a function <code>G</code> defers a function <code>D</code> that calls
+<code>recover</code> and a panic occurs in a function on the same goroutine in which <code>G</code>
+is executing.
+When the running of deferred functions reaches <code>D</code>,
+the return value of <code>D</code>'s call to <code>recover</code> will be the value passed to the call of <code>panic</code>.
+If <code>D</code> returns normally, without starting a new
+<code>panic</code>, the panicking sequence stops. In that case,
+the state of functions called between <code>G</code> and the call to <code>panic</code>
+is discarded, and normal execution resumes.
+Any functions deferred by <code>G</code> before <code>D</code> are then run and <code>G</code>'s
+execution terminates by returning to its caller.
+</p>
+
+<p>
+The return value of <code>recover</code> is <code>nil</code> if any of the following conditions holds:
+</p>
+<ul>
+<li>
+<code>panic</code>'s argument was <code>nil</code>;
+</li>
+<li>
+the goroutine is not panicking;
+</li>
+<li>
+<code>recover</code> was not called directly by a deferred function.
+</li>
+</ul>
+
+<p>
+The <code>protect</code> function in the example below invokes
+the function argument <code>g</code> and protects callers from
+run-time panics raised by <code>g</code>.
+</p>
+
+<pre>
+func protect(g func()) {
+ defer func() {
+ log.Println("done") // Println executes normally even if there is a panic
+ if x := recover(); x != nil {
+ log.Printf("run time panic: %v", x)
+ }
+ }()
+ log.Println("start")
+ g()
+}
+</pre>
+
+
+<h3 id="Bootstrapping">Bootstrapping</h3>
+
+<p>
+Current implementations provide several built-in functions useful during
+bootstrapping. These functions are documented for completeness but are not
+guaranteed to stay in the language. They do not return a result.
+</p>
+
+<pre class="grammar">
+Function Behavior
+
+print prints all arguments; formatting of arguments is implementation-specific
+println like print but prints spaces between arguments and a newline at the end
+</pre>
+
+
+<h2 id="Packages">Packages</h2>
+
+<p>
+Go programs are constructed by linking together <i>packages</i>.
+A package in turn is constructed from one or more source files
+that together declare constants, types, variables and functions
+belonging to the package and which are accessible in all files
+of the same package. Those elements may be
+<a href="#Exported_identifiers">exported</a> and used in another package.
+</p>
+
+<h3 id="Source_file_organization">Source file organization</h3>
+
+<p>
+Each source file consists of a package clause defining the package
+to which it belongs, followed by a possibly empty set of import
+declarations that declare packages whose contents it wishes to use,
+followed by a possibly empty set of declarations of functions,
+types, variables, and constants.
+</p>
+
+<pre class="ebnf">
+SourceFile = PackageClause ";" { ImportDecl ";" } { TopLevelDecl ";" } .
+</pre>
+
+<h3 id="Package_clause">Package clause</h3>
+
+<p>
+A package clause begins each source file and defines the package
+to which the file belongs.
+</p>
+
+<pre class="ebnf">
+PackageClause = "package" PackageName .
+PackageName = identifier .
+</pre>
+
+<p>
+The PackageName must not be the <a href="#Blank_identifier">blank identifier</a>.
+</p>
+
+<pre>
+package math
+</pre>
+
+<p>
+A set of files sharing the same PackageName form the implementation of a package.
+An implementation may require that all source files for a package inhabit the same directory.
+</p>
+
+<h3 id="Import_declarations">Import declarations</h3>
+
+<p>
+An import declaration states that the source file containing the declaration
+depends on functionality of the <i>imported</i> package
+(<a href="#Program_initialization_and_execution">§Program initialization and execution</a>)
+and enables access to <a href="#Exported_identifiers">exported</a> identifiers
+of that package.
+The import names an identifier (PackageName) to be used for access and an ImportPath
+that specifies the package to be imported.
+</p>
+
+<pre class="ebnf">
+ImportDecl = "import" ( ImportSpec | "(" { ImportSpec ";" } ")" ) .
+ImportSpec = [ "." | PackageName ] ImportPath .
+ImportPath = string_lit .
+</pre>
+
+<p>
+The PackageName is used in <a href="#Qualified_identifiers">qualified identifiers</a>
+to access exported identifiers of the package within the importing source file.
+It is declared in the <a href="#Blocks">file block</a>.
+If the PackageName is omitted, it defaults to the identifier specified in the
+<a href="#Package_clause">package clause</a> of the imported package.
+If an explicit period (<code>.</code>) appears instead of a name, all the
+package's exported identifiers declared in that package's
+<a href="#Blocks">package block</a> will be declared in the importing source
+file's file block and must be accessed without a qualifier.
+</p>
+
+<p>
+The interpretation of the ImportPath is implementation-dependent but
+it is typically a substring of the full file name of the compiled
+package and may be relative to a repository of installed packages.
+</p>
+
+<p>
+Implementation restriction: A compiler may restrict ImportPaths to
+non-empty strings using only characters belonging to
+<a href="http://www.unicode.org/versions/Unicode6.3.0/">Unicode's</a>
+L, M, N, P, and S general categories (the Graphic characters without
+spaces) and may also exclude the characters
+<code>!"#$%&'()*,:;<=>?[\]^`{|}</code>
+and the Unicode replacement character U+FFFD.
+</p>
+
+<p>
+Assume we have compiled a package containing the package clause
+<code>package math</code>, which exports function <code>Sin</code>, and
+installed the compiled package in the file identified by
+<code>"lib/math"</code>.
+This table illustrates how <code>Sin</code> is accessed in files
+that import the package after the
+various types of import declaration.
+</p>
+
+<pre class="grammar">
+Import declaration Local name of Sin
+
+import "lib/math" math.Sin
+import m "lib/math" m.Sin
+import . "lib/math" Sin
+</pre>
+
+<p>
+An import declaration declares a dependency relation between
+the importing and imported package.
+It is illegal for a package to import itself, directly or indirectly,
+or to directly import a package without
+referring to any of its exported identifiers. To import a package solely for
+its side-effects (initialization), use the <a href="#Blank_identifier">blank</a>
+identifier as explicit package name:
+</p>
+
+<pre>
+import _ "lib/math"
+</pre>
+
+
+<h3 id="An_example_package">An example package</h3>
+
+<p>
+Here is a complete Go package that implements a concurrent prime sieve.
+</p>
+
+<pre>
+package main
+
+import "fmt"
+
+// Send the sequence 2, 3, 4, … to channel 'ch'.
+func generate(ch chan<- int) {
+ for i := 2; ; i++ {
+ ch <- i // Send 'i' to channel 'ch'.
+ }
+}
+
+// Copy the values from channel 'src' to channel 'dst',
+// removing those divisible by 'prime'.
+func filter(src <-chan int, dst chan<- int, prime int) {
+ for i := range src { // Loop over values received from 'src'.
+ if i%prime != 0 {
+ dst <- i // Send 'i' to channel 'dst'.
+ }
+ }
+}
+
+// The prime sieve: Daisy-chain filter processes together.
+func sieve() {
+ ch := make(chan int) // Create a new channel.
+ go generate(ch) // Start generate() as a subprocess.
+ for {
+ prime := <-ch
+ fmt.Print(prime, "\n")
+ ch1 := make(chan int)
+ go filter(ch, ch1, prime)
+ ch = ch1
+ }
+}
+
+func main() {
+ sieve()
+}
+</pre>
+
+<h2 id="Program_initialization_and_execution">Program initialization and execution</h2>
+
+<h3 id="The_zero_value">The zero value</h3>
+<p>
+When storage is allocated for a <a href="#Variables">variable</a>,
+either through a declaration or a call of <code>new</code>, or when
+a new value is created, either through a composite literal or a call
+of <code>make</code>,
+and no explicit initialization is provided, the variable or value is
+given a default value. Each element of such a variable or value is
+set to the <i>zero value</i> for its type: <code>false</code> for booleans,
+<code>0</code> for integers, <code>0.0</code> for floats, <code>""</code>
+for strings, and <code>nil</code> for pointers, functions, interfaces, slices, channels, and maps.
+This initialization is done recursively, so for instance each element of an
+array of structs will have its fields zeroed if no value is specified.
+</p>
+<p>
+These two simple declarations are equivalent:
+</p>
+
+<pre>
+var i int
+var i int = 0
+</pre>
+
+<p>
+After
+</p>
+
+<pre>
+type T struct { i int; f float64; next *T }
+t := new(T)
+</pre>
+
+<p>
+the following holds:
+</p>
+
+<pre>
+t.i == 0
+t.f == 0.0
+t.next == nil
+</pre>
+
+<p>
+The same would also be true after
+</p>
+
+<pre>
+var t T
+</pre>
+
+<h3 id="Package_initialization">Package initialization</h3>
+
+<p>
+Within a package, package-level variables are initialized in
+<i>declaration order</i> but after any of the variables
+they <i>depend</i> on.
+</p>
+
+<p>
+More precisely, a package-level variable is considered <i>ready for
+initialization</i> if it is not yet initialized and either has
+no <a href="#Variable_declarations">initialization expression</a> or
+its initialization expression has no dependencies on uninitialized variables.
+Initialization proceeds by repeatedly initializing the next package-level
+variable that is earliest in declaration order and ready for initialization,
+until there are no variables ready for initialization.
+</p>
+
+<p>
+If any variables are still uninitialized when this
+process ends, those variables are part of one or more initialization cycles,
+and the program is not valid.
+</p>
+
+<p>
+The declaration order of variables declared in multiple files is determined
+by the order in which the files are presented to the compiler: Variables
+declared in the first file are declared before any of the variables declared
+in the second file, and so on.
+</p>
+
+<p>
+Dependency analysis does not rely on the actual values of the
+variables, only on lexical <i>references</i> to them in the source,
+analyzed transitively. For instance, if a variable <code>x</code>'s
+initialization expression refers to a function whose body refers to
+variable <code>y</code> then <code>x</code> depends on <code>y</code>.
+Specifically:
+</p>
+
+<ul>
+<li>
+A reference to a variable or function is an identifier denoting that
+variable or function.
+</li>
+
+<li>
+A reference to a method <code>m</code> is a
+<a href="#Method_values">method value</a> or
+<a href="#Method_expressions">method expression</a> of the form
+<code>t.m</code>, where the (static) type of <code>t</code> is
+not an interface type, and the method <code>m</code> is in the
+<a href="#Method_sets">method set</a> of <code>t</code>.
+It is immaterial whether the resulting function value
+<code>t.m</code> is invoked.
+</li>
+
+<li>
+A variable, function, or method <code>x</code> depends on a variable
+<code>y</code> if <code>x</code>'s initialization expression or body
+(for functions and methods) contains a reference to <code>y</code>
+or to a function or method that depends on <code>y</code>.
+</li>
+</ul>
+
+<p>
+Dependency analysis is performed per package; only references referring
+to variables, functions, and methods declared in the current package
+are considered.
+</p>
+
+<p>
+For example, given the declarations
+</p>
+
+<pre>
+var (
+ a = c + b
+ b = f()
+ c = f()
+ d = 3
+)
+
+func f() int {
+ d++
+ return d
+}
+</pre>
+
+<p>
+the initialization order is <code>d</code>, <code>b</code>, <code>c</code>, <code>a</code>.
+</p>
+
+<p>
+Variables may also be initialized using functions named <code>init</code>
+declared in the package block, with no arguments and no result parameters.
+</p>
+
+<pre>
+func init() { … }
+</pre>
+
+<p>
+Multiple such functions may be defined, even within a single
+source file. The <code>init</code> identifier is not
+<a href="#Declarations_and_scope">declared</a> and thus
+<code>init</code> functions cannot be referred to from anywhere
+in a program.
+</p>
+
+<p>
+A package with no imports is initialized by assigning initial values
+to all its package-level variables followed by calling all <code>init</code>
+functions in the order they appear in the source, possibly in multiple files,
+as presented to the compiler.
+If a package has imports, the imported packages are initialized
+before initializing the package itself. If multiple packages import
+a package, the imported package will be initialized only once.
+The importing of packages, by construction, guarantees that there
+can be no cyclic initialization dependencies.
+</p>
+
+<p>
+Package initialization—variable initialization and the invocation of
+<code>init</code> functions—happens in a single goroutine,
+sequentially, one package at a time.
+An <code>init</code> function may launch other goroutines, which can run
+concurrently with the initialization code. However, initialization
+always sequences
+the <code>init</code> functions: it will not invoke the next one
+until the previous one has returned.
+</p>
+
+<p>
+To ensure reproducible initialization behavior, build systems are encouraged
+to present multiple files belonging to the same package in lexical file name
+order to a compiler.
+</p>
+
+
+<h3 id="Program_execution">Program execution</h3>
+<p>
+A complete program is created by linking a single, unimported package
+called the <i>main package</i> with all the packages it imports, transitively.
+The main package must
+have package name <code>main</code> and
+declare a function <code>main</code> that takes no
+arguments and returns no value.
+</p>
+
+<pre>
+func main() { … }
+</pre>
+
+<p>
+Program execution begins by initializing the main package and then
+invoking the function <code>main</code>.
+When that function invocation returns, the program exits.
+It does not wait for other (non-<code>main</code>) goroutines to complete.
+</p>
+
+<h2 id="Errors">Errors</h2>
+
+<p>
+The predeclared type <code>error</code> is defined as
+</p>
+
+<pre>
+type error interface {
+ Error() string
+}
+</pre>
+
+<p>
+It is the conventional interface for representing an error condition,
+with the nil value representing no error.
+For instance, a function to read data from a file might be defined:
+</p>
+
+<pre>
+func Read(f *File, b []byte) (n int, err error)
+</pre>
+
+<h2 id="Run_time_panics">Run-time panics</h2>
+
+<p>
+Execution errors such as attempting to index an array out
+of bounds trigger a <i>run-time panic</i> equivalent to a call of
+the built-in function <a href="#Handling_panics"><code>panic</code></a>
+with a value of the implementation-defined interface type <code>runtime.Error</code>.
+That type satisfies the predeclared interface type
+<a href="#Errors"><code>error</code></a>.
+The exact error values that
+represent distinct run-time error conditions are unspecified.
+</p>
+
+<pre>
+package runtime
+
+type Error interface {
+ error
+ // and perhaps other methods
+}
+</pre>
+
+<h2 id="System_considerations">System considerations</h2>
+
+<h3 id="Package_unsafe">Package <code>unsafe</code></h3>
+
+<p>
+The built-in package <code>unsafe</code>, known to the compiler,
+provides facilities for low-level programming including operations
+that violate the type system. A package using <code>unsafe</code>
+must be vetted manually for type safety and may not be portable.
+The package provides the following interface:
+</p>
+
+<pre class="grammar">
+package unsafe
+
+type ArbitraryType int // shorthand for an arbitrary Go type; it is not a real type
+type Pointer *ArbitraryType
+
+func Alignof(variable ArbitraryType) uintptr
+func Offsetof(selector ArbitraryType) uintptr
+func Sizeof(variable ArbitraryType) uintptr
+</pre>
+
+<p>
+A <code>Pointer</code> is a <a href="#Pointer_types">pointer type</a> but a <code>Pointer</code>
+value may not be <a href="#Address_operators">dereferenced</a>.
+Any pointer or value of <a href="#Types">underlying type</a> <code>uintptr</code> can be converted to
+a <code>Pointer</code> type and vice versa.
+The effect of converting between <code>Pointer</code> and <code>uintptr</code> is implementation-defined.
+</p>
+
+<pre>
+var f float64
+bits = *(*uint64)(unsafe.Pointer(&f))
+
+type ptr unsafe.Pointer
+bits = *(*uint64)(ptr(&f))
+
+var p ptr = nil
+</pre>
+
+<p>
+The functions <code>Alignof</code> and <code>Sizeof</code> take an expression <code>x</code>
+of any type and return the alignment or size, respectively, of a hypothetical variable <code>v</code>
+as if <code>v</code> was declared via <code>var v = x</code>.
+</p>
+<p>
+The function <code>Offsetof</code> takes a (possibly parenthesized) <a href="#Selectors">selector</a>
+<code>s.f</code>, denoting a field <code>f</code> of the struct denoted by <code>s</code>
+or <code>*s</code>, and returns the field offset in bytes relative to the struct's address.
+If <code>f</code> is an <a href="#Struct_types">embedded field</a>, it must be reachable
+without pointer indirections through fields of the struct.
+For a struct <code>s</code> with field <code>f</code>:
+</p>
+
+<pre>
+uintptr(unsafe.Pointer(&s)) + unsafe.Offsetof(s.f) == uintptr(unsafe.Pointer(&s.f))
+</pre>
+
+<p>
+Computer architectures may require memory addresses to be <i>aligned</i>;
+that is, for addresses of a variable to be a multiple of a factor,
+the variable's type's <i>alignment</i>. The function <code>Alignof</code>
+takes an expression denoting a variable of any type and returns the
+alignment of the (type of the) variable in bytes. For a variable
+<code>x</code>:
+</p>
+
+<pre>
+uintptr(unsafe.Pointer(&x)) % unsafe.Alignof(x) == 0
+</pre>
+
+<p>
+Calls to <code>Alignof</code>, <code>Offsetof</code>, and
+<code>Sizeof</code> are compile-time constant expressions of type <code>uintptr</code>.
+</p>
+
+<h3 id="Size_and_alignment_guarantees">Size and alignment guarantees</h3>
+
+<p>
+For the <a href="#Numeric_types">numeric types</a>, the following sizes are guaranteed:
+</p>
+
+<pre class="grammar">
+type size in bytes
+
+byte, uint8, int8 1
+uint16, int16 2
+uint32, int32, float32 4
+uint64, int64, float64, complex64 8
+complex128 16
+</pre>
+
+<p>
+The following minimal alignment properties are guaranteed:
+</p>
+<ol>
+<li>For a variable <code>x</code> of any type: <code>unsafe.Alignof(x)</code> is at least 1.
+</li>
+
+<li>For a variable <code>x</code> of struct type: <code>unsafe.Alignof(x)</code> is the largest of
+ all the values <code>unsafe.Alignof(x.f)</code> for each field <code>f</code> of <code>x</code>, but at least 1.
+</li>
+
+<li>For a variable <code>x</code> of array type: <code>unsafe.Alignof(x)</code> is the same as
+ <code>unsafe.Alignof(x[0])</code>, but at least 1.
+</li>
+</ol>
+
+<p>
+A struct or array type has size zero if it contains no fields (or elements, respectively) that have a size greater than zero. Two distinct zero-size variables may have the same address in memory.
+</p>
diff --git a/doc/gopher/README b/doc/gopher/README
new file mode 100644
index 0000000..936a24c
--- /dev/null
+++ b/doc/gopher/README
@@ -0,0 +1,3 @@
+The Go gopher was designed by Renee French. (http://reneefrench.blogspot.com/)
+The design is licensed under the Creative Commons 3.0 Attributions license.
+Read this article for more details: http://blog.golang.org/gopher
diff --git a/doc/gopher/appenginegopher.jpg b/doc/gopher/appenginegopher.jpg
new file mode 100644
index 0000000..0a64306
--- /dev/null
+++ b/doc/gopher/appenginegopher.jpg
Binary files differ
diff --git a/doc/gopher/appenginegophercolor.jpg b/doc/gopher/appenginegophercolor.jpg
new file mode 100644
index 0000000..68795a9
--- /dev/null
+++ b/doc/gopher/appenginegophercolor.jpg
Binary files differ
diff --git a/doc/gopher/appenginelogo.gif b/doc/gopher/appenginelogo.gif
new file mode 100644
index 0000000..46b3c1e
--- /dev/null
+++ b/doc/gopher/appenginelogo.gif
Binary files differ
diff --git a/doc/gopher/biplane.jpg b/doc/gopher/biplane.jpg
new file mode 100644
index 0000000..d5e666f
--- /dev/null
+++ b/doc/gopher/biplane.jpg
Binary files differ
diff --git a/doc/gopher/bumper.png b/doc/gopher/bumper.png
new file mode 100644
index 0000000..b357cdf
--- /dev/null
+++ b/doc/gopher/bumper.png
Binary files differ
diff --git a/doc/gopher/bumper192x108.png b/doc/gopher/bumper192x108.png
new file mode 100644
index 0000000..925474e
--- /dev/null
+++ b/doc/gopher/bumper192x108.png
Binary files differ
diff --git a/doc/gopher/bumper320x180.png b/doc/gopher/bumper320x180.png
new file mode 100644
index 0000000..611c417
--- /dev/null
+++ b/doc/gopher/bumper320x180.png
Binary files differ
diff --git a/doc/gopher/bumper480x270.png b/doc/gopher/bumper480x270.png
new file mode 100644
index 0000000..cf18715
--- /dev/null
+++ b/doc/gopher/bumper480x270.png
Binary files differ
diff --git a/doc/gopher/bumper640x360.png b/doc/gopher/bumper640x360.png
new file mode 100644
index 0000000..a5073e0
--- /dev/null
+++ b/doc/gopher/bumper640x360.png
Binary files differ
diff --git a/doc/gopher/doc.png b/doc/gopher/doc.png
new file mode 100644
index 0000000..e15a323
--- /dev/null
+++ b/doc/gopher/doc.png
Binary files differ
diff --git a/doc/gopher/fiveyears.jpg b/doc/gopher/fiveyears.jpg
new file mode 100644
index 0000000..df10648
--- /dev/null
+++ b/doc/gopher/fiveyears.jpg
Binary files differ
diff --git a/doc/gopher/frontpage.png b/doc/gopher/frontpage.png
new file mode 100644
index 0000000..1eb81f0
--- /dev/null
+++ b/doc/gopher/frontpage.png
Binary files differ
diff --git a/doc/gopher/gopherbw.png b/doc/gopher/gopherbw.png
new file mode 100644
index 0000000..3bfe85d
--- /dev/null
+++ b/doc/gopher/gopherbw.png
Binary files differ
diff --git a/doc/gopher/gophercolor.png b/doc/gopher/gophercolor.png
new file mode 100644
index 0000000..b5f8d01
--- /dev/null
+++ b/doc/gopher/gophercolor.png
Binary files differ
diff --git a/doc/gopher/gophercolor16x16.png b/doc/gopher/gophercolor16x16.png
new file mode 100644
index 0000000..ec7028c
--- /dev/null
+++ b/doc/gopher/gophercolor16x16.png
Binary files differ
diff --git a/doc/gopher/help.png b/doc/gopher/help.png
new file mode 100644
index 0000000..6ee5238
--- /dev/null
+++ b/doc/gopher/help.png
Binary files differ
diff --git a/doc/gopher/pencil/gopherhat.jpg b/doc/gopher/pencil/gopherhat.jpg
new file mode 100644
index 0000000..f34d7b3
--- /dev/null
+++ b/doc/gopher/pencil/gopherhat.jpg
Binary files differ
diff --git a/doc/gopher/pencil/gopherhelmet.jpg b/doc/gopher/pencil/gopherhelmet.jpg
new file mode 100644
index 0000000..c7b6c61
--- /dev/null
+++ b/doc/gopher/pencil/gopherhelmet.jpg
Binary files differ
diff --git a/doc/gopher/pencil/gophermega.jpg b/doc/gopher/pencil/gophermega.jpg
new file mode 100644
index 0000000..779fb07
--- /dev/null
+++ b/doc/gopher/pencil/gophermega.jpg
Binary files differ
diff --git a/doc/gopher/pencil/gopherrunning.jpg b/doc/gopher/pencil/gopherrunning.jpg
new file mode 100644
index 0000000..eeeddf1
--- /dev/null
+++ b/doc/gopher/pencil/gopherrunning.jpg
Binary files differ
diff --git a/doc/gopher/pencil/gopherswim.jpg b/doc/gopher/pencil/gopherswim.jpg
new file mode 100644
index 0000000..2f32877
--- /dev/null
+++ b/doc/gopher/pencil/gopherswim.jpg
Binary files differ
diff --git a/doc/gopher/pencil/gopherswrench.jpg b/doc/gopher/pencil/gopherswrench.jpg
new file mode 100644
index 0000000..93005f4
--- /dev/null
+++ b/doc/gopher/pencil/gopherswrench.jpg
Binary files differ
diff --git a/doc/gopher/pkg.png b/doc/gopher/pkg.png
new file mode 100644
index 0000000..ac96551
--- /dev/null
+++ b/doc/gopher/pkg.png
Binary files differ
diff --git a/doc/gopher/project.png b/doc/gopher/project.png
new file mode 100644
index 0000000..24603f3
--- /dev/null
+++ b/doc/gopher/project.png
Binary files differ
diff --git a/doc/gopher/ref.png b/doc/gopher/ref.png
new file mode 100644
index 0000000..0508f6e
--- /dev/null
+++ b/doc/gopher/ref.png
Binary files differ
diff --git a/doc/gopher/run.png b/doc/gopher/run.png
new file mode 100644
index 0000000..eb690e3
--- /dev/null
+++ b/doc/gopher/run.png
Binary files differ
diff --git a/doc/gopher/talks.png b/doc/gopher/talks.png
new file mode 100644
index 0000000..589db47
--- /dev/null
+++ b/doc/gopher/talks.png
Binary files differ
diff --git a/doc/help.html b/doc/help.html
new file mode 100644
index 0000000..2cc4780
--- /dev/null
+++ b/doc/help.html
@@ -0,0 +1,50 @@
+<!--{
+ "Title": "Getting Help",
+ "Path": "/help/"
+}-->
+
+<img class="gopher" src="/doc/gopher/help.png"/>
+
+<p>
+Need help with Go? Try these resources.
+</p>
+
+<div id="manual-nav"></div>
+
+<h3 id="faq"><a href="/doc/faq">Frequently Asked Questions (FAQ)</a></h3>
+<p>Answers to common questions about Go.</p>
+
+<h3 id="playground"><a href="/play">The Go Playground</a></h3>
+<p>A place to write, run, and share Go code.</p>
+
+<h3 id="wiki"><a href="/wiki">The Go Wiki</a></h3>
+<p>A wiki maintained by the Go community.</p>
+
+<h3 id="mailinglist"><a href="//groups.google.com/group/golang-nuts">Go Nuts Mailing List</a></h3>
+<p>
+Search the <a href="//groups.google.com/group/golang-nuts">golang-nuts</a>
+archives and consult the <a href="/doc/go_faq.html">FAQ</a> and
+<a href="//golang.org/wiki">wiki</a> before posting.
+</p>
+
+<h3 id="irc"><a href="irc:irc.freenode.net/go-nuts">Go IRC Channel</a></h3>
+<p>Get live support at <b>#go-nuts</b> on <b>irc.freenode.net</b>, the official
+Go IRC channel.</p>
+
+<h3 id="pluscom"><a href="https://plus.google.com/communities/114112804251407510571">The Go+ community</a></h3>
+<p>The Google+ community for Go enthusiasts.</p>
+
+<h3 id="plus"><a href="https://plus.google.com/101406623878176903605/posts">The Go Programming Language at Google+</a></h3>
+<p>The Go project's Google+ page.</p>
+
+<h3 id="twitter"><a href="//twitter.com/golang">@golang at Twitter</a></h3>
+<p>The Go project's official Twitter account.</p>
+<p>Tweeting about your problem with the <code>#golang</code> hashtag usually
+generates some helpful responses.</p>
+
+<h3 id="go_user_groups"><a href="/wiki/GoUserGroups">Go User Groups</a></h3>
+<p>
+Each month in places around the world, groups of Go programmers ("gophers")
+meet to talk about Go. Find a chapter near you.
+</p>
+
diff --git a/doc/ie.css b/doc/ie.css
new file mode 100644
index 0000000..bb89d54
--- /dev/null
+++ b/doc/ie.css
@@ -0,0 +1 @@
+#nav-main li { display: inline; }
diff --git a/doc/install-source.html b/doc/install-source.html
new file mode 100644
index 0000000..7daf360
--- /dev/null
+++ b/doc/install-source.html
@@ -0,0 +1,502 @@
+<!--{
+ "Title": "Installing Go from source",
+ "Path": "/doc/install/source"
+}-->
+
+<h2 id="introduction">Introduction</h2>
+
+<p>
+Go is an open source project, distributed under a
+<a href="/LICENSE">BSD-style license</a>.
+This document explains how to check out the sources,
+build them on your own machine, and run them.
+</p>
+
+<p>
+Most users don't need to do this, and will instead install
+from precompiled binary packages as described in
+<a href="/doc/install">Getting Started</a>,
+a much simpler process.
+If you want to help develop what goes into those precompiled
+packages, though, read on.
+</p>
+
+<div class="detail">
+
+<p>
+There are two official Go compiler tool chains.
+This document focuses on the <code>gc</code> Go
+compiler and tools (<code>6g</code>, <code>8g</code> etc.).
+For information on how to work on <code>gccgo</code>, a more traditional
+compiler using the GCC back end, see
+<a href="/doc/install/gccgo">Setting up and using gccgo</a>.
+</p>
+
+<p>
+The Go compilers support three instruction sets.
+There are important differences in the quality of the compilers for the different
+architectures.
+</p>
+
+<dl>
+<dt>
+ <code>amd64</code> (a.k.a. <code>x86-64</code>); <code>6g,6l,6c,6a</code>
+</dt>
+<dd>
+ A mature implementation. The compiler has an effective
+ optimizer (registerizer) and generates good code (although
+ <code>gccgo</code> can do noticeably better sometimes).
+</dd>
+<dt>
+ <code>386</code> (a.k.a. <code>x86</code> or <code>x86-32</code>); <code>8g,8l,8c,8a</code>
+</dt>
+<dd>
+ Comparable to the <code>amd64</code> port.
+</dd>
+<dt>
+ <code>arm</code> (a.k.a. <code>ARM</code>); <code>5g,5l,5c,5a</code>
+</dt>
+<dd>
+ Supports Linux, FreeBSD and NetBSD binaries. Less widely used than the other ports.
+</dd>
+</dl>
+
+<p>
+Except for things like low-level operating system interface code, the run-time
+support is the same in all ports and includes a mark-and-sweep garbage
+collector, efficient array and string slicing, and support for efficient
+goroutines, such as stacks that grow and shrink on demand.
+</p>
+
+<p>
+The compilers can target the DragonFly BSD, FreeBSD, Linux, NetBSD, OpenBSD,
+OS X (Darwin), Plan 9, Solaris and Windows operating systems.
+The full set of supported combinations is listed in the discussion of
+<a href="#environment">environment variables</a> below.
+</p>
+
+</div>
+
+<h2 id="ctools">Install C tools, if needed</h2>
+
+<p>
+The Go tool chain is written in C. To build it, you need a C compiler installed.
+Please refer to the <a href="//golang.org/wiki/InstallFromSource#install-c-tools">InstallFromSource</a>
+page on the Go community Wiki for operating system specific instructions.
+</p>
+
+<h2 id="git">Install Git, if needed</h2>
+
+<p>
+To perform the next step you must have Git installed. (Check that you
+have a <code>git</code> command before proceeding.)
+</p>
+
+<p>
+If you do not have a working Git installation,
+follow the instructions on the
+<a href="http://git-scm.com/downloads">Git downloads</a> page.
+</p>
+
+
+<h2 id="fetch">Fetch the repository</h2>
+
+<p>Go will install to a directory named <code>go</code>.
+Change to the directory that will be its parent
+and make sure the <code>go</code> directory does not exist.
+Then clone the repository and check out the latest release tag:</p>
+
+<pre>
+$ git clone https://go.googlesource.com/go
+$ cd go
+$ git checkout go1.4.1
+</pre>
+
+<h2 id="head">(Optional) Switch to the master branch</h2>
+
+<p>If you intend to modify the go source code, and
+<a href="/doc/contribute.html">contribute your changes</a>
+to the project, then move your repository
+off the release branch, and onto the master (development) branch.
+Otherwise, skip this step.</p>
+
+<pre>
+$ git checkout master
+</pre>
+
+<h2 id="install">Install Go</h2>
+
+<p>
+To build the Go distribution, run
+</p>
+
+<pre>
+$ cd go/src
+$ ./all.bash
+</pre>
+
+<p>
+(To build under Windows use <code>all.bat</code>.)
+</p>
+
+<p>
+If all goes well, it will finish by printing output like:
+</p>
+
+<pre>
+ALL TESTS PASSED
+
+---
+Installed Go for linux/amd64 in /home/you/go.
+Installed commands in /home/you/go/bin.
+*** You need to add /home/you/go/bin to your $PATH. ***
+</pre>
+
+<p>
+where the details on the last few lines reflect the operating system,
+architecture, and root directory used during the install.
+</p>
+
+<div class="detail">
+<p>
+For more information about ways to control the build, see the discussion of
+<a href="#environment">environment variables</a> below.
+<code>all.bash</code> (or <code>all.bat</code>) runs important tests for Go,
+which can take more time than simply building Go. If you do not want to run
+the test suite use <code>make.bash</code> (or <code>make.bat</code>)
+instead.
+</p>
+</div>
+
+
+<h2 id="testing">Testing your installation</h2>
+
+<p>
+Check that Go is installed correctly by building a simple program.
+</p>
+
+<p>
+Create a file named <code>hello.go</code> and put the following program in it:
+</p>
+
+<pre>
+package main
+
+import "fmt"
+
+func main() {
+ fmt.Printf("hello, world\n")
+}
+</pre>
+
+<p>
+Then run it with the <code>go</code> tool:
+</p>
+
+<pre>
+$ go run hello.go
+hello, world
+</pre>
+
+<p>
+If you see the "hello, world" message then Go is installed correctly.
+</p>
+
+<h2 id="gopath">Set up your work environment</h2>
+
+<p>
+You're almost done.
+You just need to do a little more setup.
+</p>
+
+<p>
+<a href="/doc/code.html" class="download" id="start">
+<span class="big">How to Write Go Code</span>
+<span class="desc">Learn how to set up and use the Go tools</span>
+</a>
+</p>
+
+<p>
+The <a href="/doc/code.html">How to Write Go Code</a> document
+provides <b>essential setup instructions</b> for using the Go tools.
+</p>
+
+
+<h2 id="tools">Install additional tools</h2>
+
+<p>
+The source code for several Go tools (including <a href="/cmd/godoc/">godoc</a>)
+is kept in <a href="https://golang.org/x/tools">the go.tools repository</a>.
+To install all of them, run the <code>go</code> <code>get</code> command:
+</p>
+
+<pre>
+$ go get golang.org/x/tools/cmd/...
+</pre>
+
+<p>
+Or if you just want to install a specific command (<code>godoc</code> in this case):
+</p>
+
+<pre>
+$ go get golang.org/x/tools/cmd/godoc
+</pre>
+
+<p>
+To install these tools, the <code>go</code> <code>get</code> command requires
+that <a href="#git">Git</a> be installed locally.
+</p>
+
+<p>
+You must also have a workspace (<code>GOPATH</code>) set up;
+see <a href="/doc/code.html">How to Write Go Code</a> for the details.
+</p>
+
+<p>
+<b>Note</b>: The <code>go</code> command will install the <code>godoc</code>
+binary to <code>$GOROOT/bin</code> (or <code>$GOBIN</code>) and the
+<code>cover</code> and <code>vet</code> binaries to
+<code>$GOROOT/pkg/tool/$GOOS_$GOARCH</code>.
+You can access the latter commands with
+"<code>go</code> <code>tool</code> <code>cover</code>" and
+"<code>go</code> <code>tool</code> <code>vet</code>".
+</p>
+
+<h2 id="community">Community resources</h2>
+
+<p>
+The usual community resources such as
+<code>#go-nuts</code> on the <a href="http://freenode.net/">Freenode</a> IRC server
+and the
+<a href="//groups.google.com/group/golang-nuts">Go Nuts</a>
+mailing list have active developers that can help you with problems
+with your installation or your development work.
+For those who wish to keep up to date,
+there is another mailing list, <a href="//groups.google.com/group/golang-checkins">golang-checkins</a>,
+that receives a message summarizing each checkin to the Go repository.
+</p>
+
+<p>
+Bugs can be reported using the <a href="//golang.org/issue/new">Go issue tracker</a>.
+</p>
+
+
+<h2 id="releases">Keeping up with releases</h2>
+
+<p>
+New releases are announced on the
+<a href="//groups.google.com/group/golang-announce">golang-announce</a>
+mailing list.
+Each announcement mentions the latest release tag, for instance,
+<code>go1.4</code>.
+</p>
+
+<p>
+To update an existing tree to the latest release, you can run:
+</p>
+
+<pre>
+$ cd go/src
+$ git fetch
+$ git checkout <i><tag></i>
+$ ./all.bash
+</pre>
+
+Where <code><tag></code> is the version string of the release.
+
+
+<h2 id="environment">Optional environment variables</h2>
+
+<p>
+The Go compilation environment can be customized by environment variables.
+<i>None is required by the build</i>, but you may wish to set some
+to override the defaults.
+</p>
+
+<ul>
+<li><code>$GOROOT</code>
+<p>
+The root of the Go tree, often <code>$HOME/go</code>.
+Its value is built into the tree when it is compiled, and
+defaults to the parent of the directory where <code>all.bash</code> was run.
+There is no need to set this unless you want to switch between multiple
+local copies of the repository.
+</p>
+
+<li><code>$GOROOT_FINAL</code>
+<p>
+The value assumed by installed binaries and scripts when
+<code>$GOROOT</code> is not set explicitly.
+It defaults to the value of <code>$GOROOT</code>.
+If you want to build the Go tree in one location
+but move it elsewhere after the build, set
+<code>$GOROOT_FINAL</code> to the eventual location.
+</p>
+
+<li><code>$GOOS</code> and <code>$GOARCH</code>
+<p>
+The name of the target operating system and compilation architecture.
+These default to the values of <code>$GOHOSTOS</code> and
+<code>$GOHOSTARCH</code> respectively (described below).
+
+<p>
+Choices for <code>$GOOS</code> are
+<code>darwin</code> (Mac OS X 10.6 and above), <code>dragonfly</code>, <code>freebsd</code>,
+<code>linux</code>, <code>netbsd</code>, <code>openbsd</code>,
+<code>plan9</code>, <code>solaris</code> and <code>windows</code>.
+Choices for <code>$GOARCH</code> are
+<code>amd64</code> (64-bit x86, the most mature port),
+<code>386</code> (32-bit x86), and <code>arm</code> (32-bit ARM).
+The valid combinations of <code>$GOOS</code> and <code>$GOARCH</code> are:
+<table cellpadding="0">
+<tr>
+<th width="50"></th><th align="left" width="100"><code>$GOOS</code></th> <th align="left" width="100"><code>$GOARCH</code></th>
+</tr>
+<tr>
+<td></td><td><code>darwin</code></td> <td><code>386</code></td>
+</tr>
+<tr>
+<td></td><td><code>darwin</code></td> <td><code>amd64</code></td>
+</tr>
+<tr>
+<td></td><td><code>dragonfly</code></td> <td><code>386</code></td>
+</tr>
+<tr>
+<td></td><td><code>dragonfly</code></td> <td><code>amd64</code></td>
+</tr>
+<tr>
+<td></td><td><code>freebsd</code></td> <td><code>386</code></td>
+</tr>
+<tr>
+<td></td><td><code>freebsd</code></td> <td><code>amd64</code></td>
+</tr>
+<tr>
+<td></td><td><code>freebsd</code></td> <td><code>arm</code></td>
+</tr>
+<tr>
+<td></td><td><code>linux</code></td> <td><code>386</code></td>
+</tr>
+<tr>
+<td></td><td><code>linux</code></td> <td><code>amd64</code></td>
+</tr>
+<tr>
+<td></td><td><code>linux</code></td> <td><code>arm</code></td>
+</tr>
+<tr>
+<td></td><td><code>netbsd</code></td> <td><code>386</code></td>
+</tr>
+<tr>
+<td></td><td><code>netbsd</code></td> <td><code>amd64</code></td>
+</tr>
+<tr>
+<td></td><td><code>netbsd</code></td> <td><code>arm</code></td>
+</tr>
+<tr>
+<td></td><td><code>openbsd</code></td> <td><code>386</code></td>
+</tr>
+<tr>
+<td></td><td><code>openbsd</code></td> <td><code>amd64</code></td>
+</tr>
+<tr>
+<td></td><td><code>plan9</code></td> <td><code>386</code></td>
+</tr>
+<tr>
+<td></td><td><code>plan9</code></td> <td><code>amd64</code></td>
+</tr>
+<tr>
+<td></td><td><code>solaris</code></td> <td><code>amd64</code></td>
+</tr>
+<tr>
+<td></td><td><code>windows</code></td> <td><code>386</code></td>
+</tr>
+<tr>
+<td></td><td><code>windows</code></td> <td><code>amd64</code></td>
+</tr>
+</table>
+
+<li><code>$GOHOSTOS</code> and <code>$GOHOSTARCH</code>
+<p>
+The name of the host operating system and compilation architecture.
+These default to the local system's operating system and
+architecture.
+</p>
+
+<p>
+Valid choices are the same as for <code>$GOOS</code> and
+<code>$GOARCH</code>, listed above.
+The specified values must be compatible with the local system.
+For example, you should not set <code>$GOHOSTARCH</code> to
+<code>arm</code> on an x86 system.
+</p>
+
+<li><code>$GOBIN</code>
+<p>
+The location where Go binaries will be installed.
+The default is <code>$GOROOT/bin</code>.
+After installing, you will want to arrange to add this
+directory to your <code>$PATH</code>, so you can use the tools.
+If <code>$GOBIN</code> is set, the <a href="/cmd/go">go command</a>
+installs all commands there.
+</p>
+
+<li><code>$GO386</code> (for <code>386</code> only, default is auto-detected
+if built on either <code>386</code> or <code>amd64</code>, <code>387</code> otherwise)
+<p>
+This controls the code generated by 8g to use either the 387 floating-point unit
+(set to <code>387</code>) or SSE2 instructions (set to <code>sse2</code>) for
+floating point computations.
+</p>
+<ul>
+ <li><code>GO386=387</code>: use x87 for floating point operations; should support all x86 chips (Pentium MMX or later).
+ <li><code>GO386=sse2</code>: use SSE2 for floating point operations; has better performance than 387, but only available on Pentium 4/Opteron/Athlon 64 or later.
+</ul>
+
+<li><code>$GOARM</code> (for <code>arm</code> only; default is auto-detected if building
+on the target processor, 6 if not)
+<p>
+This sets the ARM floating point co-processor architecture version the run-time
+should target. If you are compiling on the target system, its value will be auto-detected.
+</p>
+<ul>
+ <li><code>GOARM=5</code>: use software floating point; when CPU doesn't have VFP co-processor
+ <li><code>GOARM=6</code>: use VFPv1 only; default if cross compiling; usually ARM11 or better cores (VFPv2 or better is also supported)
+ <li><code>GOARM=7</code>: use VFPv3; usually Cortex-A cores
+</ul>
+<p>
+If in doubt, leave this variable unset, and adjust it if required
+when you first run the Go executable.
+The <a href="//golang.org/wiki/GoArm">GoARM</a> page
+on the <a href="//golang.org/wiki">Go community wiki</a>
+contains further details regarding Go's ARM support.
+</p>
+
+</ul>
+
+<p>
+Note that <code>$GOARCH</code> and <code>$GOOS</code> identify the
+<em>target</em> environment, not the environment you are running on.
+In effect, you are always cross-compiling.
+By architecture, we mean the kind of binaries
+that the target environment can run:
+an x86-64 system running a 32-bit-only operating system
+must set <code>GOARCH</code> to <code>386</code>,
+not <code>amd64</code>.
+</p>
+
+<p>
+If you choose to override the defaults,
+set these variables in your shell profile (<code>$HOME/.bashrc</code>,
+<code>$HOME/.profile</code>, or equivalent). The settings might look
+something like this:
+</p>
+
+<pre>
+export GOROOT=$HOME/go
+export GOARCH=amd64
+export GOOS=linux
+</pre>
+
+<p>
+although, to reiterate, none of these variables needs to be set to build,
+install, and develop the Go tree.
+</p>
diff --git a/doc/install.html b/doc/install.html
new file mode 100644
index 0000000..9561fdd
--- /dev/null
+++ b/doc/install.html
@@ -0,0 +1,272 @@
+<!--{
+ "Title": "Getting Started",
+ "Path": "/doc/install"
+}-->
+
+<h2 id="download">Download the Go distribution</h2>
+
+<p>
+<a href="https://golang.org/dl/" id="start" class="download" target="_blank">
+<span class="big">Download Go</span>
+<span class="desc">Click here to visit the downloads page</span>
+</a>
+</p>
+
+<p>
+<a href="https://golang.org/dl/" target="_blank">Official binary
+distributions</a> are available for the FreeBSD (release 8 and above), Linux, Mac OS X (Snow Leopard
+and above), and Windows operating systems and the 32-bit (<code>386</code>) and
+64-bit (<code>amd64</code>) x86 processor architectures.
+</p>
+
+<p>
+If a binary distribution is not available for your combination of operating
+system and architecture, try
+<a href="/doc/install/source">installing from source</a> or
+<a href="/doc/install/gccgo">installing gccgo instead of gc</a>.
+</p>
+
+
+<h2 id="requirements">System requirements</h2>
+
+<p>
+The <code>gc</code> compiler supports the following operating systems and
+architectures. Please ensure your system meets these requirements before
+proceeding. If your OS or architecture is not on the list, it's possible that
+<code>gccgo</code> might support your setup; see
+<a href="/doc/install/gccgo">Setting up and using gccgo</a> for details.
+</p>
+
+<table class="codetable" frame="border" summary="requirements">
+<tr>
+<th align="center">Operating system</th>
+<th align="center">Architectures</th>
+<th align="center">Notes</th>
+</tr>
+<tr><td colspan="3"><hr></td></tr>
+<tr><td>FreeBSD 8 or later</td> <td>amd64, 386, arm</td> <td>Debian GNU/kFreeBSD not supported; FreeBSD/ARM needs FreeBSD 10 or later</td></tr>
+<tr><td>Linux 2.6.23 or later with glibc</td> <td>amd64, 386, arm</td> <td>CentOS/RHEL 5.x not supported; no binary distribution for ARM yet</td></tr>
+<tr><td>Mac OS X 10.6 or later</td> <td>amd64, 386</td> <td>use the gcc<sup>†</sup> that comes with Xcode<sup>‡</sup></td></tr>
+<tr><td>Windows XP or later</td> <td>amd64, 386</td> <td>use MinGW gcc<sup>†</sup>. No need for cygwin or msys.</td></tr>
+</table>
+
+<p>
+<sup>†</sup><code>gcc</code> is required only if you plan to use
+<a href="/cmd/cgo">cgo</a>.<br/>
+<sup>‡</sup>You only need to install the command line tools for
+<a href="http://developer.apple.com/Xcode/">Xcode</a>. If you have already
+installed Xcode 4.3+, you can install it from the Components tab of the
+Downloads preferences panel.
+</p>
+
+
+<h2 id="install">Install the Go tools</h2>
+
+<p>
+If you are upgrading from an older version of Go you must
+first <a href="#uninstall">remove the existing version</a>.
+</p>
+
+<h3 id="tarball">Linux, Mac OS X, and FreeBSD tarballs</h3>
+
+<p>
+<a href="https://golang.org/dl/">Download the archive</a>
+and extract it into <code>/usr/local</code>, creating a Go tree in
+<code>/usr/local/go</code>. For example:
+</p>
+
+<pre>
+tar -C /usr/local -xzf go$VERSION.$OS-$ARCH.tar.gz
+</pre>
+
+<p>
+Choose the archive file appropriate for your installation.
+For instance, if you are installing Go version 1.2.1 for 64-bit x86 on Linux,
+the archive you want is called <code>go1.2.1.linux-amd64.tar.gz</code>.
+</p>
+
+<p>
+(Typically these commands must be run as root or through <code>sudo</code>.)
+</p>
+
+<p>
+Add <code>/usr/local/go/bin</code> to the <code>PATH</code> environment
+variable. You can do this by adding this line to your <code>/etc/profile</code>
+(for a system-wide installation) or <code>$HOME/.profile</code>:
+</p>
+
+<pre>
+export PATH=$PATH:/usr/local/go/bin
+</pre>
+
+<h4 id="tarball_non_standard">Installing to a custom location</h4>
+
+<p>
+The Go binary distributions assume they will be installed in
+<code>/usr/local/go</code> (or <code>c:\Go</code> under Windows),
+but it is possible to install the Go tools to a different location.
+In this case you must set the <code>GOROOT</code> environment variable
+to point to the directory in which it was installed.
+</p>
+
+<p>
+For example, if you installed Go to your home directory you should add the
+following commands to <code>$HOME/.profile</code>:
+</p>
+
+<pre>
+export GOROOT=$HOME/go
+export PATH=$PATH:$GOROOT/bin
+</pre>
+
+<p>
+<b>Note</b>: <code>GOROOT</code> must be set only when installing to a custom
+location.
+</p>
+
+<h3 id="osx">Mac OS X package installer</h3>
+
+<p>
+<a href="https://golang.org/dl/">Download the package file</a>,
+open it, and follow the prompts to install the Go tools.
+The package installs the Go distribution to <code>/usr/local/go</code>.
+</p>
+
+<p>
+The package should put the <code>/usr/local/go/bin</code> directory in your
+<code>PATH</code> environment variable. You may need to restart any open
+Terminal sessions for the change to take effect.
+</p>
+
+<h3 id="windows">Windows</h3>
+
+<p>
+The Go project provides two installation options for Windows users
+(besides <a href="/doc/install/source">installing from source</a>):
+a zip archive that requires you to set some environment variables and an
+MSI installer that configures your installation automatically.
+</p>
+
+<h4 id="windows_msi">MSI installer</h4>
+
+<p>
+Open the <a href="https://golang.org/dl/">MSI file</a>
+and follow the prompts to install the Go tools.
+By default, the installer puts the Go distribution in <code>c:\Go</code>.
+</p>
+
+<p>
+The installer should put the <code>c:\Go\bin</code> directory in your
+<code>PATH</code> environment variable. You may need to restart any open
+command prompts for the change to take effect.
+</p>
+
+<h4 id="windows_zip">Zip archive</h4>
+
+<p>
+<a href="https://golang.org/dl/">Download the zip file</a> and extract it into the directory of your choice (we suggest <code>c:\Go</code>).
+</p>
+
+<p>
+If you chose a directory other than <code>c:\Go</code>,
+you must set the <code>GOROOT</code> environment variable to your chosen path.
+</p>
+
+<p>
+Add the <code>bin</code> subdirectory of your Go root (for example, <code>c:\Go\bin</code>) to your <code>PATH</code> environment variable.
+</p>
+
+<h4 id="windows_env">Setting environment variables under Windows</h4>
+
+<p>
+Under Windows, you may set environment variables through the "Environment
+Variables" button on the "Advanced" tab of the "System" control panel. Some
+versions of Windows provide this control panel through the "Advanced System
+Settings" option inside the "System" control panel.
+</p>
+
+
+<h2 id="testing">Test your installation</h2>
+
+<p>
+Check that Go is installed correctly by building a simple program, as follows.
+</p>
+
+<p>
+Create a file named <code>hello.go</code> and put the following program in it:
+</p>
+
+<pre>
+package main
+
+import "fmt"
+
+func main() {
+ fmt.Printf("hello, world\n")
+}
+</pre>
+
+<p>
+Then run it with the <code>go</code> tool:
+</p>
+
+<pre>
+$ go run hello.go
+hello, world
+</pre>
+
+<p>
+If you see the "hello, world" message then your Go installation is working.
+</p>
+
+
+<h2 id="gopath">Set up your work environment</h2>
+
+<p>
+You're almost done.
+You just need to set up your environment.
+</p>
+
+<p>
+Read the <a href="/doc/code.html">How to Write Go Code</a> document,
+which provides <b>essential setup instructions</b> for using the Go tools.
+</p>
+
+
+<h2 id="uninstall">Uninstalling Go</h2>
+
+<p>
+To remove an existing Go installation from your system delete the
+<code>go</code> directory. This is usually <code>/usr/local/go</code>
+under Linux, Mac OS X, and FreeBSD or <code>c:\Go</code>
+under Windows.
+</p>
+
+<p>
+You should also remove the Go <code>bin</code> directory from your
+<code>PATH</code> environment variable.
+Under Linux and FreeBSD you should edit <code>/etc/profile</code> or
+<code>$HOME/.profile</code>.
+If you installed Go with the <a href="#osx">Mac OS X package</a> then you
+should remove the <code>/etc/paths.d/go</code> file.
+Windows users should read the section about <a href="#windows_env">setting
+environment variables under Windows</a>.
+</p>
+
+
+<h2 id="help">Getting help</h2>
+
+<p>
+For real-time help, ask the helpful gophers in <code>#go-nuts</code> on the
+<a href="http://freenode.net/">Freenode</a> IRC server.
+</p>
+
+<p>
+The official mailing list for discussion of the Go language is
+<a href="//groups.google.com/group/golang-nuts">Go Nuts</a>.
+</p>
+
+<p>
+Report bugs using the
+<a href="//golang.org/issue">Go issue tracker</a>.
+</p>
diff --git a/doc/logo-153x55.png b/doc/logo-153x55.png
new file mode 100644
index 0000000..8ec22aa
--- /dev/null
+++ b/doc/logo-153x55.png
Binary files differ
diff --git a/doc/play/fib.go b/doc/play/fib.go
new file mode 100644
index 0000000..19e4721
--- /dev/null
+++ b/doc/play/fib.go
@@ -0,0 +1,19 @@
+package main
+
+import "fmt"
+
+// fib returns a function that returns
+// successive Fibonacci numbers.
+func fib() func() int {
+ a, b := 0, 1
+ return func() int {
+ a, b = b, a+b
+ return a
+ }
+}
+
+func main() {
+ f := fib()
+ // Function calls are evaluated left-to-right.
+ fmt.Println(f(), f(), f(), f(), f())
+}
diff --git a/doc/play/hello.go b/doc/play/hello.go
new file mode 100644
index 0000000..078ddff
--- /dev/null
+++ b/doc/play/hello.go
@@ -0,0 +1,7 @@
+package main
+
+import "fmt"
+
+func main() {
+ fmt.Println("Hello, 世界")
+}
diff --git a/doc/play/life.go b/doc/play/life.go
new file mode 100644
index 0000000..51afb61
--- /dev/null
+++ b/doc/play/life.go
@@ -0,0 +1,113 @@
+// An implementation of Conway's Game of Life.
+package main
+
+import (
+ "bytes"
+ "fmt"
+ "math/rand"
+ "time"
+)
+
+// Field represents a two-dimensional field of cells.
+type Field struct {
+ s [][]bool
+ w, h int
+}
+
+// NewField returns an empty field of the specified width and height.
+func NewField(w, h int) *Field {
+ s := make([][]bool, h)
+ for i := range s {
+ s[i] = make([]bool, w)
+ }
+ return &Field{s: s, w: w, h: h}
+}
+
+// Set sets the state of the specified cell to the given value.
+func (f *Field) Set(x, y int, b bool) {
+ f.s[y][x] = b
+}
+
+// Alive reports whether the specified cell is alive.
+// If the x or y coordinates are outside the field boundaries they are wrapped
+// toroidally. For instance, an x value of -1 is treated as width-1.
+func (f *Field) Alive(x, y int) bool {
+ x += f.w
+ x %= f.w
+ y += f.h
+ y %= f.h
+ return f.s[y][x]
+}
+
+// Next returns the state of the specified cell at the next time step.
+func (f *Field) Next(x, y int) bool {
+ // Count the adjacent cells that are alive.
+ alive := 0
+ for i := -1; i <= 1; i++ {
+ for j := -1; j <= 1; j++ {
+ if (j != 0 || i != 0) && f.Alive(x+i, y+j) {
+ alive++
+ }
+ }
+ }
+ // Return next state according to the game rules:
+ // exactly 3 neighbors: on,
+ // exactly 2 neighbors: maintain current state,
+ // otherwise: off.
+ return alive == 3 || alive == 2 && f.Alive(x, y)
+}
+
+// Life stores the state of a round of Conway's Game of Life.
+type Life struct {
+ a, b *Field
+ w, h int
+}
+
+// NewLife returns a new Life game state with a random initial state.
+func NewLife(w, h int) *Life {
+ a := NewField(w, h)
+ for i := 0; i < (w * h / 4); i++ {
+ a.Set(rand.Intn(w), rand.Intn(h), true)
+ }
+ return &Life{
+ a: a, b: NewField(w, h),
+ w: w, h: h,
+ }
+}
+
+// Step advances the game by one instant, recomputing and updating all cells.
+func (l *Life) Step() {
+ // Update the state of the next field (b) from the current field (a).
+ for y := 0; y < l.h; y++ {
+ for x := 0; x < l.w; x++ {
+ l.b.Set(x, y, l.a.Next(x, y))
+ }
+ }
+ // Swap fields a and b.
+ l.a, l.b = l.b, l.a
+}
+
+// String returns the game board as a string.
+func (l *Life) String() string {
+ var buf bytes.Buffer
+ for y := 0; y < l.h; y++ {
+ for x := 0; x < l.w; x++ {
+ b := byte(' ')
+ if l.a.Alive(x, y) {
+ b = '*'
+ }
+ buf.WriteByte(b)
+ }
+ buf.WriteByte('\n')
+ }
+ return buf.String()
+}
+
+func main() {
+ l := NewLife(40, 15)
+ for i := 0; i < 300; i++ {
+ l.Step()
+ fmt.Print("\x0c", l) // Clear screen and print field.
+ time.Sleep(time.Second / 30)
+ }
+}
diff --git a/doc/play/peano.go b/doc/play/peano.go
new file mode 100644
index 0000000..c1ee5ad
--- /dev/null
+++ b/doc/play/peano.go
@@ -0,0 +1,88 @@
+// Peano integers are represented by a linked
+// list whose nodes contain no data
+// (the nodes are the data).
+// http://en.wikipedia.org/wiki/Peano_axioms
+
+// This program demonstrates the power of Go's
+// segmented stacks when doing massively
+// recursive computations.
+
+package main
+
+import "fmt"
+
+// Number is a pointer to a Number
+type Number *Number
+
+// The arithmetic value of a Number is the
+// count of the nodes comprising the list.
+// (See the count function below.)
+
+// -------------------------------------
+// Peano primitives
+
+func zero() *Number {
+ return nil
+}
+
+func isZero(x *Number) bool {
+ return x == nil
+}
+
+func add1(x *Number) *Number {
+ e := new(Number)
+ *e = x
+ return e
+}
+
+func sub1(x *Number) *Number {
+ return *x
+}
+
+func add(x, y *Number) *Number {
+ if isZero(y) {
+ return x
+ }
+ return add(add1(x), sub1(y))
+}
+
+func mul(x, y *Number) *Number {
+ if isZero(x) || isZero(y) {
+ return zero()
+ }
+ return add(mul(x, sub1(y)), x)
+}
+
+func fact(n *Number) *Number {
+ if isZero(n) {
+ return add1(zero())
+ }
+ return mul(fact(sub1(n)), n)
+}
+
+// -------------------------------------
+// Helpers to generate/count Peano integers
+
+func gen(n int) *Number {
+ if n > 0 {
+ return add1(gen(n - 1))
+ }
+ return zero()
+}
+
+func count(x *Number) int {
+ if isZero(x) {
+ return 0
+ }
+ return count(sub1(x)) + 1
+}
+
+// -------------------------------------
+// Print i! for i in [0,9]
+
+func main() {
+ for i := 0; i <= 9; i++ {
+ f := count(fact(gen(i)))
+ fmt.Println(i, "! =", f)
+ }
+}
diff --git a/doc/play/pi.go b/doc/play/pi.go
new file mode 100644
index 0000000..f2f5dca
--- /dev/null
+++ b/doc/play/pi.go
@@ -0,0 +1,34 @@
+// Concurrent computation of pi.
+// See http://goo.gl/ZuTZM.
+//
+// This demonstrates Go's ability to handle
+// large numbers of concurrent processes.
+// It is an unreasonable way to calculate pi.
+package main
+
+import (
+ "fmt"
+ "math"
+)
+
+func main() {
+ fmt.Println(pi(5000))
+}
+
+// pi launches n goroutines to compute an
+// approximation of pi.
+func pi(n int) float64 {
+ ch := make(chan float64)
+ for k := 0; k <= n; k++ {
+ go term(ch, float64(k))
+ }
+ f := 0.0
+ for k := 0; k <= n; k++ {
+ f += <-ch
+ }
+ return f
+}
+
+func term(ch chan float64, k float64) {
+ ch <- 4 * math.Pow(-1, k) / (2*k + 1)
+}
diff --git a/doc/play/sieve.go b/doc/play/sieve.go
new file mode 100644
index 0000000..5190934
--- /dev/null
+++ b/doc/play/sieve.go
@@ -0,0 +1,36 @@
+// A concurrent prime sieve
+
+package main
+
+import "fmt"
+
+// Send the sequence 2, 3, 4, ... to channel 'ch'.
+func Generate(ch chan<- int) {
+ for i := 2; ; i++ {
+ ch <- i // Send 'i' to channel 'ch'.
+ }
+}
+
+// Copy the values from channel 'in' to channel 'out',
+// removing those divisible by 'prime'.
+func Filter(in <-chan int, out chan<- int, prime int) {
+ for {
+ i := <-in // Receive value from 'in'.
+ if i%prime != 0 {
+ out <- i // Send 'i' to 'out'.
+ }
+ }
+}
+
+// The prime sieve: Daisy-chain Filter processes.
+func main() {
+ ch := make(chan int) // Create a new channel.
+ go Generate(ch) // Launch Generate goroutine.
+ for i := 0; i < 10; i++ {
+ prime := <-ch
+ fmt.Println(prime)
+ ch1 := make(chan int)
+ go Filter(ch, ch1, prime)
+ ch = ch1
+ }
+}
diff --git a/doc/play/solitaire.go b/doc/play/solitaire.go
new file mode 100644
index 0000000..15022aa
--- /dev/null
+++ b/doc/play/solitaire.go
@@ -0,0 +1,117 @@
+// This program solves the (English) peg
+// solitaire board game.
+// http://en.wikipedia.org/wiki/Peg_solitaire
+
+package main
+
+import "fmt"
+
+const N = 11 + 1 // length of a row (+1 for \n)
+
+// The board must be surrounded by 2 illegal
+// fields in each direction so that move()
+// doesn't need to check the board boundaries.
+// Periods represent illegal fields,
+// ● are pegs, and ○ are holes.
+
+var board = []rune(
+ `...........
+...........
+....●●●....
+....●●●....
+..●●●●●●●..
+..●●●○●●●..
+..●●●●●●●..
+....●●●....
+....●●●....
+...........
+...........
+`)
+
+// center is the position of the center hole if
+// there is a single one; otherwise it is -1.
+var center int
+
+func init() {
+ n := 0
+ for pos, field := range board {
+ if field == '○' {
+ center = pos
+ n++
+ }
+ }
+ if n != 1 {
+ center = -1 // no single hole
+ }
+}
+
+var moves int // number of times move is called
+
+// move tests if there is a peg at position pos that
+// can jump over another peg in direction dir. If the
+// move is valid, it is executed and move returns true.
+// Otherwise, move returns false.
+func move(pos, dir int) bool {
+ moves++
+ if board[pos] == '●' && board[pos+dir] == '●' && board[pos+2*dir] == '○' {
+ board[pos] = '○'
+ board[pos+dir] = '○'
+ board[pos+2*dir] = '●'
+ return true
+ }
+ return false
+}
+
+// unmove reverts a previously executed valid move.
+func unmove(pos, dir int) {
+ board[pos] = '●'
+ board[pos+dir] = '●'
+ board[pos+2*dir] = '○'
+}
+
+// solve tries to find a sequence of moves such that
+// there is only one peg left at the end; if center is
+// >= 0, that last peg must be in the center position.
+// If a solution is found, solve prints the board after
+// each move in a backward fashion (i.e., the last
+// board position is printed first, all the way back to
+// the starting board position).
+func solve() bool {
+ var last, n int
+ for pos, field := range board {
+ // try each board position
+ if field == '●' {
+ // found a peg
+ for _, dir := range [...]int{-1, -N, +1, +N} {
+ // try each direction
+ if move(pos, dir) {
+ // a valid move was found and executed,
+ // see if this new board has a solution
+ if solve() {
+ unmove(pos, dir)
+ fmt.Println(string(board))
+ return true
+ }
+ unmove(pos, dir)
+ }
+ }
+ last = pos
+ n++
+ }
+ }
+ // tried each possible move
+ if n == 1 && (center < 0 || last == center) {
+ // there's only one peg left
+ fmt.Println(string(board))
+ return true
+ }
+ // no solution found for this board
+ return false
+}
+
+func main() {
+ if !solve() {
+ fmt.Println("no solution found")
+ }
+ fmt.Println(moves, "moves tried")
+}
diff --git a/doc/play/tree.go b/doc/play/tree.go
new file mode 100644
index 0000000..3790e6c
--- /dev/null
+++ b/doc/play/tree.go
@@ -0,0 +1,100 @@
+// Go's concurrency primitives make it easy to
+// express concurrent concepts, such as
+// this binary tree comparison.
+//
+// Trees may be of different shapes,
+// but have the same contents. For example:
+//
+// 4 6
+// 2 6 4 7
+// 1 3 5 7 2 5
+// 1 3
+//
+// This program compares a pair of trees by
+// walking each in its own goroutine,
+// sending their contents through a channel
+// to a third goroutine that compares them.
+
+package main
+
+import (
+ "fmt"
+ "math/rand"
+)
+
+// A Tree is a binary tree with integer values.
+type Tree struct {
+ Left *Tree
+ Value int
+ Right *Tree
+}
+
+// Walk traverses a tree depth-first,
+// sending each Value on a channel.
+func Walk(t *Tree, ch chan int) {
+ if t == nil {
+ return
+ }
+ Walk(t.Left, ch)
+ ch <- t.Value
+ Walk(t.Right, ch)
+}
+
+// Walker launches Walk in a new goroutine,
+// and returns a read-only channel of values.
+func Walker(t *Tree) <-chan int {
+ ch := make(chan int)
+ go func() {
+ Walk(t, ch)
+ close(ch)
+ }()
+ return ch
+}
+
+// Compare reads values from two Walkers
+// that run simultaneously, and returns true
+// if t1 and t2 have the same contents.
+func Compare(t1, t2 *Tree) bool {
+ c1, c2 := Walker(t1), Walker(t2)
+ for {
+ v1, ok1 := <-c1
+ v2, ok2 := <-c2
+ if !ok1 || !ok2 {
+ return ok1 == ok2
+ }
+ if v1 != v2 {
+ break
+ }
+ }
+ return false
+}
+
+// New returns a new, random binary tree
+// holding the values 1k, 2k, ..., nk.
+func New(n, k int) *Tree {
+ var t *Tree
+ for _, v := range rand.Perm(n) {
+ t = insert(t, (1+v)*k)
+ }
+ return t
+}
+
+func insert(t *Tree, v int) *Tree {
+ if t == nil {
+ return &Tree{nil, v, nil}
+ }
+ if v < t.Value {
+ t.Left = insert(t.Left, v)
+ return t
+ }
+ t.Right = insert(t.Right, v)
+ return t
+}
+
+func main() {
+ t1 := New(100, 1)
+ fmt.Println(Compare(t1, New(100, 1)), "Same Contents")
+ fmt.Println(Compare(t1, New(99, 1)), "Differing Sizes")
+ fmt.Println(Compare(t1, New(100, 2)), "Differing Values")
+ fmt.Println(Compare(t1, New(101, 2)), "Dissimilar")
+}
diff --git a/doc/progs/cgo1.go b/doc/progs/cgo1.go
new file mode 100644
index 0000000..805fe3c
--- /dev/null
+++ b/doc/progs/cgo1.go
@@ -0,0 +1,23 @@
+// skip
+
+// Copyright 2012 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+package rand
+
+/*
+#include <stdlib.h>
+*/
+import "C"
+
+// STOP OMIT
+func Random() int {
+ return int(C.rand())
+}
+
+// STOP OMIT
+func Seed(i int) {
+ C.srand(C.uint(i))
+}
+
+// END OMIT
diff --git a/doc/progs/cgo2.go b/doc/progs/cgo2.go
new file mode 100644
index 0000000..b9e9f7d
--- /dev/null
+++ b/doc/progs/cgo2.go
@@ -0,0 +1,23 @@
+// skip
+
+// Copyright 2012 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+package rand2
+
+/*
+#include <stdlib.h>
+*/
+import "C"
+
+func Random() int {
+ var r C.int = C.rand()
+ return int(r)
+}
+
+// STOP OMIT
+func Seed(i int) {
+ C.srand(C.uint(i))
+}
+
+// END OMIT
diff --git a/doc/progs/cgo3.go b/doc/progs/cgo3.go
new file mode 100644
index 0000000..c4f4791
--- /dev/null
+++ b/doc/progs/cgo3.go
@@ -0,0 +1,19 @@
+// skip
+
+// Copyright 2012 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+package print
+
+// #include <stdio.h>
+// #include <stdlib.h>
+import "C"
+import "unsafe"
+
+func Print(s string) {
+ cs := C.CString(s)
+ C.fputs(cs, (*C.FILE)(C.stdout))
+ C.free(unsafe.Pointer(cs))
+}
+
+// END OMIT
diff --git a/doc/progs/cgo4.go b/doc/progs/cgo4.go
new file mode 100644
index 0000000..30b8935
--- /dev/null
+++ b/doc/progs/cgo4.go
@@ -0,0 +1,19 @@
+// skip
+
+// Copyright 2012 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+package print
+
+// #include <stdio.h>
+// #include <stdlib.h>
+import "C"
+import "unsafe"
+
+func Print(s string) {
+ cs := C.CString(s)
+ defer C.free(unsafe.Pointer(cs))
+ C.fputs(cs, (*C.FILE)(C.stdout))
+}
+
+// END OMIT
diff --git a/doc/progs/defer.go b/doc/progs/defer.go
new file mode 100644
index 0000000..006a474
--- /dev/null
+++ b/doc/progs/defer.go
@@ -0,0 +1,66 @@
+// cmpout
+
+// Copyright 2011 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// This file contains the code snippets included in "Defer, Panic, and Recover."
+
+package main
+
+import (
+ "fmt"
+ "io"
+ "os"
+)
+
+func a() {
+ i := 0
+ defer fmt.Println(i)
+ i++
+ return
+}
+
+// STOP OMIT
+
+func b() {
+ for i := 0; i < 4; i++ {
+ defer fmt.Print(i)
+ }
+}
+
+// STOP OMIT
+
+func c() (i int) {
+ defer func() { i++ }()
+ return 1
+}
+
+// STOP OMIT
+
+// Initial version.
+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
+}
+
+// STOP OMIT
+
+func main() {
+ a()
+ b()
+ fmt.Println()
+ fmt.Println(c())
+}
diff --git a/doc/progs/defer.out b/doc/progs/defer.out
new file mode 100644
index 0000000..0cdf53a
--- /dev/null
+++ b/doc/progs/defer.out
@@ -0,0 +1,3 @@
+0
+3210
+2
diff --git a/doc/progs/defer2.go b/doc/progs/defer2.go
new file mode 100644
index 0000000..ff7eaf9
--- /dev/null
+++ b/doc/progs/defer2.go
@@ -0,0 +1,60 @@
+// cmpout
+
+// Copyright 2011 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// This file contains the code snippets included in "Defer, Panic, and Recover."
+
+package main
+
+import "fmt"
+import "io" // OMIT
+import "os" // OMIT
+
+func main() {
+ f()
+ fmt.Println("Returned normally from f.")
+}
+
+func f() {
+ defer func() {
+ if r := recover(); r != nil {
+ fmt.Println("Recovered in f", r)
+ }
+ }()
+ fmt.Println("Calling g.")
+ g(0)
+ fmt.Println("Returned normally from g.")
+}
+
+func g(i int) {
+ if i > 3 {
+ fmt.Println("Panicking!")
+ panic(fmt.Sprintf("%v", i))
+ }
+ defer fmt.Println("Defer in g", i)
+ fmt.Println("Printing in g", i)
+ g(i + 1)
+}
+
+// STOP OMIT
+
+// Revised version.
+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)
+}
+
+// STOP OMIT
diff --git a/doc/progs/defer2.out b/doc/progs/defer2.out
new file mode 100644
index 0000000..6110685
--- /dev/null
+++ b/doc/progs/defer2.out
@@ -0,0 +1,12 @@
+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.
diff --git a/doc/progs/eff_bytesize.go b/doc/progs/eff_bytesize.go
new file mode 100644
index 0000000..a0c3d50
--- /dev/null
+++ b/doc/progs/eff_bytesize.go
@@ -0,0 +1,49 @@
+// cmpout
+
+// Copyright 2009 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import "fmt"
+
+type ByteSize float64
+
+const (
+ _ = iota // ignore first value by assigning to blank identifier
+ KB ByteSize = 1 << (10 * iota)
+ MB
+ GB
+ TB
+ PB
+ EB
+ ZB
+ YB
+)
+
+func (b ByteSize) String() string {
+ switch {
+ case b >= YB:
+ return fmt.Sprintf("%.2fYB", b/YB)
+ case b >= ZB:
+ return fmt.Sprintf("%.2fZB", b/ZB)
+ case b >= EB:
+ return fmt.Sprintf("%.2fEB", b/EB)
+ case b >= PB:
+ return fmt.Sprintf("%.2fPB", b/PB)
+ case b >= TB:
+ return fmt.Sprintf("%.2fTB", b/TB)
+ case b >= GB:
+ return fmt.Sprintf("%.2fGB", b/GB)
+ case b >= MB:
+ return fmt.Sprintf("%.2fMB", b/MB)
+ case b >= KB:
+ return fmt.Sprintf("%.2fKB", b/KB)
+ }
+ return fmt.Sprintf("%.2fB", b)
+}
+
+func main() {
+ fmt.Println(YB, ByteSize(1e13))
+}
diff --git a/doc/progs/eff_bytesize.out b/doc/progs/eff_bytesize.out
new file mode 100644
index 0000000..df763f3
--- /dev/null
+++ b/doc/progs/eff_bytesize.out
@@ -0,0 +1 @@
+1.00YB 9.09TB
diff --git a/doc/progs/eff_qr.go b/doc/progs/eff_qr.go
new file mode 100644
index 0000000..861131d
--- /dev/null
+++ b/doc/progs/eff_qr.go
@@ -0,0 +1,52 @@
+// compile
+
+// Copyright 2009 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "flag"
+ "html/template"
+ "log"
+ "net/http"
+)
+
+var addr = flag.String("addr", ":1718", "http service address") // Q=17, R=18
+
+var templ = template.Must(template.New("qr").Parse(templateStr))
+
+func main() {
+ flag.Parse()
+ http.Handle("/", http.HandlerFunc(QR))
+ err := http.ListenAndServe(*addr, nil)
+ if err != nil {
+ log.Fatal("ListenAndServe:", err)
+ }
+}
+
+func QR(w http.ResponseWriter, req *http.Request) {
+ templ.Execute(w, req.FormValue("s"))
+}
+
+const templateStr = `
+<html>
+<head>
+<title>QR Link Generator</title>
+</head>
+<body>
+{{if .}}
+<img src="http://chart.apis.google.com/chart?chs=300x300&cht=qr&choe=UTF-8&chl={{.}}" />
+<br>
+{{.}}
+<br>
+<br>
+{{end}}
+<form action="/" name=f method="GET"><input maxLength=1024 size=70
+name=s value="" title="Text to QR Encode"><input type=submit
+value="Show QR" name=qr>
+</form>
+</body>
+</html>
+`
diff --git a/doc/progs/eff_sequence.go b/doc/progs/eff_sequence.go
new file mode 100644
index 0000000..c9b18ba
--- /dev/null
+++ b/doc/progs/eff_sequence.go
@@ -0,0 +1,44 @@
+// cmpout
+
+// Copyright 2009 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "fmt"
+ "sort"
+)
+
+func main() {
+ seq := Sequence{6, 2, -1, 44, 16}
+ sort.Sort(seq)
+ fmt.Println(seq)
+}
+
+type Sequence []int
+
+// Methods required by sort.Interface.
+func (s Sequence) Len() int {
+ return len(s)
+}
+func (s Sequence) Less(i, j int) bool {
+ return s[i] < s[j]
+}
+func (s Sequence) Swap(i, j int) {
+ s[i], s[j] = s[j], s[i]
+}
+
+// Method for printing - sorts the elements before printing.
+func (s Sequence) String() string {
+ sort.Sort(s)
+ str := "["
+ for i, elem := range s {
+ if i > 0 {
+ str += " "
+ }
+ str += fmt.Sprint(elem)
+ }
+ return str + "]"
+}
diff --git a/doc/progs/eff_sequence.out b/doc/progs/eff_sequence.out
new file mode 100644
index 0000000..fd01a7d
--- /dev/null
+++ b/doc/progs/eff_sequence.out
@@ -0,0 +1 @@
+[-1 2 6 16 44]
diff --git a/doc/progs/eff_unused1.go b/doc/progs/eff_unused1.go
new file mode 100644
index 0000000..f990a19
--- /dev/null
+++ b/doc/progs/eff_unused1.go
@@ -0,0 +1,18 @@
+// skip
+
+package main
+
+import (
+ "fmt"
+ "io"
+ "log"
+ "os"
+)
+
+func main() {
+ fd, err := os.Open("test.go")
+ if err != nil {
+ log.Fatal(err)
+ }
+ // TODO: use fd.
+}
diff --git a/doc/progs/eff_unused2.go b/doc/progs/eff_unused2.go
new file mode 100644
index 0000000..3e6e041
--- /dev/null
+++ b/doc/progs/eff_unused2.go
@@ -0,0 +1,22 @@
+// compile
+
+package main
+
+import (
+ "fmt"
+ "io"
+ "log"
+ "os"
+)
+
+var _ = fmt.Printf // For debugging; delete when done.
+var _ io.Reader // For debugging; delete when done.
+
+func main() {
+ fd, err := os.Open("test.go")
+ if err != nil {
+ log.Fatal(err)
+ }
+ // TODO: use fd.
+ _ = fd
+}
diff --git a/doc/progs/error.go b/doc/progs/error.go
new file mode 100644
index 0000000..57854c5
--- /dev/null
+++ b/doc/progs/error.go
@@ -0,0 +1,129 @@
+// compile
+
+// Copyright 2011 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// This file contains the code snippets included in "Error Handling and Go."
+
+package main
+
+import (
+ "encoding/json"
+ "errors"
+ "fmt"
+ "log"
+ "net"
+ "os"
+ "time"
+)
+
+type File struct{}
+
+func Open(name string) (file *File, err error) {
+ // OMIT
+ panic(1)
+ // STOP OMIT
+}
+
+func openFile() { // OMIT
+ f, err := os.Open("filename.ext")
+ if err != nil {
+ log.Fatal(err)
+ }
+ // do something with the open *File f
+ // STOP OMIT
+ _ = f
+}
+
+// errorString is a trivial implementation of error.
+type errorString struct {
+ s string
+}
+
+func (e *errorString) Error() string {
+ return e.s
+}
+
+// STOP OMIT
+
+// New returns an error that formats as the given text.
+func New(text string) error {
+ return &errorString{text}
+}
+
+// STOP OMIT
+
+func Sqrt(f float64) (float64, error) {
+ if f < 0 {
+ return 0, errors.New("math: square root of negative number")
+ }
+ // implementation
+ return 0, nil // OMIT
+}
+
+// STOP OMIT
+
+func printErr() (int, error) { // OMIT
+ f, err := Sqrt(-1)
+ if err != nil {
+ fmt.Println(err)
+ }
+ // STOP OMIT
+ // fmtError OMIT
+ if f < 0 {
+ return 0, fmt.Errorf("math: square root of negative number %g", f)
+ }
+ // STOP OMIT
+ return 0, nil
+}
+
+type NegativeSqrtError float64
+
+func (f NegativeSqrtError) Error() string {
+ return fmt.Sprintf("math: square root of negative number %g", float64(f))
+}
+
+// STOP OMIT
+
+type SyntaxError struct {
+ msg string // description of error
+ Offset int64 // error occurred after reading Offset bytes
+}
+
+func (e *SyntaxError) Error() string { return e.msg }
+
+// STOP OMIT
+
+func decodeError(dec *json.Decoder, val struct{}) error { // OMIT
+ var f os.FileInfo // OMIT
+ if err := dec.Decode(&val); err != nil {
+ if serr, ok := err.(*json.SyntaxError); ok {
+ line, col := findLine(f, serr.Offset)
+ return fmt.Errorf("%s:%d:%d: %v", f.Name(), line, col, err)
+ }
+ return err
+ }
+ // STOP OMIT
+ return nil
+}
+
+func findLine(os.FileInfo, int64) (int, int) {
+ // place holder; no need to run
+ return 0, 0
+}
+
+func netError(err error) { // OMIT
+ for { // OMIT
+ if nerr, ok := err.(net.Error); ok && nerr.Temporary() {
+ time.Sleep(1e9)
+ continue
+ }
+ if err != nil {
+ log.Fatal(err)
+ }
+ // STOP OMIT
+ }
+}
+
+func main() {}
diff --git a/doc/progs/error2.go b/doc/progs/error2.go
new file mode 100644
index 0000000..aad1dc8
--- /dev/null
+++ b/doc/progs/error2.go
@@ -0,0 +1,56 @@
+// compile
+
+// Copyright 2011 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// This file contains the code snippets included in "Error Handling and Go."
+
+package main
+
+import (
+ "net/http"
+ "text/template"
+)
+
+func init() {
+ http.HandleFunc("/view", viewRecord)
+}
+
+func viewRecord(w http.ResponseWriter, r *http.Request) {
+ c := appengine.NewContext(r)
+ key := datastore.NewKey(c, "Record", r.FormValue("id"), 0, nil)
+ record := new(Record)
+ if err := datastore.Get(c, key, record); err != nil {
+ http.Error(w, err.Error(), 500)
+ return
+ }
+ if err := viewTemplate.Execute(w, record); err != nil {
+ http.Error(w, err.Error(), 500)
+ }
+}
+
+// STOP OMIT
+
+type ap struct{}
+
+func (ap) NewContext(*http.Request) *ctx { return nil }
+
+type ctx struct{}
+
+func (*ctx) Errorf(string, ...interface{}) {}
+
+var appengine ap
+
+type ds struct{}
+
+func (ds) NewKey(*ctx, string, string, int, *int) string { return "" }
+func (ds) Get(*ctx, string, *Record) error { return nil }
+
+var datastore ds
+
+type Record struct{}
+
+var viewTemplate *template.Template
+
+func main() {}
diff --git a/doc/progs/error3.go b/doc/progs/error3.go
new file mode 100644
index 0000000..9f1b300
--- /dev/null
+++ b/doc/progs/error3.go
@@ -0,0 +1,65 @@
+// compile
+
+// Copyright 2011 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// This file contains the code snippets included in "Error Handling and Go."
+
+package main
+
+import (
+ "net/http"
+ "text/template"
+)
+
+func init() {
+ http.Handle("/view", appHandler(viewRecord))
+}
+
+// STOP OMIT
+
+func viewRecord(w http.ResponseWriter, r *http.Request) error {
+ c := appengine.NewContext(r)
+ key := datastore.NewKey(c, "Record", r.FormValue("id"), 0, nil)
+ record := new(Record)
+ if err := datastore.Get(c, key, record); err != nil {
+ return err
+ }
+ return viewTemplate.Execute(w, record)
+}
+
+// STOP OMIT
+
+type appHandler func(http.ResponseWriter, *http.Request) error
+
+func (fn appHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+ if err := fn(w, r); err != nil {
+ http.Error(w, err.Error(), 500)
+ }
+}
+
+// STOP OMIT
+
+type ap struct{}
+
+func (ap) NewContext(*http.Request) *ctx { return nil }
+
+type ctx struct{}
+
+func (*ctx) Errorf(string, ...interface{}) {}
+
+var appengine ap
+
+type ds struct{}
+
+func (ds) NewKey(*ctx, string, string, int, *int) string { return "" }
+func (ds) Get(*ctx, string, *Record) error { return nil }
+
+var datastore ds
+
+type Record struct{}
+
+var viewTemplate *template.Template
+
+func main() {}
diff --git a/doc/progs/error4.go b/doc/progs/error4.go
new file mode 100644
index 0000000..d40fc6e
--- /dev/null
+++ b/doc/progs/error4.go
@@ -0,0 +1,76 @@
+// compile
+
+// Copyright 2011 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// This file contains the code snippets included in "Error Handling and Go."
+
+package main
+
+import (
+ "net/http"
+ "text/template"
+)
+
+type appError struct {
+ Error error
+ Message string
+ Code int
+}
+
+// STOP OMIT
+
+type appHandler func(http.ResponseWriter, *http.Request) *appError
+
+func (fn appHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+ if e := fn(w, r); e != nil { // e is *appError, not error.
+ c := appengine.NewContext(r)
+ c.Errorf("%v", e.Error)
+ http.Error(w, e.Message, e.Code)
+ }
+}
+
+// STOP OMIT
+
+func viewRecord(w http.ResponseWriter, r *http.Request) *appError {
+ c := appengine.NewContext(r)
+ key := datastore.NewKey(c, "Record", r.FormValue("id"), 0, nil)
+ record := new(Record)
+ if err := datastore.Get(c, key, record); err != nil {
+ return &appError{err, "Record not found", 404}
+ }
+ if err := viewTemplate.Execute(w, record); err != nil {
+ return &appError{err, "Can't display record", 500}
+ }
+ return nil
+}
+
+// STOP OMIT
+
+func init() {
+ http.Handle("/view", appHandler(viewRecord))
+}
+
+type ap struct{}
+
+func (ap) NewContext(*http.Request) *ctx { return nil }
+
+type ctx struct{}
+
+func (*ctx) Errorf(string, ...interface{}) {}
+
+var appengine ap
+
+type ds struct{}
+
+func (ds) NewKey(*ctx, string, string, int, *int) string { return "" }
+func (ds) Get(*ctx, string, *Record) error { return nil }
+
+var datastore ds
+
+type Record struct{}
+
+var viewTemplate *template.Template
+
+func main() {}
diff --git a/doc/progs/go1.go b/doc/progs/go1.go
new file mode 100644
index 0000000..a4dc64d
--- /dev/null
+++ b/doc/progs/go1.go
@@ -0,0 +1,248 @@
+// compile
+// this file will output a list of filenames in cwd, not suitable for cmpout
+
+// Copyright 2011 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// This file contains examples to embed in the Go 1 release notes document.
+
+package main
+
+import (
+ "errors"
+ "flag"
+ "fmt"
+ "log"
+ "os"
+ "path/filepath"
+ "testing"
+ "time"
+ "unicode"
+)
+
+func main() {
+ flag.Parse()
+ stringAppend()
+ mapDelete()
+ mapIteration()
+ multipleAssignment()
+ structEquality()
+ compositeLiterals()
+ runeType()
+ errorExample()
+ timePackage()
+ walkExample()
+ osIsExist()
+}
+
+var timeout = flag.Duration("timeout", 30*time.Second, "how long to wait for completion")
+
+func init() {
+ // canonicalize the logging
+ log.SetFlags(0)
+}
+
+func mapDelete() {
+ m := map[string]int{"7": 7, "23": 23}
+ k := "7"
+ delete(m, k)
+ if m["7"] != 0 || m["23"] != 23 {
+ log.Fatal("mapDelete:", m)
+ }
+}
+
+func stringAppend() {
+ greeting := []byte{}
+ greeting = append(greeting, []byte("hello ")...)
+ greeting = append(greeting, "world"...)
+ if string(greeting) != "hello world" {
+ log.Fatal("stringAppend: ", string(greeting))
+ }
+}
+
+func mapIteration() {
+ m := map[string]int{"Sunday": 0, "Monday": 1}
+ for name, value := range m {
+ // This loop should not assume Sunday will be visited first.
+ f(name, value)
+ }
+}
+
+func f(string, int) {
+}
+
+func assert(t bool) {
+ if !t {
+ log.Panic("assertion fail")
+ }
+}
+
+func multipleAssignment() {
+ 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)
+
+ assert(i == 1 && sa[0] == 2)
+ assert(j == 1 && sb[0] == 2)
+ assert(sc[0] == 2)
+}
+
+func structEquality() {
+ type Day struct {
+ long string
+ short string
+ }
+ Christmas := Day{"Christmas", "XMas"}
+ Thanksgiving := Day{"Thanksgiving", "Turkey"}
+ holiday := map[Day]bool{
+ Christmas: true,
+ Thanksgiving: true,
+ }
+ fmt.Printf("Christmas is a holiday: %t\n", holiday[Christmas])
+}
+
+func compositeLiterals() {
+ type Date struct {
+ month string
+ day int
+ }
+ // Struct values, fully qualified; always legal.
+ holiday1 := []Date{
+ Date{"Feb", 14},
+ Date{"Nov", 11},
+ Date{"Dec", 25},
+ }
+ // Struct values, type name elided; always legal.
+ holiday2 := []Date{
+ {"Feb", 14},
+ {"Nov", 11},
+ {"Dec", 25},
+ }
+ // Pointers, fully qualified, always legal.
+ holiday3 := []*Date{
+ &Date{"Feb", 14},
+ &Date{"Nov", 11},
+ &Date{"Dec", 25},
+ }
+ // Pointers, type name elided; legal in Go 1.
+ holiday4 := []*Date{
+ {"Feb", 14},
+ {"Nov", 11},
+ {"Dec", 25},
+ }
+ // STOP OMIT
+ _, _, _, _ = holiday1, holiday2, holiday3, holiday4
+}
+
+func runeType() {
+ // STARTRUNE OMIT
+ delta := 'δ' // delta has type rune.
+ var DELTA rune
+ DELTA = unicode.ToUpper(delta)
+ epsilon := unicode.ToLower(DELTA + 1)
+ if epsilon != 'δ'+1 {
+ log.Fatal("inconsistent casing for Greek")
+ }
+ // ENDRUNE OMIT
+}
+
+// START ERROR EXAMPLE OMIT
+type SyntaxError struct {
+ File string
+ Line int
+ Message string
+}
+
+func (se *SyntaxError) Error() string {
+ return fmt.Sprintf("%s:%d: %s", se.File, se.Line, se.Message)
+}
+
+// END ERROR EXAMPLE OMIT
+
+func errorExample() {
+ var ErrSyntax = errors.New("syntax error")
+ _ = ErrSyntax
+ se := &SyntaxError{"file", 7, "error"}
+ got := fmt.Sprint(se)
+ const expect = "file:7: error"
+ if got != expect {
+ log.Fatalf("errorsPackage: expected %q got %q", expect, got)
+ }
+}
+
+// sleepUntil sleeps until the specified time. It returns immediately if it's too late.
+func sleepUntil(wakeup time.Time) {
+ now := time.Now() // A Time.
+ if !wakeup.After(now) {
+ return
+ }
+ delta := wakeup.Sub(now) // A Duration.
+ fmt.Printf("Sleeping for %.3fs\n", delta.Seconds())
+ time.Sleep(delta)
+}
+
+func timePackage() {
+ sleepUntil(time.Now().Add(123 * time.Millisecond))
+}
+
+func walkExample() {
+ // STARTWALK OMIT
+ markFn := func(path string, info os.FileInfo, err error) error {
+ if path == "pictures" { // Will skip walking of directory pictures and its contents.
+ return filepath.SkipDir
+ }
+ if err != nil {
+ return err
+ }
+ log.Println(path)
+ return nil
+ }
+ err := filepath.Walk(".", markFn)
+ if err != nil {
+ log.Fatal(err)
+ }
+ // ENDWALK OMIT
+}
+
+func initializationFunction(c chan int) {
+ c <- 1
+}
+
+var PackageGlobal int
+
+func init() {
+ c := make(chan int)
+ go initializationFunction(c)
+ PackageGlobal = <-c
+}
+
+func BenchmarkSprintf(b *testing.B) {
+ // Verify correctness before running benchmark.
+ b.StopTimer()
+ got := fmt.Sprintf("%x", 23)
+ const expect = "17"
+ if expect != got {
+ b.Fatalf("expected %q; got %q", expect, got)
+ }
+ b.StartTimer()
+ for i := 0; i < b.N; i++ {
+ fmt.Sprintf("%x", 23)
+ }
+}
+
+func osIsExist() {
+ name := "go1.go"
+ f, err := os.OpenFile(name, os.O_RDWR|os.O_CREATE|os.O_EXCL, 0600)
+ if os.IsExist(err) {
+ log.Printf("%s already exists", name)
+ }
+ _ = f
+}
diff --git a/doc/progs/gobs1.go b/doc/progs/gobs1.go
new file mode 100644
index 0000000..d95f765
--- /dev/null
+++ b/doc/progs/gobs1.go
@@ -0,0 +1,24 @@
+// compile
+
+// Copyright 2011 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package gobs1
+
+type T struct{ X, Y, Z int } // Only exported fields are encoded and decoded.
+var t = T{X: 7, Y: 0, Z: 8}
+
+// STOP OMIT
+
+type U struct{ X, Y *int8 } // Note: pointers to int8s
+var u U
+
+// STOP OMIT
+
+type Node struct {
+ Value int
+ Left, Right *Node
+}
+
+// STOP OMIT
diff --git a/doc/progs/gobs2.go b/doc/progs/gobs2.go
new file mode 100644
index 0000000..acd1838
--- /dev/null
+++ b/doc/progs/gobs2.go
@@ -0,0 +1,45 @@
+// compile
+
+// Copyright 2011 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "bytes"
+ "encoding/gob"
+ "fmt"
+ "log"
+)
+
+type P struct {
+ X, Y, Z int
+ Name string
+}
+
+type Q struct {
+ X, Y *int32
+ Name string
+}
+
+func main() {
+ // Initialize the encoder and decoder. Normally enc and dec would be
+ // bound to network connections and the encoder and decoder would
+ // run in different processes.
+ var network bytes.Buffer // Stand-in for a network connection
+ enc := gob.NewEncoder(&network) // Will write to network.
+ dec := gob.NewDecoder(&network) // Will read from network.
+ // Encode (send) the value.
+ err := enc.Encode(P{3, 4, 5, "Pythagoras"})
+ if err != nil {
+ log.Fatal("encode error:", err)
+ }
+ // Decode (receive) the value.
+ var q Q
+ err = dec.Decode(&q)
+ if err != nil {
+ log.Fatal("decode error:", err)
+ }
+ fmt.Printf("%q: {%d,%d}\n", q.Name, *q.X, *q.Y)
+}
diff --git a/doc/progs/image_draw.go b/doc/progs/image_draw.go
new file mode 100644
index 0000000..0a1f7ac
--- /dev/null
+++ b/doc/progs/image_draw.go
@@ -0,0 +1,144 @@
+// compile
+
+// Copyright 2012 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// This file contains the code snippets included in "The Go image/draw package."
+
+package main
+
+import (
+ "image"
+ "image/color"
+ "image/draw"
+)
+
+func main() {
+ Color()
+ Rect()
+ RectAndScroll()
+ ConvAndCircle()
+ Glyph()
+}
+
+func Color() {
+ c := color.RGBA{255, 0, 255, 255}
+ r := image.Rect(0, 0, 640, 480)
+ dst := image.NewRGBA(r)
+
+ // ZERO OMIT
+ // image.ZP is the zero point -- the origin.
+ draw.Draw(dst, r, &image.Uniform{c}, image.ZP, draw.Src)
+ // STOP OMIT
+
+ // BLUE OMIT
+ m := image.NewRGBA(image.Rect(0, 0, 640, 480))
+ blue := color.RGBA{0, 0, 255, 255}
+ draw.Draw(m, m.Bounds(), &image.Uniform{blue}, image.ZP, draw.Src)
+ // STOP OMIT
+
+ // RESET OMIT
+ draw.Draw(m, m.Bounds(), image.Transparent, image.ZP, draw.Src)
+ // STOP OMIT
+}
+
+func Rect() {
+ dst := image.NewRGBA(image.Rect(0, 0, 640, 480))
+ sr := image.Rect(0, 0, 200, 200)
+ src := image.Black
+ dp := image.Point{100, 100}
+
+ // RECT OMIT
+ r := image.Rectangle{dp, dp.Add(sr.Size())}
+ draw.Draw(dst, r, src, sr.Min, draw.Src)
+ // STOP OMIT
+}
+
+func RectAndScroll() {
+ dst := image.NewRGBA(image.Rect(0, 0, 640, 480))
+ sr := image.Rect(0, 0, 200, 200)
+ src := image.Black
+ dp := image.Point{100, 100}
+
+ // RECT2 OMIT
+ r := sr.Sub(sr.Min).Add(dp)
+ draw.Draw(dst, r, src, sr.Min, draw.Src)
+ // STOP OMIT
+
+ m := dst
+
+ // SCROLL OMIT
+ b := m.Bounds()
+ p := image.Pt(0, 20)
+ // Note that even though the second argument is b,
+ // the effective rectangle is smaller due to clipping.
+ draw.Draw(m, b, m, b.Min.Add(p), draw.Src)
+ dirtyRect := b.Intersect(image.Rect(b.Min.X, b.Max.Y-20, b.Max.X, b.Max.Y))
+ // STOP OMIT
+
+ _ = dirtyRect // noop
+}
+
+func ConvAndCircle() {
+ src := image.NewRGBA(image.Rect(0, 0, 640, 480))
+ dst := image.NewRGBA(image.Rect(0, 0, 640, 480))
+
+ // CONV OMIT
+ b := src.Bounds()
+ m := image.NewRGBA(b)
+ draw.Draw(m, b, src, b.Min, draw.Src)
+ // STOP OMIT
+
+ p := image.Point{100, 100}
+ r := 50
+
+ // CIRCLE2 OMIT
+ draw.DrawMask(dst, dst.Bounds(), src, image.ZP, &circle{p, r}, image.ZP, draw.Over)
+ // STOP OMIT
+}
+
+func theGlyphImageForAFont() image.Image {
+ return image.NewRGBA(image.Rect(0, 0, 640, 480))
+}
+
+func theBoundsFor(index int) image.Rectangle {
+ return image.Rect(0, 0, 32, 32)
+}
+
+func Glyph() {
+ p := image.Point{100, 100}
+ dst := image.NewRGBA(image.Rect(0, 0, 640, 480))
+ glyphIndex := 42
+
+ // GLYPH OMIT
+ src := &image.Uniform{color.RGBA{0, 0, 255, 255}}
+ mask := theGlyphImageForAFont()
+ mr := theBoundsFor(glyphIndex)
+ draw.DrawMask(dst, mr.Sub(mr.Min).Add(p), src, image.ZP, mask, mr.Min, draw.Over)
+ // STOP OMIT
+}
+
+//CIRCLESTRUCT OMIT
+type circle struct {
+ p image.Point
+ r int
+}
+
+func (c *circle) ColorModel() color.Model {
+ return color.AlphaModel
+}
+
+func (c *circle) Bounds() image.Rectangle {
+ return image.Rect(c.p.X-c.r, c.p.Y-c.r, c.p.X+c.r, c.p.Y+c.r)
+}
+
+func (c *circle) At(x, y int) color.Color {
+ xx, yy, rr := float64(x-c.p.X)+0.5, float64(y-c.p.Y)+0.5, float64(c.r)
+ if xx*xx+yy*yy < rr*rr {
+ return color.Alpha{255}
+ }
+ return color.Alpha{0}
+}
+
+//STOP OMIT
diff --git a/doc/progs/image_package1.go b/doc/progs/image_package1.go
new file mode 100644
index 0000000..d331834
--- /dev/null
+++ b/doc/progs/image_package1.go
@@ -0,0 +1,17 @@
+// cmpout
+
+// Copyright 2012 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "fmt"
+ "image"
+)
+
+func main() {
+ p := image.Point{2, 1}
+ fmt.Println("X is", p.X, "Y is", p.Y)
+}
diff --git a/doc/progs/image_package1.out b/doc/progs/image_package1.out
new file mode 100644
index 0000000..809b31b
--- /dev/null
+++ b/doc/progs/image_package1.out
@@ -0,0 +1 @@
+X is 2 Y is 1
diff --git a/doc/progs/image_package2.go b/doc/progs/image_package2.go
new file mode 100644
index 0000000..e5b78b4
--- /dev/null
+++ b/doc/progs/image_package2.go
@@ -0,0 +1,18 @@
+// cmpout
+
+// Copyright 2012 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "fmt"
+ "image"
+)
+
+func main() {
+ r := image.Rect(2, 1, 5, 5)
+ // Dx and Dy return a rectangle's width and height.
+ fmt.Println(r.Dx(), r.Dy(), image.Pt(0, 0).In(r)) // prints 3 4 false
+}
diff --git a/doc/progs/image_package2.out b/doc/progs/image_package2.out
new file mode 100644
index 0000000..616d307
--- /dev/null
+++ b/doc/progs/image_package2.out
@@ -0,0 +1 @@
+3 4 false
diff --git a/doc/progs/image_package3.go b/doc/progs/image_package3.go
new file mode 100644
index 0000000..95d72a0
--- /dev/null
+++ b/doc/progs/image_package3.go
@@ -0,0 +1,17 @@
+// cmpout
+
+// Copyright 2012 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "fmt"
+ "image"
+)
+
+func main() {
+ r := image.Rect(2, 1, 5, 5).Add(image.Pt(-4, -2))
+ fmt.Println(r.Dx(), r.Dy(), image.Pt(0, 0).In(r)) // prints 3 4 true
+}
diff --git a/doc/progs/image_package3.out b/doc/progs/image_package3.out
new file mode 100644
index 0000000..3fe35de
--- /dev/null
+++ b/doc/progs/image_package3.out
@@ -0,0 +1 @@
+3 4 true
diff --git a/doc/progs/image_package4.go b/doc/progs/image_package4.go
new file mode 100644
index 0000000..ec0e461
--- /dev/null
+++ b/doc/progs/image_package4.go
@@ -0,0 +1,18 @@
+// cmpout
+
+// Copyright 2012 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "fmt"
+ "image"
+)
+
+func main() {
+ r := image.Rect(0, 0, 4, 3).Intersect(image.Rect(2, 2, 5, 5))
+ // Size returns a rectangle's width and height, as a Point.
+ fmt.Printf("%#v\n", r.Size()) // prints image.Point{X:2, Y:1}
+}
diff --git a/doc/progs/image_package4.out b/doc/progs/image_package4.out
new file mode 100644
index 0000000..cb1b777
--- /dev/null
+++ b/doc/progs/image_package4.out
@@ -0,0 +1 @@
+image.Point{X:2, Y:1}
diff --git a/doc/progs/image_package5.go b/doc/progs/image_package5.go
new file mode 100644
index 0000000..b9e27d6
--- /dev/null
+++ b/doc/progs/image_package5.go
@@ -0,0 +1,19 @@
+// cmpout
+
+// Copyright 2012 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "fmt"
+ "image"
+ "image/color"
+)
+
+func main() {
+ m := image.NewRGBA(image.Rect(0, 0, 640, 480))
+ m.Set(5, 5, color.RGBA{255, 0, 0, 255})
+ fmt.Println(m.At(5, 5))
+}
diff --git a/doc/progs/image_package5.out b/doc/progs/image_package5.out
new file mode 100644
index 0000000..2da80c1
--- /dev/null
+++ b/doc/progs/image_package5.out
@@ -0,0 +1 @@
+{255 0 0 255}
diff --git a/doc/progs/image_package6.go b/doc/progs/image_package6.go
new file mode 100644
index 0000000..5e6eefa
--- /dev/null
+++ b/doc/progs/image_package6.go
@@ -0,0 +1,19 @@
+// cmpout
+
+// Copyright 2012 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "fmt"
+ "image"
+)
+
+func main() {
+ m0 := image.NewRGBA(image.Rect(0, 0, 8, 5))
+ m1 := m0.SubImage(image.Rect(1, 2, 5, 5)).(*image.RGBA)
+ fmt.Println(m0.Bounds().Dx(), m1.Bounds().Dx()) // prints 8, 4
+ fmt.Println(m0.Stride == m1.Stride) // prints true
+}
diff --git a/doc/progs/image_package6.out b/doc/progs/image_package6.out
new file mode 100644
index 0000000..fcd13c0
--- /dev/null
+++ b/doc/progs/image_package6.out
@@ -0,0 +1,2 @@
+8 4
+true
diff --git a/doc/progs/interface.go b/doc/progs/interface.go
new file mode 100644
index 0000000..6972b72
--- /dev/null
+++ b/doc/progs/interface.go
@@ -0,0 +1,64 @@
+// compile
+
+// Copyright 2012 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// This file contains the code snippets included in "The Laws of Reflection."
+
+package main
+
+import (
+ "bufio"
+ "bytes"
+ "io"
+ "os"
+)
+
+type MyInt int
+
+var i int
+var j MyInt
+
+// STOP OMIT
+
+// 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)
+}
+
+// STOP OMIT
+
+func readers() { // OMIT
+ var r io.Reader
+ r = os.Stdin
+ r = bufio.NewReader(r)
+ r = new(bytes.Buffer)
+ // and so on
+ // STOP OMIT
+}
+
+func typeAssertions() (interface{}, error) { // OMIT
+ var r io.Reader
+ tty, err := os.OpenFile("/dev/tty", os.O_RDWR, 0)
+ if err != nil {
+ return nil, err
+ }
+ r = tty
+ // STOP OMIT
+ var w io.Writer
+ w = r.(io.Writer)
+ // STOP OMIT
+ var empty interface{}
+ empty = w
+ // STOP OMIT
+ return empty, err
+}
+
+func main() {
+}
diff --git a/doc/progs/interface2.go b/doc/progs/interface2.go
new file mode 100644
index 0000000..85e7d51
--- /dev/null
+++ b/doc/progs/interface2.go
@@ -0,0 +1,134 @@
+// cmpout
+
+// Copyright 2012 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// This file contains the code snippets included in "The Laws of Reflection."
+
+package main
+
+import (
+ "fmt"
+ "reflect"
+)
+
+func main() {
+ var x float64 = 3.4
+ fmt.Println("type:", reflect.TypeOf(x))
+ // STOP OMIT
+ // TODO(proppy): test output OMIT
+}
+
+// STOP main OMIT
+
+func f1() {
+ // START f1 OMIT
+ var x float64 = 3.4
+ v := reflect.ValueOf(x)
+ fmt.Println("type:", v.Type())
+ fmt.Println("kind is float64:", v.Kind() == reflect.Float64)
+ fmt.Println("value:", v.Float())
+ // STOP OMIT
+}
+
+func f2() {
+ // START f2 OMIT
+ var x uint8 = 'x'
+ v := reflect.ValueOf(x)
+ fmt.Println("type:", v.Type()) // uint8.
+ fmt.Println("kind is uint8: ", v.Kind() == reflect.Uint8) // true.
+ x = uint8(v.Uint()) // v.Uint returns a uint64.
+ // STOP OMIT
+}
+
+func f3() {
+ // START f3 OMIT
+ type MyInt int
+ var x MyInt = 7
+ v := reflect.ValueOf(x)
+ // STOP OMIT
+ // START f3b OMIT
+ y := v.Interface().(float64) // y will have type float64.
+ fmt.Println(y)
+ // STOP OMIT
+ // START f3c OMIT
+ fmt.Println(v.Interface())
+ // STOP OMIT
+ // START f3d OMIT
+ fmt.Printf("value is %7.1e\n", v.Interface())
+ // STOP OMIT
+}
+
+func f4() {
+ // START f4 OMIT
+ var x float64 = 3.4
+ v := reflect.ValueOf(x)
+ v.SetFloat(7.1) // Error: will panic.
+ // STOP OMIT
+}
+
+func f5() {
+ // START f5 OMIT
+ var x float64 = 3.4
+ v := reflect.ValueOf(x)
+ fmt.Println("settability of v:", v.CanSet())
+ // STOP OMIT
+}
+
+func f6() {
+ // START f6 OMIT
+ var x float64 = 3.4
+ v := reflect.ValueOf(x)
+ // STOP OMIT
+ // START f6b OMIT
+ v.SetFloat(7.1)
+ // STOP OMIT
+}
+
+func f7() {
+ // START f7 OMIT
+ var x float64 = 3.4
+ p := reflect.ValueOf(&x) // Note: take the address of x.
+ fmt.Println("type of p:", p.Type())
+ fmt.Println("settability of p:", p.CanSet())
+ // STOP OMIT
+ // START f7b OMIT
+ v := p.Elem()
+ fmt.Println("settability of v:", v.CanSet())
+ // STOP OMIT
+ // START f7c OMIT
+ v.SetFloat(7.1)
+ fmt.Println(v.Interface())
+ fmt.Println(x)
+ // STOP OMIT
+}
+
+func f8() {
+ // START f8 OMIT
+ type T struct {
+ A int
+ B string
+ }
+ t := T{23, "skidoo"}
+ s := reflect.ValueOf(&t).Elem()
+ typeOfT := s.Type()
+ for i := 0; i < s.NumField(); i++ {
+ f := s.Field(i)
+ fmt.Printf("%d: %s %s = %v\n", i,
+ typeOfT.Field(i).Name, f.Type(), f.Interface())
+ }
+ // STOP OMIT
+ // START f8b OMIT
+ s.Field(0).SetInt(77)
+ s.Field(1).SetString("Sunset Strip")
+ fmt.Println("t is now", t)
+ // STOP OMIT
+}
+
+func f9() {
+ // START f9 OMIT
+ var x float64 = 3.4
+ fmt.Println("value:", reflect.ValueOf(x))
+ // STOP OMIT
+}
diff --git a/doc/progs/interface2.out b/doc/progs/interface2.out
new file mode 100644
index 0000000..085bd01
--- /dev/null
+++ b/doc/progs/interface2.out
@@ -0,0 +1 @@
+type: float64
diff --git a/doc/progs/json1.go b/doc/progs/json1.go
new file mode 100644
index 0000000..887d7d1
--- /dev/null
+++ b/doc/progs/json1.go
@@ -0,0 +1,90 @@
+// run
+
+// Copyright 2012 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "encoding/json"
+ "log"
+ "reflect"
+)
+
+type Message struct {
+ Name string
+ Body string
+ Time int64
+}
+
+// STOP OMIT
+
+func Encode() {
+ m := Message{"Alice", "Hello", 1294706395881547000}
+ b, err := json.Marshal(m)
+
+ if err != nil {
+ panic(err)
+ }
+
+ expected := []byte(`{"Name":"Alice","Body":"Hello","Time":1294706395881547000}`)
+ if !reflect.DeepEqual(b, expected) {
+ log.Panicf("Error marshalling %q, expected %q, got %q.", m, expected, b)
+ }
+
+}
+
+func Decode() {
+ b := []byte(`{"Name":"Alice","Body":"Hello","Time":1294706395881547000}`)
+ var m Message
+ err := json.Unmarshal(b, &m)
+
+ if err != nil {
+ panic(err)
+ }
+
+ expected := Message{
+ Name: "Alice",
+ Body: "Hello",
+ Time: 1294706395881547000,
+ }
+
+ if !reflect.DeepEqual(m, expected) {
+ log.Panicf("Error unmarshalling %q, expected %q, got %q.", b, expected, m)
+ }
+
+ m = Message{
+ Name: "Alice",
+ Body: "Hello",
+ Time: 1294706395881547000,
+ }
+
+ // STOP OMIT
+}
+
+func PartialDecode() {
+ b := []byte(`{"Name":"Bob","Food":"Pickle"}`)
+ var m Message
+ err := json.Unmarshal(b, &m)
+
+ // STOP OMIT
+
+ if err != nil {
+ panic(err)
+ }
+
+ expected := Message{
+ Name: "Bob",
+ }
+
+ if !reflect.DeepEqual(expected, m) {
+ log.Panicf("Error unmarshalling %q, expected %q, got %q.", b, expected, m)
+ }
+}
+
+func main() {
+ Encode()
+ Decode()
+ PartialDecode()
+}
diff --git a/doc/progs/json2.go b/doc/progs/json2.go
new file mode 100644
index 0000000..f358fea
--- /dev/null
+++ b/doc/progs/json2.go
@@ -0,0 +1,44 @@
+// cmpout
+
+// Copyright 2012 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "fmt"
+ "math"
+)
+
+func InterfaceExample() {
+ var i interface{}
+ i = "a string"
+ i = 2011
+ i = 2.777
+
+ // STOP OMIT
+
+ r := i.(float64)
+ fmt.Println("the circle's area", math.Pi*r*r)
+
+ // STOP OMIT
+
+ switch v := i.(type) {
+ case int:
+ fmt.Println("twice i is", v*2)
+ case float64:
+ fmt.Println("the reciprocal of i is", 1/v)
+ case string:
+ h := len(v) / 2
+ fmt.Println("i swapped by halves is", v[h:]+v[:h])
+ default:
+ // i isn't one of the types above
+ }
+
+ // STOP OMIT
+}
+
+func main() {
+ InterfaceExample()
+}
diff --git a/doc/progs/json2.out b/doc/progs/json2.out
new file mode 100644
index 0000000..8f2dea5
--- /dev/null
+++ b/doc/progs/json2.out
@@ -0,0 +1,2 @@
+the circle's area 24.227111172875365
+the reciprocal of i is 0.3601008282319049
diff --git a/doc/progs/json3.go b/doc/progs/json3.go
new file mode 100644
index 0000000..41eb373
--- /dev/null
+++ b/doc/progs/json3.go
@@ -0,0 +1,75 @@
+// compile
+
+// Copyright 2012 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "encoding/json"
+ "fmt"
+ "log"
+ "reflect"
+)
+
+func Decode() {
+ b := []byte(`{"Name":"Wednesday","Age":6,"Parents":["Gomez","Morticia"]}`)
+
+ var f interface{}
+ err := json.Unmarshal(b, &f)
+
+ // STOP OMIT
+
+ if err != nil {
+ panic(err)
+ }
+
+ expected := map[string]interface{}{
+ "Name": "Wednesday",
+ "Age": float64(6),
+ "Parents": []interface{}{
+ "Gomez",
+ "Morticia",
+ },
+ }
+
+ if !reflect.DeepEqual(f, expected) {
+ log.Panicf("Error unmarshalling %q, expected %q, got %q", b, expected, f)
+ }
+
+ f = map[string]interface{}{
+ "Name": "Wednesday",
+ "Age": 6,
+ "Parents": []interface{}{
+ "Gomez",
+ "Morticia",
+ },
+ }
+
+ // STOP OMIT
+
+ m := f.(map[string]interface{})
+
+ for k, v := range m {
+ switch vv := v.(type) {
+ case string:
+ fmt.Println(k, "is string", vv)
+ case int:
+ fmt.Println(k, "is int", vv)
+ case []interface{}:
+ fmt.Println(k, "is an array:")
+ for i, u := range vv {
+ fmt.Println(i, u)
+ }
+ default:
+ fmt.Println(k, "is of a type I don't know how to handle")
+ }
+ }
+
+ // STOP OMIT
+}
+
+func main() {
+ Decode()
+}
diff --git a/doc/progs/json4.go b/doc/progs/json4.go
new file mode 100644
index 0000000..ee38f31
--- /dev/null
+++ b/doc/progs/json4.go
@@ -0,0 +1,47 @@
+// run
+
+// Copyright 2012 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "encoding/json"
+ "log"
+ "reflect"
+)
+
+type FamilyMember struct {
+ Name string
+ Age int
+ Parents []string
+}
+
+// STOP OMIT
+
+func Decode() {
+ b := []byte(`{"Name":"Bob","Age":20,"Parents":["Morticia", "Gomez"]}`)
+ var m FamilyMember
+ err := json.Unmarshal(b, &m)
+
+ // STOP OMIT
+
+ if err != nil {
+ panic(err)
+ }
+
+ expected := FamilyMember{
+ Name: "Bob",
+ Age: 20,
+ Parents: []string{"Morticia", "Gomez"},
+ }
+
+ if !reflect.DeepEqual(expected, m) {
+ log.Panicf("Error unmarshalling %q, expected %q, got %q", b, expected, m)
+ }
+}
+
+func main() {
+ Decode()
+}
diff --git a/doc/progs/json5.go b/doc/progs/json5.go
new file mode 100644
index 0000000..9ab972d
--- /dev/null
+++ b/doc/progs/json5.go
@@ -0,0 +1,33 @@
+// compile
+
+// Copyright 2012 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "encoding/json"
+ "log"
+ "os"
+)
+
+func main() {
+ dec := json.NewDecoder(os.Stdin)
+ enc := json.NewEncoder(os.Stdout)
+ for {
+ var v map[string]interface{}
+ if err := dec.Decode(&v); err != nil {
+ log.Println(err)
+ return
+ }
+ for k := range v {
+ if k != "Name" {
+ delete(v, k)
+ }
+ }
+ if err := enc.Encode(&v); err != nil {
+ log.Println(err)
+ }
+ }
+}
diff --git a/doc/progs/run b/doc/progs/run
new file mode 100755
index 0000000..6e680b8
--- /dev/null
+++ b/doc/progs/run
@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+# Copyright 2009 The Go Authors. All rights reserved.
+# Use of this source code is governed by a BSD-style
+# license that can be found in the LICENSE file.
+
+set -e
+
+goos=$(go env GOOS)
+
+defer_panic_recover="
+ defer
+ defer2
+"
+
+effective_go="
+ eff_bytesize
+ eff_qr
+ eff_sequence
+ eff_unused2
+"
+
+error_handling="
+ error
+ error2
+ error3
+ error4
+"
+
+law_of_reflection="
+ interface
+ interface2
+"
+
+c_go_cgo="
+ cgo1
+ cgo2
+ cgo3
+ cgo4
+"
+# cgo1 and cgo2 don't run on freebsd, srandom has a different signature
+if [ "$goos" == "freebsd" ]; then
+ c_go_cgo="cgo3 cgo4"
+fi
+# cgo1 and cgo2 don't run on netbsd, srandom has a different signature
+# cgo3 and cgo4 don't run on netbsd, since cgo cannot handle stdout correctly
+if [ "$goos" == "netbsd" ]; then
+ c_go_cgo=""
+fi
+# cgo3 and cgo4 don't run on openbsd, since cgo cannot handle stdout correctly
+if [ "$goos" == "openbsd" ]; then
+ c_go_cgo="cgo1 cgo2"
+fi
+if [ "$CGO_ENABLED" != 1 ]; then
+ c_go_cgo=""
+fi
+
+timeout="
+ timeout1
+ timeout2
+"
+
+gobs="
+ gobs1
+ gobs2
+"
+
+json="
+ json1
+ json2
+ json3
+ json4
+ json5
+"
+
+image_package="
+ image_package1
+ image_package2
+ image_package3
+ image_package4
+ image_package5
+ image_package6
+"
+
+all=$(echo $defer_panic_recover $effective_go $error_handling $law_of_reflection $c_go_cgo $timeout $gobs $json $image_package slices go1)
+
+for i in $all; do
+ go build $i.go
+done
+
+# Write to temporary file to avoid mingw bash bug.
+TMPFILE="${TMPDIR:-/tmp}/gotest3.$USER"
+
+function testit {
+ ./$1 >"$TMPFILE" 2>&1 || true
+ x=$(echo $(cat "$TMPFILE")) # extra echo canonicalizes
+ if ! echo "$x" | grep "$2" > /dev/null
+ then
+ echo $1 failed: '"'$x'"' is not '"'$2'"'
+ fi
+}
+
+
+testit defer '^0 3210 2$'
+testit defer2 '^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.$'
+
+testit eff_bytesize '^1.00YB 9.09TB$'
+testit eff_sequence '^\[-1 2 6 16 44\]$'
+
+testit go1 '^Christmas is a holiday: true Sleeping for 0.123s.*go1.go already exists$'
+
+testit interface2 "^type: float64$"
+
+testit json1 "^$"
+testit json2 "the reciprocal of i is"
+testit json3 "Age is int 6"
+testit json4 "^$"
+
+testit image_package1 "^X is 2 Y is 1$"
+testit image_package2 "^3 4 false$"
+testit image_package3 "^3 4 true$"
+testit image_package4 "^image.Point{X:2, Y:1}$"
+testit image_package5 "^{255 0 0 255}$"
+testit image_package6 "^8 4 true$"
+
+rm -f $all "$TMPFILE"
diff --git a/doc/progs/slices.go b/doc/progs/slices.go
new file mode 100644
index 0000000..f9af5fe
--- /dev/null
+++ b/doc/progs/slices.go
@@ -0,0 +1,65 @@
+// compile
+
+// Copyright 2012 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+ "io/ioutil"
+ "regexp"
+)
+
+func AppendByte(slice []byte, data ...byte) []byte {
+ m := len(slice)
+ n := m + len(data)
+ if n > cap(slice) { // if necessary, reallocate
+ // allocate double what's needed, for future growth.
+ newSlice := make([]byte, (n+1)*2)
+ copy(newSlice, slice)
+ slice = newSlice
+ }
+ slice = slice[0:n]
+ copy(slice[m:n], data)
+ return slice
+}
+
+// STOP OMIT
+
+// Filter returns a new slice holding only
+// the elements of s that satisfy fn.
+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
+}
+
+// STOP OMIT
+
+var digitRegexp = regexp.MustCompile("[0-9]+")
+
+func FindDigits(filename string) []byte {
+ b, _ := ioutil.ReadFile(filename)
+ return digitRegexp.Find(b)
+}
+
+// STOP OMIT
+
+func CopyDigits(filename string) []byte {
+ b, _ := ioutil.ReadFile(filename)
+ b = digitRegexp.Find(b)
+ c := make([]byte, len(b))
+ copy(c, b)
+ return c
+}
+
+// STOP OMIT
+
+func main() {
+ // place holder; no need to run
+}
diff --git a/doc/progs/timeout1.go b/doc/progs/timeout1.go
new file mode 100644
index 0000000..fbc39ca
--- /dev/null
+++ b/doc/progs/timeout1.go
@@ -0,0 +1,30 @@
+// compile
+
+// Copyright 2012 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+package timeout
+
+import (
+ "time"
+)
+
+func Timeout() {
+ ch := make(chan bool, 1)
+ timeout := make(chan bool, 1)
+ go func() {
+ time.Sleep(1 * time.Second)
+ timeout <- true
+ }()
+
+ // STOP OMIT
+
+ select {
+ case <-ch:
+ // a read from ch has occurred
+ case <-timeout:
+ // the read from ch has timed out
+ }
+
+ // STOP OMIT
+}
diff --git a/doc/progs/timeout2.go b/doc/progs/timeout2.go
new file mode 100644
index 0000000..a12bc2a
--- /dev/null
+++ b/doc/progs/timeout2.go
@@ -0,0 +1,29 @@
+// compile
+
+// Copyright 2012 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+package query
+
+type Conn string
+
+func (c Conn) DoQuery(query string) Result {
+ return Result("result")
+}
+
+type Result string
+
+func Query(conns []Conn, query string) Result {
+ ch := make(chan Result, 1)
+ for _, conn := range conns {
+ go func(c Conn) {
+ select {
+ case ch <- c.DoQuery(query):
+ default:
+ }
+ }(conn)
+ }
+ return <-ch
+}
+
+// STOP OMIT
diff --git a/doc/progs/update.bash b/doc/progs/update.bash
new file mode 100755
index 0000000..d4ecfbe
--- /dev/null
+++ b/doc/progs/update.bash
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Copyright 2012 The Go Authors. All rights reserved.
+# Use of this source code is governed by a BSD-style
+# license that can be found in the LICENSE file.
+
+set -e
+
+rm -f *.out *.rej *.orig [568].out
+
+for i in *.go; do
+ if grep -q '^// cmpout$' $i; then
+ echo $i
+ go run $i &> ${i/.go/.out}
+ fi
+done
diff --git a/doc/root.html b/doc/root.html
new file mode 100644
index 0000000..3c6de2e
--- /dev/null
+++ b/doc/root.html
@@ -0,0 +1,149 @@
+<!--{
+ "Path": "/"
+}-->
+
+<div class="left">
+
+<div id="learn">
+<a class="popout share">Pop-out</a>
+<div class="rootHeading">Try Go</div>
+<div class="input">
+<textarea spellcheck="false" class="code">// You can edit this code!
+// Click here and start typing.
+package main
+
+import "fmt"
+
+func main() {
+ fmt.Println("Hello, 世界")
+}</textarea>
+</div>
+<div class="output">
+<pre>
+Hello, 世界
+</pre>
+</div>
+<div class="buttons">
+<a class="run" href="#" title="Run this code [shift-enter]">Run</a>
+<a class="share" href="#" title="Share this code">Share</a>
+<a class="tour" href="//tour.golang.org/" title="Learn Go from your browser">Tour</a>
+</div>
+<div class="toys">
+<select>
+ <option value="hello.go">Hello, World!</option>
+ <option value="life.go">Conway's Game of Life</option>
+ <option value="fib.go">Fibonacci Closure</option>
+ <option value="peano.go">Peano Integers</option>
+ <option value="pi.go">Concurrent pi</option>
+ <option value="sieve.go">Concurrent Prime Sieve</option>
+ <option value="solitaire.go">Peg Solitaire Solver</option>
+ <option value="tree.go">Tree Comparison</option>
+</select>
+</div>
+</div>
+
+</div>
+
+<div class="right">
+
+<div id="about">
+Go is an open source programming language that makes it easy to build
+simple, reliable, and efficient software.
+</div>
+
+<div id="gopher"></div>
+
+<a href="/doc/install" id="start">
+<span class="big">Download Go</span>
+<span class="desc">
+Binary distributions available for<br>
+Linux, Mac OS X, Windows, and more.
+</span>
+</a>
+
+</div>
+
+<div style="clear: both"></div>
+
+<div class="left">
+
+<div id="video">
+<div class="rootHeading">Featured video</div>
+<iframe width="415" height="241" src="//www.youtube.com/embed/ytEkHepK08c" frameborder="0" allowfullscreen></iframe>
+</div>
+
+</div>
+
+<div class="right">
+
+<div id="blog">
+<div class="rootHeading">Featured articles</div>
+<div class="read"><a href="//blog.golang.org/">Read more</a></div>
+</div>
+
+</div>
+
+<div style="clear: both;"></div>
+
+<script type="text/javascript">
+
+function readableTime(t) {
+ var m = ["January", "February", "March", "April", "May", "June", "July",
+ "August", "September", "October", "November", "December"];
+ var p = t.substring(0, t.indexOf("T")).split("-");
+ var d = new Date(p[0], p[1]-1, p[2]);
+ return d.getDate() + " " + m[d.getMonth()] + " " + d.getFullYear();
+}
+
+function feedLoaded(result) {
+ var blog = document.getElementById("blog");
+ var read = blog.getElementsByClassName("read")[0];
+ for (var i = 0; i < result.length && i < 2; i++) {
+ var entry = result[i];
+ var title = document.createElement("a");
+ title.className = "title";
+ title.href = entry.Link;
+ title.innerHTML = entry.Title;
+ blog.insertBefore(title, read);
+ var extract = document.createElement("div");
+ extract.className = "extract";
+ extract.innerHTML = entry.Summary;
+ blog.insertBefore(extract, read);
+ var when = document.createElement("div");
+ when.className = "when";
+ when.innerHTML = "Published " + readableTime(entry.Time);
+ blog.insertBefore(when, read);
+ }
+}
+
+window.initFuncs.push(function() {
+ // Set up playground if enabled.
+ if (window.playground) {
+ window.playground({
+ "codeEl": "#learn .code",
+ "outputEl": "#learn .output",
+ "runEl": "#learn .run",
+ "shareEl": "#learn .share",
+ "shareRedirect": "//play.golang.org/p/",
+ "toysEl": "#learn .toys select"
+ });
+ } else {
+ $('#learn').hide()
+ }
+
+ // Load blog feed.
+ $('<script/>').attr('text', 'text/javascript')
+ .attr('src', '//blog.golang.org/.json?jsonp=feedLoaded')
+ .appendTo('body');
+
+ // Set the video at random.
+ var videos = [
+ {h: 241, s: "//www.youtube.com/embed/ytEkHepK08c"}, // Tour of Go
+ {h: 241, s: "//www.youtube.com/embed/f6kdp27TYZs"}, // Concurrency Patterns
+ {h: 233, s: "//player.vimeo.com/video/69237265"} // Simple environment
+ ];
+ var v = videos[Math.floor(Math.random()*videos.length)];
+ $('#video iframe').attr('height', v.h).attr('src', v.s);
+});
+
+</script>
diff --git a/doc/share.png b/doc/share.png
new file mode 100644
index 0000000..c04f0c7
--- /dev/null
+++ b/doc/share.png
Binary files differ
diff --git a/doc/sieve.gif b/doc/sieve.gif
new file mode 100644
index 0000000..8018ae2
--- /dev/null
+++ b/doc/sieve.gif
Binary files differ
diff --git a/doc/tos.html b/doc/tos.html
new file mode 100644
index 0000000..fff4642
--- /dev/null
+++ b/doc/tos.html
@@ -0,0 +1,11 @@
+<!--{
+ "Title": "Terms of service"
+}-->
+
+<p>
+The Go website (the "Website") is hosted by Google.
+By using and/or visiting the Website, you consent to be bound by Google's general
+<a href="//www.google.com/intl/en/policies/terms/">Terms of Service</a>
+and Google's general
+<a href="//www.google.com/intl/en/privacy/privacy-policy.html">Privacy Policy</a>.
+</p>
