-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Look up class instances at runtime. -- -- This package allows clients to build a database of class instances, -- queryable at runtime. Accordingly, this allows runtime class instance -- lookup. Template Haskell utility functions are provided for creating -- the instance database from the set of instances in scope at a given -- point in your program. @package runtime-instances @version 1.0 -- | 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. module Instance.Runtime -- | A database of instances available for runtime queries. An -- Instances tn c contains instances of the class c, -- indexed by type names rendered according to the rules for tn. data Instances type_namer c -- | Create an Instances for a type denoted by the given -- TypeRep. instanceForTypeRep :: forall {k} (x :: k) (c :: k -> Constraint) tn. c x => TypeText tn => TypeRep x -> Instances tn c -- | Create an Instances for a type passed invisibly. Example: -- instanceForInvisible Int@. instanceForInvisible :: forall {k} (x :: k) (c :: k -> Constraint) tn. Typeable x => c x => TypeText tn => Instances tn c -- | Create an Instances for a list of types passed invisibly. -- Example: instancesForInvisible [Int, Bool, Double]@. instancesForInvisible :: forall {k} (xs :: [k]) (c :: k -> Constraint) tn. Typeable xs => All c xs => TypeText tn => Instances tn c -- | Look up an instance in Instances, making the instance available -- for use in the continuation function. If the lookup fails, this -- returns Nothing. Until -- https://github.com/ghc-proposals/ghc-proposals/pull/448 is -- implemented, there is no way to bind a type variable to the found -- type, so this function is likely impossible to use well. For now, see -- withInstanceProxy instead. withInstance :: Ord tn => Instances tn c -> tn -> (forall x. c x => r) -> Maybe r -- | Look up an instance in Instances, making the instance available -- for use in the continuation function. If the lookup fails, this -- returns Nothing. If -- https://github.com/ghc-proposals/ghc-proposals/pull/448 has -- been implemented in your GHC, you may prefer withInstance. withInstanceProxy :: Ord tn => Instances tn c -> tn -> (forall x. c x => Proxy x -> r) -> Maybe r -- | Look up an instance in Instances, when you already have a -- TypeRep for the type to look up. To use this function, the -- class c used in your Instances must imply -- Typeable; the Typeable instance is used to check that -- the retrieved type is actually the one you want. If it's not, this -- function throws an exception (this really shouldn't happen). (In GHCs -- before 9.4, this check is skipped, because of a bug around -- Typeable and quantified constraints.) If the lookup fails, this -- returns Nothing. withInstanceTypeRep :: forall t c tn r. TypeText tn => Instances tn c -> TypeRep t -> (c t => r) -> Maybe r -- | Perform a computation for each instance in the database, accumulating -- results in a monoid. Your monoid should be commutative, because there -- is no predictable order of instances in the Instances. foldInstances :: Monoid m => Instances tn c -> (forall x. c x => Proxy x -> m) -> m instance forall type_namer k (c :: k -> GHC.Types.Constraint). GHC.Classes.Ord type_namer => GHC.Base.Monoid (Instance.Runtime.Instances type_namer c) instance forall type_namer k (c :: k -> GHC.Types.Constraint). GHC.Classes.Ord type_namer => GHC.Base.Semigroup (Instance.Runtime.Instances type_namer c) instance forall k type_namer (c :: k -> GHC.Types.Constraint). (GHC.Show.Show type_namer, Data.Typeable.Internal.Typeable c) => GHC.Show.Show (Instance.Runtime.Instances type_namer c) module Instance.Runtime.TH -- | Build an Instances containing all in-scope ground instances for -- the given class. A ground instance is one that includes no type -- variables. Example usage: -- -- 
--   instanceDatabase :: Instances Unqualified MyClass
--   instanceDatabase = $(allGroundInstances [t| MyClass |])
--
-- -- It is an infelicity in the design of Template Haskell that requires -- repeating the MyClass part; it should be inferrable. -- -- Note that this just looks at instance declarations to determine -- whether an instance is ground. So it would not pick up, e.g. Eq -- (Maybe Int), because the instance declaration looks like Eq -- (Maybe a). -- -- Due to a limitation of Template Haskell, this will find only instances -- declared in other modules or before a declaration splice in the -- current module. If you want to find instances declared in the current -- module, you can add a line -- -- 
--   $(pure [])
--
-- -- above the use of allGroundInstances in the file. This line -- forces GHC to finish processing everything above the line before -- looking at anything below the line, so those instances declared above -- the line are available below it. allGroundInstances :: Q Type -> Q Exp -- | Returns a list of ground (= no variables) types that satisfy the given -- constraint. The passed-in Type must have kind k -> -- Constraint for some k; all the returned types will then -- have kind k. -- -- This finds only types that appear in ground instances. So if you look -- for Eq, you'll get Int, and Double, but not -- Maybe Int, even though Maybe Int is a ground type: -- it comes from instance ... => Eq (Maybe a), which is not a -- ground instance. -- -- See also allGroundInstances, for more usage information. allGroundInstanceTypes :: Type -> Q [Type] -- | Constructs a promoted list type from a list of types. Useful for -- synthesizing calls to instancesForInvisible using Template -- Haskell. promotedList :: [Type] -> Type