Array with records of multiple contract type.

[nialov]

How do I check that all values of a record fulfill one of several possible records?

E.g. here I define two contracts and apply one of the contracts to the array of record values. How would I check if either Contract1 or Contract2 is fulfilled?

let Contract1 = {a | Num} in 
let Contract2 = {a | Str} in 
[{a=1}, {a="a"}] | Array Contract1

I tried the following but as contract failure causes an error rather than returning a boolean it obviously fails:

let Contract1 = {a | Num} in 
let Contract2 = {a | Str} in 
[{a=1}, {a="a"}] | Array (contract.from_predicate (
    fun value => (value | Contract1) || (value | Contract2)
))

Hopefully it illustrates my question. And I am interested in the case where both contracts can be arbitrarily complex, rather than the simple case of checking individual numbers or strings.

[yannham]

The short answer is, you can't in full generality, for good reasons. You can read this blogpost for more details about the consequences of implementing such a generic or operator.

At the end of the post, we gloss over a possible limited or operator that would still be useful, and I imagine it could cover your use case (with Num and Str at least, it depends for more complex contract). To this day, this operator is not implemented, unfortunately.

In the meantime, it can be helpful to define independently the predicates that are used in your contracts, in order to combine them as predicates. What I mean by that is, instead of doing:

let MyComplexContract = fun label value =>
  ... some conditions ...
in
let MyComplexContract' = fun label value =>
 ... some conditions ...
in

You can do

# Dyn -> Bool
let MyComplexPred = fun value => ... in
let MyComplexContract = contract.from_predicate MyComplexPred in
let MyComplexPred' = fun value => ... in
let MyComplexContract' = contract.from_predicate MyComplexPred' in
let OneOfComplexPred = fun value => MyComplexPred value || MyComplexPred' value in
let OneOfComplex = contract.from_predicate OneOfComplexPred in
{a = ["foo", "bar"]} | {a | OneOfComplex}

Of course, all contracts can't be defined as simple predicates (using contract.from_predicate), and you still have to build the inner union contract by yourself first, before creating a record contract out of it. It's pretty limited and manual. I hope we can find time to get our hands on designing a proper or - necessarily not a fully general one - combinator for contracts.

[jmgilman]

Thanks for this answer, however, I'm having a hard time understanding the example being given. Perhaps you can share something more simple instead? For example, how can I make a contract that validates a type is either a Str or Array Str?

[yannham]

The general issue with or of arbitrary contracts is that there is no obvious way to build such contracts while keeping them lazy. Lazyness means that they don't require to evaluate fully the value that they are given (for example, Array Str just checks that the given parameter is an array, but will only check that an element is a string when it is first evaluated, so it doesn't have to evaluate the elements yet). It's a useful property, because Nickel is a lazy language, which means that the interpreter only has to evaluate what's actually needed in the end (you may only export part of a configuration, depending on some fields and other options, for example).

There is a subcategory of contracts that is of interest. Let's call them boolean predicates. Those contracts can immediately decide if the value they are given is legal, without having to put delayed checks inside. For example, Num and Str are of this kind. Contract that you create using contract.from_predicate are of this kind too (and, in fact, any boolean predicate can be written as contract.from_predicate of some function, modulo custom error messages).

Now, if you take Array Num, or {_ : Num} (a record with fields that are numbers), those aren't boolean predicates. In Nickel, an array or a record, even once evaluated, may contain unevaluated chunks inside. So you can't know right away if every element is a number: what you do is returning a new array (or record), whose elements have been wrapped by a function that checks that they are numbers. Very schematically, [1 + 1] | Array Num check that the argument is an array, and then map the Num contract onto the elements. Only when an element is extracted, and then would be evaluated anyway, that we can perform the contract check. This way, builtin-in contracts never incur additional evaluation (which would defeat the purpose of laziness).

Boolean predicates are easy to combine using or: if you have C1 = contract.from_predicate pred1 and C2 = contract.from_predicate pred2, then C1 OR C1 is just C1Or2 = contract.from_predicate (fun val => pred1 val || pred2 val). You can even write this as a combinator OrOfPredicates = fun predicates => contract.from_predicate (fun val => array.any (fun pred => pred val) predicates) and then write OrOfPredicates [C1, C2]. So my answer was just about: if your contracts are actually predicates, you should write them as such, and extract the predicate function as to make it accessible, so that it can be reused to build OR, AND, etc.

However, it's not the case of Array Str, so this doesn't directly apply. That being said, we can still manage to write a generic or combinator for an arbitrary number of predicates + one non-predicate contract:

{
  OrOfPredicatesThenContract = fun predicates contract label value =>
    # first test if one of the predicate passes
    if array.any (fun pred => pred value) predicates then value
    # otherwise pass the contract
    else contract.apply contract label value,
  StrOrArrayStr = OrOfPredicatesThenContract [builtin.is_str] (Array Str),
}

(maybe the error reporting can be improved, but this is functional at least).

Now, if you want to do "Array Str" or "Array Num", there is no general combinator. You can still implement it by hand this specific combination, but you will have to make a choice: how do I decide, just by looking at my argument, what contract should I go with? For example, you could check the type of the first element of the array, if not empty, and then apply the corresponding contract in the normal, lazy way (then you loose a bit of laziness, because you force the evaluation of something that may a priori not be evaluated if not for the contract). Or check that array.all builtin.is_str array || array.all builtin.is_num array (but that forces the evaluation of all the elements of the array.

If you want to understand why the general union is really hard, the blogpost enters into more details. Let me know if there is anything which isn't clear !

[nialov]

Thank you!