docs/howto: use list.Contains to search in a list

This adds a Commented CUE guide demonstrating how to use list.Contains to report if value is found in a list. The function call is initially demonstrated with an inline example, and then in slightly more structured form with 2x2 simple and 1x2 composite examples. It's important to include the composite example to show the range of options that /don't/ trigger a positive result - i.e. what CUE /doesn't/ consider a match by this function's standards. Preview-Path: /docs/howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/ Signed-off-by: Jonathan Matthews <[email protected]> Change-Id: I5db7e64b786f239d031cfec00e4ba50db0ef8e0f Dispatch-Trailer: {"type":"trybot","CL":1174384,"patchset":14,"ref":"refs/changes/84/1174384/14","targetBranch":"alpha"}
cue-lang · Jan 23, 2024 · c373f1a · c373f1a
1 parent d686593
commit c373f1a
Show file tree

Hide file tree

Showing 8 changed files with 478 additions and 0 deletions.
diff --git a/...nt/docs/howto/use-the-built-in-function-list-contains-as-a-list-validator/en.md b/...nt/docs/howto/use-the-built-in-function-list-contains-as-a-list-validator/en.md
@@ -0,0 +1,128 @@
+---
+title: Using the built-in function "list.Contains" as a list validator
+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"
+
+// aList is the example unified with this guide's list.Contains validators.
+aList: [
+	1,
+	"two",
+	{
+		Int:    3
+		String: "three"
+	},
+	[4, "four"],
+]
+
+// When passed a single argument and unified with a list, list.Contains emits
+// an error if the argument is not an element directly contained in 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({Int: 3})
+aList: list.Contains({Int: 3, String: "three"})
+aList: list.Contains({Int: 3, String: "three", Float: 3.0})
+
+// If the argument is a list, then the entire list must be an element contained
+// directly in 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])
+-- out --
+aList: invalid value [1,"two",{Int:3,String:"three"},[4,"four"]] (does not satisfy list.Contains("TWO")):
+    ./file.cue:20:8
+    ./file.cue:6:8
+    ./file.cue:19:8
+    ./file.cue:20:22
+    ./file.cue:25:8
+    ./file.cue:26:8
+    ./file.cue:27:8
+    ./file.cue:32:8
+    ./file.cue:33:8
+    ./file.cue:34:8
+    ./file.cue:35:8
+aList: invalid value [1,"two",{Int:3,String:"three"},[4,"four"]] (does not satisfy list.Contains({Int:3})):
+    ./file.cue:25:8
+    ./file.cue:6:8
+    ./file.cue:19:8
+    ./file.cue:20:8
+    ./file.cue:26:8
+    ./file.cue:27:8
+    ./file.cue:32:8
+    ./file.cue:33:8
+    ./file.cue:34:8
+    ./file.cue:35:8
+aList: invalid value [1,"two",{Int:3,String:"three"},[4,"four"]] (does not satisfy list.Contains({Int:3,String:"three",Float:3.0})):
+    ./file.cue:27:8
+    ./file.cue:6:8
+    ./file.cue:19:8
+    ./file.cue:20:8
+    ./file.cue:25:8
+    ./file.cue:26:8
+    ./file.cue:32:8
+    ./file.cue:33:8
+    ./file.cue:34:8
+    ./file.cue:35:8
+aList: invalid value [1,"two",{Int:3,String:"three"},[4,"four"]] (does not satisfy list.Contains(["four"])):
+    ./file.cue:32:8
+    ./file.cue:6:8
+    ./file.cue:19:8
+    ./file.cue:20:8
+    ./file.cue:25:8
+    ./file.cue:26:8
+    ./file.cue:27:8
+    ./file.cue:33:8
+    ./file.cue:34:8
+    ./file.cue:35:8
+aList: invalid value [1,"two",{Int:3,String:"three"},[4,"four"]] (does not satisfy list.Contains(["four",4,4.0])):
+    ./file.cue:35:8
+    ./file.cue:6:8
+    ./file.cue:19:8
+    ./file.cue:20:8
+    ./file.cue:25:8
+    ./file.cue:26:8
+    ./file.cue:27:8
+    ./file.cue:32:8
+    ./file.cue:33:8
+    ./file.cue:34: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" or
+"equal". When this documentation is complete it will be linked from here, and
+fewer examples will be presented in this guide.
+{{< /info >}}
+
+## Related content
+
+- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package
+- How to [use the built-in function `list.Contains` to report if a value is contained in a list]({{<
+    relref "../use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list"
+  >}})
diff --git a/content/docs/howto/use-the-built-in-function-list-contains-as-a-list-validator/gen_cache.cue b/content/docs/howto/use-the-built-in-function-list-contains-as-a-list-validator/gen_cache.cue
@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-the-built-in-function-list-contains-as-a-list-validator": {
+					page: {
+						cache: {
+							code: {
+								cc: "Z1KgPyfoumAaJEKXbITd9ktHpfeJdojNOo1ewOADd6M="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}
diff --git a/content/docs/howto/use-the-built-in-function-list-contains-as-a-list-validator/page.cue b/content/docs/howto/use-the-built-in-function-list-contains-as-a-list-validator/page.cue
@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-the-built-in-function-list-contains-as-a-list-validator": {}
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,91 @@
+---
+title: Using the built-in function "list.Contains" to report if a value is contained 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 directly contained in the first.
+contains: list.Contains([1, 2, 3, 4, 5], 4)
+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, {
+	Int: 3
+})
+containsStructAllFields: list.Contains(_source, {
+	Int:    3
+	String: "three"
+})
+containsStructExtraFields: list.Contains(_source, {
+	Int:    3
+	String: "three"
+	Float:  3.0
+})
+
+// If the second argument is a list, then the entire list must be an element
+// contained directly in 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 is the list being searched through in these examples.
+_source: [
+	1,
+	"two",
+	{
+		Int:    3
+		String: "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" or
+"equal". When this documentation is complete it will be linked from here, and
+fewer examples will be presented in this guide.
+{{< /info >}}
+
+## Related content
+
+- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package
+- How to [use the built-in function `list.Contains` as a list validator]({{< 
+    relref "../use-the-built-in-function-list-contains-as-a-list-validator"
+  >}})
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: "hrMIpm1+PMtJ6rex0/vmRKo1OqiNTdnQif7aK5hygvQ="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}
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/...docs/howto/use-the-built-in-function-list-contains-as-a-list-validator/index.md b/...docs/howto/use-the-built-in-function-list-contains-as-a-list-validator/index.md
@@ -0,0 +1,127 @@
+---
+title: Using the built-in function "list.Contains" as a list validator
+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.
+
+{{< code-tabs >}}
+{{< code-tab name="file.cue" language="cue"  area="top" >}}
+package example
+
+import "list"
+
+// aList is the example unified with this guide's list.Contains validators.
+aList: [
+	1,
+	"two",
+	{
+		Int:    3
+		String: "three"
+	},
+	[4, "four"],
+]
+
+// When passed a single argument and unified with a list, list.Contains emits
+// an error if the argument is not an element directly contained in 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({Int: 3})
+aList: list.Contains({Int: 3, String: "three"})
+aList: list.Contains({Int: 3, String: "three", Float: 3.0})
+
+// If the argument is a list, then the entire list must be an element contained
+// directly in 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])
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" type="terminal" area="bottom" >}}
+$ cue vet
+aList: invalid value [1,"two",{Int:3,String:"three"},[4,"four"]] (does not satisfy list.Contains("TWO")):
+    ./file.cue:20:8
+    ./file.cue:6:8
+    ./file.cue:19:8
+    ./file.cue:20:22
+    ./file.cue:25:8
+    ./file.cue:26:8
+    ./file.cue:27:8
+    ./file.cue:32:8
+    ./file.cue:33:8
+    ./file.cue:34:8
+    ./file.cue:35:8
+aList: invalid value [1,"two",{Int:3,String:"three"},[4,"four"]] (does not satisfy list.Contains({Int:3})):
+    ./file.cue:25:8
+    ./file.cue:6:8
+    ./file.cue:19:8
+    ./file.cue:20:8
+    ./file.cue:26:8
+    ./file.cue:27:8
+    ./file.cue:32:8
+    ./file.cue:33:8
+    ./file.cue:34:8
+    ./file.cue:35:8
+aList: invalid value [1,"two",{Int:3,String:"three"},[4,"four"]] (does not satisfy list.Contains({Int:3,String:"three",Float:3.0})):
+    ./file.cue:27:8
+    ./file.cue:6:8
+    ./file.cue:19:8
+    ./file.cue:20:8
+    ./file.cue:25:8
+    ./file.cue:26:8
+    ./file.cue:32:8
+    ./file.cue:33:8
+    ./file.cue:34:8
+    ./file.cue:35:8
+aList: invalid value [1,"two",{Int:3,String:"three"},[4,"four"]] (does not satisfy list.Contains(["four"])):
+    ./file.cue:32:8
+    ./file.cue:6:8
+    ./file.cue:19:8
+    ./file.cue:20:8
+    ./file.cue:25:8
+    ./file.cue:26:8
+    ./file.cue:27:8
+    ./file.cue:33:8
+    ./file.cue:34:8
+    ./file.cue:35:8
+aList: invalid value [1,"two",{Int:3,String:"three"},[4,"four"]] (does not satisfy list.Contains(["four",4,4.0])):
+    ./file.cue:35:8
+    ./file.cue:6:8
+    ./file.cue:19:8
+    ./file.cue:20:8
+    ./file.cue:25:8
+    ./file.cue:26:8
+    ./file.cue:27:8
+    ./file.cue:32:8
+    ./file.cue:33:8
+    ./file.cue:34:8
+{{< /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" or
+"equal". When this documentation is complete it will be linked from here, and
+fewer examples will be presented in this guide.
+{{< /info >}}
+
+## Related content
+
+- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package
+- How to [use the built-in function `list.Contains` to report if a value is contained in a list]({{<
+    relref "../use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list"
+  >}})
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-as-a-list-validator": {}