docs/howto: use list.FlattenN

This adds a Commented CUE demonstrating how to use list.FlattenN to
expand a list's elements to different depths.

Preview-Path: /docs/howto/use-the-built-in-function-list-flattenn-to-flatten-lists/
Signed-off-by: Jonathan Matthews <[email protected]>
Change-Id: I97415642812fa137cd5c2dd4e6efadd3c5d80a3d
Dispatch-Trailer: {"type":"trybot","CL":1174439,"patchset":14,"ref":"refs/changes/39/1174439/14","targetBranch":"alpha"}

content/docs/howto/use-the-built-in-function-list-flattenn-to-flatten-lists/en.md

@@ -0,0 +1,57 @@
+---
+title: Using the built-in function "list.FlattenN" to flatten lists
+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
+[`list.FlattenN`](https://pkg.go.dev/cuelang.org/go/pkg/list#FlattenN)
+to flatten a list by expanding its list elements by a specified depth.
+
+{{{with code "en" "cc"}}}
+#location top bottom
+
+exec cue eval
+cmp stdout out
+-- file.cue --
+package example
+
+import "list"
+
+// src is a list (of lists (of lists ...)), defined below.
+src: [...]
+
+// one transforms src by expanding its first-level list elements.
+one: list.FlattenN(src, 1)
+// two transforms src by expanding its first- and second-level list elements.
+two: list.FlattenN(src, 2)
+// all transforms src by expanding all its list elements, recursively, no
+// matter their depth.
+all: list.FlattenN(src, -1)
+
+src: [
+	1, 2, 3,
+	["a", "b", "c"],
+	[
+		[4, 5, 6],
+		[
+			["d", "e", "f"],
+			[[7, 8, 9]],
+		],
+	],
+	[[[[["g", "h", "i"]]]]],
+]
+-- out --
+src: [1, 2, 3, ["a", "b", "c"], [[4, 5, 6], [["d", "e", "f"], [[7, 8, 9]]]], [[[[["g", "h", "i"]]]]]]
+one: [1, 2, 3, "a", "b", "c", [4, 5, 6], [["d", "e", "f"], [[7, 8, 9]]], [[[["g", "h", "i"]]]]]
+two: [1, 2, 3, "a", "b", "c", 4, 5, 6, ["d", "e", "f"], [[7, 8, 9]], [[["g", "h", "i"]]]]
+all: [1, 2, 3, "a", "b", "c", 4, 5, 6, "d", "e", "f", 7, 8, 9, "g", "h", "i"]
+{{{end}}}
+
+## Related content
+
+- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package

content/docs/howto/use-the-built-in-function-list-flattenn-to-flatten-lists/gen_cache.cue

@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-the-built-in-function-list-flattenn-to-flatten-lists": {
+					page: {
+						cache: {
+							code: {
+								cc: "AhHhGLP8qj1FskfTMcu85QL032IzKy8voDJ9XuA68OE="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/howto/use-the-built-in-function-list-flattenn-to-flatten-lists/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-the-built-in-function-list-flattenn-to-flatten-lists": {}

hugo/content/en/docs/howto/use-the-built-in-function-list-flattenn-to-flatten-lists/index.md

@@ -0,0 +1,56 @@
+---
+title: Using the built-in function "list.FlattenN" to flatten lists
+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
+[`list.FlattenN`](https://pkg.go.dev/cuelang.org/go/pkg/list#FlattenN)
+to flatten a list by expanding its list elements by a specified depth.
+
+{{< code-tabs >}}
+{{< code-tab name="file.cue" language="cue"  area="top" >}}
+package example
+
+import "list"
+
+// src is a list (of lists (of lists ...)), defined below.
+src: [...]
+
+// one transforms src by expanding its first-level list elements.
+one: list.FlattenN(src, 1)
+// two transforms src by expanding its first- and second-level list elements.
+two: list.FlattenN(src, 2)
+// all transforms src by expanding all its list elements, recursively, no
+// matter their depth.
+all: list.FlattenN(src, -1)
+
+src: [
+	1, 2, 3,
+	["a", "b", "c"],
+	[
+		[4, 5, 6],
+		[
+			["d", "e", "f"],
+			[[7, 8, 9]],
+		],
+	],
+	[[[[["g", "h", "i"]]]]],
+]
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" type="terminal" area="bottom" >}}
+$ cue eval
+src: [1, 2, 3, ["a", "b", "c"], [[4, 5, 6], [["d", "e", "f"], [[7, 8, 9]]]], [[[[["g", "h", "i"]]]]]]
+one: [1, 2, 3, "a", "b", "c", [4, 5, 6], [["d", "e", "f"], [[7, 8, 9]]], [[[["g", "h", "i"]]]]]
+two: [1, 2, 3, "a", "b", "c", 4, 5, 6, ["d", "e", "f"], [[7, 8, 9]], [[["g", "h", "i"]]]]
+all: [1, 2, 3, "a", "b", "c", 4, 5, 6, "d", "e", "f", 7, 8, 9, "g", "h", "i"]
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+## Related content
+
+- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package