howto: go-api-basics

First cut.

DO NOT SUBMIT
DO NOT REVIEW

Preview-Path: /docs/howto/go-api-basics
Signed-off-by: Paul Jolly <[email protected]>
Change-Id: If4b9c36c934ee348944cfca091bf1ba2abbe967c
Dispatch-Trailer: {"type":"trybot","CL":1170263,"patchset":43,"ref":"refs/changes/63/1170263/43","targetBranch":"alpha"}

content/docs/howto/go-api-basics/en.md

@@ -0,0 +1,109 @@
+---
+title: Go API basics
+tags:
+- go api
+authors:
+- myitcv
+toc_hide: true
+---
+
+This howto demonstrates getting started with CUE's Go API.
+
+{{{with _script "en" "set caches to speed up re-running"}}}
+export GOMODCACHE=/caches/gomodcache
+export GOCACHE=/caches/gobuild
+{{{end}}}
+
+{{{with script "en" "cue version"}}}
+#ellipsis 1
+cue version
+{{{end}}}
+
+{{{with script "en" "go version"}}}
+go version
+{{{end}}}
+
+{{{with script "en" "start modules"}}}
+cue mod init company.com/example
+go mod init company.com/example
+{{{end}}}
+
+{{{with upload "en" "initial cue code"}}}
+-- some.cue --
+package example
+
+output: "Hello \(name)"
+name:   "Joe"
+{{{end}}}
+
+
+{{{with script "en" "cue export"}}}
+cue export .
+{{{end}}}
+
+
+{{{with upload "en" "initial go code"}}}
+-- main.go --
+package main
+
+import (
+	"fmt"
+	"path/filepath"
+
+	"cuelang.org/go/cue"
+	"cuelang.org/go/cue/cuecontext"
+	"cuelang.org/go/cue/load"
+)
+
+func main() {
+	// Load the package "example" relative to the directory testdata/testmod.
+	// Akin to loading via: cd testdata/testmod && cue export ./example
+	insts := load.Instances([]string{"./example"}, &load.Config{
+		Dir: filepath.Join("testdata", "testmod"),
+	})
+
+	// testdata/testmod/example just has one file without any build tags,
+	// so we get a single instance as a result.
+	fmt.Println("Number of instances:", len(insts))
+	inst := insts[0]
+	if err := inst.Err; err != nil {
+		fmt.Println(err)
+		return
+	}
+	fmt.Println("Instance module:", inst.Module)
+	fmt.Println("Instance import path:", inst.ImportPath)
+	fmt.Println()
+
+	// Inspect the syntax trees.
+	fmt.Println("Source files:")
+	for _, file := range inst.Files {
+		fmt.Println(filepath.Base(file.Filename), "with", len(file.Decls), "declarations")
+	}
+	fmt.Println()
+
+	// Build the instance into a value.
+	// We can also use BuildInstances for many instances at once.
+	ctx := cuecontext.New()
+	val := ctx.BuildInstance(inst)
+	if err := val.Err(); err != nil {
+		fmt.Println(err)
+		return
+	}
+
+	// Inspect the contents of the value, such as one string field.
+	fieldStr, err := val.LookupPath(cue.MakePath(cue.Str("output"))).String()
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	fmt.Println("Field string:", fieldStr)
+}
+{{{end}}}
+
+{{{with script "en" "go test"}}}
+#ellipsis 0
+go get cuelang.org/go@$CUELANG_CUE_PRERELEASE
+#ellipsis 1
+go mod tidy
+go run .
+{{{end}}}

content/docs/howto/go-api-basics/gen_cache.cue

@@ -0,0 +1,100 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"go-api-basics": {
+					page: {
+						cache: {
+							upload: {
+								"initial cue code": "pxgTHvIPrEgGLOS3cwelEs7MDV3uVAMQRwVOTEWPVmg="
+								"initial go code":  "5pTpBtgEUigrEEcH3N1srQUQZMS0NU6Bal5ksTZXbow="
+							}
+							multi_step: {
+								"340DHPGTEEK2U1S1JBHMLQK6KCA489S9PB50CSRNCQ0S06H0OSEG====": [{
+									doc:      ""
+									cmd:      "export GOMODCACHE=/caches/gomodcache"
+									exitCode: 0
+									output:   ""
+								}, {
+									doc:      ""
+									cmd:      "export GOCACHE=/caches/gobuild"
+									exitCode: 0
+									output:   ""
+								}, {
+									doc:      "#ellipsis 1"
+									cmd:      "cue version"
+									exitCode: 0
+									output: """
+											cue version v0.8.0-alpha.1
+											...
+
+											"""
+								}, {
+									doc:      ""
+									cmd:      "go version"
+									exitCode: 0
+									output: """
+											go version go1.22.0 linux/amd64
+
+											"""
+								}, {
+									doc:      ""
+									cmd:      "cue mod init company.com/example"
+									exitCode: 0
+									output:   ""
+								}, {
+									doc:      ""
+									cmd:      "go mod init company.com/example"
+									exitCode: 0
+									output: """
+											go: creating new go.mod: module company.com/example
+											go: to add module requirements and sums:
+											\tgo mod tidy
+
+											"""
+								}, {
+									doc:      ""
+									cmd:      "cue export ."
+									exitCode: 0
+									output: """
+											{
+											    "output": "Hello Joe",
+											    "name": "Joe"
+											}
+
+											"""
+								}, {
+									doc:      "#ellipsis 0"
+									cmd:      "go get cuelang.org/[email protected]"
+									exitCode: 0
+									output: """
+											...
+
+											"""
+								}, {
+									doc:      "#ellipsis 1"
+									cmd:      "go mod tidy"
+									exitCode: 0
+									output: """
+											...
+
+											"""
+								}, {
+									doc:      ""
+									cmd:      "go run ."
+									exitCode: 0
+									output: """
+											Number of instances: 1
+											cannot find package "./example"
+
+											"""
+								}]
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/howto/go-api-basics/page.cue

@@ -0,0 +1,15 @@
+package site
+
+content: docs: howto: "go-api-basics": {
+	page: comparators: [
+		{
+			kind:    "patternComparator"
+			command: "go test"
+			pattern: expr: #"(?m)^ok .*\t(\d(\.\d+)?)s"#
+		},
+		{
+			kind:    "unstableLineOrderComparator"
+			command: "go test"
+		},
+	]
+}

hugo/content/en/docs/howto/go-api-basics/index.md

@@ -0,0 +1,113 @@
+---
+title: Go API basics
+tags:
+- go api
+authors:
+- myitcv
+toc_hide: true
+---
+
+This howto demonstrates getting started with CUE's Go API.
+
+```text { title="TERMINAL" codeToCopy="Y3VlIHZlcnNpb24K" }
+$ cue version
+cue version v0.8.0-alpha.1
+...
+```
+
+```text { title="TERMINAL" codeToCopy="Z28gdmVyc2lvbgo=" }
+$ go version
+go version go1.22.0 linux/amd64
+```
+
+```text { title="TERMINAL" codeToCopy="Y3VlIG1vZCBpbml0IGNvbXBhbnkuY29tL2V4YW1wbGUKZ28gbW9kIGluaXQgY29tcGFueS5jb20vZXhhbXBsZQo=" }
+$ cue mod init company.com/example
+$ go mod init company.com/example
+go: creating new go.mod: module company.com/example
+go: to add module requirements and sums:
+	go mod tidy
+```
+
+```cue { title="some.cue" }
+package example
+
+output: "Hello \(name)"
+name:   "Joe"
+```
+
+
+```text { title="TERMINAL" codeToCopy="Y3VlIGV4cG9ydCAuCg==" }
+$ cue export .
+{
+    "output": "Hello Joe",
+    "name": "Joe"
+}
+```
+
+
+```go { title="main.go" }
+package main
+
+import (
+	"fmt"
+	"path/filepath"
+
+	"cuelang.org/go/cue"
+	"cuelang.org/go/cue/cuecontext"
+	"cuelang.org/go/cue/load"
+)
+
+func main() {
+	// Load the package "example" relative to the directory testdata/testmod.
+	// Akin to loading via: cd testdata/testmod && cue export ./example
+	insts := load.Instances([]string{"./example"}, &load.Config{
+		Dir: filepath.Join("testdata", "testmod"),
+	})
+
+	// testdata/testmod/example just has one file without any build tags,
+	// so we get a single instance as a result.
+	fmt.Println("Number of instances:", len(insts))
+	inst := insts[0]
+	if err := inst.Err; err != nil {
+		fmt.Println(err)
+		return
+	}
+	fmt.Println("Instance module:", inst.Module)
+	fmt.Println("Instance import path:", inst.ImportPath)
+	fmt.Println()
+
+	// Inspect the syntax trees.
+	fmt.Println("Source files:")
+	for _, file := range inst.Files {
+		fmt.Println(filepath.Base(file.Filename), "with", len(file.Decls), "declarations")
+	}
+	fmt.Println()
+
+	// Build the instance into a value.
+	// We can also use BuildInstances for many instances at once.
+	ctx := cuecontext.New()
+	val := ctx.BuildInstance(inst)
+	if err := val.Err(); err != nil {
+		fmt.Println(err)
+		return
+	}
+
+	// Inspect the contents of the value, such as one string field.
+	fieldStr, err := val.LookupPath(cue.MakePath(cue.Str("output"))).String()
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	fmt.Println("Field string:", fieldStr)
+}
+```
+
+```text { title="TERMINAL" codeToCopy="Z28gZ2V0IGN1ZWxhbmcub3JnL2dvQHYwLjguMC1hbHBoYS4xCmdvIG1vZCB0aWR5CmdvIHJ1biAuCg==" }
+$ go get cuelang.org/[email protected]
+...
+$ go mod tidy
+...
+$ go run .
+Number of instances: 1
+cannot find package "./example"
+```

site.cue

@@ -42,6 +42,41 @@ _contentDefaults: {
 	page: {
 		leftDelim:  *"{{{" | _
 		rightDelim: *"}}}" | _
+
+		comparators: *[
+			{
+				kind:    "patternComparator"
+				command: "go test"
+				pattern: expr: #"(?m)^ok .*\t(\d(\.\d+)?)s"#
+			},
+		] | _
+
+		sanitisers: *[
+			{
+				kind:    "patternSanitiser"
+				command: "go version"
+				pattern: expr: #"(?m)linux\/.+$"#
+				replacement: "linux/amd64"
+			},
+			{
+				kind:    "patternSanitiser"
+				command: "cue version"
+				pattern: expr: #"(?m)GOARCH .+$"#
+				replacement: "GOARCH amd64"
+			},
+			{
+				kind:    "patternSanitiser"
+				command: "cue version"
+				pattern: expr: #"(?m)GOOS .+$"#
+				replacement: "GOOS linux"
+			},
+			{
+				kind:    "patternSanitiser"
+				command: "cue version"
+				pattern: expr: #"(?m)^\s*GOAMD64 .*\n"#
+				replacement: ""
+			},
+		] | _
 	}
 }
 content: _contentDefaults