Home / Docs / Language guide / Kinds and types
kind
What it does
kind declares a type. It takes one of four forms:
- an alias, another name for a type;
- a refinement, a type narrowed by a predicate;
- a sum, a choice among variants, which may carry fields;
- a record, a set of named fields.
Records and sums are nominal, which means a type is known by its name: two declarations of the same shape are two types. Aliases and refinements are structural over their base, which means they are the type they rename or narrow, so a Seats value is an Int wherever an Int is expected.
Learn more: Records and Sum kinds, and is.
module shop
pub kind Seats = Int in 0..5000
pub kind Availability = SoldOut | Few | Open
pub kind Lookup = Found(name: Text) | Missing
pub kind Event
name: Text
remaining: Seats
pub kind NonEmpty[T] = List[T] where it.len > 0
pub kind Count = IntForms
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.
kind_decl = [ "pub" ] "kind" upper_ident [ type_params ] kind_body ;
type_params = "[" upper_ident { "," upper_ident } "]" ;
kind_body = alias_body | sum_body | record_body ;
alias_body = "=" type [ "where" line_expr ] NEWLINE ;
sum_body = "=" ( "|" variant { "|" variant }
| variant "|" variant { "|" variant } ) NEWLINE ;
record_body = NEWLINE INDENT field { field } DEDENT ;
field = lower_ident ":" type NEWLINE ;
variant = upper_ident [ "(" field_sig { "," field_sig } ")" ] ;
field_sig = lower_ident ":" type ;- Alias:
kind Count = Int. - Refinement:
kind Phone = Text where valid_phone(it), or with range sugar,kind Seats = Int in 0..5000.in a..bincludesb, andin a..<bexcludes it. Seewhereand refinements. - Sum:
kind Availability = SoldOut | Few | Open, with fields in parentheses for a variant that carries them. A sum of one variant starts with a bar:kind OrderError = | TooMany. - Record: fields one per line, indented under the name.
- Type parameters:
kind NonEmpty[T] = List[T] where it.len > 0. A kind's type parameters take no constraint.
Examples
A refinement is checked where a value enters it. Here the verifier, the part of una check that proves what the program must keep, refutes that an arbitrary Int lies in 0..5000:
-- fails with U5001
module shop
pub kind Seats = Int in 0..5000
pub to_seats(count: Int) -> Seats = countThe other direction needs no proof: a Seats value is an Int:
module shop
pub kind Seats = Int in 0..5000
pub widen(s: Seats) -> Int = sA refinement of a refined kind conjoins both predicates, so the verifier knows both here:
module shop
pub kind Stock = Int in 0..100
pub kind LowStock = Stock where it < 10
pub low_stock_level(level: LowStock) -> Int
ensures result < 10 and result >= 0
=
levelRecords are nominal: the same fields do not make the same type:
-- fails with U2001
module shop
pub kind Warehouse
aisle: Int
shelf: Int
pub kind Bin
aisle: Int
shelf: Int
pub as_bin(warehouse: Warehouse) -> Bin = warehouseEdge cases
Recursive kinds. In edition 0.2, a kind may contain itself through any field, when it has a finite value:
module shop
pub kind Bundle = Item(sku: Int) | Pair(left: Bundle, right: Bundle)A kind with no finite value is rejected:
-- fails with U2002
module shop
pub kind Chain = | Link(rest: Chain)Refined type arguments. In editions 0.1 and 0.2, a refined kind cannot be a type argument (the type in brackets, as in List[Quantity]), inside a kind either, since refinements are top-level:
-- fails with U2002
module shop
pub kind Quantity = Int where it > 0
pub kind Order
quantities: List[Quantity]One name per declaration. Two declarations of a module may not share a name in one namespace, variants included:
-- fails with U1002
module shop
pub kind Size = | Small
pub kind Fit = | SmallFurther rules:
- A single-variant sum needs its bar.
kind Chain = Link(rest: Chain)is a syntax error (U0101). - Built-in names. In edition
0.2, a kind or variant cannot take the name of a built-in type, such asInt,Text,ListorMap(U1002). In edition0.1such a declaration shadows the built-in type in its module. - A refinement of a function type is ill-formed. Refine its parameters or its result instead (U2002).
Diagnostics
- U0101: a malformed declaration, such as a single-variant sum without its bar.
- U1002: a kind or variant name defined twice in a module.
- U2001: a value of one nominal kind where another is expected.
- U2002: an ill-formed kind, such as a recursion without a finite value or, in editions
0.1and0.2, a refined type argument. - U5001: a refinement refuted where a value enters the kind.
Edition
Every form is in editions 0.1 and 0.2. 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. Recursion differs: edition 0.1 allows a kind to contain itself only through List or Option fields.
-- edition 0.1
-- fails with U2002
module shop
pub kind Bundle = Item(sku: Int) | Pair(left: Bundle, right: Bundle)Normative source
- spec/03 §2: kinds and rules 1 to 5; spec/03 §3: refinements, range sugar, refined type arguments and function kinds.
- spec/02 §2: the grammar.
- spec/12 §3: the
refinementobligation. - spec/03 §1: built-in type names.
- spec/10 §11 rule 5: duplicate names; spec/10 §12: the formal rules of recursive kinds.
- spec/20 §2 rule 1: a kind's type parameters take no constraint.
- Decision records: ADR 0060, for recursive kinds; ADR 0040, for refined type arguments in editions
0.1and0.2; ADR 0103, for refined type arguments in edition0.3; ADR 0045, for refined function kinds.