From c373f1a471543bb9d57678feb5c955a3311819c6 Mon Sep 17 00:00:00 2001 From: Jonathan Matthews Date: Wed, 10 Jan 2024 14:55:44 +0000 Subject: [PATCH] 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 Change-Id: I5db7e64b786f239d031cfec00e4ba50db0ef8e0f Dispatch-Trailer: {"type":"trybot","CL":1174384,"patchset":14,"ref":"refs/changes/84/1174384/14","targetBranch":"alpha"} --- .../en.md | 128 ++++++++++++++++++ .../gen_cache.cue | 18 +++ .../page.cue | 3 + .../en.md | 91 +++++++++++++ .../gen_cache.cue | 18 +++ .../page.cue | 3 + .../index.md | 127 +++++++++++++++++ .../index.md | 90 ++++++++++++ 8 files changed, 478 insertions(+) create mode 100644 content/docs/howto/use-the-built-in-function-list-contains-as-a-list-validator/en.md create mode 100644 content/docs/howto/use-the-built-in-function-list-contains-as-a-list-validator/gen_cache.cue create mode 100644 content/docs/howto/use-the-built-in-function-list-contains-as-a-list-validator/page.cue create mode 100644 content/docs/howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/en.md create mode 100644 content/docs/howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/gen_cache.cue create mode 100644 content/docs/howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/page.cue create mode 100644 hugo/content/en/docs/howto/use-the-built-in-function-list-contains-as-a-list-validator/index.md create mode 100644 hugo/content/en/docs/howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/index.md diff --git a/content/docs/howto/use-the-built-in-function-list-contains-as-a-list-validator/en.md b/content/docs/howto/use-the-built-in-function-list-contains-as-a-list-validator/en.md new file mode 100644 index 000000000..655bd80c1 --- /dev/null +++ b/content/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 new file mode 100644 index 000000000..36afa27ad --- /dev/null +++ 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 new file mode 100644 index 000000000..c96a1c96a --- /dev/null +++ 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/content/docs/howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/en.md b/content/docs/howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/en.md new file mode 100644 index 000000000..47377cfa3 --- /dev/null +++ b/content/docs/howto/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/content/docs/howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/gen_cache.cue b/content/docs/howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/gen_cache.cue new file mode 100644 index 000000000..b3d185ddb --- /dev/null +++ b/content/docs/howto/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/content/docs/howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/page.cue b/content/docs/howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/page.cue new file mode 100644 index 000000000..a511da125 --- /dev/null +++ b/content/docs/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/hugo/content/en/docs/howto/use-the-built-in-function-list-contains-as-a-list-validator/index.md b/hugo/content/en/docs/howto/use-the-built-in-function-list-contains-as-a-list-validator/index.md new file mode 100644 index 000000000..916c8e9be --- /dev/null +++ b/hugo/content/en/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" + >}}) diff --git a/hugo/content/en/docs/howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/index.md b/hugo/content/en/docs/howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/index.md new file mode 100644 index 000000000..85a339fe4 --- /dev/null +++ b/hugo/content/en/docs/howto/use-the-built-in-function-list-contains-to-report-if-a-value-is-in-a-list/index.md @@ -0,0 +1,90 @@ +--- +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. + +{{< code-tabs >}} +{{< code-tab name="file.cue" language="cue" area="top" >}} +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"], +] +{{< /code-tab >}} +{{< code-tab name="TERMINAL" language="" type="terminal" area="bottom" >}} +$ cue eval +contains: true +containsBasicInt: true +containsBasicString: false +containsStructMissingField: false +containsStructAllFields: true +containsStructExtraFields: false +containsListMissingElement: false +containsListAllElementsIncorrectOrder: false +containsListAllElementsCorrectOrder: true +containsListExtraElements: false +{{< /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` as a list validator]({{< + relref "../use-the-built-in-function-list-contains-as-a-list-validator" + >}})