## 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`. However for all types `x` it holds that `Nothing <: x`. Put another way, `Nothing` is a valid type to give 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.

### 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 signatures of the same arity:

``````(Fn [Symbol -> Number]
[Number -> Symbol])
``````

This function returns a `Number` if passed a `Symbol`, and returns a `Symbol` if passed a `Number`.

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 `Symbol` and a `Number`, so at most one arity triggers for any given arguments.

Overlapping arities hints at the power of ordered intersections.

``````(Fn [Long -> Symbol]
[Number -> Keyword])
``````

This type always returns a `Symbol` for `Long` arguments.

Beware, swapping the arities produces different results!

``````(Fn [Number -> Keyword]
[Long -> Symbol])
``````

The first arity always "wins" because `Number` 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 -> Keyword]
[Any Number -> Symbol])
``````

Calling with `Long` `Long` arguments gives `Keyword`, and `Number` `Long` gives `Symbol`.

Flipping the arities gives different results:

``````(Fn [Any Number -> Symbol]
[Long Any -> Keyword])
``````

Now `Long` `Long` gives `Symbol`, and `Number` `Long` gives `Symbol`. 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 -> Symbol] [Number -> Keyword])` to handle the case where the argument is either a `Long` or a `Number`. We can express this by using a union (to express a least-upper-bound of `Long` and `Number`).

``````(Fn [Long -> Symbol]
[Number -> Keyword]
[(U Long Number) -> (U Symbol Keyword)])
``````

Note the result type is sufficiently general to show the result type is either a `Symbol` or `Keyword`.

#### Rest parameters

Rest parameters are specified using a `*`.

eg.

``````(Fn [Any Number * -> Any])
``````

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

#### Keyword parameters

Keyword parameters are specified using `&` after the fixed domain.

eg.

``````(Fn [Any & {:a Number} -> Any])
``````

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

We can also specify mandatory keyword parameters:

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

is the same function, except the keyword argumetn `: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 Number :b Number} -> Number]
[Any & {:a Number :b Number} -> Any])
``````

This function type returns a `Number` 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
``````

### 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 (IMapEntry Symbol Number)))
(clojure.lang.Seqable (clojure.lang.IMapEntry clojure.lang.Symbol java.lang.Number))
clojure.core.typed=> (cf [1 2 3] (Seqable Number))
(clojure.lang.Seqable java.lang.Number)
clojure.core.typed=> (cf '#{a b c} (Seqable Symbol))
(clojure.lang.Seqable clojure.lang.Symbol)
``````

### Seqs

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

``````clojure.core.typed=> (cf (seq [1 2]) (ISeq Number))
(clojure.lang.ISeq java.lang.Number)
``````

### Lists

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

``````clojure.core.typed=> (cf '(1 2) (IPersistentList Number))
(clojure.lang.IPersistentList java.lang.Number)
``````

### Vectors

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

``````clojure.core.typed=> (cf [1 2] (IPersistentVector Number))
(clojure.lang.IPersistentVector java.lang.Number)
``````

### Maps

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

``````clojure.core.typed=> (cf {'a 1 'b 3} (IPersistentMap Symbol Long))
(clojure.lang.IPersistentMap clojure.lang.Symbol java.lang.Long)
``````

### Sets

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

``````clojure.core.typed=> (cf #{1 2 3} (IPersistentSet Number))
(clojure.lang.IPersistentSet java.lang.Number)
``````

### Atoms

An Atom of type `(Atom 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 `(clojure.core.typed/Atom1 wr)` is provided, which is equivalent to `(Atom wr wr)`.

``````clojure.core.typed=> (cf (atom {}) (Atom1 (IPersistentMap Symbol Number)))
(clojure.core.typed/Atom1 (clojure.lang.IPersistentMap clojure.lang.Symbol java.lang.Number))
``````

## Type Grammar

A rough grammar for core.typed types.

``````Type :=  nil
|   true
|   false
|   (U Type*)
|   (I Type+)
|   FunctionIntersection
|   (Value CONSTANT-VALUE)
|   (Rec [Symbol] Type)
|   (All [Symbol+] Type)
|   (All [Symbol* Symbol ...] Type)
|   (HMap {Keyword Type*})        ;eg (HMap {:a (Value 1), :b nil})
|   '{Keyword Type*}              ;eg '{:a (Value 1), :b nil}
|   (Vector* 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

Warning: Heterogeneous maps are alpha and their design is subject to change.

A heterogeneous map type represents a map that has at least a particular set of keyword keys.

``````clojure.core.typed=> (cf {:a 1})
[(HMap {:a (Value 1)}) {:then tt, :else ff}]
``````

This type can also be written `'{:a (Value 1)}`.

Lookups of known keys infer accurate types.

``````clojure.core.typed=> (cf (-> {:a 1} :a))
(Value 1)
``````

Currently, they are limited (but still quite useful):

• the presence of keys is recorded, but not their absence
• only keyword value keys are allowed.

These rules have several implications.

#### Absent keys

Looking up keys that are not recorded as present give inaccurate types

``````clojure.core.typed=> (cf (-> {:a 1} :b))
Any
``````

#### 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}]
``````

Optional keys can be defined either by constructing a union of map types, or by passing the `HMap` type constructor an `:optional` keyword argument with a map of optional keys.

### Heterogeneous Vectors

`(Vector* (Value 1) (Value 2))` is a IPersistentVector of length 2, essentially representing the value `[1 2]`. The type `'[(Value 1) (Value 2)]` is identical.

### 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 (HMap {:op (Value :if)
:test x
:then x
:else x})
(HMap {:op (Value :var)
:var clojure.lang.Var})
(HMap {:op (Value :nil)})
(HMap {:op (Value :false)})))))
``````