docs/integration/go: review unique content

[jpluscplusm]

https://cuelang.org/docs/integration/go/ contains some content which we didn't find a home when we published https://cuelang.org/docs/concept/how-cue-works-with-go/.

Before #80 removes /docs/integrations/go/, we should review this content and track its placement elsewhere, if merited.

Content

Download CUE definitions from Go packages

Projects, like Kubernetes, do not have to support such conversions. CUE derives the interpretation by analyzing how the Go types convert with encoding/json.

---

Mixing manually-created and generated files The files that the cue tool generates all end with _go_gen.cue. The cue tool will never create, remove, or modify files not ending with _gen.go, so it safe to add such files in these directories to further tighten down definitions. Remember that the order in which files get merged is irrelevant for CUE.

---

Load CUE into Go There are two primary ways to load CUE into Go. To load entire packages, consistent with the cue tool, use the cuelang.org/go/cue/load package. To load CUE parse trees or raw CUE text, use a cuelang.org/go/cue.Runtime.

---

Use a single Runtime For any operation that involves two CUE values these two values must have been created using the same Runtime.

---

Validate Go values The Codec type in package cuelang.org/go/encoding/gocode/gocodec provides the Validate method for validating Go values.

var codec = gocodec.New(r, nil)
var myValueConstraints cue.Value

func (x *MyValue) Validate() error {
    return codec.Validate(myValueConstraints, x)
}

Package cuelang.org/go/encoding/gocode, discussed below, can generate these kind of stubs to make life a bit easier.

---

Complete Go values A gocodec.Codec also defines a Complete method, which is similar to Validate, but fills in missing values if these can be derived from the CUE definitions.

---

Combine CUE values The cue.Value’s Unify method can be used to merge two values. It is the programmatic equivalent of the & operation in the CUE language.

With Unify one can combine constraints from multiple sources programmatically. For instance, one could add some context-dependent policy constraints to a set of base constraints.

---

Copy CUE values into Go values The simplest way to set a Go value to the contents of a CUE value is to use the Decode method of the later.

type ab struct{ A, B int }

var r cue.Runtime

var x ab

i, _ := r.Compile("test", `{A: 2, B: 4}`)
_ = i.Value().Decode(&x)
fmt.Println(x)

i, _ = r.Compile("test", `{B: "foo"}`)
_ = i.Value().Decode(&x)
fmt.Println(x)

// Output:
// {2 4}
// json: cannot unmarshal string into Go struct field ab.B of type int

Package cuelang.com/go/encoding/gocode/gocodec gives a bit more control over encoding and allows incorporating Go field tags with constraints as well as deriving unspecified values from constraints.

---

Modify CUE values A field in a CUE instance can be set to a Go value that conforms to the constraints of this instance using the Fill method. Building on the example of the “Load CUE into Go” section, we can write

inst, _ := instance.Fill("you", "place")
str, _ = inst.Lookup("msg").String()

fmt.Println(str)

// Output:
// Hello you!

To ensure the integrity of references with the CUE instance, modifications are only allowed at the whole-instance level.

---

Generate Go code Programmatically

The Generate function in package cuelang.org/go/encoding/gocode generates stubs for validation functions and method from a given CUE instance. It does so by lining up the top-level CUE names with Go definitions. The CUE code can use field tags, similar to those used in Go, to override the naming.

b, err := gocode.Generate("path/to/go/pkg", instance, nil)
if err != nil {
    // handle error
}

err = os.WriteFile("cue_gen.go", b, 0644)

---

[myitcv]

Is this the complete list of diffs?

If not, where is that list so we can see what needs to be done?

[jpluscplusm]

Is this the complete list of diffs?

I've updated the issue so that the list is complete.

[myitcv]

In the meantime I've raised https://review.gerrithub.io/c/cue-lang/cuelang.org/+/1194125 so people don't "struggle" on the old content.

[myitcv]

That said we should prioritise what to do/not do from the list above.