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" + >}})