docs/howto: ensure one list is a subset of another

This adds a guide demonstrating how to use CUE's built-in "or" function
to ensure one list contains only values found in another list.

A "matchN"-based approach could also be used to achieve this, but it
might prove more fiddly to encode in a generic form that can be
trivially copied and pasted by the reader. cue-lang/docs-and-content#169
is left open to track this additional possibility.

For cue-lang/docs-and-content#169.

Signed-off-by: Jonathan Matthews <[email protected]>
Preview-Path: /docs/howto/ensure-list-is-subset-of-another-list/
Change-Id: Idc7a60d0290f26a2376189bdd4af56257ac3c8b2
Dispatch-Trailer: {"type":"trybot","CL":1206329,"patchset":1,"ref":"refs/changes/29/1206329/1","targetBranch":"master"}

content/docs/howto/ensure-list-is-subset-of-another-list/en.md

@@ -0,0 +1,60 @@
+---
+title: Ensuring a list is a subset of another list
+tags: [commented cue]
+authors: [jpluscplusm]
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto/about-commented-cue-guides" >}})
+demonstrates how to make sure that a list of concrete, simple values only
+contains elements that are *also* present in another list.
+In other words, how to ensure that one list is a subset of another list.
+
+{{{with code "en" "cc"}}}
+! exec cue vet
+cmp stderr out
+-- file.cue --
+package example
+
+_X: ["a", "b", "c"]
+
+A: ["a", "a", "b", "a"]
+// A must contain only values in _X.
+A: [...or(_X)]
+
+B: ["a", "b", "b", "E"]
+// B must be a subset of _X.
+B: [...or(_X)]
+-- out --
+B.3: 3 errors in empty disjunction:
+B.3: conflicting values "a" and "E":
+    ./file.cue:3:6
+    ./file.cue:9:20
+    ./file.cue:11:5
+B.3: conflicting values "b" and "E":
+    ./file.cue:3:11
+    ./file.cue:9:20
+    ./file.cue:11:5
+B.3: conflicting values "c" and "E":
+    ./file.cue:3:16
+    ./file.cue:9:20
+    ./file.cue:11:5
+{{{end}}}
+
+{{<info>}}
+This guide shows some lists of concrete and simple values being validated against another list.
+
+The technique it demonstrates can also be used to validate incomplete
+(non-concrete) and composite (struct and list) values, but the rules around its
+use are nuanced and evolving.
+
+{{<issue 2583>}}Issue #2583{{</issue>}} tracks some open questions about
+comparability in CUE that are worth considering before using this technique
+to validate more complex values.
+{{</info>}}
+
+## Related content
+
+- {{<issue 2583>}}Issue #2583{{</issue>}}
+- Reference: [The CUE Language Specification: Comparison operators]({{< relref "docs/reference/spec" >}}#comparison-operators)
+  -- CUE's comparability rules

content/docs/howto/ensure-list-is-subset-of-another-list/gen_cache.cue

@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"ensure-list-is-subset-of-another-list": {
+					page: {
+						cache: {
+							code: {
+								cc: "+aNd4pXHt/dhbIH1Pl6fiqAWuU8hyvI/75vTEIA8Ge4="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/howto/ensure-list-is-subset-of-another-list/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "ensure-list-is-subset-of-another-list": page: _

hugo/content/en/docs/howto/ensure-list-is-subset-of-another-list/index.md

@@ -0,0 +1,61 @@
+---
+title: Ensuring a list is a subset of another list
+tags: [commented cue]
+authors: [jpluscplusm]
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto/about-commented-cue-guides" >}})
+demonstrates how to make sure that a list of concrete, simple values only
+contains elements that are *also* present in another list.
+In other words, how to ensure that one list is a subset of another list.
+
+{{< code-tabs >}}
+{{< code-tab name="file.cue" language="cue" area="top-left" >}}
+package example
+
+_X: ["a", "b", "c"]
+
+A: ["a", "a", "b", "a"]
+// A must contain only values in _X.
+A: [...or(_X)]
+
+B: ["a", "b", "b", "E"]
+// B must be a subset of _X.
+B: [...or(_X)]
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" area="top-right" type="terminal" codetocopy="Y3VlIHZldA==" >}}
+$ cue vet
+B.3: 3 errors in empty disjunction:
+B.3: conflicting values "a" and "E":
+    ./file.cue:3:6
+    ./file.cue:9:20
+    ./file.cue:11:5
+B.3: conflicting values "b" and "E":
+    ./file.cue:3:11
+    ./file.cue:9:20
+    ./file.cue:11:5
+B.3: conflicting values "c" and "E":
+    ./file.cue:3:16
+    ./file.cue:9:20
+    ./file.cue:11:5
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+{{<info>}}
+This guide shows some lists of concrete and simple values being validated against another list.
+
+The technique it demonstrates can also be used to validate incomplete
+(non-concrete) and composite (struct and list) values, but the rules around its
+use are nuanced and evolving.
+
+{{<issue 2583>}}Issue #2583{{</issue>}} tracks some open questions about
+comparability in CUE that are worth considering before using this technique
+to validate more complex values.
+{{</info>}}
+
+## Related content
+
+- {{<issue 2583>}}Issue #2583{{</issue>}}
+- Reference: [The CUE Language Specification: Comparison operators]({{< relref "docs/reference/spec" >}}#comparison-operators)
+  -- CUE's comparability rules