docs/howto: Ensuring a list is a subset of another list

cue-lang / docs-and-content

A place to discuss, plan, and track documentation on cuelang.org

6 stars 1 forks source link

docs/howto: Ensuring a list is a subset of another list #169

Open jpluscplusm opened 4 months ago

jpluscplusm commented 4 months ago

A Commented CUE guide that demonstrates this solution to the problem:

allowed_values: ["a", "b", "c"]
my_values: [...or(allowed_values)]
my_values: ["a", "nope"]

Notes:

it's probably worth making sure the word "subset" appears in the page's prose
we can probably display one passing and one failing example in the same CUE, via cue eval -i
/docs/howto/ensure-list-is-subset-of-another-list feels like a suitable path
given this might only work 100% as expected with primitive values, it might be worth calling this out via a note and a link to https://github.com/cue-lang/cue/issues/2583

jpluscplusm commented 4 months ago

@sa-spag is going to give writing this guide a try 👍 🎉

jpluscplusm commented 3 months ago

@sa-spag Hey there 👋 Just a friendly check-in ... did you manage to get anywhere with writing this How-to Guide? :-)

sa-spag commented 3 months ago

@sa-spag Hey there 👋 Just a friendly check-in ... did you manage to get anywhere with writing this How-to Guide? :-)

👋 I had other priorities, but it is still in my backlog.

extemporalgenome commented 3 weeks ago

That code is certainly more concise than what I ended up trying, though it gives error messages like:

my_values.1: 3 errors in empty disjunction:
my_values.1: conflicting values "a" and "nope":
    -:1:18
    -:2:13
    -:3:18
my_values.1: conflicting values "b" and "nope":
    -:1:23
    -:2:13
    -:3:18
my_values.1: conflicting values "c" and "nope":
    -:1:28
    -:2:13
    -:3:18

This failure reporting is a bit verbose and could be a bit confusing to newcomers. It the meantime this is definitely helpful. Long term, matchN could perhaps provide better error reporting.

The must/constrain proposal could also provide this if we had something like a list.IsSubsetOf function, like:

constrain(list.IsSubsetOf(my_values, allowed_values))

jpluscplusm commented 3 weeks ago

Yes, using matchN() does provide more succinct error messaging:

allowed_values: ["a", "b", "c"]
my_values: ["a", "nope"]
my_values: matchN(1, allowed_values)

my_values: invalid value ["a","nope"] (does not satisfy matchN(1, ["a","b","c"])): 0 matched, expected 1:
    ./foo.cue:4:12
    ./foo.cue:2:12
    ./foo.cue:4:19

For the moment I'm going to defer to other folks about the relative suitability and appropriateness of either approach, specifically in the limited context of the guide this issue is tracking.