From ebdcbf1cdc3309c6cd234d93ae033937ce89a1fb Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Mon, 12 Dec 2011 12:26:56 -0800 Subject: [PATCH] doc/go1: the simpler package changes R=golang-dev, fullung, dsymonds, r, adg CC=golang-dev https://golang.org/cl/5477056 --- doc/go1.html | 176 +++++++++++++++++++++++++++++++++++++++-------- doc/go1.tmpl | 164 +++++++++++++++++++++++++++++++++++-------- doc/progs/go1.go | 26 +++++++ 3 files changed, 310 insertions(+), 56 deletions(-) diff --git a/doc/go1.html b/doc/go1.html index ae9ea283401..dee680add6b 100644 --- a/doc/go1.html +++ b/doc/go1.html @@ -217,7 +217,7 @@ Go 1 introduces a new built-in type, error, which has the following

Since the consequences of this type are all in the package library, -it is discussed below. +it is discussed below.

Deleting from maps

@@ -547,15 +547,73 @@ by hand.

The error type and errors package

+

+As mentioned above, Go 1 introduces a new built-in interface type called error. +Its intent is to replace the old os.Error type with a more central concept. +So the widely-used String method does not cause accidental satisfaction +of the error interface, the error interface uses instead +the name Error for that method: +

+ +
+    type error interface {
+        Error() string
+    }
+
+ +

+The fmt library automatically invokes Error, as it already +does for String, for easy printing of error values. +

+ +
type SyntaxError struct {
+    File    string
+    Line    int
+    Message string
+}
+
+func (se *SyntaxError) Error() string {
+    return fmt.Sprintf("%s:%d: %s", se.File, se.Line, se.Message)
+}
+
+ +

+All standard packages have been updated to use the new interface; the old os.Error is gone. +

+ +

+A new package, errors, contains the function +

+ +
+func New(text string) error
+
+ +

+to turn a string into an error. It replaces the old os.NewError. +

+ +
    var ErrSyntax = errors.New("syntax error")
+
+ +

+Updating: +Gofix will update almost all code affected by the change. +Code that defines error types with a String method will need to be updated +by hand to rename the methods to Error. +

+

System call errors

In Go 1, the -syscall +syscall package returns an error for system call errors, rather than plain integer errno values. On Unix, the implementation is done by a -syscall.Errno type +syscall.Errno type that satisfies error and replaces the old os.Errno.

@@ -568,15 +626,13 @@ rather than syscall and so will be unaffected.

Time

-

The html package

-

The http package

The strconv package

In Go 1, the -strconv +strconv package has been significantly reworked to make it more Go-like and less C-like, although Atoi lives on (it's similar to int(ParseInt(x, 10, 0)), as does @@ -587,7 +643,7 @@ return strings, to allow control over allocation.

This table summarizes the renamings; see the -package documentation +package documentation for full details.

@@ -666,33 +722,99 @@ they may require a cast that must be added by hand; gofix will warn about it.

+

The os.FileInfo type

+

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

+ + + +

+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 will warn 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

- +

+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

@@ -701,8 +823,6 @@ crypto/openpgp to XXX maybe exp/ssh? --> -

The os.FileInfo type

-

The go command

Packaged releases

diff --git a/doc/go1.tmpl b/doc/go1.tmpl index 2d1c2948a23..c830b3572ca 100644 --- a/doc/go1.tmpl +++ b/doc/go1.tmpl @@ -163,7 +163,7 @@ Go 1 introduces a new built-in type, error, which has the following

Since the consequences of this type are all in the package library, -it is discussed below. +it is discussed below.

Deleting from maps

@@ -462,15 +462,61 @@ by hand.

The error type and errors package

+

+As mentioned above, Go 1 introduces a new built-in interface type called error. +Its intent is to replace the old os.Error type with a more central concept. +So the widely-used String method does not cause accidental satisfaction +of the error interface, the error interface uses instead +the name Error for that method: +

+ +
+    type error interface {
+        Error() string
+    }
+
+ +

+The fmt library automatically invokes Error, as it already +does for String, for easy printing of error values. +

+ +{{code "progs/go1.go" `/START ERROR EXAMPLE/` `/END ERROR EXAMPLE/`}} + +

+All standard packages have been updated to use the new interface; the old os.Error is gone. +

+ +

+A new package, errors, contains the function +

+ +
+func New(text string) error
+
+ +

+to turn a string into an error. It replaces the old os.NewError. +

+ +{{code "progs/go1.go" `/ErrSyntax/`}} + +

+Updating: +Gofix will update almost all code affected by the change. +Code that defines error types with a String method will need to be updated +by hand to rename the methods to Error. +

+

System call errors

In Go 1, the -syscall +syscall package returns an error for system call errors, rather than plain integer errno values. On Unix, the implementation is done by a -syscall.Errno type +syscall.Errno type that satisfies error and replaces the old os.Errno.

@@ -483,15 +529,13 @@ rather than syscall and so will be unaffected.

Time

-

The html package

-

The http package

The strconv package

In Go 1, the -strconv +strconv package has been significantly reworked to make it more Go-like and less C-like, although Atoi lives on (it's similar to int(ParseInt(x, 10, 0)), as does @@ -502,7 +546,7 @@ return strings, to allow control over allocation.

This table summarizes the renamings; see the -package documentation +package documentation for full details.

@@ -581,33 +625,99 @@ they may require a cast that must be added by hand; gofix will warn about it.

+

The os.FileInfo type

+

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

+ + + +

+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 will warn 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

- +

+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

@@ -616,8 +726,6 @@ crypto/openpgp to XXX maybe exp/ssh? --> -

The os.FileInfo type

-

The go command

Packaged releases

diff --git a/doc/progs/go1.go b/doc/progs/go1.go index caceb0513cf..54b7d206674 100644 --- a/doc/progs/go1.go +++ b/doc/progs/go1.go @@ -7,6 +7,8 @@ package main import ( + "errors" + "fmt" "log" "unicode" ) @@ -19,6 +21,7 @@ func main() { structEquality() compositeLiterals() runeType() + errorExample() } func mapDelete() { @@ -130,6 +133,29 @@ func runeType() { // ENDRUNE OMIT } +// START ERROR EXAMPLE OMIT +type SyntaxError struct { + File string + Line int + Message string +} + +func (se *SyntaxError) Error() string { + return fmt.Sprintf("%s:%d: %s", se.File, se.Line, se.Message) +} +// END ERROR EXAMPLE OMIT + +func errorExample() { + var ErrSyntax = errors.New("syntax error") + _ = ErrSyntax + se := &SyntaxError{"file", 7, "error"} + got := fmt.Sprint(se) + const expect = "file:7: error" + if got != expect { + log.Fatalf("errorsPackage: expected %q got %q", expect, got) + } +} + func f(string, int) { }