docs/howto: use list.Contains

This adds a pair of Commented CUE guides demonstrating how to use list.Contains to report if value is found in a list, and how to use it as a validator. Preview-Path: /docs/howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/ Preview-Path: /docs/howto/use-the-built-in-function-list-contains-as-a-list-validator/ Signed-off-by: Jonathan Matthews <[email protected]> Change-Id: I5db7e64b786f239d031cfec00e4ba50db0ef8e0f Dispatch-Trailer: {"type":"trybot","CL":1174384,"patchset":15,"ref":"refs/changes/84/1174384/15","targetBranch":"alpha"}
cue-lang · Jan 24, 2024 · 22c253f · 22c253f
1 parent 6dde690
commit 22c253f
Show file tree

Hide file tree

Showing 8 changed files with 488 additions and 0 deletions.
diff --git a/...use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/en.md b/...use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/en.md
@@ -0,0 +1,92 @@
+---
+title: Using the built-in function "list.Contains" to report if a value is in a list
+tags:
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the built-in function
+[`list.Contains`](https://pkg.go.dev/cuelang.org/go/pkg/list#Contains)
+to report if a simple or composite value is contained in a list.
+
+{{{with code "en" "cc"}}}
+#location top bottom
+
+exec cue eval
+cmp stdout out
+-- file.cue --
+package example
+
+import "list"
+
+// When passed two arguments, list.Contains returns a boolean value reporting
+// if the second argument is an element present at the top level of the first.
+contains: list.Contains([1, 2, 3, 4, 5], 4)
+
+// The example contents of _source are assigned below.
+_source: [...]
+
+// Either of list.Contains' arguments may be a reference.
+containsBasicInt:    list.Contains(_source, 1)
+containsBasicString: list.Contains(_source, "TWO")
+
+// If the second argument is a struct, then for a match to be reported all the
+// struct's fields must be present inside a single struct member of the first
+// argument, with both structs' fields holding equivalent values. There must be
+// no additional fields present.
+containsStructMissingField: list.Contains(_source, {
+	asInt: 3
+})
+containsStructAllFields: list.Contains(_source, {
+	asInt:    3
+	asString: "three"
+})
+containsStructExtraFields: list.Contains(_source, {
+	asInt:    3
+	asString: "three"
+	asFloat:  3.0
+})
+
+// If the second argument is a list, then the entire list must be an element
+// present at the top level of the first argument, with both lists' elements
+// holding the same values in the same order.
+containsListMissingElement: list.Contains(_source, ["four"])
+containsListAllElementsIncorrectOrder: list.Contains(_source, ["four", 4])
+containsListAllElementsCorrectOrder: list.Contains(_source, [4, "four"])
+containsListExtraElements: list.Contains(_source, ["four", 4, 4.0])
+
+_source: [
+	1, "two",
+	{asInt: 3, asString: "three"},
+	[4, "four"],
+]
+-- out --
+contains:                              true
+containsBasicInt:                      true
+containsBasicString:                   false
+containsStructMissingField:            false
+containsStructAllFields:               true
+containsStructExtraFields:             false
+containsListMissingElement:            false
+containsListAllElementsIncorrectOrder: false
+containsListAllElementsCorrectOrder:   true
+containsListExtraElements:             false
+{{{end}}}
+
+{{< info >}}
+[Issue #49](https://github.com/cue-lang/docs-and-content/issues/49) tracks the
+documentation of precisely what CUE means by values being "equivalent",
+"equal", or "comparable". When this documentation is complete it will be linked
+to, and fewer examples will be presented in this guide.
+{{< /info >}}
+
+## Related content
+
+- `list.Contains` can also be used
+  [as a field validator]({{< relref
+    "../use-the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list"
+  >}})
+- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package
diff --git a/...o/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/gen_cache.cue b/...o/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/gen_cache.cue
@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list": {
+					page: {
+						cache: {
+							code: {
+								cc: "7y8OZIMI60CsLiJQHcQ6gsT0ztL7h/dnmw2hLL39RMk="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}
diff --git a/.../howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/page.cue b/.../howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/page.cue
@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list": {}
diff --git a/...the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list/en.md b/...the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list/en.md
@@ -0,0 +1,132 @@
+---
+title: Using the built-in function "list.Contains" to validate that a value is in a list
+tags:
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the built-in function
+[`list.Contains`](https://pkg.go.dev/cuelang.org/go/pkg/list#Contains)
+as a validator that checks if a simple or composite value is contained in a
+list.
+
+{{{with code "en" "cc"}}}
+#location top bottom
+
+! exec cue vet
+cmp stderr out
+-- file.cue --
+package example
+
+import "list"
+
+// The example contents of aList are assigned below.
+aList: [...]
+
+// When passed a single argument and unified with a list, list.Contains emits
+// an error if the argument is not an element present at the top level of the
+// unified list.
+aList: list.Contains(1)
+aList: list.Contains("TWO")
+
+// If the argument is a struct, then all the struct's fields must be present
+// inside a single struct member of the unified list, with both structs' fields
+// holding equivalent values. There must be no additional fields present.
+aList: list.Contains({asInt: 3})
+aList: list.Contains({asInt: 3, asString: "three"})
+aList: list.Contains({asInt: 3, asString: "three", asFloat: 3.0})
+
+// If the argument is a list, then the entire list must be an element present
+// at the top level of the unified list, with both lists' elements holding the
+// same values in the same order.
+aList: list.Contains(["four"])
+aList: list.Contains(["four", 4])
+aList: list.Contains([4, "four"])
+aList: list.Contains(["four", 4, 4.0])
+
+aList: [
+	1, "two",
+	{asInt: 3, asString: "three"},
+	[4, "four"],
+]
+-- out --
+aList: invalid value [1,"two",{asInt:3,asString:"three"},[4,"four"]] (does not satisfy list.Contains("TWO")):
+    ./file.cue:12:8
+    ./file.cue:6:8
+    ./file.cue:11:8
+    ./file.cue:12:22
+    ./file.cue:17:8
+    ./file.cue:18:8
+    ./file.cue:19:8
+    ./file.cue:24:8
+    ./file.cue:25:8
+    ./file.cue:26:8
+    ./file.cue:27:8
+    ./file.cue:29:8
+aList: invalid value [1,"two",{asInt:3,asString:"three"},[4,"four"]] (does not satisfy list.Contains({asInt:3})):
+    ./file.cue:17:8
+    ./file.cue:6:8
+    ./file.cue:11:8
+    ./file.cue:12:8
+    ./file.cue:18:8
+    ./file.cue:19:8
+    ./file.cue:24:8
+    ./file.cue:25:8
+    ./file.cue:26:8
+    ./file.cue:27:8
+    ./file.cue:29:8
+aList: invalid value [1,"two",{asInt:3,asString:"three"},[4,"four"]] (does not satisfy list.Contains({asInt:3,asString:"three",asFloat:3.0})):
+    ./file.cue:19:8
+    ./file.cue:6:8
+    ./file.cue:11:8
+    ./file.cue:12:8
+    ./file.cue:17:8
+    ./file.cue:18:8
+    ./file.cue:24:8
+    ./file.cue:25:8
+    ./file.cue:26:8
+    ./file.cue:27:8
+    ./file.cue:29:8
+aList: invalid value [1,"two",{asInt:3,asString:"three"},[4,"four"]] (does not satisfy list.Contains(["four"])):
+    ./file.cue:24:8
+    ./file.cue:6:8
+    ./file.cue:11:8
+    ./file.cue:12:8
+    ./file.cue:17:8
+    ./file.cue:18:8
+    ./file.cue:19:8
+    ./file.cue:25:8
+    ./file.cue:26:8
+    ./file.cue:27:8
+    ./file.cue:29:8
+aList: invalid value [1,"two",{asInt:3,asString:"three"},[4,"four"]] (does not satisfy list.Contains(["four",4,4.0])):
+    ./file.cue:27:8
+    ./file.cue:6:8
+    ./file.cue:11:8
+    ./file.cue:12:8
+    ./file.cue:17:8
+    ./file.cue:18:8
+    ./file.cue:19:8
+    ./file.cue:24:8
+    ./file.cue:25:8
+    ./file.cue:26:8
+    ./file.cue:29:8
+{{{end}}}
+
+{{< info >}}
+[Issue #49](https://github.com/cue-lang/docs-and-content/issues/49) tracks the
+documentation of precisely what CUE means by values being "equivalent",
+"equal", or "comparable". When this documentation is complete it will be linked
+to, and fewer examples will be presented in this guide.
+{{< /info >}}
+
+## Related content
+
+- `list.Contains` can also be used
+  [to report if a value is in a list]({{< relref
+    "../use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list"
+  >}})
+- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package
diff --git a/...e-the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list/gen_cache.cue b/...e-the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list/gen_cache.cue
@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list": {
+					page: {
+						cache: {
+							code: {
+								cc: "hv8PfR/54xrzDBdAYXVKZCrJ+3ampKOVguKYaTTqDAg="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}
diff --git a/...to/use-the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list/page.cue b/...to/use-the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list/page.cue
@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list": {}
diff --git a/...-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/index.md b/...-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/index.md
@@ -0,0 +1,91 @@
+---
+title: Using the built-in function "list.Contains" to report if a value is in a list
+tags:
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the built-in function
+[`list.Contains`](https://pkg.go.dev/cuelang.org/go/pkg/list#Contains)
+to report if a simple or composite value is contained in a list.
+
+{{< code-tabs >}}
+{{< code-tab name="file.cue" language="cue"  area="top" >}}
+package example
+
+import "list"
+
+// When passed two arguments, list.Contains returns a boolean value reporting
+// if the second argument is an element present at the top level of the first.
+contains: list.Contains([1, 2, 3, 4, 5], 4)
+
+// The example contents of _source are assigned below.
+_source: [...]
+
+// Either of list.Contains' arguments may be a reference.
+containsBasicInt:    list.Contains(_source, 1)
+containsBasicString: list.Contains(_source, "TWO")
+
+// If the second argument is a struct, then for a match to be reported all the
+// struct's fields must be present inside a single struct member of the first
+// argument, with both structs' fields holding equivalent values. There must be
+// no additional fields present.
+containsStructMissingField: list.Contains(_source, {
+	asInt: 3
+})
+containsStructAllFields: list.Contains(_source, {
+	asInt:    3
+	asString: "three"
+})
+containsStructExtraFields: list.Contains(_source, {
+	asInt:    3
+	asString: "three"
+	asFloat:  3.0
+})
+
+// If the second argument is a list, then the entire list must be an element
+// present at the top level of the first argument, with both lists' elements
+// holding the same values in the same order.
+containsListMissingElement: list.Contains(_source, ["four"])
+containsListAllElementsIncorrectOrder: list.Contains(_source, ["four", 4])
+containsListAllElementsCorrectOrder: list.Contains(_source, [4, "four"])
+containsListExtraElements: list.Contains(_source, ["four", 4, 4.0])
+
+_source: [
+	1, "two",
+	{asInt: 3, asString: "three"},
+	[4, "four"],
+]
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" type="terminal" area="bottom" >}}
+$ cue eval
+contains:                              true
+containsBasicInt:                      true
+containsBasicString:                   false
+containsStructMissingField:            false
+containsStructAllFields:               true
+containsStructExtraFields:             false
+containsListMissingElement:            false
+containsListAllElementsIncorrectOrder: false
+containsListAllElementsCorrectOrder:   true
+containsListExtraElements:             false
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+{{< info >}}
+[Issue #49](https://github.com/cue-lang/docs-and-content/issues/49) tracks the
+documentation of precisely what CUE means by values being "equivalent",
+"equal", or "comparable". When this documentation is complete it will be linked
+to, and fewer examples will be presented in this guide.
+{{< /info >}}
+
+## Related content
+
+- `list.Contains` can also be used
+  [as a field validator]({{< relref
+    "../use-the-built-in-function-list-contains-to-validate-that-a-value-is-in-a-list"
+  >}})
+- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) 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-list-contains-to-report-if-a-value-is-in-a-list": {}