From 15ca0d2b9acedac9cf70b10de9a070e7affe4d27 Mon Sep 17 00:00:00 2001 From: Jonathan Matthews Date: Fri, 19 Jan 2024 16:27:11 +0000 Subject: [PATCH] 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 Change-Id: I4701aeff47c3d91d458d89922064ce8f71deb5df Dispatch-Trailer: {"type":"trybot","CL":1174775,"patchset":15,"ref":"refs/changes/75/1174775/15","targetBranch":"alpha"} --- .../en.md | 77 +++++++++++++++++++ .../gen_cache.cue | 18 +++++ .../page.cue | 3 + .../index.md | 76 ++++++++++++++++++ 4 files changed, 174 insertions(+) create mode 100644 content/docs/howto/use-the-built-in-function-text-template-execute-to-generate-text-from-data/en.md create mode 100644 content/docs/howto/use-the-built-in-function-text-template-execute-to-generate-text-from-data/gen_cache.cue create mode 100644 content/docs/howto/use-the-built-in-function-text-template-execute-to-generate-text-from-data/page.cue create mode 100644 hugo/content/en/docs/howto/use-the-built-in-function-text-template-execute-to-generate-text-from-data/index.md diff --git a/content/docs/howto/use-the-built-in-function-text-template-execute-to-generate-text-from-data/en.md b/content/docs/howto/use-the-built-in-function-text-template-execute-to-generate-text-from-data/en.md new file mode 100644 index 000000000..fd0b82738 --- /dev/null +++ b/content/docs/howto/use-the-built-in-function-text-template-execute-to-generate-text-from-data/en.md @@ -0,0 +1,77 @@ +--- +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`](https://pkg.go.dev/cuelang.org/go/pkg/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` diff --git a/content/docs/howto/use-the-built-in-function-text-template-execute-to-generate-text-from-data/gen_cache.cue b/content/docs/howto/use-the-built-in-function-text-template-execute-to-generate-text-from-data/gen_cache.cue new file mode 100644 index 000000000..fe0b3bcd9 --- /dev/null +++ b/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=" + } + } + } + } + } + } + } +} diff --git a/content/docs/howto/use-the-built-in-function-text-template-execute-to-generate-text-from-data/page.cue b/content/docs/howto/use-the-built-in-function-text-template-execute-to-generate-text-from-data/page.cue new file mode 100644 index 000000000..d22dd2c0d --- /dev/null +++ b/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": {} diff --git a/hugo/content/en/docs/howto/use-the-built-in-function-text-template-execute-to-generate-text-from-data/index.md b/hugo/content/en/docs/howto/use-the-built-in-function-text-template-execute-to-generate-text-from-data/index.md new file mode 100644 index 000000000..077efbe94 --- /dev/null +++ b/hugo/content/en/docs/howto/use-the-built-in-function-text-template-execute-to-generate-text-from-data/index.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`](https://pkg.go.dev/cuelang.org/go/pkg/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`