docs/howto: place data using the Go API

DO NOT SUBMIT Preview-Path: /docs/howto/place-data-go-api Signed-off-by: Paul Jolly <[email protected]> Change-Id: I0e5618207da2bc78cff9df715b1a4827503142dd Dispatch-Trailer: {"type":"trybot","CL":1199814,"patchset":1,"ref":"refs/changes/14/1199814/1","targetBranch":"master"}
cue-lang · Aug 21, 2024 · b885b4d · b885b4d
1 parent b24925a
commit b885b4d
Show file tree

Hide file tree

Showing 4 changed files with 314 additions and 0 deletions.
diff --git a/content/docs/howto/place-data-go-api/en.md b/content/docs/howto/place-data-go-api/en.md
@@ -0,0 +1,123 @@
+---
+title: Placing data using the Go API
+tags:
+- go api
+authors:
+- myitcv
+toc_hide: true
+---
+
+{{{with _script_ "en" "set caches to speed up re-running"}}}
+export GOMODCACHE=/caches/gomodcache
+export GOCACHE=/caches/gobuild
+{{{end}}}
+
+This tutorial demonstrates how to mimic the `--path` or `-l` flag for `cmd/cue` to "place" data using the Go API.
+
+{{{with step}}}
+Initialize a CUE module to hold our configuration:
+
+{{{with script "en" "start modules"}}}
+cue mod init mod.example
+{{{end}}}
+
+{{{end}}}
+
+{{{with step}}}
+Write some CUE code and JSON data:
+
+{{{with upload "en" "initial cue code"}}}
+#location top-left top-right
+-- some.cue --
+package example
+
+// We will place the data here
+input!: {
+	name!: string
+}
+
+output: "Hello \(input.name)"
+-- input.json --
+{
+    "name": "cueckoo"
+}
+{{{end}}}
+
+{{{end}}}
+
+{{{with step}}}
+Initialize a Go module to hold our program
+
+{{{with script "en" "go mod init"}}}
+#ellipsis 0
+go mod init mod.example
+{{{end}}}
+
+{{{end}}}
+
+
+{{{with step}}}
+Write our Go program to place the
+
+{{{with upload "en" "go program"}}}
+#location top-left
+-- main.go --
+package main
+
+import (
+	"fmt"
+	"log"
+	"os"
+
+	"cuelang.org/go/cue"
+	"cuelang.org/go/cue/cuecontext"
+	"cuelang.org/go/cue/load"
+	"cuelang.org/go/encoding/json"
+)
+
+func main() {
+	ctx := cuecontext.New()
+	bis := load.Instances([]string{"."}, nil)
+	v := ctx.BuildInstance(bis[0])
+
+	// Load our input data
+	jsonBytes, err := os.ReadFile("input.json")
+	if err != nil {
+		log.Fatal(err)
+	}
+	jsonData, err := json.Extract("input.json", jsonBytes)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Place as in the "input" field value
+	complete := v.FillPath(cue.ParsePath("input"), jsonData)
+
+	// Print the "output" field value
+	fmt.Printf("%v\n", complete.LookupPath(cue.ParsePath("output")))
+}
+{{{end}}}
+
+{{{end}}}
+
+{{{with step}}}
+Add a dependency on `cuelang.org/go` and ensure the Go module is tidy:
+
+{{{with script "en" "go test"}}}
+#ellipsis 0
+go get cuelang.org/go@$CUELANG_CUE_LATEST
+#ellipsis 0
+go mod tidy
+{{{end}}}
+
+{{{end}}}
+
+{{{with step}}}
+Run our program:
+
+{{{with script "en" "go run"}}}
+go run .
+{{{end}}}
+
+{{{end}}}
+
diff --git a/content/docs/howto/place-data-go-api/gen_cache.cue b/content/docs/howto/place-data-go-api/gen_cache.cue
@@ -0,0 +1,71 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"place-data-go-api": {
+					page: {
+						cache: {
+							upload: {
+								"initial cue code": "gMKHkYUfuinmR+O5QZ1d1Z6EI71elyXDTQGG/V/5J8o="
+								"go program":       "VpGy9o+xxzIuFgqzNfExnPCnMhkGxd0RCFWGukUpRcI="
+							}
+							multi_step: {
+								hash:       "K04DNBGVEQ01PCVEBO0QCG4QMREU4MAHA8GJFBFOKRV7FD6O1FL0===="
+								scriptHash: "FS2QTTF3KP29SMDJ7TOMVKL8GJ94T47QTVKV73I9SJ3L5V7GRAV0===="
+								steps: [{
+									doc:      ""
+									cmd:      "export GOMODCACHE=/caches/gomodcache"
+									exitCode: 0
+									output:   ""
+								}, {
+									doc:      ""
+									cmd:      "export GOCACHE=/caches/gobuild"
+									exitCode: 0
+									output:   ""
+								}, {
+									doc:      ""
+									cmd:      "cue mod init mod.example"
+									exitCode: 0
+									output:   ""
+								}, {
+									doc:      "#ellipsis 0"
+									cmd:      "go mod init mod.example"
+									exitCode: 0
+									output: """
+											...
+
+											"""
+								}, {
+									doc:      "#ellipsis 0"
+									cmd:      "go get cuelang.org/[email protected]"
+									exitCode: 0
+									output: """
+											...
+
+											"""
+								}, {
+									doc:      "#ellipsis 0"
+									cmd:      "go mod tidy"
+									exitCode: 0
+									output: """
+											...
+
+											"""
+								}, {
+									doc:      ""
+									cmd:      "go run ."
+									exitCode: 0
+									output: """
+											"Hello cueckoo"
+
+											"""
+								}]
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}
diff --git a/content/docs/howto/place-data-go-api/page.cue b/content/docs/howto/place-data-go-api/page.cue
@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "place-data-go-api": page: _
diff --git a/hugo/content/en/docs/howto/place-data-go-api/index.md b/hugo/content/en/docs/howto/place-data-go-api/index.md
@@ -0,0 +1,117 @@
+---
+title: Placing data using the Go API
+tags:
+- go api
+authors:
+- myitcv
+toc_hide: true
+---
+
+This tutorial demonstrates how to mimic the `--path` or `-l` flag for `cmd/cue` to "place" data using the Go API.
+
+{{< step stepNumber="1" >}}
+Initialize a CUE module to hold our configuration:
+
+```text { title="TERMINAL" type="terminal" codeToCopy="Y3VlIG1vZCBpbml0IG1vZC5leGFtcGxl" }
+$ cue mod init mod.example
+```
+
+{{< /step >}}
+
+{{< step stepNumber="2" >}}
+Write some CUE code and JSON data:
+
+{{< code-tabs >}}
+{{< code-tab name="some.cue" language="cue" area="top-left" >}}
+package example
+
+// We will place the data here
+input!: {
+	name!: string
+}
+
+output: "Hello \(input.name)"
+{{< /code-tab >}}{{< code-tab name="input.json" language="json" area="top-right" >}}
+{
+    "name": "cueckoo"
+}
+{{< /code-tab >}}{{< /code-tabs >}}
+
+{{< /step >}}
+
+{{< step stepNumber="3" >}}
+Initialize a Go module to hold our program
+
+```text { title="TERMINAL" type="terminal" codeToCopy="Z28gbW9kIGluaXQgbW9kLmV4YW1wbGU=" }
+$ go mod init mod.example
+...
+```
+
+{{< /step >}}
+
+
+{{< step stepNumber="4" >}}
+Write our Go program to place the
+
+{{< code-tabs >}}
+{{< code-tab name="main.go" language="go" area="top-left" >}}
+package main
+
+import (
+	"fmt"
+	"log"
+	"os"
+
+	"cuelang.org/go/cue"
+	"cuelang.org/go/cue/cuecontext"
+	"cuelang.org/go/cue/load"
+	"cuelang.org/go/encoding/json"
+)
+
+func main() {
+	ctx := cuecontext.New()
+	bis := load.Instances([]string{"."}, nil)
+	v := ctx.BuildInstance(bis[0])
+
+	// Load our input data
+	jsonBytes, err := os.ReadFile("input.json")
+	if err != nil {
+		log.Fatal(err)
+	}
+	jsonData, err := json.Extract("input.json", jsonBytes)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Place as in the "input" field value
+	complete := v.FillPath(cue.ParsePath("input"), jsonData)
+
+	// Print the "output" field value
+	fmt.Printf("%v\n", complete.LookupPath(cue.ParsePath("output")))
+}
+{{< /code-tab >}}{{< /code-tabs >}}
+
+{{< /step >}}
+
+{{< step stepNumber="5" >}}
+Add a dependency on `cuelang.org/go` and ensure the Go module is tidy:
+
+```text { title="TERMINAL" type="terminal" codeToCopy="Z28gZ2V0IGN1ZWxhbmcub3JnL2dvQHYwLjEwLjAKZ28gbW9kIHRpZHk=" }
+$ go get cuelang.org/[email protected]
+...
+$ go mod tidy
+...
+```
+
+{{< /step >}}
+
+{{< step stepNumber="6" >}}
+Run our program:
+
+```text { title="TERMINAL" type="terminal" codeToCopy="Z28gcnVuIC4=" }
+$ go run .
+"Hello cueckoo"
+```
+
+{{< /step >}}
+
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		package site

		content: docs: howto: "place-data-go-api": page: _