internal/encoding/gotypes: implement optional=nillable

This requires recording "facts" about how we generated each Go type,
such as whether it came from a `@go(type=)` override or whether
the resulting Go type is nillable or not.

This now works for inline types, as well as references to generated
local types. References to generated types from imported packages
is left as a TODO for a follow-up, given the size of this patch.

Document the feature as well, and clean up the help text a bit.
For example, it didn't use the same "experimental" prefix
we already used in other commands like `cue mod mirror`.

Fixes #3760.

Signed-off-by: Daniel Martí <[email protected]>
Change-Id: Ib2dd8ace6eb75462ca9247ca06613ab3ba5bcafd
Reviewed-on: https://review.gerrithub.io/c/cue-lang/cue/+/1214380
TryBot-Result: CUEcueckoo <[email protected]>
Unity-Result: CUE porcuepine <[email protected]>
Reviewed-by: Roger Peppe <[email protected]>

Author: mvdan

cmd/cue/cmd/exp.go

@@ -40,52 +40,57 @@ as the objective is to gain experience and then move the feature elsewhere.
 	return cmd
 }
 
-// TODO(mvdan): document the "optional" attribute option when finished.
-
 func newExpGenGoTypesCmd(c *Command) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "gengotypes",
 		Short: "generate Go types from CUE definitions",
-		Long: `
-gengotypes generates Go type definitions from exported CUE definitions.
+		Long: `WARNING: THIS COMMAND IS EXPERIMENTAL.
 
-*This command is experimental and may be changed at any time - see "cue help exp"*
+gengotypes generates Go type definitions from exported CUE definitions.
 
 The generated Go types are guaranteed to accept any value accepted by the CUE definitions,
 but may be more general. For example, "string | int" will translate into the Go
-type "any" because the Go type system is not able to express
-disjunctions.
+type "any" because the Go type system is not able to express disjunctions.
 
 To ensure that the resulting Go code works, any imported CUE packages or
 referenced CUE definitions are transitively generated as well.
-The generated code is placed in cue_types*_gen.go files in the directory of
-each CUE package.
+Generated code is placed in cue_types*_gen.go files in each CUE package directory.
 
 Generated Go type and field names may differ from the original CUE names by default.
 For instance, an exported definition "#foo" becomes "Foo",
-given that Go uses capitalization to export names in a package,
-and a nested definition like "#foo.#bar" becomes "Foo_Bar",
-given that Go does not allow declaring nested types.
+and a nested definition like "#foo.#bar" becomes "Foo_Bar".
 
-@go attributes can be used to override which name or type to be generated, for example:
+@go attributes can be used to override which name to be generated:
 
 	package foo
 	@go(betterpkgname)
 
 	#Bar: {
 		@go(BetterBarTypeName)
 		renamed: int @go(BetterFieldName)
-
-		retypedLocal:  [...string] @go(,type=[]LocalType)
-		retypedImport: [...string] @go(,type=[]"foo.com/bar".ImportedType)
 	}
 
-The attribute "@go(-)" can be used to ignore a definition or field, for example:
+The attribute "@go(-)" can be used to ignore a definition or field:
 
 	#ignoredDefinition: {
 		@go(-)
 	}
 	ignoredField: int @go(-)
+
+"type=" overrides an entire value to generate as a given Go type expression:
+
+	retypedLocal:  [string]: int @go(,type=map[LocalType]int)
+	retypedImport: [...string]   @go(,type=[]"foo.com/bar".ImportedType)
+
+"optional=" controls how CUE optional fields are generated as Go fields.
+The default is "zero", representing a missing field as the zero value.
+"nillable" ensures the generated Go type can represent missing fields as nil.
+
+	optionalDefault?:  int                         // generates as "int64"
+	optionalNillable?: int @go(,optional=nillable) // generates as "*int64"
+	nested: {
+		@go(,optional=nillable) // set for all fields under this struct
+	}
 `[1:],
 		// TODO: write a long help text once the feature set is reasonably stable.
 		RunE: mkRunE(c, runExpGenGoTypes),

cmd/cue/cmd/testdata/script/exp_gengotypes.txtar

@@ -289,19 +289,20 @@ func main() {
 	zeroRoot.Fields.OptionalList = make([]int64, 0)
 	zeroRoot.Fields.OptionalMap = make(map[string]int64, 0)
 
-	zeroRoot.Fields.OptionalTopAttrNillable = (*any)(nil)
-	zeroRoot.Fields.OptionalNullAttrNillable = (**struct{})(nil)
+	zeroRoot.Fields.OptionalTopAttrNillable = (any)(nil)
+	zeroRoot.Fields.OptionalNullAttrNillable = (*struct{})(nil)
 	zeroRoot.Fields.OptionalBasicAttrNillable = (*int64)(nil)
-	zeroRoot.Fields.OptionalListAttrNillable = (*[]int64)(nil)
+	zeroRoot.Fields.OptionalListAttrNillable = ([]int64)(nil)
 
-	zeroRoot.Fields.OptionalInlineMapAttrNillable = (*map[string]int64)(nil)
-	zeroRoot.Fields.OptionalLocalMapAttrNillable = (*root.LocalMap)(nil)
-	zeroRoot.Fields.OptionalInlineNestedAttrNillable = (*struct{F *[]string `json:"f,omitempty"`})(nil)
+	zeroRoot.Fields.OptionalInlineMapAttrNillable = (map[string]int64)(nil)
+	zeroRoot.Fields.OptionalLocalMapAttrNillable = (root.LocalMap)(nil)
+	zeroRoot.Fields.OptionalInlineNestedAttrNillable = (*struct{F []string `json:"f,omitempty"`})(nil)
 	zeroRoot.Fields.OptionalLocalNestedAttrNillable = (*root.LocalNested)(nil)
 
 	// #localNested is not affected by one of the references using optional=nullable.
 	var _ = root.LocalNested{F: []string{}}
 
+	// TODO: we should notice when types from imported packages are nillable already.
 	zeroRootImports.OptionalRemoteMapAttrNillable = (*imported.RemoteMap)(nil)
 	zeroRootImports.OptionalRemoteNestedAttrNillable = (*imported.RemoteNested)(nil)
 
@@ -739,20 +740,20 @@ type Root struct {
 
 		OptionalMap map[string]int64 `json:"optionalMap,omitempty"`
 
-		OptionalTopAttrNillable *any/* CUE top */ `json:"optionalTopAttrNillable,omitempty"`
+		OptionalTopAttrNillable any/* CUE top */ `json:"optionalTopAttrNillable,omitempty"`
 
-		OptionalNullAttrNillable **struct{}/* CUE null */ `json:"optionalNullAttrNillable,omitempty"`
+		OptionalNullAttrNillable *struct{}/* CUE null */ `json:"optionalNullAttrNillable,omitempty"`
 
 		OptionalBasicAttrNillable *int64 `json:"optionalBasicAttrNillable,omitempty"`
 
-		OptionalListAttrNillable *[]int64 `json:"optionalListAttrNillable,omitempty"`
+		OptionalListAttrNillable []int64 `json:"optionalListAttrNillable,omitempty"`
 
-		OptionalInlineMapAttrNillable *map[string]int64 `json:"optionalInlineMapAttrNillable,omitempty"`
+		OptionalInlineMapAttrNillable map[string]int64 `json:"optionalInlineMapAttrNillable,omitempty"`
 
-		OptionalLocalMapAttrNillable *LocalMap `json:"optionalLocalMapAttrNillable,omitempty"`
+		OptionalLocalMapAttrNillable LocalMap `json:"optionalLocalMapAttrNillable,omitempty"`
 
 		OptionalInlineNestedAttrNillable *struct {
-			F *[]string `json:"f,omitempty"`
+			F []string `json:"f,omitempty"`
 		} `json:"optionalInlineNestedAttrNillable,omitempty"`
 
 		OptionalLocalNestedAttrNillable *LocalNested `json:"optionalLocalNestedAttrNillable,omitempty"`