docs/howto: use text/template.Execute

This adapts an example from Cuetorials to serve as a demonstration of
how to use text/template.Execute to template text from data.

The aim of this guide and the Cuetorials page are different: Cuetorials
integrates multiple rendered texts into a cue command invocation, which
is out of scope for this guide. The original example is therefore
simplified, here, with only a single rendered text being generated.

cf. https://cuetorials.com/first-steps/generate-all-the-things/

Preview-Path: /docs/howto/use-the-built-in-function-text-template-execute-to-generate-text-from-data/
Signed-off-by: Jonathan Matthews <[email protected]>
Change-Id: I4701aeff47c3d91d458d89922064ce8f71deb5df
Dispatch-Trailer: {"type":"trybot","CL":1174775,"patchset":3,"ref":"refs/changes/75/1174775/3","targetBranch":"alpha"}

content/docs/howto/use-the-built-in-function-text-template-execute-to-generate-text-from-data/en.md

@@ -0,0 +1,76 @@
+---
+title: Using the built-in function "text/template.Execute" to generate text from data
+tags:
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the built-in function `text/template.Execute` with
+data-driven templates to generate text output, using Go's
+[template format](https://pkg.go.dev/text/template).
+
+{{{with code "en" "cc"}}}
+#location top bottom
+
+exec cue export -e tasklist --out text
+cmp stdout out
+-- file.cue --
+package example
+
+import "text/template"
+
+tasklist: template.Execute(message, data)
+message: """
+	Hello, {{ .name }}.
+
+	Here are the tasks you still need to do:
+	-- TODO --------------------------------
+	{{ range $T := .incomplete -}}
+	▢ {{ printf "%s [estimated effort: %v]" $T.name $T.effort }}
+	{{ end }}
+	You've already completed these tasks - well done!
+	-- DONE -----------------------------------------
+	{{ range $T := .complete -}}
+	✅︎ {{ $T.name }}
+	{{ end -}}
+	"""
+data: {
+	name: "Alex"
+	tasks: [
+		{name: "Write CUE how-to guide", effort: 1, complete: true},
+		{name: "Train for 10k race", effort:     4, complete: false},
+		{name: "Violin practise", effort:        3, complete: false},
+		{name: "Go shopping", effort:            3, complete: true},
+		{name: "Feed cat", effort:               1, complete: false},
+	]
+	complete: [for t in tasks if t.complete {t}]
+	incomplete: [for t in tasks if !t.complete {t}]
+}
+-- out --
+Hello, Alex.
+
+Here are the tasks you still need to do:
+-- TODO --------------------------------
+▢ Train for 10k race [estimated effort: 4]
+▢ Violin practise [estimated effort: 3]
+▢ Feed cat [estimated effort: 1]
+
+You've already completed these tasks - well done!
+-- DONE -----------------------------------------
+✅︎ Write CUE how-to guide
+✅︎ Go shopping
+
+{{{end}}}
+
+## Related content
+
+- The [`text/template`](https://pkg.go.dev/cuelang.org/go/pkg/text/template)
+  built-in package
+- Go's documentation of [the template format](https://pkg.go.dev/text/template)
+  used by `text/template.Execute`
+- The example on this page is adapted from the excellent Cuetorials'
+  [page](https://cuetorials.com/first-steps/generate-all-the-things/) on
+  `text/template`

content/docs/howto/use-the-built-in-function-text-template-execute-to-generate-text-from-data/gen_cache.cue

@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-the-built-in-function-text-template-execute-to-generate-text-from-data": {
+					page: {
+						cache: {
+							code: {
+								cc: "AEr10JdvkxW2IgF7WBXA/9ptAz1MzbffJxz6vJIDzJE="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/howto/use-the-built-in-function-text-template-execute-to-generate-text-from-data/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-the-built-in-function-text-template-execute-to-generate-text-from-data": {}

hugo/content/en/docs/howto/use-the-built-in-function-text-template-execute-to-generate-text-from-data/index.md

@@ -0,0 +1,75 @@
+---
+title: Using the built-in function "text/template.Execute" to generate text from data
+tags:
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the built-in function `text/template.Execute` with
+data-driven templates to generate text output, using Go's
+[template format](https://pkg.go.dev/text/template).
+
+{{< code-tabs >}}
+{{< code-tab name="file.cue" language="cue"  area="top" >}}
+package example
+
+import "text/template"
+
+tasklist: template.Execute(message, data)
+message: """
+	Hello, {{ .name }}.
+
+	Here are the tasks you still need to do:
+	-- TODO --------------------------------
+	{{ range $T := .incomplete -}}
+	▢ {{ printf "%s [estimated effort: %v]" $T.name $T.effort }}
+	{{ end }}
+	You've already completed these tasks - well done!
+	-- DONE -----------------------------------------
+	{{ range $T := .complete -}}
+	✅︎ {{ $T.name }}
+	{{ end -}}
+	"""
+data: {
+	name: "Alex"
+	tasks: [
+		{name: "Write CUE how-to guide", effort: 1, complete: true},
+		{name: "Train for 10k race", effort:     4, complete: false},
+		{name: "Violin practise", effort:        3, complete: false},
+		{name: "Go shopping", effort:            3, complete: true},
+		{name: "Feed cat", effort:               1, complete: false},
+	]
+	complete: [for t in tasks if t.complete {t}]
+	incomplete: [for t in tasks if !t.complete {t}]
+}
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" type="terminal" area="bottom" >}}
+$ cue export -e tasklist --out text
+Hello, Alex.
+
+Here are the tasks you still need to do:
+-- TODO --------------------------------
+▢ Train for 10k race [estimated effort: 4]
+▢ Violin practise [estimated effort: 3]
+▢ Feed cat [estimated effort: 1]
+
+You've already completed these tasks - well done!
+-- DONE -----------------------------------------
+✅︎ Write CUE how-to guide
+✅︎ Go shopping
+
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+## Related content
+
+- The [`text/template`](https://pkg.go.dev/cuelang.org/go/pkg/text/template)
+  built-in package
+- Go's documentation of [the template format](https://pkg.go.dev/text/template)
+  used by `text/template.Execute`
+- The example on this page is adapted from the excellent Cuetorials'
+  [page](https://cuetorials.com/first-steps/generate-all-the-things/) on
+  `text/template`