docs/howto: combine multiple files by using metadata

This adds a yaml/json pair of commented cue guides that demonstrate
placing multiple input files at dynamic path locations based on their
filename metadata.

For cue-lang/docs-and-content#7

Preview-Path: /docs/howto/combine-multiple-json-files-by-using-file-metadata/
Preview-Path: /docs/howto/combine-multiple-yaml-files-by-using-file-metadata/
Signed-off-by: Jonathan Matthews <[email protected]>
Change-Id: I76f47ddddd99999aaaaeb3838ae3916dc1ef6761
Dispatch-Trailer: {"type":"trybot","CL":1173580,"patchset":5,"ref":"refs/changes/80/1173580/5","targetBranch":"alpha"}

content/docs/howto/combine-multiple-json-files-by-using-file-metadata/en.md

@@ -0,0 +1,100 @@
+---
+title: Combining multiple JSON files by using file metadata
+tags:
+- cue command
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto/#commented-cue" >}}) demonstrates
+how to use the `cue` command to combine multiple JSON files by making reference
+to the files' metadata.
+
+The **`TERMINAL`** section shows the use of:
+- the `--with-context` parameter, which makes information about each input file
+  available as metadata
+- the `filename` metadata field combined with the `-l` parameter, which places
+  each file's contents at an individual and deterministic location in the
+  evaluation space
+
+{{{with code "en" "cc"}}}
+#location top-right top-left top-left top-left bottom
+
+exec cue export --with-context -l 'inputs:' -l 'path.Base(filename)' -e output a.json b.json c.json example.cue
+cmp stdout out
+-- example.cue --
+package example
+
+// inputs is the location under which we place
+// each data file's contents, so that their
+// contents can be accessed by the CUE in this
+// file. The cue CLI -l parameter places them
+// here, under a secondary key determined by each
+// file's name.
+inputs: [string]: _
+
+output: {
+	for _name, _content in inputs {
+		(_name): {
+			filename: _name
+			content:  _content
+		}
+	}
+}
+-- a.json --
+{
+    "a": 1,
+    "b": 2,
+    "c": 3
+}
+-- b.json --
+{
+    "a": "a string",
+    "b": true,
+    "c": 42
+}
+-- c.json --
+[
+    "a list element",
+    "another element",
+    "the last element"
+]
+-- out --
+{
+    "a.json": {
+        "filename": "a.json",
+        "content": {
+            "a": 1,
+            "b": 2,
+            "c": 3
+        }
+    },
+    "b.json": {
+        "filename": "b.json",
+        "content": {
+            "a": "a string",
+            "b": true,
+            "c": 42
+        }
+    },
+    "c.json": {
+        "filename": "c.json",
+        "content": [
+            "a list element",
+            "another element",
+            "the last element"
+        ]
+    }
+}
+{{{end}}}
+
+## Related content
+
+- [Combining multiple YAML files by using file metadata]({{< relref
+    "../combine-multiple-yaml-files-by-using-file-metadata"
+  >}})
+- [cue help flags]({{< relref
+    "docs/reference/cli/cue-flags"
+  >}}) documents the `--with-context` and `-l` flags

content/docs/howto/combine-multiple-json-files-by-using-file-metadata/gen_cache.cue

@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"combine-multiple-json-files-by-using-file-metadata": {
+					page: {
+						cache: {
+							code: {
+								cc: "jojRN9qbopZeqZ+9E0cKYowypjawCrNbXI/ilS7Dt7g="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/howto/combine-multiple-json-files-by-using-file-metadata/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "combine-multiple-json-files-by-using-file-metadata": {}

content/docs/howto/combine-multiple-yaml-files-by-using-file-metadata/en.md

@@ -0,0 +1,86 @@
+---
+title: Combining multiple YAML files by using file metadata
+tags:
+- cue command
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto/#commented-cue" >}}) demonstrates
+how to use the `cue` command to combine multiple YAML files by making reference
+to the files' metadata.
+
+The **`TERMINAL`** section shows the use of:
+- the `--with-context` parameter, which makes information about each input file
+  available as metadata
+- the `filename` metadata field combined with the `-l` parameter, which places
+  each file's contents at an individual and deterministic location in the
+  evaluation space
+
+{{{with code "en" "cc"}}}
+#location top-right top-left top-left top-left bottom
+
+exec cue export --with-context -l 'inputs:' -l 'path.Base(filename)' -e output a.yaml b.yml c.yaml example.cue --out yaml
+cmp stdout out
+-- example.cue --
+package example
+
+// inputs is the location under which we place
+// each data file's contents, so that their
+// contents can be accessed by the CUE in this
+// file. The cue CLI -l parameter places them
+// here, under a secondary key determined by each
+// file's name.
+inputs: [string]: _
+
+output: {
+	for _name, _content in inputs {
+		(_name): {
+			filename: _name
+			content:  _content
+		}
+	}
+}
+-- a.yaml --
+a: 1
+b: 2
+c: 3
+-- b.yml --
+a: a string
+b: true
+c: 42
+-- c.yaml --
+- a list element
+- another element
+- the last element
+-- out --
+a.yaml:
+  filename: a.yaml
+  content:
+    a: 1
+    b: 2
+    c: 3
+b.yml:
+  filename: b.yml
+  content:
+    a: a string
+    b: true
+    c: 42
+c.yaml:
+  filename: c.yaml
+  content:
+    - a list element
+    - another element
+    - the last element
+{{{end}}}
+
+## Related content
+
+- [Combining multiple JSON files by using file metadata]({{< relref
+    "../combine-multiple-json-files-by-using-file-metadata"
+  >}})
+- [cue help flags]({{< relref
+    "docs/reference/cli/cue-flags"
+  >}}) documents the `--with-context` and `-l` flags

content/docs/howto/combine-multiple-yaml-files-by-using-file-metadata/gen_cache.cue

@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"combine-multiple-yaml-files-by-using-file-metadata": {
+					page: {
+						cache: {
+							code: {
+								cc: "chq4S2pvF0rqelnytshjaC3Uj2loB79yaPcEavKCc8g="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/howto/combine-multiple-yaml-files-by-using-file-metadata/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "combine-multiple-yaml-files-by-using-file-metadata": {}

hugo/content/en/docs/howto/combine-multiple-json-files-by-using-file-metadata/index.md

@@ -0,0 +1,102 @@
+---
+title: Combining multiple JSON files by using file metadata
+tags:
+- cue command
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto/#commented-cue" >}}) demonstrates
+how to use the `cue` command to combine multiple JSON files by making reference
+to the files' metadata.
+
+The **`TERMINAL`** section shows the use of:
+- the `--with-context` parameter, which makes information about each input file
+  available as metadata
+- the `filename` metadata field combined with the `-l` parameter, which places
+  each file's contents at an individual and deterministic location in the
+  evaluation space
+
+{{< code-tabs >}}
+{{< code-tab name="example.cue" language="cue"  area="top-right" >}}
+package example
+
+// inputs is the location under which we place
+// each data file's contents, so that their
+// contents can be accessed by the CUE in this
+// file. The cue CLI -l parameter places them
+// here, under a secondary key determined by each
+// file's name.
+inputs: [string]: _
+
+output: {
+	for _name, _content in inputs {
+		(_name): {
+			filename: _name
+			content:  _content
+		}
+	}
+}
+{{< /code-tab >}}
+{{< code-tab name="a.json" language="json"  area="top-left" >}}
+{
+    "a": 1,
+    "b": 2,
+    "c": 3
+}
+{{< /code-tab >}}
+{{< code-tab name="b.json" language="json"  area="top-left" >}}
+{
+    "a": "a string",
+    "b": true,
+    "c": 42
+}
+{{< /code-tab >}}
+{{< code-tab name="c.json" language="json"  area="top-left" >}}
+[
+    "a list element",
+    "another element",
+    "the last element"
+]
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" type="terminal" area="bottom" >}}
+$ cue export --with-context -l 'inputs:' -l 'path.Base(filename)' -e output a.json b.json c.json example.cue
+{
+    "a.json": {
+        "filename": "a.json",
+        "content": {
+            "a": 1,
+            "b": 2,
+            "c": 3
+        }
+    },
+    "b.json": {
+        "filename": "b.json",
+        "content": {
+            "a": "a string",
+            "b": true,
+            "c": 42
+        }
+    },
+    "c.json": {
+        "filename": "c.json",
+        "content": [
+            "a list element",
+            "another element",
+            "the last element"
+        ]
+    }
+}
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+## Related content
+
+- [Combining multiple YAML files by using file metadata]({{< relref
+    "../combine-multiple-yaml-files-by-using-file-metadata"
+  >}})
+- [cue help flags]({{< relref
+    "docs/reference/cli/cue-flags"
+  >}}) documents the `--with-context` and `-l` flags