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

[jpluscplusm]

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 proposal: allow all values to be compared for equality cue#2583

[jpluscplusm]

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

[jpluscplusm]

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

[sa-spag]

@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]

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]

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.