{-# LANGUAGE CPP #-}
{-# LANGUAGE TemplateHaskellQuotes #-}
-- | Generate functions for performing operations of dynamically dispatched
-- effects via Template Haskell.
module Effectful.TH
  ( makeEffect
  , makeEffect_
  ) where

import Control.Monad
import Data.Char (toLower)
import Data.Foldable (foldl')
import Data.Maybe
import Language.Haskell.TH
import Language.Haskell.TH.Datatype
import Language.Haskell.TH.Datatype.TyVarBndr
import qualified Data.Map.Strict as Map

import Effectful
import Effectful.Dispatch.Dynamic

-- | For an effect data type @E@, @'makeEffect' E@ generates the appropriate
-- instance of 'DispatchOf' as well as functions for performing operations of
-- @E@ by 'send'ing them to the effect handler.
--
-- >>> :{
--   data E :: Effect where
--     Op1 :: Int -> m a -> E m a
--     Op2 :: IOE :> es => Int -> E (Eff es) ()
--     Op3 :: (forall r. m r -> m r) -> E m Int
--   makeEffect ''E
-- :}
--
-- >>> :kind! DispatchOf E
-- DispatchOf E :: Dispatch
-- = 'Dynamic
--
-- >>> :i op1
-- op1 :: (HasCallStack, E :> es) => Int -> Eff es a -> Eff es a
-- ...
--
-- >>> :i op2
-- op2 :: (HasCallStack, E :> es, IOE :> es) => Int -> Eff es ()
-- ...
--
-- >>> :i op3
-- op3 ::
--   (HasCallStack, E :> es) =>
--   (forall r. Eff es r -> Eff es r) -> Eff es Int
-- ...
--
-- The naming rule changes the first uppercase letter in the constructor name to
-- lowercase or removes the @:@ symbol in case of operators. Any fixity
-- annotations defined for the constructors are preserved for the corresponding
-- definitions.
makeEffect :: Name -> Q [Dec]
makeEffect :: Name -> Q [Dec]
makeEffect = Bool -> Name -> Q [Dec]
makeEffectImpl Bool
True

-- | Like 'makeEffect', but doesn't generate type signatures. This is useful
-- when you want to attach Haddock documentation to function signatures:
--
-- >>> :{
--   data Noop :: Effect where
--     Noop :: Noop m ()
--   makeEffect_ ''Noop
--   -- | Perform nothing at all.
--   noop :: Noop :> es => Eff es ()
-- :}
--
-- /Note:/ function signatures must be added /after/ the call to 'makeEffect_'.
makeEffect_ :: Name -> Q [Dec]
makeEffect_ :: Name -> Q [Dec]
makeEffect_ = Bool -> Name -> Q [Dec]
makeEffectImpl Bool
False

makeEffectImpl :: Bool -> Name -> Q [Dec]
makeEffectImpl :: Bool -> Name -> Q [Dec]
makeEffectImpl Bool
makeSig Name
effName = do
  Q ()
checkRequiredExtensions
  DatatypeInfo
info <- Name -> Q DatatypeInfo
reifyDatatype Name
effName
  Dec
dispatch <- do
    Type
e <- Type -> [Type] -> Q Type
getEff (Name -> Type
ConT forall a b. (a -> b) -> a -> b
$ DatatypeInfo -> Name
datatypeName DatatypeInfo
info) (DatatypeInfo -> [Type]
datatypeInstTypes DatatypeInfo
info)
    let dispatchE :: Type
dispatchE = Name -> Type
ConT ''DispatchOf Type -> Type -> Type
`AppT` Type
e
        dynamic :: Type
dynamic   = Name -> Type
PromotedT 'Dynamic
    forall (f :: Type -> Type) a. Applicative f => a -> f a
pure forall b c a. (b -> c) -> (a -> b) -> a -> c
. TySynEqn -> Dec
TySynInstD forall a b. (a -> b) -> a -> b
$ Maybe [TyVarBndr ()] -> Type -> Type -> TySynEqn
TySynEqn forall a. Maybe a
Nothing Type
dispatchE Type
dynamic
  [[Dec]]
ops <- forall (t :: Type -> Type) (f :: Type -> Type) a b.
(Traversable t, Applicative f) =>
(a -> f b) -> t a -> f (t b)
traverse (Bool -> Name -> Q [Dec]
makeCon Bool
makeSig) (ConstructorInfo -> Name
constructorName forall (f :: Type -> Type) a b. Functor f => (a -> b) -> f a -> f b
<$> DatatypeInfo -> [ConstructorInfo]
datatypeCons DatatypeInfo
info)
  forall (f :: Type -> Type) a. Applicative f => a -> f a
pure forall a b. (a -> b) -> a -> b
$ Dec
dispatch forall a. a -> [a] -> [a]
: forall (t :: Type -> Type) a. Foldable t => t [a] -> [a]
concat (forall a. [a] -> [a]
reverse [[Dec]]
ops)
  where
    getEff :: Type -> [Type] -> Q Type
    getEff :: Type -> [Type] -> Q Type
getEff Type
e = \case
      [Type
m, Type
r]   -> do
        forall {f :: Type -> Type}.
MonadFail f =>
String -> Type -> Type -> f ()
checkKind String
"the next to last" (Type
ArrowT Type -> Type -> Type
`AppT` Type
StarT Type -> Type -> Type
`AppT` Type
StarT) Type
m
        forall {f :: Type -> Type}.
MonadFail f =>
String -> Type -> Type -> f ()
checkKind String
"the last" Type
StarT Type
r
        forall (f :: Type -> Type) a. Applicative f => a -> f a
pure Type
e
      (Type
v : [Type]
vs) -> Type -> [Type] -> Q Type
getEff (Type
e Type -> Type -> Type
`AppT` Type -> Type
forgetKind Type
v) [Type]
vs
      [Type]
_        -> forall (m :: Type -> Type) a. MonadFail m => String -> m a
fail String
"The effect data type needs at least 2 type parameters"
      where
        forgetKind :: Type -> Type
forgetKind = \case
          SigT Type
v Type
_ -> Type
v
          Type
ty       -> Type
ty

    checkKind :: String -> Type -> Type -> f ()
checkKind String
which Type
expected = \case
      SigT (VarT Name
_) Type
k
        | Type
k forall a. Eq a => a -> a -> Bool
== Type
expected -> forall (f :: Type -> Type) a. Applicative f => a -> f a
pure ()
        | Bool
otherwise -> forall (m :: Type -> Type) a. MonadFail m => String -> m a
fail
           forall a b. (a -> b) -> a -> b
$ String
"Expected " forall a. [a] -> [a] -> [a]
++ String
which forall a. [a] -> [a] -> [a]
++ String
" type parameter to have a kind "
          forall a. [a] -> [a] -> [a]
++ forall a. Ppr a => a -> String
pprint Type
expected forall a. [a] -> [a] -> [a]
++ String
", got " forall a. [a] -> [a] -> [a]
++ forall a. Ppr a => a -> String
pprint Type
k
      -- Weird type, let it through and see what happens.
      Type
_ -> forall (f :: Type -> Type) a. Applicative f => a -> f a
pure ()

-- | Generate a single definition of an effect operation.
makeCon :: Bool -> Name -> Q [Dec]
makeCon :: Bool -> Name -> Q [Dec]
makeCon Bool
makeSig Name
name = do
  Maybe Fixity
fixity <- Name -> Q (Maybe Fixity)
reifyFixity Name
name
  Type
typ <- Name -> Q Info
reify Name
name forall (m :: Type -> Type) a b. Monad m => m a -> (a -> m b) -> m b
>>= \case
    DataConI Name
_ Type
typ Name
_ -> forall (f :: Type -> Type) a. Applicative f => a -> f a
pure Type
typ
    Info
_ -> forall (m :: Type -> Type) a. MonadFail m => String -> m a
fail forall a b. (a -> b) -> a -> b
$ String
"Not a data constructor: " forall a. [a] -> [a] -> [a]
++ Name -> String
nameBase Name
name

  ([Type]
actionParams, (Type
effTy, Either Name Name
ename, Type
resTy)) <- Type -> Q ([Type], (Type, Either Name Name, Type))
extractParams Type
typ

  -- The 'ename' can be either:
  --
  -- - A variable for the monad, in which case we need to generate the @es@
  --   variable and substitute it later for 'Eff es'.
  --
  -- - A variable 'es' for the local 'Eff es' if the monad parameter was locally
  --   substituted in the contructor.
  --
  -- For example in the following effect:
  --
  -- data E :: Effect where
  --   E1 :: Int -> E m ()
  --   E2 :: IOE :> es => E (Eff es) ()
  --
  -- Processing 'E1' will yield 'Right m', but 'E2' will yield 'Left es'.
  --
  -- In the first case we need to substitute the variable ourselves in a few
  -- places, but in the second we're good since it was already substituted.
  (Name
esName, Maybe Name
maybeMonadName) <- case Either Name Name
ename of
    Left  Name
esName    -> forall (f :: Type -> Type) a. Applicative f => a -> f a
pure (Name
esName, forall a. Maybe a
Nothing)
    Right Name
monadName -> (, forall a. a -> Maybe a
Just Name
monadName) forall (f :: Type -> Type) a b. Functor f => (a -> b) -> f a -> f b
<$> forall (m :: Type -> Type). Quote m => String -> m Name
newName String
"es"

  let fnName :: Name
fnName = String -> Name
mkName forall b c a. (b -> c) -> (a -> b) -> a -> c
. String -> String
toSmartConName forall a b. (a -> b) -> a -> b
$ Name -> String
nameBase Name
name
  [Name]
fnArgs <- forall (t :: Type -> Type) (f :: Type -> Type) a b.
(Traversable t, Applicative f) =>
(a -> f b) -> t a -> f (t b)
traverse (forall a b. a -> b -> a
const forall a b. (a -> b) -> a -> b
$ forall (m :: Type -> Type). Quote m => String -> m Name
newName String
"x") [Type]
actionParams

  let esVar :: Type
esVar = Name -> Type
VarT Name
esName

      substM :: Type -> Type
      substM :: Type -> Type
substM = case Maybe Name
maybeMonadName of
        Just Name
m  -> forall a. TypeSubstitution a => Map Name Type -> a -> a
applySubstitution forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall k a. k -> a -> Map k a
Map.singleton Name
m forall a b. (a -> b) -> a -> b
$ Name -> Type
ConT ''Eff Type -> Type -> Type
`AppT` Type
esVar
        Maybe Name
Nothing -> forall a. a -> a
id

      ([TyVarBndrSpec]
origActionVars, [Type]
actionCtx) = Type -> ([TyVarBndrSpec], [Type])
extractCtx Type
typ
      actionVars :: [TyVarBndrSpec]
actionVars = case Maybe Name
maybeMonadName of
        Just Name
m  -> forall a. (a -> Bool) -> [a] -> [a]
filter ((Name
m forall a. Eq a => a -> a -> Bool
/=) forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall flag. TyVarBndr_ flag -> Name
tvName) [TyVarBndrSpec]
origActionVars
                forall a. [a] -> [a] -> [a]
++ [Name -> Type -> TyVarBndrSpec
kindedTVSpecified Name
esName forall a b. (a -> b) -> a -> b
$ Type
ListT Type -> Type -> Type
`AppT` Name -> Type
ConT ''Effect]
        Maybe Name
Nothing -> [TyVarBndrSpec]
origActionVars

#if MIN_VERSION_template_haskell(2,17,0)
  -- In GHC >= 9.0 it's possible to generate the following body:
  --
  -- e x1 .. xN = send (E @ty1 .. @tyN x1 .. xN)
  --
  -- because specificities of constructor variables are exposed.
  --
  -- This allows to generate functions for such effects:
  --
  -- type family F ty :: Type
  -- data AmbEff :: Effect where
  --   AmbEff :: Int -> AmbEff m (F ty)
  --
  -- Sadly the version for GHC < 9 will not compile due to ambiguity error.
  let fnBody :: Exp
fnBody =
        let tvFlag :: TyVarBndr flag -> flag
tvFlag = \case
              PlainTV  Name
_ flag
flag   -> flag
flag
              KindedTV Name
_ flag
flag Type
_ -> flag
flag

            tyApps :: [Type]
tyApps = (forall a b. (a -> Maybe b) -> [a] -> [b]
`mapMaybe` [TyVarBndrSpec]
origActionVars) forall a b. (a -> b) -> a -> b
$ \TyVarBndrSpec
v -> case forall {flag}. TyVarBndr flag -> flag
tvFlag TyVarBndrSpec
v of
              Specificity
InferredSpec  -> forall a. Maybe a
Nothing
              Specificity
SpecifiedSpec -> forall a. a -> Maybe a
Just forall a b. (a -> b) -> a -> b
$ if Maybe Name
maybeMonadName forall a. Eq a => a -> a -> Bool
== forall a. a -> Maybe a
Just (forall flag. TyVarBndr_ flag -> Name
tvName TyVarBndrSpec
v)
                                      then Name -> Type
ConT ''Eff Type -> Type -> Type
`AppT` Type
esVar
                                      else Name -> Type
VarT (forall flag. TyVarBndr_ flag -> Name
tvName TyVarBndrSpec
v)

            effCon :: Exp
effCon = if Bool
makeSig
              then forall (t :: Type -> Type) b a.
Foldable t =>
(b -> a -> b) -> b -> t a -> b
foldl' Exp -> Type -> Exp
AppTypeE (Name -> Exp
ConE Name
name) [Type]
tyApps
              else                  Name -> Exp
ConE Name
name
        in Name -> Exp
VarE 'send Exp -> Exp -> Exp
`AppE` forall (t :: Type -> Type) b a.
Foldable t =>
(b -> a -> b) -> b -> t a -> b
foldl' (\Exp
f -> Exp -> Exp -> Exp
AppE Exp
f forall b c a. (b -> c) -> (a -> b) -> a -> c
. Name -> Exp
VarE) Exp
effCon [Name]
fnArgs
#else
  -- In GHC < 9.0, generate the following body:
  --
  -- e :: E v1 .. vN :> es => x1 -> .. -> xK -> E v1 .. vN (Eff es) r
  -- e x1 .. xK = send (E x1 .. xN :: E v1 .. vK (Eff es) r)
  let fnBody =
        let effOp  = foldl' (\f -> AppE f . VarE) (ConE name) fnArgs
            effSig = effTy `AppT` (ConT ''Eff `AppT` esVar) `AppT` substM resTy
        in if makeSig
           then VarE 'send `AppE` SigE effOp effSig
           else VarE 'send `AppE`      effOp
#endif
  let fnSig :: Type
fnSig = [TyVarBndrSpec] -> [Type] -> Type -> Type
ForallT [TyVarBndrSpec]
actionVars
        (Name -> Type
ConT ''HasCallStack forall a. a -> [a] -> [a]
: Type -> Name -> Type -> Type
UInfixT Type
effTy ''(:>) Type
esVar forall a. a -> [a] -> [a]
: [Type]
actionCtx)
        (Type -> (Type -> Type) -> Type -> [Type] -> Type
makeTyp Type
esVar Type -> Type
substM Type
resTy [Type]
actionParams)

  let rest :: [Dec]
rest = Name -> [Clause] -> Dec
FunD Name
fnName [[Pat] -> Body -> [Dec] -> Clause
Clause (Name -> Pat
VarP forall (f :: Type -> Type) a b. Functor f => (a -> b) -> f a -> f b
<$> [Name]
fnArgs) (Exp -> Body
NormalB Exp
fnBody) []]
           forall a. a -> [a] -> [a]
: forall a. Maybe a -> [a]
maybeToList ((Fixity -> Name -> Dec
`InfixD` Name
name) forall (f :: Type -> Type) a b. Functor f => (a -> b) -> f a -> f b
<$> Maybe Fixity
fixity)
  (forall a. [a] -> [a] -> [a]
++ [Dec]
rest) forall (f :: Type -> Type) a b. Functor f => (a -> b) -> f a -> f b
<$> Name -> [Dec] -> Q [Dec]
withHaddock Name
name [Name -> Type -> Dec
SigD Name
fnName Type
fnSig | Bool
makeSig]

----------------------------------------
-- Helpers

toSmartConName :: String -> String
toSmartConName :: String -> String
toSmartConName = \case
  (Char
':' : String
xs) -> String
xs
  (Char
x : String
xs)   -> Char -> Char
toLower Char
x forall a. a -> [a] -> [a]
: String
xs
  String
_          -> forall a. HasCallStack => String -> a
error String
"empty constructor name"

extractCtx :: Type -> ([TyVarBndrSpec], Cxt)
extractCtx :: Type -> ([TyVarBndrSpec], [Type])
extractCtx = \case
  ForallT [TyVarBndrSpec]
vars [Type]
ctx Type
_ -> ([TyVarBndrSpec]
vars, [Type]
ctx)
  Type
ty                 -> forall a. HasCallStack => String -> a
error forall a b. (a -> b) -> a -> b
$ String
"unexpected type: " forall a. [a] -> [a] -> [a]
++ forall a. Show a => a -> String
show Type
ty

extractParams :: Type -> Q ([Type], (Type, Either Name Name, Type))
extractParams :: Type -> Q ([Type], (Type, Either Name Name, Type))
extractParams = \case
  ForallT [TyVarBndrSpec]
_ [Type]
_ Type
ty -> Type -> Q ([Type], (Type, Either Name Name, Type))
extractParams Type
ty
  SigT Type
ty Type
_ -> Type -> Q ([Type], (Type, Either Name Name, Type))
extractParams Type
ty
  ParensT Type
ty -> Type -> Q ([Type], (Type, Either Name Name, Type))
extractParams Type
ty
  Type
ArrowT `AppT` Type
a `AppT` Type
ty -> do
    ([Type]
args, (Type, Either Name Name, Type)
ret) <- Type -> Q ([Type], (Type, Either Name Name, Type))
extractParams Type
ty
    forall (f :: Type -> Type) a. Applicative f => a -> f a
pure (Type
a forall a. a -> [a] -> [a]
: [Type]
args, (Type, Either Name Name, Type)
ret)
#if MIN_VERSION_template_haskell(2,17,0)
  Type
MulArrowT `AppT` Type
_ `AppT` Type
a `AppT` Type
ty -> do
    ([Type]
args, (Type, Either Name Name, Type)
ret) <- Type -> Q ([Type], (Type, Either Name Name, Type))
extractParams Type
ty
    forall (f :: Type -> Type) a. Applicative f => a -> f a
pure (Type
a forall a. a -> [a] -> [a]
: [Type]
args, (Type, Either Name Name, Type)
ret)
#endif
  Type
effTy `AppT` Type
monadTy `AppT` Type
resTy -> case Type
monadTy of
    VarT Name
monadName -> forall (f :: Type -> Type) a. Applicative f => a -> f a
pure ([], (Type
effTy, forall a b. b -> Either a b
Right Name
monadName, Type
resTy))
    ConT Name
eff `AppT` VarT Name
esName
      | Name
eff forall a. Eq a => a -> a -> Bool
== ''Eff -> forall (f :: Type -> Type) a. Applicative f => a -> f a
pure ([], (Type
effTy, forall a b. a -> Either a b
Left Name
esName, Type
resTy))
    Type
ty -> forall (m :: Type -> Type) a. MonadFail m => String -> m a
fail forall a b. (a -> b) -> a -> b
$ String
"Invalid instantiation of the monad parameter: " forall a. [a] -> [a] -> [a]
++ forall a. Ppr a => a -> String
pprint Type
ty
  Type
ty -> forall (m :: Type -> Type) a. MonadFail m => String -> m a
fail forall a b. (a -> b) -> a -> b
$ String
"Unexpected type: " forall a. [a] -> [a] -> [a]
++ forall a. Ppr a => a -> String
pprint Type
ty

makeTyp :: Type -> (Type -> Type) -> Type -> [Type] -> Type
makeTyp :: Type -> (Type -> Type) -> Type -> [Type] -> Type
makeTyp Type
esVar Type -> Type
substM Type
resTy = \case
  []       -> Name -> Type
ConT ''Eff Type -> Type -> Type
`AppT` Type
esVar Type -> Type -> Type
`AppT` Type -> Type
substM Type
resTy
  (Type
p : [Type]
ps) -> Type
ArrowT Type -> Type -> Type
`AppT` Type -> Type
substM Type
p Type -> Type -> Type
`AppT` Type -> (Type -> Type) -> Type -> [Type] -> Type
makeTyp Type
esVar Type -> Type
substM Type
resTy [Type]
ps

withHaddock :: Name -> [Dec] -> Q [Dec]
#if MIN_VERSION_template_haskell(2,18,0)
withHaddock :: Name -> [Dec] -> Q [Dec]
withHaddock Name
name [Dec]
dec = String -> Q [Dec] -> Q [Dec]
withDecsDoc
  (String
"Perform the operation '" forall a. [a] -> [a] -> [a]
++ Name -> String
nameBase Name
name forall a. [a] -> [a] -> [a]
++ String
"'.") (forall (f :: Type -> Type) a. Applicative f => a -> f a
pure [Dec]
dec)
#else
withHaddock _ dec = pure dec
#endif

checkRequiredExtensions :: Q ()
checkRequiredExtensions :: Q ()
checkRequiredExtensions = do
  [Extension]
missing <- forall (m :: Type -> Type) a.
Applicative m =>
(a -> m Bool) -> [a] -> m [a]
filterM (forall (f :: Type -> Type) a b. Functor f => (a -> b) -> f a -> f b
fmap Bool -> Bool
not forall b c a. (b -> c) -> (a -> b) -> a -> c
. Extension -> Q Bool
isExtEnabled) [Extension]
exts
  let ppMissing :: [String]
ppMissing = forall a b. (a -> b) -> [a] -> [b]
map (\Extension
ext -> String
"{-# LANGUAGE " forall a. Semigroup a => a -> a -> a
<> forall a. Show a => a -> String
show Extension
ext forall a. Semigroup a => a -> a -> a
<> String
" #-}") [Extension]
missing
  forall (f :: Type -> Type). Applicative f => Bool -> f () -> f ()
unless (forall (t :: Type -> Type) a. Foldable t => t a -> Bool
null [Extension]
missing) forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall (m :: Type -> Type) a. MonadFail m => String -> m a
fail forall b c a. (b -> c) -> (a -> b) -> a -> c
. [String] -> String
unlines forall a b. (a -> b) -> a -> b
$
    [ String
"Generating functions requires additional language extensions.\n"
    , String
"You can enable them by adding them to the 'default-extensions'"
    , String
"field in the .cabal file or the following pragmas to the beginning"
    , String
"of the source file:\n"
    ] forall a. [a] -> [a] -> [a]
++ [String]
ppMissing
  where
    exts :: [Extension]
exts = [ Extension
FlexibleContexts
           , Extension
ScopedTypeVariables
#if MIN_VERSION_template_haskell(2,17,0)
           , Extension
TypeApplications
#endif
           , Extension
TypeFamilies
           , Extension
TypeOperators
           ]