mirror of
https://github.com/golang/go.git
synced 2024-09-29 14:26:50 +00:00
doc/go1: rearrange a bit, sort the packages
This should make it easier to add the zillion little changes coming. No content change here beyond a couple of introductory sentences. Sections have been moved wholesale without editing them. R=golang-dev, rsc, gri CC=golang-dev https://golang.org/cl/5557074
This commit is contained in:
Rob Pike
parent
290e68b983
commit
0a1376a1df
545
doc/go1.html
545
doc/go1.html
@ -450,7 +450,13 @@ Few programs will be affected, but the fix may require some
|
|||||||
redesign.
|
redesign.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<h2 id="library">Changes to the library</h2>
|
<h2 id="packages">The package hierarchy</h2>
|
||||||
|
|
||||||
|
<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>
|
<h3 id="hierarchy">The package hierarchy</h3>
|
||||||
|
|
||||||
@ -538,6 +544,116 @@ by hand.
|
|||||||
<font color="red">TODO: gofix should also handle packages that move to subrepos.</font>
|
<font color="red">TODO: gofix should also handle packages that move to subrepos.</font>
|
||||||
</p>
|
</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="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>
|
<h3 id="errors">The error type and errors package</h3>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
@ -688,6 +804,117 @@ the correct function or method for the old functionality, but
|
|||||||
may have the wrong type or require further analysis.
|
may have the wrong type or require further analysis.
|
||||||
</p>
|
</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 gofix.
|
||||||
|
This category includes packages that are new in Go 1.
|
||||||
|
</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_x509">The crypto/x509 package</h3>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
In Go 1, the
|
||||||
|
<a href="/pkg/crypto/x509/#CreateCertificate"><code>CreateCertificate</code></a>
|
||||||
|
and
|
||||||
|
<a href="/pkg/crypto/x509/#CreateCRL"><code>CreateCRL</code></a>
|
||||||
|
functions in <code>crypto/x509</code> have been altered to take an
|
||||||
|
<code>interface{}</code> where they previously took a <code>*rsa.PublicKey</code>
|
||||||
|
or <code>*rsa.PrivateKey</code>. This will allow other public key algorithms
|
||||||
|
to be implemented in the future.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
<em>Updating</em>:
|
||||||
|
No changes will be needed.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<h3 id="go">The go/* packages</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="hash">The hash package</h3>
|
<h3 id="hash">The hash package</h3>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
@ -763,6 +990,80 @@ apply to any activity on the connection, the new methods set an
|
|||||||
absolute deadline (as a <code>time.Time</code> value) after which
|
absolute deadline (as a <code>time.Time</code> value) after which
|
||||||
reads and writes will time out and no longer block.</p>
|
reads and writes will time out and no longer block.</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="strconv">The strconv package</h3>
|
<h3 id="strconv">The strconv package</h3>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
@ -857,248 +1158,6 @@ they may require
|
|||||||
a cast that must be added by hand; gofix will warn about it.
|
a cast that must be added by hand; gofix will warn about it.
|
||||||
</p>
|
</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="/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 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 <a href="/pkg/go/doc/#Package"><code>Package</code></a>, <code>ValueDoc</code>
|
|
||||||
is <a href="/pkg/go/doc/#Value"><code>Value</code></a>, 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
|
|
||||||
<a href="/pkg/go/doc/#Method"><code>Method</code></a> 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
|
|
||||||
<a href="/pkg/go/doc/#Mode"><code>Mode</code></a>: if set to
|
|
||||||
<code>AllDecls</code>, 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>
|
|
||||||
<em>Updating</em>:
|
|
||||||
Code that uses these packages in <a href="/pkg/go/">go</a> will have to be updated by hand;
|
|
||||||
the compiler will reject incorrect uses. Templates used in conjuction with any of the
|
|
||||||
<a href="/pkg/go/doc/"><code>go/doc</code></a> 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="go_command">The go command</h2>
|
||||||
|
|
||||||
|
|||||||
510
doc/go1.tmpl
510
doc/go1.tmpl
@ -374,7 +374,13 @@ Few programs will be affected, but the fix may require some
|
|||||||
redesign.
|
redesign.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<h2 id="library">Changes to the library</h2>
|
<h2 id="packages">The package hierarchy</h2>
|
||||||
|
|
||||||
|
<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>
|
<h3 id="hierarchy">The package hierarchy</h3>
|
||||||
|
|
||||||
@ -462,6 +468,116 @@ by hand.
|
|||||||
<font color="red">TODO: gofix should also handle packages that move to subrepos.</font>
|
<font color="red">TODO: gofix should also handle packages that move to subrepos.</font>
|
||||||
</p>
|
</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="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>
|
<h3 id="errors">The error type and errors package</h3>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
@ -592,7 +708,16 @@ the correct function or method for the old functionality, but
|
|||||||
may have the wrong type or require further analysis.
|
may have the wrong type or require further analysis.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<h3 id="crypto/elliptic">The crypto/elliptic package</h3>
|
<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 gofix.
|
||||||
|
This category includes packages that are new in Go 1.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<h3 id="crypto_elliptic">The crypto/elliptic package</h3>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
In Go 1, <a href="/pkg/crypto/elliptic/#Curve"><code>elliptic.Curve</code></a>
|
In Go 1, <a href="/pkg/crypto/elliptic/#Curve"><code>elliptic.Curve</code></a>
|
||||||
@ -611,7 +736,7 @@ in <code>crypto/elliptic</code> that take an <code>elliptic.Curve</code>
|
|||||||
as their first argument.
|
as their first argument.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<h3 id="crypto/x509">The crypto/x509 package</h3>
|
<h3 id="crypto_x509">The crypto/x509 package</h3>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
In Go 1, the
|
In Go 1, the
|
||||||
@ -629,6 +754,71 @@ to be implemented in the future.
|
|||||||
No changes will be needed.
|
No changes will be needed.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
|
<h3 id="go">The go/* packages</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="hash">The hash package</h3>
|
<h3 id="hash">The hash package</h3>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
@ -704,6 +894,80 @@ apply to any activity on the connection, the new methods set an
|
|||||||
absolute deadline (as a <code>time.Time</code> value) after which
|
absolute deadline (as a <code>time.Time</code> value) after which
|
||||||
reads and writes will time out and no longer block.</p>
|
reads and writes will time out and no longer block.</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="strconv">The strconv package</h3>
|
<h3 id="strconv">The strconv package</h3>
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
@ -798,246 +1062,6 @@ they may require
|
|||||||
a cast that must be added by hand; gofix will warn about it.
|
a cast that must be added by hand; gofix will warn about it.
|
||||||
</p>
|
</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="go_command">The go command</h2>
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user