docs/howto: use list.{Max,Min}Items

This converts a how-to guide to be a Commented CUE guide, demonstrating
the use of list.MaxItems and list.MinItems to constrain a list's length.
An alias is set up for anyone with existing bookmarks.

The function-based form is promoted to the start of the page, relative
to the core language mechanism, due to the top-based mechanism omitting
line numbers from its error messages, and only applying to the
minimum-length use case.

Preview-Path: /docs/howto/use-the-built-in-functions-list-maxitems-list-minitems-to-constrain-list-length/
Signed-off-by: Jonathan Matthews <[email protected]>
Change-Id: Ia6716c97cd876e75b1f8c6e2492fd5cec53f0c7c
Dispatch-Trailer: {"type":"trybot","CL":1174389,"patchset":13,"ref":"refs/changes/89/1174389/13","targetBranch":"alpha"}

content/docs/howto/use-the-built-in-functions-list-maxitems-list-minitems-to-constrain-list-length/en.md

@@ -0,0 +1,72 @@
+---
+title: Using the built-in functions "list.MaxItems" and "list.MinItems" to constrain the length of a list
+tags:
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+aliases:
+- ensure-min-max-list
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the built-in functions
+[`list.MaxItems`](https://pkg.go.dev/cuelang.org/go/pkg/list#MaxItems) and
+[`list.MinItems`](https://pkg.go.dev/cuelang.org/go/pkg/list#MinItems)
+to require that a list contains a maximum and/or minimum number of items.
+
+{{{with code "en" "cc"}}}
+#location top bottom
+
+! exec cue vet
+cmp stderr out
+-- file.cue --
+package example
+
+import "list"
+
+a: [1, 2, 3, 4, 5]
+b: [1, 2, 3, 4, 5]
+c: [1, 2, 3, 4, 5]
+
+// a must contain no more than 2 items
+a: list.MaxItems(2)
+
+// b must contain at least 6 items
+b: list.MinItems(6)
+
+// c must contain at least 2 items, and no more than 6 items
+c: list.MinItems(2) & list.MaxItems(6)
+-- out --
+a: invalid value [1,2,3,4,5] (does not satisfy list.MaxItems(2)): len(list) > MaxItems(2) (5 > 2):
+    ./file.cue:10:4
+    ./file.cue:5:4
+    ./file.cue:10:18
+b: invalid value [1,2,3,4,5] (does not satisfy list.MinItems(6)): len(list) < MinItems(6) (5 < 6):
+    ./file.cue:13:4
+    ./file.cue:6:4
+    ./file.cue:13:18
+{{{end}}}
+
+## Alternative to `list.MinItems`
+
+If the number of required items is both small and known in advance, then this
+core language syntax might be preferred instead of `list.MinItems`:
+
+{{{with code "en" "min"}}}
+! exec cue vet
+cmp stderr out
+-- file.cue --
+package example
+
+// f must contain at least 3 elements
+f: [_, _, _, ...]
+
+f: [1, 2]
+-- out --
+f: incompatible list lengths (2 and 3)
+{{{end}}}
+
+## Related content
+
+- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package

content/docs/howto/use-the-built-in-functions-list-maxitems-list-minitems-to-constrain-list-length/gen_cache.cue

@@ -0,0 +1,19 @@
+package site
+{
+	content: {
+		docs: {
+			howto: {
+				"use-the-built-in-functions-list-maxitems-list-minitems-to-constrain-list-length": {
+					page: {
+						cache: {
+							code: {
+								cc:  "3pqaLQFYDy85gTbGiH5vpCW3ySN2gG8eitUIodpakvg="
+								min: "UkBWLoXqioD0IVzn95P6voeGbTSXKpD2URDOhWT50EI="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/howto/use-the-built-in-functions-list-maxitems-list-minitems-to-constrain-list-length/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: howto: "use-the-built-in-functions-list-maxitems-list-minitems-to-constrain-list-length": {}

hugo/content/en/docs/howto/use-the-built-in-functions-list-maxitems-list-minitems-to-constrain-list-length/index.md

@@ -0,0 +1,72 @@
+---
+title: Using the built-in functions "list.MaxItems" and "list.MinItems" to constrain the length of a list
+tags:
+- commented cue
+authors:
+- jpluscplusm
+toc_hide: true
+aliases:
+- ensure-min-max-list
+---
+
+This [Commented CUE]({{< relref "docs/howto#commented-cue-guides" >}})
+demonstrates how to use the built-in functions
+[`list.MaxItems`](https://pkg.go.dev/cuelang.org/go/pkg/list#MaxItems) and
+[`list.MinItems`](https://pkg.go.dev/cuelang.org/go/pkg/list#MinItems)
+to require that a list contains a maximum and/or minimum number of items.
+
+{{< code-tabs >}}
+{{< code-tab name="file.cue" language="cue"  area="top" >}}
+package example
+
+import "list"
+
+a: [1, 2, 3, 4, 5]
+b: [1, 2, 3, 4, 5]
+c: [1, 2, 3, 4, 5]
+
+// a must contain no more than 2 items
+a: list.MaxItems(2)
+
+// b must contain at least 6 items
+b: list.MinItems(6)
+
+// c must contain at least 2 items, and no more than 6 items
+c: list.MinItems(2) & list.MaxItems(6)
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" type="terminal" area="bottom" >}}
+$ cue vet
+a: invalid value [1,2,3,4,5] (does not satisfy list.MaxItems(2)): len(list) > MaxItems(2) (5 > 2):
+    ./file.cue:10:4
+    ./file.cue:5:4
+    ./file.cue:10:18
+b: invalid value [1,2,3,4,5] (does not satisfy list.MinItems(6)): len(list) < MinItems(6) (5 < 6):
+    ./file.cue:13:4
+    ./file.cue:6:4
+    ./file.cue:13:18
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+## Alternative to `list.MinItems`
+
+If the number of required items is both small and known in advance, then this
+core language syntax might be preferred instead of `list.MinItems`:
+
+{{< code-tabs >}}
+{{< code-tab name="file.cue" language="cue"  area="top-left" >}}
+package example
+
+// f must contain at least 3 elements
+f: [_, _, _, ...]
+
+f: [1, 2]
+{{< /code-tab >}}
+{{< code-tab name="TERMINAL" language="" type="terminal" area="top-right" >}}
+$ cue vet
+f: incompatible list lengths (2 and 3)
+{{< /code-tab >}}
+{{< /code-tabs >}}
+
+## Related content
+
+- The [`list`](https://pkg.go.dev/cuelang.org/go/pkg/list) built-in package