The key innovation in this library is the Instances type, which is a database of instances that can be queried at runtime. More specifically, an Instances tt c is a mapping from elements of type tt to instances of class c.

It is expected that tt be an instance of the TypeText class, which controls how types are rendered into text. A good initial choice for tt is Unqualified, which will render all types as unqualified names. This is simple, but potentially ambiguous, if you have multiple types with the same name (declared in different modules). See Type.Reflection.Name for other alternatives.

An important restriction is that Instances can hold only ground instances: instances with no type variables or type families. Maybe we can accommodate non-ground instances in the future, but not today. (There seems to be no fundamental reason we cannot support non-ground instances, but doing so would be a good deal harder than ground instances.) The instance declarations may have variables, even though the Instances database will hold those instances' instantiations. For example, while we have instance Eq a => Eq (Maybe a), that polymorphic instance cannot be stored in Instances. Instead, you can build an Instances Unqualified Eq with, say, Eq (Maybe Int), Eq (Maybe Bool), and Eq (Maybe Double). Looking up Maybe Int, Maybe Bool, and Maybe Double will all succeed, but looking up Maybe Char would fail.

To create an Instances, use the instancesFor... functions. The Invisible variants accept a type argument specifying the (ground) types which should be used to populate the Instances database. The TypeRep variant expects a TypeRep. In the future, we expect to offer a instancesFor function which will use visible dependent quantification to accept the list of types. Note that Instances is a Monoid, so you can combine the results of several calls.

In order to build an Instances containing all instances in scope, see Instance.Runtime.TH.

To use an Instances, use the withInstanceProxy function. This function looks up an instance in the database and, if successful, passes that instance to a callback function. In the future, once we have the ability to bind type variables in a lambda, we expect withInstance to be a better interface.