HORIZON HASKELLDocslts/ghc-9.14.x45dd5372026-10-11Search names, modules, packages, or :: a typeCtrl K

GHC 9.14.1 · lts/ghc-9.14.x · 45dd537 · 2026-10-11

Moduleghc-tcplugin-api-0.20.1.0Haskell2010

GHC.TcPlugin.API.Internal

This module provides operations to directly lift and unlift computations in GHC's GHC.Tc.TcM monad to the various type-checking plugin monads, in the form of the functions

unsafeLiftTcM :: TcM a -> m a
unsafeWithRunInTcM :: ( ( forall a. m a -> TcM a ) -> TcM b ) -> m b

Here GHC.Tc.TcM is GHC's internal type-checker monad.

It also exposes extra environment available in the solving/rewriting stages:

askRewriteEnv :: TcPluginM Rewrite RewriteEnv
askEvBinds :: TcPluginM Solve EvBindsVar

It is hoped that none of these internal operations are necessary, and that users can fulfill their needs without importing this internal module.

Please file a bug on the issue tracker if you have encountered a situation which requires the import of this module.

  • 5 types
  • 2 classes
  • 10 values

Internal functions and types

3 declarations
classclass (Monad m, forall x y. Coercible x y => Coercible (m x) (m y)) => MonadTcPlugin (m :: Type -> Type) where
#

A MonadTcPlugin is essentially a reader monad over GHC's GHC.Tc.TcM monad.

This means we have both a lift and an unlift operation, similar to MonadUnliftIO or MonadBaseControl.

See for instance unsafeLiftThroughTcM, which is an example of function that one would not be able to write using only a lift operation.

Note that you must import the internal module in order to access the methods. Please report a bug if you find yourself needing this functionality.

Methods

Instances4MonadTcPlugin
classclass MonadTcPlugin m => MonadTcPluginWork (m :: Type -> Type) where
#

Monads for type-checking plugins which are able to emit new constraints and throw errors.

These operations are supported by the monads that tcPluginSolve and tcPluginRewrite use; it is not possible to emit work or throw type errors in tcPluginInit or tcPluginPostTc.

See mkTcPluginErrorTy and GHC.TcPlugin.API.emitWork for functions which require this typeclass.

Instances4MonadTcPluginWork
valueunsafeLiftThroughTcM :: MonadTcPlugin m => (TcM a -> TcM b) -> m a -> m b
#

Take a function whose argument and result types are both within the GHC.Tc.TcM monad, and return a function that works within a type-checking plugin monad.

Please report a bug if you find yourself needing to use this function.

Re-exported functions and types

19 declarations
datadata TcPlugin
#

A record containing all the stages necessary for the operation of a type-checking plugin, as defined in this API.

Note: this is not the same record as GHC's built-in TcPlugin record. Use mkTcPlugin for the conversion.

To create a type-checking plugin, define something of this type and then call mkTcPlugin on the result. This will return something that can be passed to GHC.Plugins.Plugin:

plugin :: GHC.Plugins.Plugin
plugin =
  GHC.Plugins.defaultPlugin
    { GHC.Plugins.tcPlugin =
        \ args -> Just $
           GHC.TcPlugin.API.mkTcPlugin ( myTcPlugin args )
    }

myTcPlugin :: [String] -> GHC.TcPlugin.API.TcPlugin
myTcPlugin args = ...

Constructors

  • forall s. TcPlugin
    • tcPluginInit :: TcPluginM 'Init s

      Initialize plugin (once per module), when starting the type-checker.

    • tcPluginSolve :: s -> TcPluginSolver

      Solve some constraints.

      This function will be invoked at two points in the constraint solving process: once to simplify Given constraints, and once to solve Wanted constraints. In the first case (and only in the first case), no Wanted constraints will be passed to the plugin.

      The plugin can either return a contradiction, or specify that it has solved some constraints (with evidence), and possibly emit additional constraints. These returned constraints must be Givens in the first case, and Wanteds in the second.

      Use \ _ _ _ _ -> pure $ TcPluginOk [] [] if your plugin

    • tcPluginRewrite :: s -> UniqFM TyCon TcPluginRewriter

      Rewrite saturated type family applications.

      The plugin is expected to supply a mapping from type family names to rewriting functions. For each type family TyCon, the plugin should provide a function which takes in the given constraints and arguments of a saturated type family application, and return a possible rewriting. See TcPluginRewriter for the expected shape of such a function.

      Use const emptyUFM if your plugin does not provide this functionality.

    • tcPluginPostTc :: s -> TcPluginM 'PostTc ()

      Action to run at the end of typechecking a module, e.g. to intercept the final TcGblEnv/TcLclEnv at the end of typechecking, possibly modifying mutable fields.

      Should not terminate the plugin, as the plugin may continue to be invoked when desugaring the module (as the pattern-match checker may invoke the constraint solver).

    • tcPluginShutdown :: s -> IO ()

      Clean up after the plugin, when GHC is done processing the given module (e.g. after desugaring).

datadata TcPluginStage
#

Stage of a type-checking plugin, used as a data kind.

Constructors

data familydata family TcPluginM (s :: TcPluginStage) :: Type -> Type
#

The monad used for a type-checker plugin, parametrised by the TcPluginStage of the plugin.

Instances25Monad, Functor, Applicative, MonadIO, MonadTcPlugin, MonadTcPluginWork, …
datadata TcPluginErrorMessage
#

Use this type like ErrorMessage to write an error message. This error message can then be thrown at the type-level by the plugin, by emitting a wanted constraint whose predicate is obtained from mkTcPluginErrorTy.

A GHC.Tc.Types.Constraint.CtLoc will still need to be provided in order to inform GHC of the origin of the error (e.g.: which part of the source code should be highlighted?). See setCtLocM.

Constructors

typetype TcPluginRewriter = [Ct] -> [Type] -> TcPluginM 'Rewrite TcPluginRewriteResult
#

For rewriting type family applications, a type-checking plugin provides a function of this type for each type family TyCon.

The function is provided with the current set of Given constraints, together with the arguments to the type family. The type family application will always be fully saturated.

valueaskDeriveds :: TcPluginM 'Solve [Ct]
#

Ask for the Derived constraints that the solver was provided with.

Always returns the empty list on GHC 9.4 or above.

valuemkTcPlugin
  1. :: TcPlugin

    type-checking plugin written with this library

  2. -> TcPlugin

    type-checking plugin for GHC

#

Use this function to create a type-checker plugin to pass to GHC.