Types

Common types

Any and Nothing

Every type is a subtype to Any, written x <: Any for all types x. Equivalently, any place that Any is valid, any other type can be used. Any is also known as the "Top" type.

Conversely, there are no types that are subtypes to Nothing, except itself. For all types x it holds that Nothing <: x. Put another way, Nothing is a valid type to use in positions expecting any other type. In practice, Nothing is not as useful as Any, and is usually used internally to detect dead code and other code properties. It does not make sense to assign a binding the type Nothing.

One common usage is an empty sequence, which is inferred to be of type (Seqable Nothing). The result type of throw is also Nothing.

Functions

core.typed has a special function type, which is an ordered intersection of arities. It allows us to specify fine grained function invariants.

Starting simply,

(Fn [Any -> Any])

is a function taking one argument of type Any. [Any -> Any] is an equivalent shorthand for single-arity function types.

Multiple arities

We can specify multiple arities:

(Fn [Any -> Any]
    [Any Any -> Any])

Here we can call a function of this type with either one or two arguments. In this case, the ordered intersection type acts as a simple overloading on arity.

Finer invariants can be expressed by specifying multiple arities of the same arity:

(Fn [Sym -> Num]
    [Num -> Sym])

This function returns a Num if passed a Sym, and returns a Sym if passed a Num.

The exact return type for a function application expression involving multiple arities is chosen by matching the actual types provided with each arities, top-to-bottom (this explains why our functions are "ordered" intersections). In this case, each arity is disjoint because no combination of arguments could potentially trigger both arities. More concretely, there is no type that is both a Sym and a Num, so at most one arity triggers for any given arguments.

Overlapping arities hints at the power of ordered intersections.

(Fn [Long -> Sym]
    [Num -> Kw])

This type always returns a Sym for Long arguments.

Beware, swapping the arities produces different results!

(Fn [Num -> Kw]
    [Long -> Sym])

The first arity always "wins" because Num is strictly more general than Long. Arities are usually ordered from more-specific parameters to less-specific parameters.

What about arities that have partially overlapping parameters? Consider:

(Fn [Long Any -> Kw]
    [Any Num -> Sym])

Calling with Long Long arguments gives Kw, and Num Long gives Sym.

Flipping the arities gives different results:

(Fn [Any Num -> Sym]
    [Long Any -> Kw])

Now Long Long gives Sym, and Num Long gives Sym. Partially overlapping arities can be tricky and can unexpectedly trigger earlier arities, so care must be taken here.

Finally, a common idiom is to provide a base arity, which has arguments at least as general as the ones above it.

For example, we might want our function of type (Fn [Long -> Sym] [Num -> Kw]) to handle the case where the argument is either a Long or a Num. We can express this by using a union (to express a least-upper-bound of Long and Num).

(Fn [Long -> Sym]
    [Num -> Kw]
    [(U Long Num) -> (U Sym Kw)])

Note the result type is sufficiently general to show the result type is either a Sym or Kw.

Rest parameters

Rest parameters are specified using a *.

eg.

(Fn [Any Num * -> Any])

is a function taking at least one parameter, and any number of parameters after it of type Num.

Keyword parameters

Keyword parameters are specified using & after the fixed domain.

eg.

(Fn [Any & :optional {:a Num} -> Any])

is a function that takes a fixed parameter and an optional keyword argument :a, of type Num.

We can also specify mandatory keyword parameters:

(Fn [Any & :mandatory {:a Num} -> Any])

is the same function, except the keyword argument :a now must be present when calling.

We can express finer grained invariants by combining keyword types and ordered function intersection types:

(Fn [Any & :mandatory {:a Num :b Num} -> Num]
    [Any & :optional {:a Num :b Num} -> Any])

This function type returns a Num if provided both :a and :b parameters, otherwise returns Any if some other combination of :a and :b is provided.

Java Classes

core.typed reuses Java and clojure.lang.* classes. The normal scoping rules apply in types, e.g., use :import to bring classes into scope.

Note: java.lang.* classes are implicitly in scope in Clojure namespaces.

Numbers, Strings and other Java types

core.typed follows the normal rules that apply to Clojure code.

clojure.core.typed=> (cf 1 Long)
java.lang.Long
clojure.core.typed=> (cf 1.1 Double)
java.lang.Double
clojure.core.typed=> (cf "a" String)
java.lang.String
clojure.core.typed=> (cf \a Character)
java.lang.Character

Symbols and Keywords

Symbols and Keywords are instances of their corresponding clojure.lang classes.

clojure.core.typed=> (cf 'a clojure.lang.Symbol)
clojure.lang.Symbol
clojure.core.typed=> (cf :a clojure.lang.Keyword)
clojure.lang.Keyword

The aliases Sym and Kw are shorthands for these types.

Seqables

Seqables extend (Seqable a), which is covariant in its argument. Types that extend (Seqable a) are capable of creating a sequence (aka. an (ISeq a)) representation of itself via functions like seq.

clojure.core.typed=> (cf {'a 2 'b 3} (Seqable '[Sym Num]))
(Seqable '[Sym Num]))
clojure.core.typed=> (cf [1 2 3] (Seqable Num))
(Seqable Num)
clojure.core.typed=> (cf '#{a b c} (Seqable Sym))
(Seqable Sym)

Seqs

Seqs extend (Seq a), which is covariant in its argument.

clojure.core.typed=> (cf (seq [1 2]))
(Seq Num)

Lists

Lists extend (List a), which is covariant in its argument.

clojure.core.typed=> (cf '(1 2))
(List Num)

Vectors

Vectors extend (Vec a), which is covariant in its argument.

clojure.core.typed=> (cf [1 2])
(Vec Number)

Maps

Maps extend (Map a b), which is covariant in both its arguments.

clojure.core.typed=> (cf {'a 1 'b 3})
(Map Sym Long)

Sets

Sets extend (Set a), which is covariant in its argument.

clojure.core.typed=> (cf #{1 2 3})
(Set Number) 

Atoms

An Atom of type (Atom2 w r) can accept values of type w and provide values of type r. It is contravariant in w and covariant in r.

Usually w and r are identical, so an alias (Atom1 wr) is provided, which is equivalent to (Atom2 wr wr).

core.typed isn't smart enough to infer mutable types like atoms without annotations.

clojure.core.typed=> (cf (atom {}) (Atom1 (Map Sym Num)))
(Atom1 (Map Sym Num))

The helper macro atom> makes this a little nicer.

clojure.core.typed=> (cf (atom> (Map Sym Num) {}))
(Atom1 (Map Sym Num))

Type Grammar

A rough grammar for core.typed types.

Type :=  nil | true | false
     ; Union type
     |   (U Type*)
     ; Intersection type
     |   (I Type+)
     |   FunctionIntersection
     |   (Value CONSTANT-VALUE)
     |   (Rec [Symbol] Type)
     |   (All [Symbol+] Type)
     |   (All [Symbol* Symbol ...] Type)
     ; HMap syntax
     |   (HMap :mandatory {LiteralKeyword Type*} 
               :optional {LiteralKeyword Type*}
               :absent-keys #{LiteralKeyword*}
               :complete? Boolean)        ;eg (HMap :mandatory {:a (Value 1), :b nil})
     ; Mandatory, non-complete HMap syntax
     |   '{Keyword Type*}              ;eg '{:a (Value 1), :b nil}
     |   (HVec [Type*])
     |   '[Type*]
     |   (Seq* Type*)
     |   (List* Type*)
     |   Symbol  ;class/protocol/free resolvable in context

FunctionIntersection :=  ArityType
                     |   (Fn ArityType+)

ArityType :=   [FixedArgs -> Type]
           |   [FixedArgs RestArgs * -> Type]
           |   [FixedArgs DottedType ... Symbol -> Type]

FixedArgs := Type*
RestArgs := Type
DottedType := Type

Types

Value shorthands

nil, true and false resolve to the respective singleton types for those values

Intersections

(I Type+) creates an intersection of types.

Unions

(U Type*) creates a union of types.

Functions

A function type is an ordered intersection of arity types.

There is a vector sugar for functions of one arity.

Heterogeneous Maps

A heterogeneous map type represents a map with some information about specific keyword keys.

Heterogeneous maps support:

• presence of specific keys
• absence of specific keys
• optional keys
• fully-specified

The main constructor for heterogeneous maps is the HMap constructor.

HMap takes a :mandatory keyword argument specifying the entries that always occur in this type.

clojure.core.typed=> (cf {:a 1} (HMap :mandatory {:a Num}))
;=> (HMap :mandatory {:a Num})

clojure.core.typed=> (cf {} (HMap :mandatory {:a Num}))
;Type Error (clojure.core.typed:1:30) Expected type: (HMap :mandatory {:a Num})
;Actual: (HMap :mandatory {} :complete? true)

We can forget extra keys with just :mandatory (because :complete? defaults to false).

clojure.core.typed=> (cf {:a 1 :b 'a} (HMap :mandatory {:a Num}))
;=> (HMap :mandatory {:a Num})

:optional keys specify entries that may or may not occur. If the entry does occur, the respective value is of the type specified in the :optional map.

We use :optional often in combination with :mandatory:

clojure.core.typed=> (cf {} (HMap :optional {:a Num}))
;=> (HMap :optional {:a Num})
clojure.core.typed=> (cf {:a 1 :b 'a} (HMap :mandatory {:a Num} :optional {:b Symbol}))
;=> (HMap :mandatory {:a Num} :optional {:b Symbol})
clojure.core.typed=> (cf {:a 1} (HMap :mandatory {:a Num} :optional {:b Symbol}))
;=> (HMap :mandatory {:a Num} :optional {:b Symbol})

:absent-keys declares a set of specific keys do not appear. This is useful for more accurate types with lookups on absent keys.

The first input below shows we get type Any if we lookup a key we don't know any information about. The second input shows :absent-keys is used to infer lookups on absent keys as nil.

clojure.core.typed=> (cf (let [m (ann-form {:a 1} (HMap :mandatory {}))] 
                           (:a m)))
;=> Any

clojure.core.typed=> (cf (let [m (ann-form {:a 1} (HMap :absent-keys #{:a}))] 
                           (:a m)))
;=> nil

Finally, :complete? says that there are no further entries in this map. It takes a boolean value, defaulted to false.

clojure.core.typed=> (cf (let [m (ann-form {} (HMap :complete? true))] 
                           (:a m)))
;=> nil

Non-keyword keys

Literal maps without keyword keys are inferred as APersistentMap.

clojure.core.typed=> (cf {(inc 1) 1})
[(clojure.lang.APersistentMap clojure.core.typed/AnyInteger (Value 1)) {:then tt, :else ff}]

Heterogeneous Sequentials

A HSequential is an immutable heterogeneous collection that satisfies (Coll a) and clojure.lang.Sequential.

(HSequential [Num Sym]) represents a collection of count 2 like [1 'a] or '(1 a).

Rest and dotted rest arguments are supported with similar syntax to Fn.

eg. (HSequential [Num Sym *]) (HSequential [Num b ... b])

Heterogeneous Vectors

(HVec [(Value 1) (Value 2)]) is a Vec of count 2, essentially representing the value [1 2]. The type '[(Value 1) (Value 2)] is identical.

HVecs are subtypes of HSequentials.

Rest and dotted rest arguments are supported with similar syntax to Fn.

eg. (HVec [Num Sym *]) (HVec [Num b ... b])

Polymorphism

The binding form All introduces a number of free variables inside a scope.

Optionally scopes a dotted variable by adding ... after the last symbol in the binder.

eg. The identity function: (All [x] [x -> x]) eg. Introducing dotted variables: `(All [x y ...] [x y ... y -> x])

Recursive Types

Rec introduces a recursive type. It takes a vector of one symbol and a type. The symbol is scoped to represent the entire type in the type argument.

; Type for {:op :if
;           :test {:op :var, :var #'A}
;           :then {:op :nil}
;           :else {:op :false}}
(Rec [x] 
     (U '{:op (Value :if)
          :test x
          :then x
          :else x}
        '{:op (Value :var)
          :var clojure.lang.Var}
        '{:op (Value :nil)}
        '{:op (Value :false)}))))