@check convenience syntax for record/field-level value constraints

[jrevels]

Split out from #20. With Legolas v0.5 (ref #54), we have a much nicer disciplined stance on validation-by-construction, so the path forward for convenient record-level check constraints is much simpler.

We should define a simple helper @check that can be used in the following manner:

@version FooV1 begin
    x::String # unchecked
    @check(y::Int, y > 0)
    @check(z::Any, a_predicate(z) && another_predicate(z, x))
    @check(k::Int = clamp(k, 1, 10), 
           some_other_predicate(k))
    @check begin
        # record-level predicate(s)
    end
end

where the field-level @check expansion goes from statements like

@version FooV1 begin
    ⋮
    @check(f::T = $rhs, $predicate)
    ⋮
end

...to statements like:

f::T = $rhs
$predicate || throw(CheckConstraintError(:FooV1, :f, f, $stringified_predicate))

...where CheckConstraintError might look like:

struct CheckConstraintError <: Exception
    record_name::Symbol
    field_name::Symbol
    predicate::String
    received::Any
end

function Base.showerror(io::IO, e::CheckConstraintError)
    print(io, """
              Value received for $(e.field_name) of $(e.record_name): $(e.received)
              Violates `@check` constraint: $(e.predicate)
              """)
end

[ericphanson]

Could this be done as a piece of syntax that @version understands, instead of as a new macro? To avoid clashes with ArgCheck.jl or other macros

[jrevels]

Yup, that’s the intention, updated the title/OP to clarify

[omus]

The implementation in #119 changed a couple things from the design proposed here:

1. The @check constraints are just defined on records. This allows us to supports constraints like y > z and or y > 0.
2. The @check constraint must be defined after fields. This ensures mutations such as clamp(k, 1, 10) occur before constraints are checked.
3. I ended up defining a @check macro but it is not exported and does not require itself to be imported to work.
4. The reported error message is currently quite simple but the stack trace is accurate allowing you to find the exact line of the constraint and the schema version it was defined within.