From 731c916ce60647c61fc356de5a8713dbc17b8ec6 Mon Sep 17 00:00:00 2001 From: Jonathan Matthews Date: Wed, 10 Jan 2024 15:55:48 +0000 Subject: [PATCH] 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 Change-Id: Ia6716c97cd876e75b1f8c6e2492fd5cec53f0c7c --- content/docs/howto/ensure-min-max-list/en.md | 35 --------- .../docs/howto/ensure-min-max-list/page.cue | 3 - .../en.md | 72 +++++++++++++++++++ .../gen_cache.cue | 19 +++++ .../page.cue | 3 + .../docs/howto/ensure-min-max-list/index.md | 35 --------- .../index.md | 72 +++++++++++++++++++ 7 files changed, 166 insertions(+), 73 deletions(-) delete mode 100644 content/docs/howto/ensure-min-max-list/en.md delete mode 100644 content/docs/howto/ensure-min-max-list/page.cue create mode 100644 content/docs/howto/use-the-built-in-functions-list-maxitems-list-minitems-to-constrain-list-length/en.md create mode 100644 content/docs/howto/use-the-built-in-functions-list-maxitems-list-minitems-to-constrain-list-length/gen_cache.cue create mode 100644 content/docs/howto/use-the-built-in-functions-list-maxitems-list-minitems-to-constrain-list-length/page.cue delete mode 100644 hugo/content/en/docs/howto/ensure-min-max-list/index.md create mode 100644 hugo/content/en/docs/howto/use-the-built-in-functions-list-maxitems-list-minitems-to-constrain-list-length/index.md diff --git a/content/docs/howto/ensure-min-max-list/en.md b/content/docs/howto/ensure-min-max-list/en.md deleted file mode 100644 index 0a9c8dbcbb..0000000000 --- a/content/docs/howto/ensure-min-max-list/en.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Require min or max items in a list -weight: -draft: false -toc_hide: true -tags: - - language ---- - -## Min -There are two common patterns to ensure a list has a minimum number of items. -When the number of required items is small and known in advance, use -the core language syntax: - -``` -field: [_, _, ...] -``` -When the number of required items is larger or not known in advance, use the [list.MinItems](https://pkg.go.dev/cuelang.org/go/pkg/list#MinItems): - -``` -import "list" - -field1: list.MinItems(10) -``` - -## Max - -To require your list to have a maximum number of items, use [list.MaxItems](https://pkg.go.dev/cuelang.org/go/pkg/list#MaxItems): - -``` -import "list" - -field: list.MaxItems(10) -field: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11] -``` diff --git a/content/docs/howto/ensure-min-max-list/page.cue b/content/docs/howto/ensure-min-max-list/page.cue deleted file mode 100644 index 21c8aba8b8..0000000000 --- a/content/docs/howto/ensure-min-max-list/page.cue +++ /dev/null @@ -1,3 +0,0 @@ -package site - -content: docs: howto: "ensure-min-max-list": {} diff --git a/content/docs/howto/use-the-built-in-functions-list-maxitems-list-minitems-to-constrain-list-length/en.md b/content/docs/howto/use-the-built-in-functions-list-maxitems-list-minitems-to-constrain-list-length/en.md new file mode 100644 index 0000000000..5dd7d5c012 --- /dev/null +++ b/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 diff --git a/content/docs/howto/use-the-built-in-functions-list-maxitems-list-minitems-to-constrain-list-length/gen_cache.cue b/content/docs/howto/use-the-built-in-functions-list-maxitems-list-minitems-to-constrain-list-length/gen_cache.cue new file mode 100644 index 0000000000..3da4a77353 --- /dev/null +++ b/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=" + } + } + } + } + } + } + } +} diff --git a/content/docs/howto/use-the-built-in-functions-list-maxitems-list-minitems-to-constrain-list-length/page.cue b/content/docs/howto/use-the-built-in-functions-list-maxitems-list-minitems-to-constrain-list-length/page.cue new file mode 100644 index 0000000000..468489038d --- /dev/null +++ b/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": {} diff --git a/hugo/content/en/docs/howto/ensure-min-max-list/index.md b/hugo/content/en/docs/howto/ensure-min-max-list/index.md deleted file mode 100644 index 0a9c8dbcbb..0000000000 --- a/hugo/content/en/docs/howto/ensure-min-max-list/index.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Require min or max items in a list -weight: -draft: false -toc_hide: true -tags: - - language ---- - -## Min -There are two common patterns to ensure a list has a minimum number of items. -When the number of required items is small and known in advance, use -the core language syntax: - -``` -field: [_, _, ...] -``` -When the number of required items is larger or not known in advance, use the [list.MinItems](https://pkg.go.dev/cuelang.org/go/pkg/list#MinItems): - -``` -import "list" - -field1: list.MinItems(10) -``` - -## Max - -To require your list to have a maximum number of items, use [list.MaxItems](https://pkg.go.dev/cuelang.org/go/pkg/list#MaxItems): - -``` -import "list" - -field: list.MaxItems(10) -field: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11] -``` diff --git a/hugo/content/en/docs/howto/use-the-built-in-functions-list-maxitems-list-minitems-to-constrain-list-length/index.md b/hugo/content/en/docs/howto/use-the-built-in-functions-list-maxitems-list-minitems-to-constrain-list-length/index.md new file mode 100644 index 0000000000..d3efdc8ceb --- /dev/null +++ b/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