gotypes: document proposed Go 1.9 aliases Change-Id: Ib072dd03ae808e774ceffab00fd716875fead445 Reviewed-on: https://go-review.googlesource.com/36721 Reviewed-by: Robert Griesemer <gri@golang.org>
diff --git a/gotypes/README.md b/gotypes/README.md index 5b80b8c..3886945 100644 --- a/gotypes/README.md +++ b/gotypes/README.md
@@ -352,7 +352,7 @@ Object = *Func // function, concrete method, or abstract method | *Var // variable, parameter, result, or struct field | *Const // constant - | *TypeName // named type (except for predeclared ones) + | *TypeName // type name | *Label // statement label | *PkgName // package name, e.g. json after import "encoding/json" | *Builtin // predeclared function such as append or len @@ -396,6 +396,7 @@ func (*Var) Anonymous() bool func (*Var) IsField() bool func (*Const) Val() constant.Value + func (*TypeName) IsAlias() bool // expected in Go 1.9 func (*PkgName) Imported() *Package @@ -408,6 +409,11 @@ `(*Const).Val` returns the value of a named [constant](#constants). +`(*TypeName).IsAlias`, to be introduced in Go 1.9, reports whether the +type name is simply an alias for a type (as in `type I = int`), +as opposed to a definition of a [`Named`](#named-types) type, as +in `type Celsius float64`. + `(*PkgName).Imported` returns the package (for instance, `encoding/json`) denoted by a given import name such as `json`. @@ -1251,11 +1257,37 @@ ## Named Types -A type declaration creates a `TypeName` object, and the type of -that object is a `Named`. -These two entities, an object and a type, are distinct but closely -related, and they exist in one-to-one correspondence. +Type declarations come in two forms. +The simplest kind, to be introduced in Go 1.9, +merely declares a (possibly alternative) name for an existing type. +Type names used in this way are informally called _type aliases_. +For example, this declaration lets you use the type +`Dictionary` as an alias for `map[string]string`: + type Dictionary = map[string]string + +The declaration creates a `TypeName` object for `Dictionary`. The +object's `IsAlias` method returns true, and its `Type` method returns +a `Map` type that represents `map[string]string`. + + +The second form of type declaration, and the only kind prior to Go +1.9, does not use an equals sign: + + type Celsius float64 + +This declaration does more than just give a name to a type. +It first defines a new `Named` type +whose underlying type is `float64`; this `Named` type is different +from any other type, including `float64`. The declaration binds the +`TypeName` object to the `Named` type. + +Since Go 1.9, the Go language specification has used the term _defined +types_ instead of named types; +the essential property of a defined type is not that it has a name, +but that it is a distinct type with its own method set. +However, the type checker API predates that +change and instead calls defined types "named" types. type Named struct{ ... } func (*Named) NumMethods() int @@ -1263,13 +1295,14 @@ func (*Named) Obj() *TypeName func (*Named) Underlying() Type - The `Named` type's `Obj` method returns the `TypeName` object, which provides the name, position, and other properties of the declaration. Conversely, the `TypeName` object's `Type` method returns the `Named` type. - - +A `Named` type may appear as the receiver type in a method declaration. +Methods are associated with the `Named` type, not the name (the +`TypeName` object); it's possible---though cryptic---to declare a +method on a `Named` type using one of its aliases. The `NumMethods` and `Method` methods enumerate the declared methods associated with this `Named` type (or a pointer to it), in the order they were declared.
diff --git a/gotypes/go-types.md b/gotypes/go-types.md index 07ee3e3..9dccc68 100644 --- a/gotypes/go-types.md +++ b/gotypes/go-types.md
@@ -269,7 +269,7 @@ Object = *Func // function, concrete method, or abstract method | *Var // variable, parameter, result, or struct field | *Const // constant - | *TypeName // named type (except for predeclared ones) + | *TypeName // type name | *Label // statement label | *PkgName // package name, e.g. json after import "encoding/json" | *Builtin // predeclared function such as append or len @@ -313,6 +313,7 @@ func (*Var) Anonymous() bool func (*Var) IsField() bool func (*Const) Val() constant.Value + func (*TypeName) IsAlias() bool // expected in Go 1.9 func (*PkgName) Imported() *Package @@ -325,6 +326,11 @@ `(*Const).Val` returns the value of a named [constant](#constants). +`(*TypeName).IsAlias`, to be introduced in Go 1.9, reports whether the +type name is simply an alias for a type (as in `type I = int`), +as opposed to a definition of a [`Named`](#named-types) type, as +in `type Celsius float64`. + `(*PkgName).Imported` returns the package (for instance, `encoding/json`) denoted by a given import name such as `json`. @@ -1070,11 +1076,37 @@ ## Named Types -A type declaration creates a `TypeName` object, and the type of -that object is a `Named`. -These two entities, an object and a type, are distinct but closely -related, and they exist in one-to-one correspondence. +Type declarations come in two forms. +The simplest kind, to be introduced in Go 1.9, +merely declares a (possibly alternative) name for an existing type. +Type names used in this way are informally called _type aliases_. +For example, this declaration lets you use the type +`Dictionary` as an alias for `map[string]string`: + type Dictionary = map[string]string + +The declaration creates a `TypeName` object for `Dictionary`. The +object's `IsAlias` method returns true, and its `Type` method returns +a `Map` type that represents `map[string]string`. + + +The second form of type declaration, and the only kind prior to Go +1.9, does not use an equals sign: + + type Celsius float64 + +This declaration does more than just give a name to a type. +It first defines a new `Named` type +whose underlying type is `float64`; this `Named` type is different +from any other type, including `float64`. The declaration binds the +`TypeName` object to the `Named` type. + +Since Go 1.9, the Go language specification has used the term _defined +types_ instead of named types; +the essential property of a defined type is not that it has a name, +but that it is a distinct type with its own method set. +However, the type checker API predates that +change and instead calls defined types "named" types. type Named struct{ ... } func (*Named) NumMethods() int @@ -1082,13 +1114,14 @@ func (*Named) Obj() *TypeName func (*Named) Underlying() Type - The `Named` type's `Obj` method returns the `TypeName` object, which provides the name, position, and other properties of the declaration. Conversely, the `TypeName` object's `Type` method returns the `Named` type. - - +A `Named` type may appear as the receiver type in a method declaration. +Methods are associated with the `Named` type, not the name (the +`TypeName` object); it's possible---though cryptic---to declare a +method on a `Named` type using one of its aliases. The `NumMethods` and `Method` methods enumerate the declared methods associated with this `Named` type (or a pointer to it), in the order they were declared.