From 3e2dd57cc0bccd7ad5cf5b2be1fe0fe9cbde7a7f Mon Sep 17 00:00:00 2001 From: HadesHappy Date: Fri, 4 Mar 2022 13:20:20 -0500 Subject: [PATCH] gotypes: add a link to the 1.18 API guide, and fix links Update the go/types guide to have a link to the new 1.18 API guide, for now. Also fix some links to pkg.go.dev and golang.org/x that were amended in the autogenerated README.md rather than the original source. For golang/go#50676 Change-Id: Ib98ed095d74be02046c426e51f1ae2b9ceb03b0d Reviewed-on: https://go-review.googlesource.com/c/example/+/389656 Trust: Robert Findley Run-TryBot: Robert Findley Reviewed-by: Robert Griesemer TryBot-Result: Gopher Robot --- gotypes/README.md | 18 +++++++++++++----- gotypes/defsuses/main.go | 2 +- gotypes/go-types.md | 35 +++++++++++++++++++++-------------- gotypes/implements/main.go | 2 +- gotypes/lookup/lookup.go | 2 +- gotypes/nilfunc/main.go | 2 +- gotypes/pkginfo/main.go | 2 +- gotypes/typeandvalue/main.go | 2 +- 8 files changed, 40 insertions(+), 25 deletions(-) diff --git a/gotypes/README.md b/gotypes/README.md index e6883f5..f625f6b 100644 --- a/gotypes/README.md +++ b/gotypes/README.md @@ -9,6 +9,7 @@ This document is maintained by Alan Donovan `adonovan@google.com`. # Contents +1. [Changes in Go 1.18](#changes-in-go-1.18) 1. [Introduction](#introduction) 1. [An Example](#an-example) 1. [Objects](#objects) @@ -33,6 +34,13 @@ This document is maintained by Alan Donovan `adonovan@google.com`. 1. [Formatting support](#formatting-support) 1. [Getting from A to B](#getting-from-a-to-b) +# Changes in Go 1.18 + +Go 1.18 introduces generic Go code, and several corresponding new APIs for +`go/types`. This document is not yet up-to-date for these changes, but a guide +to the new changes exists at +[`x/exp/typeparams/example`](https://github.com/golang/exp/tree/master/typeparams/example). + # Introduction @@ -995,7 +1003,7 @@ Use this function instead: For the same reason, you should not use a `Type` as a key in a map. -The [`golang.org/x/tools/go/types/typeutil` package](https://godoc.org/golang.org/x/tools/go/types/typeutil) +The [`golang.org/x/tools/go/types/typeutil` package](https://pkg.go.dev/golang.org/x/tools/go/types/typeutil) provides a map keyed by types that uses the correct equivalence relation. @@ -2225,7 +2233,7 @@ function. Here's a typical invocation on the standard `encoding/xml` package. It reports a number of places where the 7-word -[`StartElement` type](https://godoc.org/encoding/xml#StartElement) +[`StartElement` type](https://pkg.go.dev/encoding/xml#StartElement) is copied. @@ -2288,7 +2296,7 @@ ran a `go install` or `go build -i` command. -The [`golang.org/tools/x/go/loader` package](https://godoc.org/golang.org/x/tools/go/loader) +The [`golang.org/tools/x/go/loader` package](https://pkg.go.dev/golang.org/x/tools/go/loader) provides an alternative `Importer` that addresses some of these problems. It loads a complete program from source, performing @@ -2524,13 +2532,13 @@ of the form "I have an A; I need the corresponding B". To map **from a `token.Pos` to an `ast.Node`**, call the helper function -[`astutil.PathEnclosingInterval`](https://godoc.org/golang.org/x/tools/go/ast/astutil#PathEnclosingInterval). +[`astutil.PathEnclosingInterval`](https://pkg.go.dev/golang.org/x/tools/go/ast/astutil#PathEnclosingInterval). It returns the enclosing `ast.Node`, and all its ancestors up to the root of the file. You must know which file `*ast.File` the `token.Pos` belongs to. Alternatively, you can search an entire program loaded by the `loader` package, using -[`(*loader.Program).PathEnclosingInterval`](https://godoc.org/golang.org/x/tools/go/loader#Program.PathEnclosingInterval). +[`(*loader.Program).PathEnclosingInterval`](https://pkg.go.dev/golang.org/x/tools/go/loader#Program.PathEnclosingInterval). diff --git a/gotypes/defsuses/main.go b/gotypes/defsuses/main.go index 608c529..5347f48 100644 --- a/gotypes/defsuses/main.go +++ b/gotypes/defsuses/main.go @@ -58,7 +58,7 @@ func main() { /* //!+output -$ go build github.com/golang/example/gotypes/defsuses +$ go build golang.org/x/example/gotypes/defsuses $ ./defsuses hello.go:1:9: "main" defines hello.go:5:6: "main" defines func hello.main() diff --git a/gotypes/go-types.md b/gotypes/go-types.md index d59516a..4cd3d81 100644 --- a/gotypes/go-types.md +++ b/gotypes/go-types.md @@ -10,6 +10,13 @@ This document is maintained by Alan Donovan `adonovan@google.com`. %toc +# Changes in Go 1.18 + +Go 1.18 introduces generics, and several corresponding new APIs for `go/types`. +This document is not yet up-to-date for these changes, but a guide to the new +changes exists at +[`x/exp/typeparams/example`](https://github.com/golang/exp/tree/master/typeparams/example). + # Introduction @@ -55,7 +62,7 @@ constant expressions, as we'll see in -The [`golang.org/x/tools/go/loader` package](https://godoc.org/golang.org/x/tools/go/loader) +The [`golang.org/x/tools/go/loader` package](https://pkg.go.dev/golang.org/x/tools/go/loader) from the `x/tools` repository is a client of the type checker that loads, parses, and type-checks a complete Go program from source code. @@ -110,7 +117,7 @@ the _hello, world_ program, supplied as a string. Later examples will be variations on this one, and we'll often omit boilerplate details such as parsing. To check out and build the examples, -run `go get github.com/golang/example/gotypes/...`. +run `go get golang.org/x/example/gotypes/...`. %include pkginfo/main.go @@ -142,7 +149,7 @@ how to locate the imported packages. Here we use `importer.Default()`, which loads compiler-generated export data, but we'll explore alternatives in [Imports](#imports). - + Fourth, the program calls `Check`. This creates a `Package` whose path is `"cmd/hello"`, and @@ -602,7 +609,7 @@ by calling its `(*Func).Scope` method. @@ -668,7 +675,7 @@ does a name lookup at a specific position in that lexical block. -A typical input is shown below. +A typical input is shown below. The first comment causes a lookup of `"append"` in the file block. The second comment looks up `"fmt"` in the `main` function's block, and so on. @@ -814,7 +821,7 @@ Use this function instead: For the same reason, you should not use a `Type` as a key in a map. -The [`golang.org/x/tools/go/types/typeutil` package](https://godoc.org/golang.org/x/tools/go/types/typeutil) +The [`golang.org/x/tools/go/types/typeutil` package](https://pkg.go.dev/golang.org/x/tools/go/types/typeutil) provides a map keyed by types that uses the correct equivalence relation. @@ -996,7 +1003,7 @@ The type checker builds the exact same data structures given this input: A similar issue applies to the methods of named interface types. - + ## Tuple Types @@ -1230,7 +1237,7 @@ interface `v`, then the type assertion is not legal, as in this example: // error: io.Writer is not assertible to int - func f(w io.Writer) int { return w.(int) } + func f(w io.Writer) int { return w.(int) } @@ -1443,7 +1450,7 @@ all.) The final two parameters of `LookupFieldOrMethod` are `(pkg -*Package, name string)`. +*Package, name string)`. Together they specify the name of the field or method to look up. This brings us to `Id`s. @@ -1654,7 +1661,7 @@ Constants are represented using the `Value` interface from the package constant // go/constant type Value interface { - Kind() Kind + Kind() Kind } type Kind int // one of Unknown, Bool, String, Int, Float, Complex @@ -1787,7 +1794,7 @@ function. Here's a typical invocation on the standard `encoding/xml` package. It reports a number of places where the 7-word -[`StartElement` type](https://godoc.org/encoding/xml#StartElement) +[`StartElement` type](https://pkg.go.dev/encoding/xml#StartElement) is copied. @@ -1843,7 +1850,7 @@ ran a `go install` or `go build -i` command. -The [`golang.org/tools/x/go/loader` package](https://godoc.org/golang.org/x/tools/go/loader) +The [`golang.org/tools/x/go/loader` package](https://pkg.go.dev/golang.org/x/tools/go/loader) provides an alternative `Importer` that addresses some of these problems. It loads a complete program from source, performing @@ -2025,13 +2032,13 @@ of the form "I have an A; I need the corresponding B". To map **from a `token.Pos` to an `ast.Node`**, call the helper function -[`astutil.PathEnclosingInterval`](https://godoc.org/golang.org/x/tools/go/ast/astutil#PathEnclosingInterval). +[`astutil.PathEnclosingInterval`](https://pkg.go.dev/golang.org/x/tools/go/ast/astutil#PathEnclosingInterval). It returns the enclosing `ast.Node`, and all its ancestors up to the root of the file. You must know which file `*ast.File` the `token.Pos` belongs to. Alternatively, you can search an entire program loaded by the `loader` package, using -[`(*loader.Program).PathEnclosingInterval`](https://godoc.org/golang.org/x/tools/go/loader#Program.PathEnclosingInterval). +[`(*loader.Program).PathEnclosingInterval`](https://pkg.go.dev/golang.org/x/tools/go/loader#Program.PathEnclosingInterval). diff --git a/gotypes/implements/main.go b/gotypes/implements/main.go index d7e5701..70b4ee5 100644 --- a/gotypes/implements/main.go +++ b/gotypes/implements/main.go @@ -68,7 +68,7 @@ func main() { /* //!+output -$ go build github.com/golang/example/gotypes/implements +$ go build golang.org/x/example/gotypes/implements $ ./implements *hello.A satisfies hello.I hello.B satisfies hello.I diff --git a/gotypes/lookup/lookup.go b/gotypes/lookup/lookup.go index 9bdc97d..4313e2e 100644 --- a/gotypes/lookup/lookup.go +++ b/gotypes/lookup/lookup.go @@ -65,7 +65,7 @@ func main() { /* //!+output -$ go build github.com/golang/example/gotypes/lookup +$ go build golang.org/x/example/gotypes/lookup $ ./lookup At hello.go:6:1, "append" = builtin append At hello.go:8:9, "fmt" = package fmt diff --git a/gotypes/nilfunc/main.go b/gotypes/nilfunc/main.go index da4b79b..2dbb19c 100644 --- a/gotypes/nilfunc/main.go +++ b/gotypes/nilfunc/main.go @@ -95,7 +95,7 @@ func CheckNilFuncComparison(info *types.Info, n ast.Node) { /* //!+output -$ go build github.com/golang/example/gotypes/nilfunc +$ go build golang.org/x/example/gotypes/nilfunc $ ./nilfunc input.go:7:5: comparison of function Bytes == nil is always false input.go:7:25: comparison of function Repeat != nil is always true diff --git a/gotypes/pkginfo/main.go b/gotypes/pkginfo/main.go index 3050f80..957e01b 100644 --- a/gotypes/pkginfo/main.go +++ b/gotypes/pkginfo/main.go @@ -52,7 +52,7 @@ func main() { /* //!+output -$ go build github.com/golang/example/gotypes/pkginfo +$ go build golang.org/x/example/gotypes/pkginfo $ ./pkginfo Package "cmd/hello" Name: main diff --git a/gotypes/typeandvalue/main.go b/gotypes/typeandvalue/main.go index 8a6fc79..7b3b553 100644 --- a/gotypes/typeandvalue/main.go +++ b/gotypes/typeandvalue/main.go @@ -96,7 +96,7 @@ func mode(tv types.TypeAndValue) string { /* //!+output -$ go build github.com/golang/example/gotypes/typeandvalue +$ go build golang.org/x/example/gotypes/typeandvalue $ ./typeandvalue make(map[string]int) mode: value type: map[string]int