docs/howto: exporting an element from a top-level data list

This adds a guide that demonstrates using the "cue export" command to
place a list data file at an addressable location with "-l", and then
using "-e" with an integer list index to access a specific element.

Closes cue-lang/docs-and-content#195.

Preview-Path: /docs/howto/export-top-level-list-element/
Signed-off-by: Jonathan Matthews <[email protected]>
Change-Id: Idb75479a03e8c1798d39558f937f8bd01d3d60fb
Dispatch-Trailer: {"type":"trybot","CL":1208967,"patchset":2,"ref":"refs/changes/67/1208967/2","targetBranch":"master"}

content/docs/howto/export-top-level-list-element/en.md

@@ -0,0 +1,47 @@
+---
+title: Exporting an element from a top-level data list
+authors: [jpluscplusm]
+toc_hide: true
+---
+
+Many data formats can encode lists at their top-level, such as JSON arrays and
+YAML sequences.
+This guide demonstrates how to export an element from such a list using only
+the `cue` command.
+
+{{{with code "en" "example"}}}
+exec cue export data.yaml -l input: -e input[2]
+cmp stdout out
+-- data.yaml --
+# This list contains five elements of mixed types,
+# including structs, simple values, and other lists.
+- some: data
+  in: { a: list }
+- [ 1, 2, 3 ]
+- a: list element
+  of: { type: struct }
+- 4
+- 5
+-- out --
+{
+    "a": "list element",
+    "of": {
+        "type": "struct"
+    }
+}
+{{{end}}}
+
+The `cue export` command shown above uses two flags to export the list element.
+Firstly, the `--path`/`-l` flag places the data input at an addressable location.
+Then the `--expression`/`-e` flag is used to reach into that location and
+select the element at index `2` in the list.
+This results in the 3rd element being exported,
+because CUE list indices start at zero.
+
+## Related content
+
+- {{<linkto/related/reference"command/cue-export">}} -- including:
+  - [Using the `--path`/`-l` flag]({{<relref"docs/concept/using-the-cue-export-command/inputs">}}#non-cue-data-location)
+  - [Using the `--expression`/`-e` flag]({{<relref"docs/concept/using-the-cue-export-command/evaluation">}}#modified-expression)
+- {{<linkto/related/howto"export-fields-whose-names-are-not-valid-identifiers">}}
+- {{<linkto/related/howto"refer-to-fields-whose-names-are-not-valid-identifiers">}}

content/docs/howto/export-top-level-list-element/gen_cache.cue

@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"export-top-level-list-element": {
+					page: {
+						cache: {
+							code: {
+								example: "k8YJuFjKvCSXqfc47P1cTKJ6ARP+KUBgFixj0UTHE0k="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/howto/export-top-level-list-element/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "export-top-level-list-element": page: _

hugo/content/en/docs/howto/export-top-level-list-element/index.md

@@ -0,0 +1,48 @@
+---
+title: Exporting an element from a top-level data list
+authors: [jpluscplusm]
+toc_hide: true
+---
+
+Many data formats can encode lists at their top-level, such as JSON arrays and
+YAML sequences.
+This guide demonstrates how to export an element from such a list using only
+the `cue` command.
+
+{{< code-tabs >}}
+{{< code-tab name="data.yaml" language="yaml" area="top-left" >}}
+# This list contains five elements of mixed types,
+# including structs, simple values, and other lists.
+- some: data
+  in: { a: list }
+- [ 1, 2, 3 ]
+- a: list element
+  of: { type: struct }
+- 4
+- 5
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" area="top-right" type="terminal" codetocopy="Y3VlIGV4cG9ydCBkYXRhLnlhbWwgLWwgaW5wdXQ6IC1lIGlucHV0WzJd" >}}
+$ cue export data.yaml -l input: -e input[2]
+{
+    "a": "list element",
+    "of": {
+        "type": "struct"
+    }
+}
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+The `cue export` command shown above uses two flags to export the list element.
+Firstly, the `--path`/`-l` flag places the data input at an addressable location.
+Then the `--expression`/`-e` flag is used to reach into that location and
+select the element at index `2` in the list.
+This results in the 3rd element being exported,
+because CUE list indices start at zero.
+
+## Related content
+
+- {{<linkto/related/reference"command/cue-export">}} -- including:
+  - [Using the `--path`/`-l` flag]({{<relref"docs/concept/using-the-cue-export-command/inputs">}}#non-cue-data-location)
+  - [Using the `--expression`/`-e` flag]({{<relref"docs/concept/using-the-cue-export-command/evaluation">}}#modified-expression)
+- {{<linkto/related/howto"export-fields-whose-names-are-not-valid-identifiers">}}
+- {{<linkto/related/howto"refer-to-fields-whose-names-are-not-valid-identifiers">}}