docs/howto: use list.FlattenN

This adds a Commented CUE demonstrating how to use list.FlattenN to
expand list elements to varying depths.

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

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

@@ -0,0 +1,54 @@
+---
+title: Using the builtin 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 builtin function `list.FlattenN` to flatten a list
+by expanding its list elements down to a specified depth.
+
+{{{with code "en" "cc"}}}
+#location top bottom
+
+exec cue eval -e flatter
+cmp stdout out
+-- file.cue --
+package example
+
+import "list"
+
+flatter: {
+	// f1's first-level list elements are expanded
+	f1: list.FlattenN(L, 1)
+	// f2's first- and second-level list elements are expanded
+	f2: list.FlattenN(L, 2)
+	// All of fNegative's list elements are expanded, no matter their depth
+	fNegative: list.FlattenN(L, -1)
+}
+
+// L is a list (of lists (of lists ...))
+L: [
+	1, 2, 3,
+	["a", "b", "c"],
+	[
+		[4, 5, 6],
+		[
+			["d", "e", "f"],
+			[[7, 8, 9]],
+		],
+	],
+	[[[[["g", "h", "i"]]]]],
+]
+-- out --
+f1: [1, 2, 3, "a", "b", "c", [4, 5, 6], [["d", "e", "f"], [[7, 8, 9]]], [[[["g", "h", "i"]]]]]
+f2: [1, 2, 3, "a", "b", "c", 4, 5, 6, ["d", "e", "f"], [[7, 8, 9]], [[["g", "h", "i"]]]]
+fNegative: [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) builtin package

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

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

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

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

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

@@ -0,0 +1,53 @@
+---
+title: Using the builtin 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 builtin function `list.FlattenN` to flatten a list
+by expanding its list elements down to a specified depth.
+
+{{< code-tabs >}}
+{{< code-tab name="file.cue" language="cue"  area="top" >}}
+package example
+
+import "list"
+
+flatter: {
+	// f1's first-level list elements are expanded
+	f1: list.FlattenN(L, 1)
+	// f2's first- and second-level list elements are expanded
+	f2: list.FlattenN(L, 2)
+	// All of fNegative's list elements are expanded, no matter their depth
+	fNegative: list.FlattenN(L, -1)
+}
+
+// L is a list (of lists (of lists ...))
+L: [
+	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 -e flatter
+f1: [1, 2, 3, "a", "b", "c", [4, 5, 6], [["d", "e", "f"], [[7, 8, 9]]], [[[["g", "h", "i"]]]]]
+f2: [1, 2, 3, "a", "b", "c", 4, 5, 6, ["d", "e", "f"], [[7, 8, 9]], [[["g", "h", "i"]]]]
+fNegative: [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) builtin package