From: Rob Pike Date: Fri, 20 Jan 2012 22:28:48 +0000 (-0800) Subject: doc/go1: rearrange a bit, sort the packages X-Git-Tag: weekly.2012-01-27~130 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=0a1376a1df34d84a85ca7195f0499f012e62275d;p=gostls13.git 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 --- diff --git a/doc/go1.html b/doc/go1.html index b576053b09..34e4f9cd84 100644 --- a/doc/go1.html +++ b/doc/go1.html @@ -450,7 +450,13 @@ Few programs will be affected, but the fix may require some redesign.

-

Changes to the library

+

The package hierarchy

+ +

+This section describes how the packages have been rearranged in Go 1. +Some have moved, some have been renamed, some have been deleted. +New packages are described in later sections. +

The package hierarchy

@@ -538,6 +544,116 @@ by hand. TODO: gofix should also handle packages that move to subrepos.

+

The package tree exp

+ +

+Because they are not standardized, the packages under the exp directory will not be available in the +standard Go 1 release distributions, although they will be available in source code form +in the repository for +developers who wish to use them. +

+ +

+Several packages have moved under exp at the time of Go 1's release: +

+ + + +

+Also, the utf8.String type has been moved to its own package, exp/utf8string. +

+ +

+All these packages are available under the same names, with exp/ prefixed: exp/ebnf etc. +

+ +

+Also, the gotype command now resides in exp/gotype, while +ebnflint is now in exp/ebnflint +

+ +

+Updating: +Code that uses packages in exp will need to be updated by hand, +or else compiled from an installation that has exp available. +Gofix or the compiler will complain about such uses. +
+TODO: gofix should warn about such uses. +

+ +

The package tree old

+ +

+Because they are deprecated, the packages under the old directory will not be available in the +standard Go 1 release distributions, although they will be available in source code form for +developers who wish to use them. +

+ +

+The packages in their new locations are: +

+ + + +

+Updating: +Code that uses packages now in old will need to be updated by hand, +or else compiled from an installation that has old available. +Gofix will warn about such uses. +
+TODO: gofix should warn about such uses. +

+ +

Deleted packages

+ +

+Go 1 deletes several packages outright: +

+ + + +

+and also the command gotry. +

+ +

+Updating: +Code that uses container/vector should be updated to use +slices directly. See +the Go +Language Community Wiki for some suggestions. +Code that uses the other packages (there should be almost zero) will need to be rethought. +
+TODO: gofix should warn such uses. +

+ +

Packages moving to subrepositories

+ + + +

Major changes to the library

+ +

+This section describes significant changes to the core libraries, the ones that +affect the most programs. +

+

The error type and errors package

@@ -688,6 +804,117 @@ the correct function or method for the old functionality, but may have the wrong type or require further analysis.

+

Minor changes to the library

+ +

+This section describes smaller changes, such as those to less commonly +used packages or that affect +few programs beyond the need to run gofix. +This category includes packages that are new in Go 1. +

+ +

The crypto/elliptic package

+ +

+In Go 1, elliptic.Curve +has been made an interface to permit alternative implementations. The curve +parameters have been moved to the +elliptic.CurveParams +structure. +

+ +

+Updating: +Existing users of *elliptic.Curve will need to change to +simply elliptic.Curve. Calls to Marshal, +Unmarshal and GenerateKey are now functions +in crypto/elliptic that take an elliptic.Curve +as their first argument. +

+ +

The crypto/x509 package

+ +

+In Go 1, the +CreateCertificate +and +CreateCRL +functions in crypto/x509 have been altered to take an +interface{} where they previously took a *rsa.PublicKey +or *rsa.PrivateKey. This will allow other public key algorithms +to be implemented in the future. +

+ +

+Updating: +No changes will be needed. +

+ +

The go/* packages

+ +

+Several packages under go have slightly revised APIs. +

+ +

+The modes AllowIllegalChars and InsertSemis have been removed +from the go/scanner package. They were mostly +useful for scanning text other then Go source files. Instead, the +text/scanner package should be used +for that purpose. +

+ +

+The set of parse functions provided by the go/parser +package has been reduced to the primary parse function +ParseFile, and a couple of +convenience functions ParseDir +and ParseExpr. +

+ +

+The type names of the go/doc package have been +streamlined by removing the Doc suffix: PackageDoc +is now Package, ValueDoc is Value, etc. +Also, all types now consistently have a Name field (or Names, +in the case of type Value), Type.Factories has become +Type.Funcs, and there is a new type Method that describes +methods in more detail. +Instead of calling doc.NewPackageDoc(pkg, importpath), +documentation for a package is created with: +

+ +
+    doc.New(pkg, importpath, mode)
+
+ +

+where the new mode parameter specifies the operation mode: +if set to AllDecls, all declarations +(not just exported ones) are considered. +The function NewFileDoc was removed, and the function +CommentText has become the method +Text of +ast.CommentGroup. +

+ +

+In package go/token, the +token.FileSet method Files +(which originally returned a channel of *token.Files) has been replaced +with the iterator Iterate that +accepts a function argument instead. +

+ +

+Updating: +Code that uses packages in go will have to be updated by hand; the +compiler will reject incorrect uses. Templates used in conjuction with any of the +go/doc types may need manual fixes; the renamed fields will lead +to run-time errors. +

+ +

The hash package

@@ -763,6 +990,80 @@ apply to any activity on the connection, the new methods set an absolute deadline (as a time.Time value) after which reads and writes will time out and no longer block.

+

The os.FileInfo type

+ +

+Go 1 redefines the os.FileInfo type, +changing it from a struct to an interface: +

+ +
+    type FileInfo interface {
+        Name() string       // base name of the file
+        Size() int64        // length in bytes
+        Mode() FileMode     // file mode bits
+        ModTime() time.Time // modification time
+        IsDir() bool        // abbreviation for Mode().IsDir()
+    }
+
+ +

+The file mode information has been moved into a subtype called +os.FileMode, +a simple integer type with IsDir, Perm, and String +methods. +

+ +

+The system-specific details of file modes and properties such as (on Unix) +i-number have been removed from FileInfo altogether. +Instead, each operating system's os package provides an +implementation of the FileInfo interface, *os.FileStat, +which in turn contains a Sys 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 FileInfo like this: +

+ +
+    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)
+
+ +

+Assuming (which is unwise) that "hello.go" is a Unix file, +the i-number expression could be contracted to +

+ +
+    fi.(*os.FileStat).Sys.(*syscall.Stat_t).Ino
+
+ +

+The vast majority of uses of FileInfo need only the methods +of the standard interface. +

+ +

+Updating: +Gofix will update code that uses the old equivalent of the current os.FileInfo +and os.FileMode API. +Code that needs system-specific file details will need to be updated by hand. +

+

The strconv package

@@ -857,248 +1158,6 @@ they may require a cast that must be added by hand; gofix will warn about it.

-

The os.FileInfo type

- -

-Go 1 redefines the os.FileInfo type, -changing it from a struct to an interface: -

- -
-    type FileInfo interface {
-        Name() string       // base name of the file
-        Size() int64        // length in bytes
-        Mode() FileMode     // file mode bits
-        ModTime() time.Time // modification time
-        IsDir() bool        // abbreviation for Mode().IsDir()
-    }
-
- -

-The file mode information has been moved into a subtype called -os.FileMode, -a simple integer type with IsDir, Perm, and String -methods. -

- -

-The system-specific details of file modes and properties such as (on Unix) -i-number have been removed from FileInfo altogether. -Instead, each operating system's os package provides an -implementation of the FileInfo interface, *os.FileStat, -which in turn contains a Sys 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 FileInfo like this: -

- -
-    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)
-
- -

-Assuming (which is unwise) that "hello.go" is a Unix file, -the i-number expression could be contracted to -

- -
-    fi.(*os.FileStat).Sys.(*syscall.Stat_t).Ino
-
- -

-The vast majority of uses of FileInfo need only the methods -of the standard interface. -

- -

-Updating: -Gofix will update code that uses the old equivalent of the current os.FileInfo -and os.FileMode API. -Code that needs system-specific file details will need to be updated by hand. -

- -

The package tree go

- -

-Several packages under go have slightly revised APIs. -

- -

-The modes AllowIllegalChars and InsertSemis have been removed -from the go/scanner package. They were mostly -useful for scanning text other then Go source files. Instead, the -text/scanner package should be used -for that purpose. -

- -

-The set of parse functions provided by the go/parser -package has been reduced to the primary parse function -ParseFile, and a couple of -convenience functions ParseDir -and ParseExpr. -

- -

-The type names of the go/doc package have been -streamlined by removing the Doc suffix: PackageDoc -is now Package, ValueDoc -is Value, etc. -Also, all types now consistently have a Name field (or Names, -in the case of type Value), Type.Factories has become -Type.Funcs, and there is a new type -Method that describes methods in -more detail. -Instead of calling doc.NewPackageDoc(pkg, importpath), -documentation for a package is created with: -

- -
-    doc.New(pkg, importpath, mode)
-
- -

-where the new mode parameter specifies the operation -Mode: if set to -AllDecls, all declarations (not just exported ones) are considered. -The function NewFileDoc was removed, and the function -CommentText has become the method -Text of -ast.CommentGroup. -

- -

-In package go/token, the -token.FileSet method Files -(which originally returned a channel of *token.Files) has been replaced -with the iterator Iterate that -accepts a function argument instead. -

- -

-Updating: -Code that uses these packages in go will have to be updated by hand; -the compiler will reject incorrect uses. Templates used in conjuction with any of the -go/doc types may need manual fixes; the renamed -fields will lead to run-time errors. -

- -

The package tree exp

- -

-Because they are not standardized, the packages under the exp directory will not be available in the -standard Go 1 release distributions, although they will be available in source code form -in the repository for -developers who wish to use them. -

- -

-Several packages have moved under exp at the time of Go 1's release: -

- - - -

-Also, the utf8.String type has been moved to its own package, exp/utf8string. -

- -

-All these packages are available under the same names, with exp/ prefixed: exp/ebnf etc. -

- -

-Also, the gotype command now resides in exp/gotype, while -ebnflint is now in exp/ebnflint -

- -

-Updating: -Code that uses packages in exp will need to be updated by hand, -or else compiled from an installation that has exp available. -Gofix or the compiler will complain about such uses. -
-TODO: gofix should warn about such uses. -

- -

The package tree old

- -

-Because they are deprecated, the packages under the old directory will not be available in the -standard Go 1 release distributions, although they will be available in source code form for -developers who wish to use them. -

- -

-The packages in their new locations are: -

- - - -

-Updating: -Code that uses packages now in old will need to be updated by hand, -or else compiled from an installation that has old available. -Gofix will warn about such uses. -
-TODO: gofix should warn about such uses. -

- -

Deleted packages

- -

-Go 1 deletes several packages outright: -

- - - -

-and also the command gotry. -

- -

-Updating: -Code that uses container/vector should be updated to use -slices directly. See -the Go -Language Community Wiki for some suggestions. -Code that uses the other packages (there should be almost zero) will need to be rethought. -
-TODO: gofix should warn such uses. -

- -

Packages moving to subrepositories

- -

The go command

diff --git a/doc/go1.tmpl b/doc/go1.tmpl index ff58d16c34..0518d08139 100644 --- a/doc/go1.tmpl +++ b/doc/go1.tmpl @@ -374,7 +374,13 @@ Few programs will be affected, but the fix may require some redesign.

-

Changes to the library

+

The package hierarchy

+ +

+This section describes how the packages have been rearranged in Go 1. +Some have moved, some have been renamed, some have been deleted. +New packages are described in later sections. +

The package hierarchy

@@ -462,6 +468,116 @@ by hand. TODO: gofix should also handle packages that move to subrepos.

+

The package tree exp

+ +

+Because they are not standardized, the packages under the exp directory will not be available in the +standard Go 1 release distributions, although they will be available in source code form +in the repository for +developers who wish to use them. +

+ +

+Several packages have moved under exp at the time of Go 1's release: +

+ + + +

+Also, the utf8.String type has been moved to its own package, exp/utf8string. +

+ +

+All these packages are available under the same names, with exp/ prefixed: exp/ebnf etc. +

+ +

+Also, the gotype command now resides in exp/gotype, while +ebnflint is now in exp/ebnflint +

+ +

+Updating: +Code that uses packages in exp will need to be updated by hand, +or else compiled from an installation that has exp available. +Gofix or the compiler will complain about such uses. +
+TODO: gofix should warn about such uses. +

+ +

The package tree old

+ +

+Because they are deprecated, the packages under the old directory will not be available in the +standard Go 1 release distributions, although they will be available in source code form for +developers who wish to use them. +

+ +

+The packages in their new locations are: +

+ + + +

+Updating: +Code that uses packages now in old will need to be updated by hand, +or else compiled from an installation that has old available. +Gofix will warn about such uses. +
+TODO: gofix should warn about such uses. +

+ +

Deleted packages

+ +

+Go 1 deletes several packages outright: +

+ + + +

+and also the command gotry. +

+ +

+Updating: +Code that uses container/vector should be updated to use +slices directly. See +the Go +Language Community Wiki for some suggestions. +Code that uses the other packages (there should be almost zero) will need to be rethought. +
+TODO: gofix should warn such uses. +

+ +

Packages moving to subrepositories

+ + + +

Major changes to the library

+ +

+This section describes significant changes to the core libraries, the ones that +affect the most programs. +

+

The error type and errors package

@@ -592,7 +708,16 @@ the correct function or method for the old functionality, but may have the wrong type or require further analysis.

-

The crypto/elliptic package

+

Minor changes to the library

+ +

+This section describes smaller changes, such as those to less commonly +used packages or that affect +few programs beyond the need to run gofix. +This category includes packages that are new in Go 1. +

+ +

The crypto/elliptic package

In Go 1, elliptic.Curve @@ -611,7 +736,7 @@ in crypto/elliptic that take an elliptic.Curve as their first argument.

-

The crypto/x509 package

+

The crypto/x509 package

In Go 1, the @@ -629,6 +754,71 @@ to be implemented in the future. No changes will be needed.

+

The go/* packages

+ +

+Several packages under go have slightly revised APIs. +

+ +

+The modes AllowIllegalChars and InsertSemis have been removed +from the go/scanner package. They were mostly +useful for scanning text other then Go source files. Instead, the +text/scanner package should be used +for that purpose. +

+ +

+The set of parse functions provided by the go/parser +package has been reduced to the primary parse function +ParseFile, and a couple of +convenience functions ParseDir +and ParseExpr. +

+ +

+The type names of the go/doc package have been +streamlined by removing the Doc suffix: PackageDoc +is now Package, ValueDoc is Value, etc. +Also, all types now consistently have a Name field (or Names, +in the case of type Value), Type.Factories has become +Type.Funcs, and there is a new type Method that describes +methods in more detail. +Instead of calling doc.NewPackageDoc(pkg, importpath), +documentation for a package is created with: +

+ +
+    doc.New(pkg, importpath, mode)
+
+ +

+where the new mode parameter specifies the operation mode: +if set to AllDecls, all declarations +(not just exported ones) are considered. +The function NewFileDoc was removed, and the function +CommentText has become the method +Text of +ast.CommentGroup. +

+ +

+In package go/token, the +token.FileSet method Files +(which originally returned a channel of *token.Files) has been replaced +with the iterator Iterate that +accepts a function argument instead. +

+ +

+Updating: +Code that uses packages in go will have to be updated by hand; the +compiler will reject incorrect uses. Templates used in conjuction with any of the +go/doc types may need manual fixes; the renamed fields will lead +to run-time errors. +

+ +

The hash package

@@ -704,6 +894,80 @@ apply to any activity on the connection, the new methods set an absolute deadline (as a time.Time value) after which reads and writes will time out and no longer block.

+

The os.FileInfo type

+ +

+Go 1 redefines the os.FileInfo type, +changing it from a struct to an interface: +

+ +
+    type FileInfo interface {
+        Name() string       // base name of the file
+        Size() int64        // length in bytes
+        Mode() FileMode     // file mode bits
+        ModTime() time.Time // modification time
+        IsDir() bool        // abbreviation for Mode().IsDir()
+    }
+
+ +

+The file mode information has been moved into a subtype called +os.FileMode, +a simple integer type with IsDir, Perm, and String +methods. +

+ +

+The system-specific details of file modes and properties such as (on Unix) +i-number have been removed from FileInfo altogether. +Instead, each operating system's os package provides an +implementation of the FileInfo interface, *os.FileStat, +which in turn contains a Sys 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 FileInfo like this: +

+ +
+    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)
+
+ +

+Assuming (which is unwise) that "hello.go" is a Unix file, +the i-number expression could be contracted to +

+ +
+    fi.(*os.FileStat).Sys.(*syscall.Stat_t).Ino
+
+ +

+The vast majority of uses of FileInfo need only the methods +of the standard interface. +

+ +

+Updating: +Gofix will update code that uses the old equivalent of the current os.FileInfo +and os.FileMode API. +Code that needs system-specific file details will need to be updated by hand. +

+

The strconv package

@@ -798,246 +1062,6 @@ they may require a cast that must be added by hand; gofix will warn about it.

-

The os.FileInfo type

- -

-Go 1 redefines the os.FileInfo type, -changing it from a struct to an interface: -

- -
-    type FileInfo interface {
-        Name() string       // base name of the file
-        Size() int64        // length in bytes
-        Mode() FileMode     // file mode bits
-        ModTime() time.Time // modification time
-        IsDir() bool        // abbreviation for Mode().IsDir()
-    }
-
- -

-The file mode information has been moved into a subtype called -os.FileMode, -a simple integer type with IsDir, Perm, and String -methods. -

- -

-The system-specific details of file modes and properties such as (on Unix) -i-number have been removed from FileInfo altogether. -Instead, each operating system's os package provides an -implementation of the FileInfo interface, *os.FileStat, -which in turn contains a Sys 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 FileInfo like this: -

- -
-    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)
-
- -

-Assuming (which is unwise) that "hello.go" is a Unix file, -the i-number expression could be contracted to -

- -
-    fi.(*os.FileStat).Sys.(*syscall.Stat_t).Ino
-
- -

-The vast majority of uses of FileInfo need only the methods -of the standard interface. -

- -

-Updating: -Gofix will update code that uses the old equivalent of the current os.FileInfo -and os.FileMode API. -Code that needs system-specific file details will need to be updated by hand. -

- -

The package tree go

- -

-Several packages under go have slightly revised APIs. -

- -

-The modes AllowIllegalChars and InsertSemis have been removed -from the go/scanner package. They were mostly -useful for scanning text other then Go source files. Instead, the -text/scanner package should be used -for that purpose. -

- -

-The set of parse functions provided by the go/parser -package has been reduced to the primary parse function -ParseFile, and a couple of -convenience functions ParseDir -and ParseExpr. -

- -

-The type names of the go/doc package have been -streamlined by removing the Doc suffix: PackageDoc -is now Package, ValueDoc is Value, etc. -Also, all types now consistently have a Name field (or Names, -in the case of type Value), Type.Factories has become -Type.Funcs, and there is a new type Method that describes -methods in more detail. -Instead of calling doc.NewPackageDoc(pkg, importpath), -documentation for a package is created with: -

- -
-    doc.New(pkg, importpath, mode)
-
- -

-where the new mode parameter specifies the operation mode: -if set to AllDecls, all declarations -(not just exported ones) are considered. -The function NewFileDoc was removed, and the function -CommentText has become the method -Text of -ast.CommentGroup. -

- -

-In package go/token, the -token.FileSet method Files -(which originally returned a channel of *token.Files) has been replaced -with the iterator Iterate that -accepts a function argument instead. -

- -

-Updating: -Code that uses packages in go will have to be updated by hand; the -compiler will reject incorrect uses. Templates used in conjuction with any of the -go/doc types may need manual fixes; the renamed fields will lead -to run-time errors. -

- -

The package tree exp

- -

-Because they are not standardized, the packages under the exp directory will not be available in the -standard Go 1 release distributions, although they will be available in source code form -in the repository for -developers who wish to use them. -

- -

-Several packages have moved under exp at the time of Go 1's release: -

- - - -

-Also, the utf8.String type has been moved to its own package, exp/utf8string. -

- -

-All these packages are available under the same names, with exp/ prefixed: exp/ebnf etc. -

- -

-Also, the gotype command now resides in exp/gotype, while -ebnflint is now in exp/ebnflint -

- -

-Updating: -Code that uses packages in exp will need to be updated by hand, -or else compiled from an installation that has exp available. -Gofix or the compiler will complain about such uses. -
-TODO: gofix should warn about such uses. -

- -

The package tree old

- -

-Because they are deprecated, the packages under the old directory will not be available in the -standard Go 1 release distributions, although they will be available in source code form for -developers who wish to use them. -

- -

-The packages in their new locations are: -

- - - -

-Updating: -Code that uses packages now in old will need to be updated by hand, -or else compiled from an installation that has old available. -Gofix will warn about such uses. -
-TODO: gofix should warn about such uses. -

- -

Deleted packages

- -

-Go 1 deletes several packages outright: -

- - - -

-and also the command gotry. -

- -

-Updating: -Code that uses container/vector should be updated to use -slices directly. See -the Go -Language Community Wiki for some suggestions. -Code that uses the other packages (there should be almost zero) will need to be rethought. -
-TODO: gofix should warn such uses. -

- -

Packages moving to subrepositories

- -

The go command