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":4,"ref":"refs/changes/67/1208967/4","targetBranch":"master"}

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

@@ -0,0 +1,36 @@
+---
+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 --
+- A
+- B
+- C
+- D
+- E
+-- out --
+"C"
+{{{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.
+
+## 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: "4GBkWxfXnm5A6VoOJGJhkAUl4k7vrVq8Uj+kTKuZyCs="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

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,37 @@
+---
+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" >}}
+- A
+- B
+- C
+- D
+- E
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" area="top-right" type="terminal" codetocopy="Y3VlIGV4cG9ydCBkYXRhLnlhbWwgLWwgaW5wdXQ6IC1lIGlucHV0WzJd" >}}
+$ cue export data.yaml -l input: -e input[2]
+"C"
+{{< /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.
+
+## 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">}}