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.Names

This module provides an optional framework that facilitates name lookup in type-checking plugins, using constrained traversals (similar to the barbies library).

See the ResolveNames typeclass.

Before:

data PluginDefs =
  PluginDefs
    { myTyCon           :: TyCon
    , myClass           :: Class
    , myPromotedDataCon :: TyCon
    }

findMyModule :: MonadTcPlugin m => m Module
findMyModule = do
  let modlName = mkModuleName "MyModule"
  pkgQual    <- resolveImport      modlName Nothing
  findResult <- findImportedModule modlName pkgQual
  case findResult of
    Found _ res -> pure res
    _           -> error $ "MyPlugin: could not find any module named MyModule."

pluginInit :: TcPluginM Init PluginDefs
pluginInit = do
  myModule <- findMyModule
  myTyCon           <-                       tcLookupTyCon   =<< lookupOrig myModule ( mkTcOcc   "MyTyCon"   )
  myClass           <-                       tcLookupClass   =<< lookupOrig myModule ( mkClsOcc  "MyClass"   )
  myPromotedDataCon <- fmap promoteDataCon . tcLookupDataCon =<< lookupOrig myModule ( mkDataOcc "MyDataCon" )
  pure ( PluginDefs { .. } )

After:

data PluginDefsHKD n =
  PluginDefs
    { myTyCon            :: Wear n TyCon
    , myClass            :: Wear n Class
    , myPromotedDataCon  :: Wear n ( Promoted DataCon )
    }
  deriving stock Generic
  deriving ResolveNames
    via Generically1 PluginDefsHKD

type PluginDefs = PluginDefsHKD Resolved

pluginInit :: TcPluginM Init PluginDefs
pluginInit = resolveNames pluginNames
  where
    pluginNames :: PluginDefsHKD Named
    pluginNames =
      PluginDefs
        { myTyCon           = mkQualified "MyTyCon"
        , myClass           = mkQualified "MyClass"
        , myPromotedDataCon = mkQualified "MyDataCon"
        }
    mkQualified :: String -> QualifiedName thing
    mkQualified str =
      Qualified
        { name    = str
        , module' = mkModuleName "MyModule"
        , package = Nothing
        }
  • 4 types
  • 2 classes
  • 1 value
classclass ResolveNames (f :: NameResolution -> Type) where
#

This class exposes the method resolveNames which will perform name resolution for all the fields in a datatype.

Example usage: we define a record that will hold the things we want to look up, using the Wear type family.

For example:

data MyData n
  = MyData
  { myClass       :: !( Wear n Class )
  , myTyCon       :: !( Wear n TyCon )
  , myDataCon     :: !( Wear n DataCon )
  , myPromDataCon :: !( Wear n (Promoted DataCon) )
  }
  deriving stock Generic
  deriving ResolveNames
    via Generically1 MyData

Now we can specify the names of the things which we want to look up, together with the modules and packages in which they belong:

myNames :: MyData Named
myNames = MyData
 { myClass = QualifiedName "MyClass" "My.Module" ( Just "my-pkg-name" )
 , ...
 }

Then we can call resolveNames:

resolvedNames :: MonadTcPlugin m => m (MyData Resolved)
resolvedNames = resolveNames myNames

This returns a record containing the looked up things we want, e.g. myClass :: Class, myPromDataCon :: TyCon, etc.

Instances1ResolveNames
familytype family Wear (n :: NameResolution) (thing :: k) where
#

Type-family used for higher-kinded data pattern.

This allows the same record to be re-used, as explained in the worked example for ResolveNames.

For instance, if one defines:

data MyData n
  = MyData
  { myClass :: !( Wear n Class )
  , myTyCon :: !( Wear n TyCon )
  }

then a record of type MyData Named is simply a record of textual names (a typeclass name and a type-constructor name, with associated module & packages), whereas a record of type MyData Resolved contains a typeclass's Class as well as a type-constructor's TyCon.

Equations

datadata NameResolution
#

Type-level parameter to Wear type family, for higher-kinded data.

Wear Named thing is the identifier data passed in as an argument. Wear Resolved thing is the result of name resolving the thing.

This allows users to pass a record of names, of type MyData Named, and obtain a record of looked-up things, of type MyData Resolved.

Refer to ResolveNames for a worked example.

NamedResolved
Instances1ResolveNames
datadata Promoted (thing :: k)
#

Use this to refer to a Promoted DataCon.

Instances1Lookupable
classclass Lookupable (a :: k) where
#

Type-class overloading things that can be looked up by name:

  • classes,

  • data constructors (as well as their promotion),

  • type-constructors.

Methods

Instances4Lookupable

Re-export Generically1 for compatibility.

1 declaration
newtypenewtype Generically1 (f :: k -> Type) (a :: k) where
#

A type whose instances are defined generically, using the Generic1 representation. Generically1 is a higher-kinded version of Generically that uses Generic.

Generic instances can be derived for type constructors via Generically1 F using -XDerivingVia.

{-# LANGUAGE DeriveGeneric      #-}
{-# LANGUAGE DerivingStrategies #-}
{-# LANGUAGE DerivingVia        #-}

import GHC.Generics (Generic)

data V4 a = V4 a a a a
  deriving stock (Functor, Generic1)

  deriving Applicative
  via Generically1 V4

This corresponds to Applicative instances defined by pointwise lifting:

instance Applicative V4 where
  pure :: a -> V4 a
  pure a = V4 a a a a

  liftA2 :: (a -> b -> c) -> (V4 a -> V4 b -> V4 c)
  liftA2 (·) (V4 a1 b1 c1 d1) (V4 a2 b2 c2 d2) =
    V4 (a1 · a2) (b1 · b2) (c1 · c2) (d1 · d2)

Historically this required modifying the type class to include generic method definitions (-XDefaultSignatures) and deriving it with the anyclass strategy (-XDeriveAnyClass). Having a /via type/ like Generically1 decouples the instance from the type class.

Constructors

Instances8Functor, Applicative, Alternative, Eq1, Ord1, ResolveNames, …