Home / Docs / Language guide / Kinds and types

where and refinements

Release v0.4.0Edition 0.1 and laterU2002U2013U2014U5001U5002

What it does

A refinement narrows a type by a predicate: Text where valid_phone(it) is the texts for which valid_phone holds, and Int in 0..5000 the integers from 0 to 5000. The compiler proves, at every place a value enters the refined type, that the predicate holds. The proof happens at compile time, before the program runs, so a program that checks never holds a value outside its refinement, relative to the solver and to the ensures clauses of capability operations, which are assumed, not proven: a host implementation is trusted to satisfy them.

Learn more: Refined kinds and predicates.

una
module shop

pub kind Seats = Int in 0..5000

pub kind Event
  name: Text
  remaining: Seats

pub book(e: Event, count: Int) -> Seats
  requires count >= 1
  requires count <= e.remaining
=
  e.remaining - count

Forms

In the grammar below, each rule gives a name, =, what the name stands for and ;, quoted words are written as shown, NEWLINE, INDENT and DEDENT stand for a line break and for one more or one less level of indentation, [ ] marks an optional part, { } a part that may repeat, | separates alternatives, ( ) groups them, and (* *) holds a comment.

ebnf
alias_body      = "=" type [ "where" line_expr ] NEWLINE ;
type            = [ label ] type_core [ "in" range ] ;
range           = signed_int ( ".." | "..<" ) signed_int ;

The refinement language is what the verifier, the part of una check that proves what the program must keep, decides:

Examples

In the body above, the preconditions give the facts that prove e.remaining - count lies in 0..5000. A caller that cannot show a value fits is refuted, with a counterexample:

una
-- fails with U5001
module shop

pub kind Seats = Int in 0..5000

pub to_seats(count: Int) -> Seats = count

A guard is enough when it gives the facts. In the last else branch the verifier knows not (raw < 0) and not (raw > 5000), so raw lies in 0..5000, and in the then branches the literals fit:

una
module shop

pub kind Seats = Int in 0..5000

pub cap_seats(raw: Int) -> Seats = if raw < 0 then 0 else if raw > 5000 then 5000 else raw

A predicate makes a refinement readable, and a reflect predicate's definition is visible to the solver, the program that decides each obligation:

una
module shop

pub predicate reflect adult(age: Int) -> Bool = age >= 18

pub kind Adult = Int where adult(it)

pub grow(a: Adult) -> Adult = a + 1

Edge cases

Only the refinement language. An expression outside it is U2014, at the outermost offending part. Outside it are the ordering of Text, is with a literal, == against a variant, unit and interpolated text:

una
-- fails with U2014
module shop

pub kind Late = Text where it > "m"

Refinements are top-level. In editions 0.1 and 0.2, a refined kind cannot be a type argument, so List[Quantity] is ill-formed. Refine the list itself, or check each element where it is used:

una
-- fails with U2002
module shop

pub kind Quantity = Int where it > 0

pub kind Order
  quantities: List[Quantity]

Further rules:

Diagnostics

Edition

Refinements are the same in editions 0.1 and 0.2. In edition 0.2, a fixed-width integer type can be refined too, as kind Port = U16 where it > 0. Edition 0.3 accepts refined type arguments, as List[Quantity]: every value put into such a position must be proven to satisfy the refinement, and every value read from it carries it.

Normative source