mirror of
https://github.com/golang/go
synced 2024-11-24 16:30:17 -07:00
7cb21a79a4
This allows HTML pages to specify arbitrary data in a header:
<!--{
"Title": "The page title",
...
}-->
replacing the old style comments:
<!-- title The page title -->
R=gri, rsc, r, bradfitz, dsymonds
CC=golang-dev
https://golang.org/cl/5532093
1009 lines
31 KiB
Cheetah
1009 lines
31 KiB
Cheetah
<!--{
|
|
"Title": "Go 1 Release Notes"
|
|
}-->
|
|
{{donotedit}}
|
|
|
|
<h2 id="introduction">Introduction to Go 1</h2>
|
|
|
|
<p>
|
|
For a full explanation of the motivation and design of Go 1, see XXX.
|
|
Here follows a summary.
|
|
</p>
|
|
|
|
<p>
|
|
Go 1 is intended to be a stable language and core library set that
|
|
will form a reliable foundation for people and organizations that
|
|
want to make a long-term commitment to developing in the Go programming
|
|
language. Go will continue to develop, but in a way that guarantees
|
|
code written to the Go 1 specification will continue to work. For
|
|
instance, Go 1 will be a supported platform on Google App Engine
|
|
for the next few years. Incompatible changes to the environment,
|
|
should they arise, will be done in a distinct version.
|
|
</p>
|
|
|
|
<p>
|
|
This document describes the changes in the language and libraries
|
|
in Go 1, relative to the previous release, r60 (at the time of
|
|
writing, tagged as r60.3). It also explains how to update code at
|
|
r60 to compile and run under Go 1. Finally, it outlines the new
|
|
<code>go</code> command for building Go programs and the new binary
|
|
release process being introduced. Most of these topics have more
|
|
thorough presentations elsewhere; such documents are linked below.
|
|
</p>
|
|
|
|
<h2 id="language">Changes to the language</h2>
|
|
|
|
<h3 id="append">Append</h3>
|
|
|
|
<p>
|
|
The <code>append</code> built-in function is variadic, so one can
|
|
append to a byte slice using the <code>...</code> syntax in the
|
|
call.
|
|
</p>
|
|
|
|
{{code "progs/go1.go" `/greeting := ..byte/` `/append.*hello/`}}
|
|
|
|
<p>
|
|
By analogy with the similar property of <code>copy</code>, Go 1
|
|
permits a string to be appended (byte-wise) directly to a byte
|
|
slice; the conversion is no longer necessary:
|
|
</p>
|
|
|
|
{{code "progs/go1.go" `/append.*world/`}}
|
|
|
|
<p>
|
|
<em>Updating</em>:
|
|
This is a new feature, so existing code needs no changes.
|
|
</p>
|
|
|
|
<h3 id="close">Close</h3>
|
|
|
|
<p>
|
|
The <code>close</code> built-in function lets a sender tell a receiver
|
|
that no more data will be transmitted on the channel. In Go 1 the
|
|
type system enforces the directionality when possible: it is illegal
|
|
to call <code>close</code> on a receive-only channel:
|
|
</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 "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>
|
|
Go 1 allows goroutines to be created and run during initialization.
|
|
(They used to be created but were not run until after initialization
|
|
completed.) Code that uses goroutines can now be called from
|
|
<code>init</code> routines and global initialization expressions
|
|
without introducing a deadlock.
|
|
</p>
|
|
|
|
{{code "progs/go1.go" `/PackageGlobal/` `/^}/`}}
|
|
|
|
<p>
|
|
<em>Updating</em>:
|
|
This is a new feature, so existing code needs no changes,
|
|
although it's possible that code that depends on goroutines not starting before <code>main</code> will break.
|
|
There was no such code in the standard repository.
|
|
</p>
|
|
|
|
<h3 id="rune">The rune type</h3>
|
|
|
|
<p>
|
|
Go 1 introduces a new basic type, <code>rune</code>, to be used to represent
|
|
individual Unicode code points.
|
|
It is an alias for <code>int32</code>, analogous to <code>byte</code>
|
|
as an alias for <code>uint8</code>.
|
|
</p>
|
|
|
|
<p>
|
|
Character literals such as <code>'a'</code>, <code>'語'</code>, and <code>'\u0345'</code>
|
|
now have default type <code>rune</code>,
|
|
analogous to <code>1.0</code> having default type <code>float64</code>.
|
|
A variable initialized to a character constant will therefore
|
|
have type <code>rune</code> unless otherwise specified.
|
|
</p>
|
|
|
|
<p>
|
|
Libraries have been updated to use <code>rune</code> rather than <code>int</code>
|
|
when appropriate. For instance, the functions <code>unicode.ToLower</code> and
|
|
relatives now take and return a <code>rune</code>.
|
|
</p>
|
|
|
|
{{code "progs/go1.go" `/STARTRUNE/` `/ENDRUNE/`}}
|
|
|
|
<p>
|
|
<em>Updating</em>:
|
|
Most source code will be unaffected by this because the type inference from
|
|
<code>:=</code> initializers introduces the new type silently, and it propagates
|
|
from there.
|
|
Some code may get type errors that a trivial conversion will resolve.
|
|
</p>
|
|
|
|
<h3 id="error">The error type</h3>
|
|
|
|
<p>
|
|
Go 1 introduces a new built-in type, <code>error</code>, which has the following definition:
|
|
</p>
|
|
|
|
<pre>
|
|
type error interface {
|
|
Error() string
|
|
}
|
|
</pre>
|
|
|
|
<p>
|
|
Since the consequences of this type are all in the package library,
|
|
it is discussed <a href="#errors">below</a>.
|
|
</p>
|
|
|
|
<h3 id="delete">Deleting from maps</h3>
|
|
|
|
<p>
|
|
The original syntax for deleting an element in a map was:
|
|
</p>
|
|
|
|
<pre>
|
|
m[k] = ignored, false
|
|
</pre>
|
|
|
|
<p>
|
|
In Go 1, that syntax has gone; instead there is a new built-in
|
|
function, <code>delete</code>. The call
|
|
</p>
|
|
|
|
{{code "progs/go1.go" `/delete\(m, k\)/`}}
|
|
|
|
<p>
|
|
will delete the map entry retrieved by the expression <code>m[k]</code>.
|
|
There is no return value. Deleting a non-existent entry is a no-op.
|
|
</p>
|
|
|
|
<p>
|
|
<em>Updating</em>:
|
|
Gofix will convert expressions of the form <code>m[k] = ignored,
|
|
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. Gofix
|
|
will flag other uses of the syntax for inspection by the programmer.
|
|
</p>
|
|
|
|
<h3 id="iteration">Iterating in maps</h3>
|
|
|
|
<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>
|
|
|
|
{{code "progs/go1.go" `/Sunday/` `/^ }/`}}
|
|
|
|
<p>
|
|
<em>Updating</em>:
|
|
This is one change where tools cannot help. Most existing code
|
|
will be unaffected, but some programs may break or misbehave; we
|
|
recommend manual checking of all range statements over maps to
|
|
verify they do not depend on iteration order. There were a few such
|
|
examples in the standard repository; they have been fixed.
|
|
Note that it was already incorrect to depend on the iteration order, which
|
|
was unspecified. This change codifies the unpredictability.
|
|
</p>
|
|
|
|
<h3 id="multiple_assignment">Multiple assignment</h3>
|
|
|
|
<p>
|
|
Go 1 fully specifies the evaluation order in multiple assignment
|
|
statements. In particular, if the left-hand side of the assignment
|
|
statement contains expressions that require evaluation, such as
|
|
function calls or array indexing operations, these will all be done
|
|
using the usual left-to-right rule before any variables are assigned
|
|
their value. Once everything is evaluated, the actual assignments
|
|
proceed in left-to-right order.
|
|
</p>
|
|
|
|
<p>
|
|
These examples illustrate the behavior.
|
|
</p>
|
|
|
|
{{code "progs/go1.go" `/sa :=/` `/then sc.0. = 2/`}}
|
|
|
|
<p>
|
|
<em>Updating</em>:
|
|
This is one change where tools cannot help, but breakage is unlikely.
|
|
No code in the standard repository was broken by this change, and code
|
|
that depended on the previous unspecified behavior was already incorrect.
|
|
</p>
|
|
|
|
<h3 id="shadowing">Returns and shadowed variables</h3>
|
|
|
|
<p>
|
|
A shadowed variable is one that has the same name as another variable in an inner scope.
|
|
In functions with named return values,
|
|
the Go 1 compilers disallow return statements without arguments if any of the named return values is shadowed at the point of the return statement.
|
|
(It isn't part of the specification, because this is one area we are still exploring;
|
|
the situation is analogous to the compilers rejecting functions that do not end with an explicit return statement.)
|
|
</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>
|
|
Go 1 relaxes the rules about accessing structs with unexported (lower-case) fields,
|
|
permitting a client package to assign (and therefore copy) such a struct.
|
|
Of course, the client package still cannot access such fields individually.
|
|
</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 of structs and arrays</h3>
|
|
|
|
<p>
|
|
Go 1 defines equality and inequality (<code>==</code> and
|
|
<code>!=</code>) for struct and array values, respectively, provided
|
|
the elements of the data structures can themselves be compared.
|
|
That is, if equality is defined for all the fields of a struct (or
|
|
an array element), then it is defined for the struct (or array).
|
|
</p>
|
|
|
|
<p>
|
|
As a result, structs and arrays can now be used as map keys:
|
|
</p>
|
|
|
|
{{code "progs/go1.go" `/type Day struct/` `/Printf/`}}
|
|
|
|
<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>:
|
|
This is a new feature, so existing code needs no changes.
|
|
</p>
|
|
|
|
<h3 id="funcs">Function and map equality</h3>
|
|
|
|
<p>
|
|
Go 1 disallows checking for equality of functions and maps,
|
|
respectively, except to compare them directly to <code>nil</code>.
|
|
</p>
|
|
|
|
<p>
|
|
<em>Updating</em>:
|
|
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="library">Changes to the library</h2>
|
|
|
|
<h3 id="hierarchy">The package hierarchy</h3>
|
|
|
|
<p>
|
|
Go 1 has a rearranged package hierarchy that groups related items
|
|
into subdirectories. For instance, <code>utf8</code> and
|
|
<code>utf16</code> now occupy subdirectories of <code>unicode</code>.
|
|
Also, <a href="#subrepo">some packages</a> have moved into
|
|
subrepositories of
|
|
<a href="http://code.google.com/p/go"><code>code.google.com/p/go</code></a>
|
|
while <a href="#deleted">others</a> have been deleted outright.
|
|
</p>
|
|
|
|
<table class="codetable" frame="border" summary="Moved packages">
|
|
<colgroup align="left" width="60%"></colgroup>
|
|
<colgroup align="left" width="40%"></colgroup>
|
|
<tr>
|
|
<th align="left">Old path</th>
|
|
<th align="left">New path</th>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="2"><hr></td>
|
|
</tr>
|
|
<tr><td>asn1</td> <td>encoding/asn1</td></tr>
|
|
<tr><td>csv</td> <td>encoding/csv</td></tr>
|
|
<tr><td>gob</td> <td>encoding/gob</td></tr>
|
|
<tr><td>json</td> <td>encoding/json</td></tr>
|
|
<tr><td>xml</td> <td>encoding/xml</td></tr>
|
|
<tr>
|
|
<td colspan="2"><hr></td>
|
|
</tr>
|
|
<tr><td>exp/template/html</td> <td>html/template</td></tr>
|
|
<tr>
|
|
<td colspan="2"><hr></td>
|
|
</tr>
|
|
<tr><td>big</td> <td>math/big</td></tr>
|
|
<tr><td>cmath</td> <td>math/cmplx</td></tr>
|
|
<tr><td>rand</td> <td>math/rand</td></tr>
|
|
<tr>
|
|
<td colspan="2"><hr></td>
|
|
</tr>
|
|
<tr><td>http</td> <td>net/http</td></tr>
|
|
<tr><td>http/cgi</td> <td>net/http/cgi</td></tr>
|
|
<tr><td>http/fcgi</td> <td>net/http/fcgi</td></tr>
|
|
<tr><td>http/httptest</td> <td>net/http/httptest</td></tr>
|
|
<tr><td>http/pprof</td> <td>net/http/pprof</td></tr>
|
|
<tr><td>mail</td> <td>net/mail</td></tr>
|
|
<tr><td>rpc</td> <td>net/rpc</td></tr>
|
|
<tr><td>rpc/jsonrpc</td> <td>net/rpc/jsonrpc</td></tr>
|
|
<tr><td>smtp</td> <td>net/smtp</td></tr>
|
|
<tr><td>url</td> <td>net/url</td></tr>
|
|
<tr>
|
|
<td colspan="2"><hr></td>
|
|
</tr>
|
|
<tr><td>exec</td> <td>os/exec</td></tr>
|
|
<tr>
|
|
<td colspan="2"><hr></td>
|
|
</tr>
|
|
<tr><td>scanner</td> <td>text/scanner</td></tr>
|
|
<tr><td>tabwriter</td> <td>text/tabwriter</td></tr>
|
|
<tr><td>template</td> <td>text/template</td></tr>
|
|
<tr><td>template/parse</td> <td>text/template/parse</td></tr>
|
|
<tr>
|
|
<td colspan="2"><hr></td>
|
|
</tr>
|
|
<tr><td>utf8</td> <td>unicode/utf8</td></tr>
|
|
<tr><td>utf16</td> <td>unicode/utf16</td></tr>
|
|
</table>
|
|
|
|
<p>
|
|
Note that the package names for the old <code>cmath</code> and
|
|
<code>exp/template/html</code> packages have changed to <code>cmplx</code>
|
|
and <code>template</code>.
|
|
</p>
|
|
|
|
<p>
|
|
<em>Updating</em>:
|
|
Gofix 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.
|
|
<br>
|
|
<font color="red">TODO: gofix should warn about deletions.</font>
|
|
<br>
|
|
<font color="red">TODO: gofix should also handle packages that move to subrepos.</font>
|
|
</p>
|
|
|
|
<h3 id="errors">The error type and errors package</h3>
|
|
|
|
<p>
|
|
As mentioned above, Go 1 introduces a new built-in interface type called <code>error</code>.
|
|
Its intent is to replace the old <code>os.Error</code> type with a more central concept.
|
|
So the widely-used <code>String</code> method does not cause accidental satisfaction
|
|
of the <code>error</code> interface, the <code>error</code> interface uses instead
|
|
the name <code>Error</code> for that method:
|
|
</p>
|
|
|
|
<pre>
|
|
type error interface {
|
|
Error() string
|
|
}
|
|
</pre>
|
|
|
|
<p>
|
|
The <code>fmt</code> library automatically invokes <code>Error</code>, as it already
|
|
does for <code>String</code>, for easy printing of error values.
|
|
</p>
|
|
|
|
{{code "progs/go1.go" `/START ERROR EXAMPLE/` `/END ERROR EXAMPLE/`}}
|
|
|
|
<p>
|
|
All standard packages have been updated to use the new interface; the old <code>os.Error</code> is gone.
|
|
</p>
|
|
|
|
<p>
|
|
A new package, <a href="/pkg/errors/"><code>errors</code></a>, contains the function
|
|
</p>
|
|
|
|
<pre>
|
|
func New(text string) error
|
|
</pre>
|
|
|
|
<p>
|
|
to turn a string into an error. It replaces the old <code>os.NewError</code>.
|
|
</p>
|
|
|
|
{{code "progs/go1.go" `/ErrSyntax/`}}
|
|
|
|
<p>
|
|
<em>Updating</em>:
|
|
Gofix 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>
|
|
In Go 1, the
|
|
<a href="/pkg/syscall/"><code>syscall</code></a>
|
|
package returns an <code>error</code> for system call errors,
|
|
rather than plain integer <code>errno</code> values.
|
|
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>
|
|
<em>Updating</em>:
|
|
Gofix 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>
|
|
One of the most sweeping changes in the Go 1 library is the
|
|
complete redesign of the
|
|
<a href="/pkg/time/"><code>time</code></a> package.
|
|
Instead of an integer number of nanoseconds as an <code>int64</code>,
|
|
and a separate <code>*time.Time</code> type to deal with human
|
|
units such as hours and years,
|
|
there are now two fundamental types:
|
|
<a href="/pkg/time/#Time"><code>time.Time</code></a>
|
|
(a value, so the <code>*</code> is gone), which represents a moment in time;
|
|
and <a href="/pkg/time/#Duration"><code>time.Duration</code></a>,
|
|
which represents an interval.
|
|
Both have nanosecond resolution.
|
|
A <code>Time</code> can represent any time into the ancient
|
|
past and remote future, while a <code>Duration</code> can
|
|
span plus or minus only about 290 years.
|
|
There are methods on these types, plus a number of helpful
|
|
predefined constant durations such as <code>time.Second</code>.
|
|
</p>
|
|
|
|
<p>
|
|
Among the new methods are things like
|
|
<a href="/pkg/time/#Time.Add"><code>Time.Add</code></a>,
|
|
which adds a <code>Duration</code> to a <code>Time</code>, and
|
|
<a href="/pkg/time/#Time.Sub"><code>Time.Sub</code></a>,
|
|
which subtracts two <code>Times</code> to yield a <code>Duration</code>.
|
|
</p>
|
|
|
|
<p>
|
|
The most important semantic change is that the Unix epoch (Jan 1, 1970) is now
|
|
relevant only for those functions and methods that mention Unix:
|
|
<a href="/pkg/time/#Unix"><code>time.Unix</code></a>
|
|
and the <a href="/pkg/time/#Time.Unix"><code>Unix</code></a>
|
|
and <a href="/pkg/time/#Time.UnixNano"><code>UnixNano</code></a> methods
|
|
of the <code>Time</code> type.
|
|
In particular,
|
|
<a href="/pkg/time/#Now"><code>time.Now</code></a>
|
|
returns a <code>time.Time</code> value rather than, in the old
|
|
API, an integer nanosecond count since the Unix epoch.
|
|
</p>
|
|
|
|
{{code "progs/go1.go" `/sleepUntil/` `/^}/`}}
|
|
|
|
<p>
|
|
The new types, methods, and constants have been propagated through
|
|
all the standard packages that use time, such as <code>os</code> and
|
|
its representation of file time stamps.
|
|
</p>
|
|
|
|
<p>
|
|
<em>Updating</em>:
|
|
Gofix 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 gofix 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>
|
|
|
|
<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>
|
|
<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.
|
|
</p>
|
|
|
|
<h3 id="html">The html package</h3>
|
|
|
|
<p>
|
|
The <a href="/pkg/html/"><code>html</code></a> package in Go 1 provides
|
|
a full parser for HTML5.
|
|
</p>
|
|
|
|
<p>
|
|
<em>Updating</em>:
|
|
Since the package's functionality is new, no updating is necessary.
|
|
</p>
|
|
|
|
<h3 id="http">The http package</h3>
|
|
|
|
<p>
|
|
In Go 1 the <a href="/pkg/net/http/"><code>http</code></a> package is refactored,
|
|
putting some of the utilities into a
|
|
<a href="/pkg/net/httputil/"><code>httputil</code></a> subdirectory.
|
|
These pieces are only rarely needed by HTTP clients.
|
|
The affected items are:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>ClientConn</li>
|
|
<li>DumpRequest</li>
|
|
<li>DumpRequest</li>
|
|
<li>DumpRequestOut</li>
|
|
<li>DumpResponse</li>
|
|
<li>NewChunkedReader</li>
|
|
<li>NewChunkedWriter</li>
|
|
<li>NewClientConn</li>
|
|
<li>NewProxyClientConn</li>
|
|
<li>NewServerConn</li>
|
|
<li>NewSingleHostReverseProxy</li>
|
|
<li>ReverseProxy</li>
|
|
<li>ServerConn</li>
|
|
</ul>
|
|
|
|
<p>
|
|
Also, the <code>Request.RawURL</code> field has been removed; it was a
|
|
historical artifact.
|
|
</p>
|
|
|
|
<p>
|
|
<em>Updating</em>:
|
|
Gofix will update the few programs that are affected except for
|
|
uses of <code>RawURL</code>, which must be fixed 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 <code>SetDeadline</code>,
|
|
<code>SetReadDeadline</code>, and <code>SetWriteDeadline</code>,
|
|
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>
|
|
|
|
<h3 id="strconv">The strconv package</h3>
|
|
|
|
<p>
|
|
In Go 1, the
|
|
<a href="/pkg/strconv/"><code>strconv</code></a>
|
|
package has been significantly reworked to make it more Go-like and less C-like,
|
|
although <code>Atoi</code> lives on (it's similar to
|
|
<code>int(ParseInt(x, 10, 0))</code>, as does
|
|
<code>Itoa(x)</code> (<code>FormatInt(int64(x), 10)</code>).
|
|
There are also new variants of some of the functions that append to byte slices rather than
|
|
return strings, to allow control over allocation.
|
|
</p>
|
|
|
|
<p>
|
|
This table summarizes the renamings; see the
|
|
<a href="/pkg/strconv/">package documentation</a>
|
|
for full details.
|
|
</p>
|
|
|
|
<table class="codetable" frame="border" summary="strconv renames">
|
|
<colgroup align="left" width="50%"></colgroup>
|
|
<colgroup align="left" width="50%"></colgroup>
|
|
<tr>
|
|
<th align="left">Old call</th>
|
|
<th align="left">New call</th>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="2"><hr></td>
|
|
</tr>
|
|
<tr><td>Atob(x)</td> <td>ParseBool(x)</td></tr>
|
|
<tr>
|
|
<td colspan="2"><hr></td>
|
|
</tr>
|
|
<tr><td>Atof32(x)</td> <td>ParseFloat(x, 32)§</td></tr>
|
|
<tr><td>Atof64(x)</td> <td>ParseFloat(x, 64)</td></tr>
|
|
<tr><td>AtofN(x, n)</td> <td>ParseFloat(x, n)</td></tr>
|
|
<tr>
|
|
<td colspan="2"><hr></td>
|
|
</tr>
|
|
<tr><td>Atoi(x)</td> <td>Atoi(x)</td></tr>
|
|
<tr><td>Atoi(x)</td> <td>ParseInt(x, 10, 0)§</td></tr>
|
|
<tr><td>Atoi64(x)</td> <td>ParseInt(x, 10, 64)</td></tr>
|
|
<tr>
|
|
<td colspan="2"><hr></td>
|
|
</tr>
|
|
<tr><td>Atoui(x)</td> <td>ParseUint(x, 10, 0)§</td></tr>
|
|
<tr><td>Atoi64(x)</td> <td>ParseInt(x, 10, 64)</td></tr>
|
|
<tr>
|
|
<td colspan="2"><hr></td>
|
|
</tr>
|
|
<tr><td>Btoi64(x, b)</td> <td>ParseInt(x, b, 64)</td></tr>
|
|
<tr><td>Btoui64(x, b)</td> <td>ParseUint(x, b, 64)</td></tr>
|
|
<tr>
|
|
<td colspan="2"><hr></td>
|
|
</tr>
|
|
<tr><td>Btoa(x)</td> <td>FormatBool(x)</td></tr>
|
|
<tr>
|
|
<td colspan="2"><hr></td>
|
|
</tr>
|
|
<tr><td>Ftoa32(x, f, p)</td> <td>FormatFloat(x, float64(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>:
|
|
Gofix 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; gofix will warn about it.
|
|
</p>
|
|
|
|
<h3 id="os_fileinfo">The os.FileInfo type</h3>
|
|
|
|
<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()
|
|
}
|
|
</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, <code>*os.FileStat</code>,
|
|
which in turn contains a <code>Sys</code> field that stores 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)
|
|
}
|
|
// Make sure it's an implementation known to package os.
|
|
fileStat, ok := fi.(*os.FileStat)
|
|
if !ok {
|
|
log.Fatal("hello.go: not an os File")
|
|
}
|
|
// Now check that it's a Unix file.
|
|
unixStat, ok := fileStat.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.(*os.FileStat).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>
|
|
<em>Updating</em>:
|
|
Gofix 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.
|
|
</p>
|
|
|
|
<h3 id="go">The package tree go</h3>
|
|
|
|
<p>
|
|
Several packages under <code>go</code> have slightly revised APIs.
|
|
</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 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="go/parser/#ParseFile"><code>ParseFile</code></a>, and a couple of
|
|
convenience functions <a href="go/parser/#ParseDir"><code>ParseDir</code></a>
|
|
and <a href="go/parser/#ParseExpr"><code>ParseExpr</code></a>.
|
|
</p>
|
|
|
|
<p>
|
|
The type names of the <a href="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>), <code>Type.Factories</code> has become
|
|
<code>Type.Funcs</code>, and there is a new type <code>Method</code> that describes
|
|
methods in more detail.
|
|
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="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="go/ast/#Text"><code>Text</code></a> of
|
|
<a href="go/ast/#CommentGroup"><code>ast.CommentGroup</code></a>.
|
|
</p>
|
|
|
|
<p>
|
|
In package <a href="go/token/"><code>go/token</code></a>, the
|
|
<a href="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="go/token/#FileSet.Iterate"><code>Iterate</code></a> that
|
|
accepts a function argument instead.
|
|
</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 conjuction 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="exp">The package tree exp</h3>
|
|
|
|
<p>
|
|
Because they are not standardized, the packages under the <code>exp</code> directory will not be available in the
|
|
standard Go 1 release distributions, although they will be available in source code form
|
|
in <a href="http://code.google.com/p/go/">the repository</a> for
|
|
developers who wish to use them.
|
|
</p>
|
|
|
|
<p>
|
|
Several packages have moved under <code>exp</code> at the time of Go 1's release:
|
|
</p>
|
|
|
|
<ul>
|
|
<li><code>ebnf</code></li>
|
|
<li><code>go/types</code></li>
|
|
<li><code>http/spdy</code></li>
|
|
</ul>
|
|
|
|
<p>
|
|
Also, the <code>utf8.String</code> type has been moved to its own package, <code>exp/utf8string</code>.
|
|
</p>
|
|
|
|
<p>
|
|
All these packages are available under the same names, with <code>exp/</code> prefixed: <code>exp/ebnf</code> etc.
|
|
</p>
|
|
|
|
<p>
|
|
Also, the <code>gotype</code> command now resides in <code>exp/gotype</code>, while
|
|
<code>ebnflint</code> is now in <code>exp/ebnflint</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.
|
|
Gofix or the compiler will complain about such uses.
|
|
<br>
|
|
<font color="red">TODO: gofix should warn about such uses.</font>
|
|
</p>
|
|
|
|
<h3 id="old">The package tree old</h3>
|
|
|
|
<p>
|
|
Because they are deprecated, the packages under the <code>old</code> directory will not be available in the
|
|
standard Go 1 release distributions, although they will be available in source code form for
|
|
developers who wish to use them.
|
|
</p>
|
|
|
|
<p>
|
|
The packages in their new locations are:
|
|
</p>
|
|
|
|
<ul>
|
|
<li><code>old/netchan</code></li>
|
|
<li><code>old/regexp</code></li>
|
|
<li><code>old/template</code></li>
|
|
</ul>
|
|
|
|
<p>
|
|
<em>Updating</em>:
|
|
Code that uses packages now in <code>old</code> will need to be updated by hand,
|
|
or else compiled from an installation that has <code>old</code> available.
|
|
Gofix will warn about such uses.
|
|
<br>
|
|
<font color="red">TODO: gofix should warn about such uses.</font>
|
|
</p>
|
|
|
|
<h3 id="deleted">Deleted packages</h3>
|
|
|
|
<p>
|
|
Go 1 deletes several packages outright:
|
|
</p>
|
|
|
|
<ul>
|
|
<li><code>container/vector</code></li>
|
|
<li><code>exp/datafmt</code></li>
|
|
<li><code>go/typechecker</code></li>
|
|
<li><code>try</code></li>
|
|
</ul>
|
|
|
|
<p>
|
|
and also the command <code>gotry</code>.
|
|
</p>
|
|
|
|
<p>
|
|
<em>Updating</em>:
|
|
Code that uses <code>container/vector</code> should be updated to use
|
|
slices directly. See
|
|
<a href="http://code.google.com/p/go-wiki/wiki/SliceTricks">the Go
|
|
Language Community Wiki</a> for some suggestions.
|
|
Code that uses the other packages (there should be almost zero) will need to be rethought.
|
|
<br>
|
|
<font color="red">TODO: gofix should warn such uses.</font>
|
|
</p>
|
|
|
|
<h3 id="subrepo">Packages moving to subrepositories</h3>
|
|
|
|
<!--
|
|
crypto/openpgp to XXX
|
|
maybe exp/ssh?
|
|
-->
|
|
|
|
<h2 id="go_command">The go command</h2>
|
|
|
|
<h2 id="releases">Packaged releases</h2>
|
|
|