docs/howto: use encoding/csv.{De,En}code

This adds 3 Commented CUE guides demonstrating how to use the built-in functions encoding/csv.Decode and encoding/csv.Encode. The Decode function merits 2 separate guides, explaining both how to access CSV data stored natively inside CUE as a multi-line string, and also the (potentially) more common use case of how to use the cue CLI to access data stored in discrete CSV files. Preview-Path: /docs/howto/use-the-built-in-function-encoding-csv-decode-to-access-csv-data-stored-as-a-string/ Preview-Path: /docs/howto/use-the-built-in-function-encoding-csv-decode-to-access-data-stored-in-a-csv-file/ Preview-Path: /docs/howto/use-the-built-in-function-encoding-csv-encode-to-emit-csv-data/ Signed-off-by: Jonathan Matthews <[email protected]> Change-Id: I060a297b20335f6e36a51efbc36cc7a01e868fb8 Reviewed-on: https://review.gerrithub.io/c/cue-lang/cuelang.org/+/1174183 TryBot-Result: CUEcueckoo <[email protected]> Reviewed-by: Paul Jolly <[email protected]>
cue-lang · Jan 22, 2024 · a612189 · a612189
1 parent 559247b
commit a612189
Show file tree

Hide file tree

Showing 12 changed files with 435 additions and 0 deletions.
diff --git a/...ilt-in-function-encoding-csv-decode-to-access-csv-data-stored-as-a-string/en.md b/...ilt-in-function-encoding-csv-decode-to-access-csv-data-stored-as-a-string/en.md
@@ -0,0 +1,71 @@
+---
+title: Using the built-in function "encoding/csv.Decode" to access CSV data stored as a string
+tags:
+- commented cue
+- encodings
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the built-in function
+[`encoding/csv.Decode`](https://pkg.go.dev/cuelang.org/go/pkg/encoding/csv#Decode)
+to decode a string containing comma-separated values (CSV) into a list of
+lists.
+
+{{{with code "en" "cc"}}}
+exec cue export -e output
+cmp stdout out
+-- file.cue --
+package example
+
+import "encoding/csv"
+
+data: """
+	Id,Name,Location,Species
+	1,Charlie,"Ripon, North Yorkshire",cat
+	2,Fred,San Francisco,cat
+	3,Greyfriars Bobby,Edinburgh,dog
+	4,Nemo,???,fish
+	"""
+
+output: csv.Decode(data)
+-- out --
+[
+    [
+        "Id",
+        "Name",
+        "Location",
+        "Species"
+    ],
+    [
+        "1",
+        "Charlie",
+        "Ripon, North Yorkshire",
+        "cat"
+    ],
+    [
+        "2",
+        "Fred",
+        "San Francisco",
+        "cat"
+    ],
+    [
+        "3",
+        "Greyfriars Bobby",
+        "Edinburgh",
+        "dog"
+    ],
+    [
+        "4",
+        "Nemo",
+        "???",
+        "fish"
+    ]
+]
+{{{end}}}
+
+## Related content
+
+- The [`encoding/csv`](https://pkg.go.dev/cuelang.org/go/pkg/encoding/csv) built-in package
diff --git a/...built-in-function-encoding-csv-decode-to-access-csv-data-stored-as-a-string/gen_cache.cue b/...built-in-function-encoding-csv-decode-to-access-csv-data-stored-as-a-string/gen_cache.cue
@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-the-built-in-function-encoding-csv-decode-to-access-csv-data-stored-as-a-string": {
+					page: {
+						cache: {
+							code: {
+								cc: "qb3Ovwt0UuGd59488zDWr8EyBEfjJok2ic1/QIAjP4E="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}
diff --git a/...-the-built-in-function-encoding-csv-decode-to-access-csv-data-stored-as-a-string/page.cue b/...-the-built-in-function-encoding-csv-decode-to-access-csv-data-stored-as-a-string/page.cue
@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-the-built-in-function-encoding-csv-decode-to-access-csv-data-stored-as-a-string": {}
diff --git a/...built-in-function-encoding-csv-decode-to-access-data-stored-in-a-csv-file/en.md b/...built-in-function-encoding-csv-decode-to-access-data-stored-in-a-csv-file/en.md
@@ -0,0 +1,69 @@
+---
+title: Using the built-in function "encoding/csv.Decode" to access data stored in a CSV file
+tags:
+- commented cue
+- encodings
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the built-in function
+[`encoding/csv.Decode`](https://pkg.go.dev/cuelang.org/go/pkg/encoding/csv#Decode)
+to decode a file containing comma-separated values (CSV) into a list of lists.
+
+{{{with code "en" "cc"}}}
+exec cue export file.cue -l input: text: data.csv -e output
+cmp stdout out
+-- data.csv --
+Id,Name,Location,Species
+1,Charlie,"Ripon, North Yorkshire",cat
+2,Fred,San Francisco,cat
+3,Greyfriars Bobby,Edinburgh,dog
+4,Nemo,???,fish
+-- file.cue --
+package example
+
+import "encoding/csv"
+
+input:  string
+output: csv.Decode(input)
+-- out --
+[
+    [
+        "Id",
+        "Name",
+        "Location",
+        "Species"
+    ],
+    [
+        "1",
+        "Charlie",
+        "Ripon, North Yorkshire",
+        "cat"
+    ],
+    [
+        "2",
+        "Fred",
+        "San Francisco",
+        "cat"
+    ],
+    [
+        "3",
+        "Greyfriars Bobby",
+        "Edinburgh",
+        "dog"
+    ],
+    [
+        "4",
+        "Nemo",
+        "???",
+        "fish"
+    ]
+]
+{{{end}}}
+
+## Related content
+
+- The [`encoding/csv`](https://pkg.go.dev/cuelang.org/go/pkg/encoding/csv) built-in package
diff --git a/...e-built-in-function-encoding-csv-decode-to-access-data-stored-in-a-csv-file/gen_cache.cue b/...e-built-in-function-encoding-csv-decode-to-access-data-stored-in-a-csv-file/gen_cache.cue
@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-the-built-in-function-encoding-csv-decode-to-access-data-stored-in-a-csv-file": {
+					page: {
+						cache: {
+							code: {
+								cc: "tHyh1em7sHbIHYawISEep1prc5vp/XZwo7rqukH2l9Y="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}
diff --git a/...se-the-built-in-function-encoding-csv-decode-to-access-data-stored-in-a-csv-file/page.cue b/...se-the-built-in-function-encoding-csv-decode-to-access-data-stored-in-a-csv-file/page.cue
@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-the-built-in-function-encoding-csv-decode-to-access-data-stored-in-a-csv-file": {}
diff --git a/...docs/howto/use-the-built-in-function-encoding-csv-encode-to-emit-csv-data/en.md b/...docs/howto/use-the-built-in-function-encoding-csv-encode-to-emit-csv-data/en.md
@@ -0,0 +1,44 @@
+---
+title: Using the built-in function "encoding/csv.Encode" to emit CSV data
+tags:
+- commented cue
+- encodings
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the built-in function
+[`encoding/csv.Encode`](https://pkg.go.dev/cuelang.org/go/pkg/encoding/csv#Encode)
+to encode a list of lists into a string as comma-separated values (CSV).
+
+{{{with code "en" "cc"}}}
+exec cue export -e output --out text
+cmp stdout out
+-- file.cue --
+package example
+
+import "encoding/csv"
+
+data: [
+	["Id", "Name", "Location", "Species"],
+	["1", "Charlie", "Ripon, North Yorkshire", "cat"],
+	["2", "Fred", "San Francisco", "cat"],
+	["3", "Greyfriars Bobby", "Edinburgh", "dog"],
+	["4", "Nemo", "???", "fish"],
+]
+
+output: csv.Encode(data)
+-- out --
+Id,Name,Location,Species
+1,Charlie,"Ripon, North Yorkshire",cat
+2,Fred,San Francisco,cat
+3,Greyfriars Bobby,Edinburgh,dog
+4,Nemo,???,fish
+
+{{{end}}}
+
+## Related content
+
+- The [`encoding/csv`](https://pkg.go.dev/cuelang.org/go/pkg/encoding/csv) built-in package
diff --git a/...t/docs/howto/use-the-built-in-function-encoding-csv-encode-to-emit-csv-data/gen_cache.cue b/...t/docs/howto/use-the-built-in-function-encoding-csv-encode-to-emit-csv-data/gen_cache.cue
@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-the-built-in-function-encoding-csv-encode-to-emit-csv-data": {
+					page: {
+						cache: {
+							code: {
+								cc: "Mg2lD5dfuXSK/A2VfdIpOvbj1ontkBweDL3sOQ9HtfY="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}
diff --git a/content/docs/howto/use-the-built-in-function-encoding-csv-encode-to-emit-csv-data/page.cue b/content/docs/howto/use-the-built-in-function-encoding-csv-encode-to-emit-csv-data/page.cue
@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-the-built-in-function-encoding-csv-encode-to-emit-csv-data": {}
diff --git a/...-in-function-encoding-csv-decode-to-access-csv-data-stored-as-a-string/index.md b/...-in-function-encoding-csv-decode-to-access-csv-data-stored-as-a-string/index.md
@@ -0,0 +1,72 @@
+---
+title: Using the built-in function "encoding/csv.Decode" to access CSV data stored as a string
+tags:
+- commented cue
+- encodings
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the built-in function
+[`encoding/csv.Decode`](https://pkg.go.dev/cuelang.org/go/pkg/encoding/csv#Decode)
+to decode a string containing comma-separated values (CSV) into a list of
+lists.
+
+{{< code-tabs >}}
+{{< code-tab name="file.cue" language="cue"  area="top-left" >}}
+package example
+
+import "encoding/csv"
+
+data: """
+	Id,Name,Location,Species
+	1,Charlie,"Ripon, North Yorkshire",cat
+	2,Fred,San Francisco,cat
+	3,Greyfriars Bobby,Edinburgh,dog
+	4,Nemo,???,fish
+	"""
+
+output: csv.Decode(data)
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" type="terminal" area="top-right" >}}
+$ cue export -e output
+[
+    [
+        "Id",
+        "Name",
+        "Location",
+        "Species"
+    ],
+    [
+        "1",
+        "Charlie",
+        "Ripon, North Yorkshire",
+        "cat"
+    ],
+    [
+        "2",
+        "Fred",
+        "San Francisco",
+        "cat"
+    ],
+    [
+        "3",
+        "Greyfriars Bobby",
+        "Edinburgh",
+        "dog"
+    ],
+    [
+        "4",
+        "Nemo",
+        "???",
+        "fish"
+    ]
+]
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+## Related content
+
+- The [`encoding/csv`](https://pkg.go.dev/cuelang.org/go/pkg/encoding/csv) built-in package
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		package site

		content: docs: howto: "use-the-built-in-function-encoding-csv-decode-to-access-csv-data-stored-as-a-string": {}