From 5a541a87877e1fedb38d7a74c1e9d42fa38e641b Mon Sep 17 00:00:00 2001 From: Jonathan Matthews Date: Mon, 15 Jan 2024 16:17:38 +0000 Subject: [PATCH] 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 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"} --- .../en.md | 95 +++++++++++++++++++ .../gen_cache.cue | 18 ++++ .../page.cue | 3 + .../index.md | 94 ++++++++++++++++++ 4 files changed, 210 insertions(+) create mode 100644 content/docs/howto/use-the-built-in-function-list-uniqueitems-to-enforce-complete-or-partial-list-item-uniqueness/en.md create mode 100644 content/docs/howto/use-the-built-in-function-list-uniqueitems-to-enforce-complete-or-partial-list-item-uniqueness/gen_cache.cue create mode 100644 content/docs/howto/use-the-built-in-function-list-uniqueitems-to-enforce-complete-or-partial-list-item-uniqueness/page.cue create mode 100644 hugo/content/en/docs/howto/use-the-built-in-function-list-uniqueitems-to-enforce-complete-or-partial-list-item-uniqueness/index.md diff --git a/content/docs/howto/use-the-built-in-function-list-uniqueitems-to-enforce-complete-or-partial-list-item-uniqueness/en.md b/content/docs/howto/use-the-built-in-function-list-uniqueitems-to-enforce-complete-or-partial-list-item-uniqueness/en.md new file mode 100644 index 000000000..69f5369c7 --- /dev/null +++ b/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 diff --git a/content/docs/howto/use-the-built-in-function-list-uniqueitems-to-enforce-complete-or-partial-list-item-uniqueness/gen_cache.cue b/content/docs/howto/use-the-built-in-function-list-uniqueitems-to-enforce-complete-or-partial-list-item-uniqueness/gen_cache.cue new file mode 100644 index 000000000..f1a5fa7b4 --- /dev/null +++ b/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=" + } + } + } + } + } + } + } +} diff --git a/content/docs/howto/use-the-built-in-function-list-uniqueitems-to-enforce-complete-or-partial-list-item-uniqueness/page.cue b/content/docs/howto/use-the-built-in-function-list-uniqueitems-to-enforce-complete-or-partial-list-item-uniqueness/page.cue new file mode 100644 index 000000000..7f72f4a6a --- /dev/null +++ b/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": {} diff --git a/hugo/content/en/docs/howto/use-the-built-in-function-list-uniqueitems-to-enforce-complete-or-partial-list-item-uniqueness/index.md b/hugo/content/en/docs/howto/use-the-built-in-function-list-uniqueitems-to-enforce-complete-or-partial-list-item-uniqueness/index.md new file mode 100644 index 000000000..7264dd72c --- /dev/null +++ b/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