docs/howto: use list.UniqueItems

This adds a Commented CUE guide that demonstrates both how to use
list.UniqueItems to return a boolean, and how to use the function as a
field validator.

Field validation is shown operating on source data and on
comprehension-generated data which only contains a subset of the source
data.

The source data was selected to include a field name that evokes
Kubernetes configuration ("kind"), as list.UniqueItems has previously
been asked about within a Kubernetes context on Slack. *Actual*
Kubernetes configuration data would be inappropriate to display, here,
even as an example, as doing so would run the risk of the howto guide
being seen in some way as authoritative *for Kubernetes+CUE* - which is
not currently the intent for any page on cuelang.org.

Signed-off-by: Jonathan Matthews <[email protected]>
Preview-Path: /docs/howto/use-the-built-in-function-list-uniqueitems-to-enforce-complete-or-partial-list-item-uniqueness/
Change-Id: Ia956f9cd735d525394c3ee06d65831af4b243652
Dispatch-Trailer: {"type":"trybot","CL":1174648,"patchset":13,"ref":"refs/changes/48/1174648/13","targetBranch":"alpha"}

content/docs/howto/use-the-built-in-function-list-uniqueitems-to-enforce-complete-or-partial-list-item-uniqueness/en.md

@@ -0,0 +1,95 @@
+---
+title: Using the built-in function "list.UniqueItems" to enforce complete or partial list item completeness
+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.UniqueItems`](https://pkg.go.dev/cuelang.org/go/pkg/list#UniqueItems)
+to enforce that a list's items are either completely unique (taking all of each
+item's fields into account), or that they're partially unique (taking only
+*some* of each item's fields into account).
+
+{{{with code "en" "cc"}}}
+#location top bottom
+
+! exec cue vet
+cmp stderr out
+-- file.cue --
+package example
+
+import "list"
+
+// list.UniqueItems returns a boolean value. Here, its value will be "true".
+uniqueItems: list.UniqueItems([1, 2, "3", 4, "five"])
+
+// iceCreams is a list of structs representing multiple brands' specific kinds
+// (or flavours) of ice cream, along with optional names and prices.
+// It is *not* mandatory to declare a list's schema in order to use the list
+// with list.UniqueItems. We do so, here, for clarity.
+iceCreams: [...{
+	brand!: string
+	kind!:  string
+	name?:  string
+	price?: number
+}]
+
+// Assert that iceCreams contains no duplicate items by using list.UniqueItems
+// as a validator.
+iceCreams: list.UniqueItems
+
+// Assert that a synthetic list, constructed using a subset of the fields inside
+// iceCreams' items, contains no duplicate items.
+_flavoursByBrand: list.UniqueItems & [
+	for item in iceCreams {{
+		brand: item.brand
+		kind:  item.kind
+	}},
+]
+
+// Assert that a synthetic list, constructed using a different subset of the
+// fields inside iceCreams' items, contains no duplicate items.
+_names: list.UniqueItems & [
+	for item in iceCreams
+	if item.name != _|_ {{
+		name: item.name
+	}},
+]
+
+iceCreams: [{
+	brand: "Charlie's Chocs"
+	kind:  "vanilla"
+	name:  "Vanilla Deluxe"
+	price: 5
+}, {
+	brand: "Lola's Lollies"
+	kind:  "strawberry"
+}, {
+	brand: "Charlie's Chocs"
+	kind:  "strawberry"
+	name:  "Strawberry Delight"
+	price: 7.99
+}, {
+	brand: "Charlie's Chocs"
+	kind:  "vanilla"
+	name:  "Vanilla Treat"
+	price: 5
+}, {
+	brand: "Lola's Lollies"
+	kind:  "vanilla"
+	name:  "Vanilla Deluxe"
+}]
+-- out --
+_flavoursByBrand: invalid value [{brand:"Charlie's Chocs",kind:"vanilla"},{brand:"Lola's Lollies",kind:"strawberry"},{brand:"Charlie's Chocs",kind:"strawberry"},{brand:"Charlie's Chocs",kind:"vanilla"},{brand:"Lola's Lollies",kind:"vanilla"}] (does not satisfy list.UniqueItems):
+    ./file.cue:25:19
+_names: invalid value [{name:"Vanilla Deluxe"},{name:"Strawberry Delight"},{name:"Vanilla Treat"},{name:"Vanilla Deluxe"}] (does not satisfy list.UniqueItems):
+    ./file.cue:34:9
+{{{end}}}
+
+## Related content
+
+- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package

content/docs/howto/use-the-built-in-function-list-uniqueitems-to-enforce-complete-or-partial-list-item-uniqueness/gen_cache.cue

@@ -0,0 +1,18 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-the-built-in-function-list-uniqueitems-to-enforce-complete-or-partial-list-item-uniqueness": {
+					page: {
+						cache: {
+							code: {
+								cc: "L++IZjxVY6fWDxvDwxPDlF9FWAEZOS8A3UWxGqjOGCU="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/howto/use-the-built-in-function-list-uniqueitems-to-enforce-complete-or-partial-list-item-uniqueness/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-the-built-in-function-list-uniqueitems-to-enforce-complete-or-partial-list-item-uniqueness": {}

hugo/content/en/docs/howto/use-the-built-in-function-list-uniqueitems-to-enforce-complete-or-partial-list-item-uniqueness/index.md

@@ -0,0 +1,94 @@
+---
+title: Using the built-in function "list.UniqueItems" to enforce complete or partial list item completeness
+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.UniqueItems`](https://pkg.go.dev/cuelang.org/go/pkg/list#UniqueItems)
+to enforce that a list's items are either completely unique (taking all of each
+item's fields into account), or that they're partially unique (taking only
+*some* of each item's fields into account).
+
+{{< code-tabs >}}
+{{< code-tab name="file.cue" language="cue"  area="top" >}}
+package example
+
+import "list"
+
+// list.UniqueItems returns a boolean value. Here, its value will be "true".
+uniqueItems: list.UniqueItems([1, 2, "3", 4, "five"])
+
+// iceCreams is a list of structs representing multiple brands' specific kinds
+// (or flavours) of ice cream, along with optional names and prices.
+// It is *not* mandatory to declare a list's schema in order to use the list
+// with list.UniqueItems. We do so, here, for clarity.
+iceCreams: [...{
+	brand!: string
+	kind!:  string
+	name?:  string
+	price?: number
+}]
+
+// Assert that iceCreams contains no duplicate items by using list.UniqueItems
+// as a validator.
+iceCreams: list.UniqueItems
+
+// Assert that a synthetic list, constructed using a subset of the fields inside
+// iceCreams' items, contains no duplicate items.
+_flavoursByBrand: list.UniqueItems & [
+	for item in iceCreams {{
+		brand: item.brand
+		kind:  item.kind
+	}},
+]
+
+// Assert that a synthetic list, constructed using a different subset of the
+// fields inside iceCreams' items, contains no duplicate items.
+_names: list.UniqueItems & [
+	for item in iceCreams
+	if item.name != _|_ {{
+		name: item.name
+	}},
+]
+
+iceCreams: [{
+	brand: "Charlie's Chocs"
+	kind:  "vanilla"
+	name:  "Vanilla Deluxe"
+	price: 5
+}, {
+	brand: "Lola's Lollies"
+	kind:  "strawberry"
+}, {
+	brand: "Charlie's Chocs"
+	kind:  "strawberry"
+	name:  "Strawberry Delight"
+	price: 7.99
+}, {
+	brand: "Charlie's Chocs"
+	kind:  "vanilla"
+	name:  "Vanilla Treat"
+	price: 5
+}, {
+	brand: "Lola's Lollies"
+	kind:  "vanilla"
+	name:  "Vanilla Deluxe"
+}]
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" type="terminal" area="bottom" >}}
+$ cue vet
+_flavoursByBrand: invalid value [{brand:"Charlie's Chocs",kind:"vanilla"},{brand:"Lola's Lollies",kind:"strawberry"},{brand:"Charlie's Chocs",kind:"strawberry"},{brand:"Charlie's Chocs",kind:"vanilla"},{brand:"Lola's Lollies",kind:"vanilla"}] (does not satisfy list.UniqueItems):
+    ./file.cue:25:19
+_names: invalid value [{name:"Vanilla Deluxe"},{name:"Strawberry Delight"},{name:"Vanilla Treat"},{name:"Vanilla Deluxe"}] (does not satisfy list.UniqueItems):
+    ./file.cue:34:9
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+## Related content
+
+- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package